MCP tool-schema reference & contract exercises for agent platforms (Cursor, Claude Desktop, custom runtimes).
If you already gate OpenAPI breaking changes with tools like OASDiff or policy checks in the spirit of SpecShield, this repo applies the same mindset to tools/list and tool I/O schemas — where HTTP can stay 200 while agent contracts still break.
What this is
A small commerce-catalog MCP server (Go, tinymcp) you can run locally, in CI, or on a free host. It exposes get_product and list_skus with versioned output controlled by CATALOG_SCHEMA_VERSION.
Use it to:
- Prototype agent flows against a stable catalog contract
- Reproduce silent drift (healthy HTTP, changed tool schemas)
- Optional: assert every URL in
mcp.jsonis covered by an external watch (see CI)
Live endpoint
https://toolschema-kit.onrender.com/mcp
(Also: GET /health for liveness.)
Quick start
git clone https://github.com/kioie/toolschema-kit.git cd toolschema-kit CATALOG_MCP_TRANSPORT=http go run ./cmd/catalog-mcp # MCP: http://127.0.0.1:8080/mcp
Bump schema (diff exercise)
CATALOG_SCHEMA_VERSION=2026.06.02 CATALOG_MCP_TRANSPORT=http go run ./cmd/catalog-mcp
Compare tools/list or tool outputs before/after — same idea as an OpenAPI diff, for MCP.
Cursor / Claude Desktop
mcp.json.example — point url at localhost or the live host above.
Production monitoring
Teams usually run a scheduled contract watch on MCP URLs (diff tools/list, alert on breaking changes). This repo stays vendor-neutral; one workflow shows DriftGuard coverage assert as an optional gate — swap in your own checker if you prefer.
Docs
| Guide | Topic |
|---|---|
| docs/end-to-end.md | Local → agent → diff → optional watch |
| docs/ci.md | GitHub Actions contract coverage |
| docs/simulate-drift.md | Version bumps & silent drift |
| docs/comparison.md | OpenAPI diff vs MCP tool-schema diff |
Deploy
| Target | Command / file |
|---|---|
| Render | Blueprint render.yaml — auto-deploy on push when connected |
| Container | docker run -p 8080:8080 ghcr.io/kioie/toolschema-kit:latest |
| Fly | fly.toml + optional workflow (needs billing) |
Keywords
MCP schema drift, tool-schema diff, OpenAPI-style breaking changes for agents, Cursor MCP contract test, tools/list monitoring, silent API drift, SpecShield alternative MCP, OASDiff for MCP.
License
MIT — see LICENSE.