[Schema Consistency] Main Schema Missing 4 Critical MCP Properties (registry, allowed, entrypoint, mounts)

[github-actions[bot]]

Schema Consistency Check - January 24, 2026

Summary

• Inconsistencies Found: 7 critical issues
• Categories Analyzed: Main Schema, MCP Config Schema, Parser/Compiler Implementation, Documentation
• Strategy Used: Strategy-004 (Cross-Schema Consistency & Type Analysis)
• Key Discovery: Main schema missing 4 critical MCP properties that are implemented and used

Critical Issues (7 found)

1. Main Schema Missing Implemented MCP Properties

The main_workflow_schema.json tools.additionalProperties (lines 3398-3477) is missing 4 properties that ARE implemented in the parser and actively used:

Missing Properties:

1. registry (string)

   • Implementation: pkg/parser/mcp.go:86, pkg/workflow/mcp-config-custom.go:582-584
   • Usage: Tested in mcp_config_compilation_test.go (6 test cases)
   • Impact: Users cannot discover this field via main schema validation

2. allowed (array of strings)

   • Implementation: pkg/parser/mcp.go:88, pkg/workflow/mcp-config-custom.go:651-653
   • Usage: Critical for tool filtering - tested extensively
   • Impact: No schema validation for tool name filtering

3. entrypoint (string)

   • Implementation: pkg/types/mcp.go:23, pkg/workflow/mcp-config-custom.go:602-604
   • Usage: Container entrypoint override for Docker-based MCP servers
   • Impact: Container customization not schema-validated

4. mounts (array with pattern)

   • Implementation: pkg/types/mcp.go:25, pkg/workflow/mcp-config-custom.go:608-610
   • Usage: Volume mounts for containerized MCP servers
   • Impact: Critical security feature (filesystem access) lacks schema validation

2. Schema Duplication Without $ref

The main schema duplicates MCP properties inline instead of using $ref to reference mcp_config_schema.json, causing:

• Maintenance burden: Two places to update
• Schema drift: Main schema now 4 properties behind
• Inconsistent validation: Different constraints

3. Pattern Constraint Mismatches

Environment Variable Pattern:

• Main schema: ^[A-Za-z_][A-Za-z0-9_]*$ (allows lowercase)
• MCP config schema: ^[A-Z_][A-Z0-9_]*$ (uppercase only)
• Impact: Main schema accepts invalid env var names

Container Image Pattern:

• Main schema: NO pattern validation
• MCP config schema: ^[a-zA-Z0-9][a-zA-Z0-9/:_.-]*$
• Impact: Main schema accepts malformed container names

4. Validation Constraint Mismatches

URL/Command fields:

• Main schema: No minLength constraint
• MCP config schema: minLength: 1
• Impact: Main schema accepts empty strings

5. additionalProperties Conflict

• Main schema: additionalProperties: true (permissive)
• MCP config schema: additionalProperties: false (strict)
• Impact: Inconsistent validation behavior

6. Undocumented "mode" Property

• Main schema defines both mode and type with identical enum values
• MCP config schema only has type
• Issue: Unclear if mode is alias, deprecated, or workflow-specific

7. Enum Value Mismatch

• Main schema type/mode: Includes "remote"
• MCP config schema type: Does NOT include "remote"
• Impact: Inconsistent validation

Documentation Gaps

Fields Documented But Not in Main Schema

1. allowed - Documented in docs/reference/tools.md and compilation-process.md
2. entrypoint - Documented in docs/reference/mcp-gateway.md
3. mounts - Extensively documented in mcp-gateway.md (Section 4.1.5)

Fields NOT Documented Anywhere

1. registry - Implemented and tested but NO end-user documentation

Schema Improvements Needed

Priority 1: Add Missing Properties to Main Schema

Update pkg/parser/schemas/main_workflow_schema.json lines 3398-3477 to include:

{
  "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/(redacted) "/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"]]
  }
}

Priority 2: Align Pattern Constraints

1. Environment variable pattern: Use uppercase-only ^[A-Z_][A-Z0-9_]*$ (POSIX standard)
2. Container image pattern: Add ^[a-zA-Z0-9][a-zA-Z0-9/:_.-]*$ to main schema
3. URL/Command minLength: Add minLength: 1 to main schema

Priority 3: Consider Using $ref

Replace inline duplication with schema reference to eliminate maintenance burden and ensure consistency.

Priority 4: Clarify "mode" Property

Document or deprecate - unclear if it's an alias for type, workflow-specific, or obsolete.

---

Parser Updates Required

None - implementation is already complete and correct. This is a schema documentation gap only.

✅ All 4 missing properties implemented
✅ Parser extracts fields correctly
✅ Compiler processes them correctly
✅ Extensive test coverage exists

---

Recommendations

Immediate Actions (This Week)

1. Add 4 missing properties to main schema (registry, allowed, entrypoint, mounts)
2. Align pattern constraints (env, container, url, command)
3. Document registry field in user guides

Short-term Actions (Next Sprint)

4. Investigate $ref approach for eliminating duplication
5. Clarify or deprecate mode property

Long-term Strategy

6. Implement schema consistency tests to detect drift
7. Regular schema audits (monthly using Strategy-004)

---

Strategy Performance

• Strategy: Strategy-004 (Cross-Schema Consistency & Type Analysis)
• Findings: 7 critical issues
• Effectiveness: Very High
• Run Date: 2026-01-24

Key Insights:

• Schema drift is real - main schema now 4 properties behind implementation
• Duplication without $ref leads to divergence
• Implementation is correct - only schema documentation incomplete

---

References:

• Workflow run: §21323563129

AI generated by Schema Consistency Checker

• expires on Jan 31, 2026, 11:54 PM UTC

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰

[github-actions[bot]]

Plan Created ✅

I've analyzed the schema consistency findings and created 5 actionable sub-issues to address all 7 critical issues identified:

Issues Created

1. Add missing MCP properties to main workflow schema - Adds registry, allowed, entrypoint, and mounts properties (addresses issues rejig docs #1 and add cli flag to guard dropping a agentic workflow instructinos file #6)

2. Align pattern constraints between schemas - Fixes environment variable, container image, and URL/command validation mismatches (addresses issue Add workflow: githubnext/agentics/weekly-research #3 and Add workflow: githubnext/agentics/weekly-research #4)

3. Align additionalProperties and enum values - Resolves conflicts between permissive/strict validation and type enum mismatches (addresses issue Add workflow: githubnext/agentics/weekly-research #5 and Weekly Research Report: AI Workflow Automation Landscape and Market Opportunities - August 2025 #7)

4. Clarify or deprecate "mode" property - Investigates and documents the purpose of the duplicate mode field (addresses issue add cli flag to guard dropping a agentic workflow instructinos file #6)

5. Document registry field in user guides - Adds missing end-user documentation for the registry property (addresses documentation gap)

Strategy

All issues are focused, actionable, and can be assigned to GitHub Copilot agents. They follow a logical sequence:

1. Add missing properties (foundational)
2. Align constraints (consistency)
3. Resolve conflicts (correctness)
4. Clarify ambiguity (clarity)
5. Document (discoverability)

The issues will be automatically grouped under a parent tracking issue. Each has clear acceptance criteria and references the specific files and line numbers from the audit.