Skip to content

REQ-O-035: tool mcp-validate Built-In Command

Tier: Opt-In | Priority: P2

Source: §47 MCP Wrapper Schema Staleness

Addresses: Severity: High / Token Spend: Medium / Time: High / Context: Medium

Description

When the tool is wrapped as an MCP server, the framework MUST provide a built-in tool mcp-validate command that compares the MCP tool schemas with the current CLI command schemas and reports any drift. Schema drift is defined as: a field present in the CLI schema but absent from the MCP schema; a field present in the MCP schema but absent from the CLI schema; a field type that differs between the two schemas; a new command added to the CLI but not exposed in the MCP wrapper, unless its manifest entry carries mcp: false (REQ-C-032). The command MUST accept --mcp-schema-file <path> or --mcp-server-url <url> as the source of truth for the MCP schema.

Acceptance Criteria

  • tool mcp-validate --mcp-schema-file mcp.json exits 0 if schemas match, non-zero if drift is detected
  • Drift is reported as a structured JSON diff with added, removed, and changed fields
  • A new CLI command not present in the MCP schema is reported as a missing_from_mcp drift entry
  • A command marked mcp: false is never reported as missing_from_mcp
  • The command can be run in CI to detect schema staleness before deployment

Schema

Types: response-envelope.md

data contains drift with added, removed, changed, and missing_from_mcp arrays.

Wire Format

$ tool mcp-validate --mcp-schema-file mcp.json --format json

{
  "ok": false,
  "data": {
    "drift": {
      "added": [],
      "removed": [],
      "changed": [{ "command": "deploy", "field": "data.url", "cli_type": "string", "mcp_type": "null" }],
      "missing_from_mcp": ["delete"]
    }
  },
  "error": {
    "code": "SCHEMA_DRIFT_DETECTED",
    "message": "CLI schema and MCP schema differ for 2 commands",
    "retryable": false,
    "fix_required": "Regenerate the MCP schema from tool manifest"
  },
  "warnings": [],
  "meta": { "exit_code": 1, "duration_ms": 31 }
}

No drift:

{ "ok": true, "data": { "drift": { "added": [], "removed": [], "changed": [], "missing_from_mcp": [] } }, "error": null, "warnings": [], "meta": { "exit_code": 0, "duration_ms": 12 } }

Example

Opt-in at the framework level.

app = Framework("tool")
app.enable_mcp_validate()

# Run in CI to catch schema staleness before deployment:
$ tool mcp-validate --mcp-schema-file ./mcp-server/schema.json
→ exit 0 if no drift, exit 1 if drift detected
Requirement Tier Relationship
REQ-C-015 C Provides: CLI schemas compared against MCP schemas
REQ-O-041 O Provides: manifest used as the canonical CLI schema source for comparison
REQ-C-032 C Consumes: mcp: false marks a command the MCP server leaves out on purpose