Machine-readable contracts

HeyAira publishes two complementary contracts:

1. MCP-native tool contract — mcp-tools.json is generated from the tool registrations in src/heyaira/server.py. It contains the tool names, descriptions, required scopes, and JSON Schemas that clients discover through MCP tools/list.
2. OpenAPI 3.1 HTTP contract — openapi.yaml describes the HTTP, health, OAuth metadata, and authorization surface. The /mcp operation is intentionally only a JSON-RPC transport envelope; it does not replace MCP tool discovery.

Which contract should a client use?

• An MCP client should initialize the server and call tools/list. The live MCP response is authoritative for available tools and schemas.
• A human or HTTP tooling can use openapi.yaml for /healthz, OAuth discovery, token operations, and the Streamable HTTP envelope.
• Documentation pages explain workflow and safety rules; the machine-readable files remove ambiguity for validation and code generation.

Update rule

The source of truth is the server registration and MCP protocol behavior. When a tool name, parameter, schema, scope, error, or HTTP route changes:

python scripts/export_mcp_contract.py
python scripts/check_docs_contract.py
mkdocs build --strict --site-dir site-docs

The pull-request check regenerates the MCP manifest in memory and fails if the checked-in JSON is stale, if the OpenAPI document loses a required route, or if the human tool catalogue no longer covers the runtime tools. The production workflow runs the same checks before publishing docs.heyaira.eu.

The live server remains the final interoperability check: after deployment, an authenticated client must rediscover tools/list and run the synthetic smoke test. No credentials or project data belong in either contract.