46 lines
1.7 KiB
Markdown
46 lines
1.7 KiB
Markdown
# MCP Versioning and Compatibility (Agent Guide)
|
|
|
|
## Why this exists
|
|
Agents can fail for reasons that are already fixed in newer MCP runtime builds. This guide defines where to check runtime/tool versions and where fix records are tracked.
|
|
|
|
## Runtime version header
|
|
Whetstone MCP now exposes a `whetstoneVersionHeader` in:
|
|
- `initialize.result`
|
|
- `ping.result`
|
|
- `tools/list.result`
|
|
- `tools/call.result`
|
|
|
|
Header fields:
|
|
- `runtimeVersion`: MCP runtime version (for example `0.8.4`)
|
|
- `protocolVersion`: MCP protocol date string
|
|
- `toolContractDefaultVersion`: default contract version for tools
|
|
- `toolSurfaceSchemaVersion`: schema snapshot version
|
|
- `toolCount`: tool count in the running server
|
|
- `toolSurfaceFingerprint`: deterministic fingerprint of tool names
|
|
- `compatibilityLedger.path`: path to the issue/fix ledger JSON
|
|
- `compatibilityLedger.version`: ledger schema/snapshot version
|
|
|
|
## Tool-level contract header
|
|
Each `tools/list` entry includes `x-whetstone`:
|
|
- `contractVersion`
|
|
- `compatibilityLedger`
|
|
|
|
## Compatibility ledger
|
|
Machine-readable ledger:
|
|
- `docs/mcp_compatibility_ledger.json`
|
|
|
|
Use this for checks like:
|
|
- "Issue reproduced on `runtimeVersion=0.8.1`"
|
|
- "Ledger says fixed in `0.8.4`"
|
|
- "Action: update server runtime before more debugging"
|
|
|
|
## Recommended triage flow for agents
|
|
1. Call `initialize` (or `ping`) and capture `whetstoneVersionHeader`.
|
|
2. If behavior seems wrong, read `docs/mcp_compatibility_ledger.json` and match symptom tags.
|
|
3. If `runtimeVersion < fixed_in`, report upgrade recommendation first.
|
|
4. Only escalate to deep debugging after version mismatch is ruled out.
|
|
|
|
## Notes
|
|
- Keep ledger entries small and concrete (symptom, affected tools, fixed version).
|
|
- Add entries when a recurring failure pattern is fixed deterministically.
|