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.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.json
is covered by an external watch (seeCI)
https://toolschema-kit.onrender.com/mcp
(Also: GET /health
for liveness.)
git clone https://github.com/kioie/toolschema-kit.git
cd toolschema-kit
CATALOG_MCP_TRANSPORT=http go run ./cmd/catalog-mcp
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.
mcp.json.example — point
url
at localhost or the live host above.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.
| Guide | Topic |
|---|---|
docs/ci.mddocs/simulate-drift.mddocs/comparison.md| Target | Command / file |
|---|---|
Render |
Blueprint
render.yaml |
Containerdocker run -p 8080:8080 ghcr.io/kioie/toolschema-kit:latest
Fly+ optional workflow (needs billing)fly.toml
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.
MIT — see LICENSE.