Enhance MCP schema properties with examples and improved descriptions

[Copilot]

Four MCP server properties in main_workflow_schema.json lacked examples and clear descriptions, creating a documentation gap where users couldn't discover these fields through schema validation despite full implementation support.

Changes

registry (stdio + http)

• Added example: https://api.mcp.github.com/v0/servers/microsoft/markitdown

allowed (stdio + http)

• Clarified description: "List of allowed tool names for this MCP server"
• Added examples: ["*"], ["store_memory", "retrieve_memory"], ["brave_web_search"]

entrypoint (stdio)

• Enhanced description: "Optional entrypoint override for container (equivalent to docker run --entrypoint)"
• Added examples: /custom/entrypoint.sh, python

mounts (stdio)

• Already complete with pattern ^[^:]+:[^:]+:(ro|rw)$ - no changes

Example Usage

mcp-servers:
  markitdown:
    registry: "https://api.mcp.github.com/v0/servers/microsoft/markitdown"
    container: "microsoft/markitdown:latest"
    entrypoint: "/custom/entrypoint.sh"
    mounts: ["/data:/app/data:ro"]
    allowed: ["*"]

Properties updated in:

• properties.tools.additionalProperties.oneOf[1].properties
• $defs.stdio_mcp_tool.properties
• $defs.http_mcp_tool.properties

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Add Missing MCP Properties to Main Workflow Schema</issue_title>
<issue_description>## Description

The main_workflow_schema.json is missing 4 critical MCP server properties that are already implemented in the parser and actively used in workflows. This creates a schema documentation gap where users cannot discover these fields through schema validation, even though they work correctly in the implementation.

Missing Properties

1. registry (string)

   • Purpose: URI to MCP installation location when installed from registry
   • Implementation: pkg/parser/mcp.go:86, pkg/workflow/mcp-config-custom.go:582-584
   • Tested in: mcp_config_compilation_test.go (6 test cases)
   • Example: "https://api.mcp.github.com/v0/servers/microsoft/markitdown"

2. allowed (array of strings)

   • Purpose: Filter which tools from MCP server are accessible
   • Implementation: pkg/parser/mcp.go:88, pkg/workflow/mcp-config-custom.go:651-653
   • Critical for: Tool name filtering and security
   • Example: ["*"], ["store_memory", "retrieve_memory"]

3. entrypoint (string)

   • Purpose: Override container entrypoint for Docker-based MCP servers
   • Implementation: pkg/types/mcp.go:23, pkg/workflow/mcp-config-custom.go:602-604
   • Example: "/bin/sh", "/custom/entrypoint.sh", "python"

4. mounts (array)

   • Purpose: Volume mounts for containerized MCP servers (security-critical)
   • Implementation: pkg/types/mcp.go:25, pkg/workflow/mcp-config-custom.go:608-610
   • Pattern: ^[^:]+:[^:]+:(ro|rw)$
   • Example: ["/host/path:/container/path:ro"]

Suggested Changes

Update pkg/parser/schemas/main_workflow_schema.json (lines 3398-3477) to add these properties:

{
  "registry": {
    "type": "string",
    "description": "URI to the installation location when MCP is installed from a registry",
    "examples": ["https://api.mcp.github.com/v0/servers/microsoft/markitdown"]
  },
  "entrypoint": {
    "type": "string",
    "description": "Optional entrypoint override for container (equivalent to docker run --entrypoint)",
    "examples": ["/bin/sh", "/custom/entrypoint.sh", "python"]
  },
  "mounts": {
    "type": "array",
    "items": {
      "type": "string",
      "pattern": "^[^:]+:[^:]+:(ro|rw)$"
    },
    "description": "Volume mounts for container (format: 'source:dest:mode' where mode is 'ro' or 'rw')",
    "examples": [["/host/path:/container/path:ro", "/tmp/cache:/app/cache:rw"]]
  },
  "allowed": {
    "type": "array",
    "items": {"type": "string"},
    "description": "List of allowed tool names for this MCP server",
    "examples": [["*"], ["store_memory", "retrieve_memory"], ["brave_web_search"]]
  }
}

Files Affected

• pkg/parser/schemas/main_workflow_schema.json (lines 3398-3477)
• Parser implementation: Already complete - NO code changes needed
• Documentation: Add registry field to user guides (other 3 already documented)

Success Criteria

• All 4 missing properties added to main schema with correct types
• Schema includes proper descriptions and examples for each property
• Pattern validation matches implementation (mounts pattern: ^[^:]+:[^:]+:(ro|rw)$)
• All existing tests pass
• make build succeeds (schemas are embedded with //go:embed)
• make recompile regenerates workflows successfully
• Schema validation accepts workflows using these properties

Additional Context

Important: After modifying the schema JSON file, you must rebuild the binary with make build because schema files are embedded using //go:embed directives in pkg/parser/schema.go.

Testing workflow:

1. Edit pkg/parser/schemas/main_workflow_schema.json
2. Run make build to rebuild with embedded schema
3. Run ./gh-aw compile test-workflow.md to verify
4. Run make test to ensure no regressions

Source

Extracted from Schema Consistency Check discussion githubnext/gh-aw#11706 - Strategy-004 Cross-Schema Consistency Analysis (2026-01-24)

Priority

High - Schema documentation is incomplete, preventing users from discovering implemented features. No implementation changes needed, only schema updates.

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 8, 2026, 2:04 PM UTC

Comments on the Issue (you are @copilot in this...

• Fixes [Code Quality] Add Missing MCP Properties to Main Workflow Schema #11765

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.