v0.3.0 - Runtime OpenAPI Contract Loading

v0.3.0 - Runtime OpenAPI Contract Loading

Summary

Echo MCP v0.3.0 adds runtime OpenAPI contract loading through the MCP control
plane and partial contract-backed response validation for supported OpenAPI 3.0
JSON features.

This release does not make Echo MCP fully OpenAPI-first. Strict mode means
strict enforcement of the validation capabilities currently supported by Echo
MCP; it is not full OpenAPI validation.

Added

• Runtime OpenAPI contract loading through load_openapi_contract.
• Active contract inspection through get_contract_status.
• Active contract unloading through unload_openapi_contract.
• Partial contract-backed response validation for configured REST behavior.
• Local internal $ref resolution for response schemas.
• Response schema validation for common object and primitive schemas, required
  properties, enum, nullable, nested objects, arrays of supported item schemas,
  and omitted or boolean additionalProperties.
• Validation disclosure fields: validation_scope, validation_capabilities,
  and validation_mode_description.
• Contract root boundary with ECHO_MCP_CONTRACT_ROOT.
• Safe contract source path display relative to the contract root.
• Reproducible OpenAPI compatibility smoke script.

Runtime Workflow

Recommended contract-backed workflow:

1. Start Echo MCP.
2. Call load_openapi_contract with a local OpenAPI 3.0 JSON file.
3. Call get_contract_status.
4. Inspect validation_scope, validation_capabilities, and
   validation_mode_description.
5. Call configure_behavior with a concrete response.
6. Run app tests against the REST data plane.
7. Use reset between scenarios; the contract remains active.
8. Use unload_openapi_contract when switching contract contexts.

Manual mock behavior remains supported. When a contract is active, intentional
fault tests can skip validation by passing validation.mode = "off" with a
non-empty reason.

Example Config

Register Echo MCP as an MCP stdio server and choose a contract root:

[mcp_servers.echo_mcp]
command = "/absolute/path/to/project/.codex/bin/echo-mcp"
args = []
env = { ECHO_MCP_HTTP_ADDR = "127.0.0.1:18080", ECHO_MCP_CONTRACT_ROOT = "/absolute/path/to/project/contracts" }

Load a contract at runtime:

{
  "path": "provider.openapi.json",
  "contract_id": "provider",
  "validation_mode": "strict"
}

Startup loading remains available and uses the same contract-root boundary:

ECHO_MCP_CONTRACT_ROOT=./contracts \
ECHO_MCP_OPENAPI_FILE=provider.openapi.json \
./bin/echo-mcp

Compatibility

• Existing manual mock behavior remains supported when no contract is active.
• REST data-plane responses are not modified by contract guidance or validation
  warnings.
• reset clears behavior and observations but keeps the active contract loaded.
• Startup OpenAPI loading and runtime OpenAPI loading use the same contract
  manager and path boundary.
• schemas_count is the number of component schemas discovered in the loaded
  OpenAPI document. It is not the number of schemas fully supported by Echo
  MCP's validator.
• The compatibility corpus includes synthetic fixtures plus smoke probes for
  Stripe OpenAPI and GitHub REST OpenAPI. Those providers are compatibility
  checks, not special cases.

Not Included

• No echo-mcp.yaml.
• No full OpenAPI-first runtime.
• No OpenAPI 3.1 or YAML support.
• No remote refs or file refs.
• No allOf, oneOf, or anyOf semantics.
• No discriminator support.
• No request body validation.
• No query, header, or path parameter validation.
• No automatic scenario generation.
• No provider-specific Stripe simulator.
• No remote contract fetching.

Assets

GitHub release assets:

• echo-mcp_darwin_amd64.tar.gz
• echo-mcp_darwin_arm64.tar.gz
• echo-mcp_linux_amd64.tar.gz
• echo-mcp_linux_arm64.tar.gz
• echo-mcp_windows_amd64.zip
• checksums.txt

Checksums are published as checksums.txt on the GitHub release.