mcp-contracts

Snapshot and verify MCP tool contracts in CI.

MCP server changes can silently break agents when a tool disappears, an input schema shifts, or a description changes in a meaningful way. mcp-contracts turns a tools/list response into a reviewable JSON contract and fails CI when that contract changes.

git clone https://github.com/K14-coder/mcp-contracts.git
cd mcp-contracts
# Save the current tool surface as a committed contract
node src/cli.js snapshot tools-list.json --out .mcp/contracts/tools.json

# Fail when the latest response diverges from that contract
node src/cli.js verify tools-list.json --contract .mcp/contracts/tools.json

The input can be either a raw { "tools": [...] } value or the JSON-RPC tools/list response { "result": { "tools": [...] } }.

What it catches

• Removed tools
• Added tools
• Changed tool descriptions
• Changed JSON input schemas
• Duplicate or malformed tool names

Example CI step

- run: node scripts/export-tools-list.js > tools-list.json
- run: node src/cli.js verify tools-list.json --contract .mcp/contracts/tools.json

This project intentionally focuses on stable contract files. For interactive protocol debugging, use the official MCP Inspector instead.

Development

npm test

Privacy

The CLI makes no network requests and collects no telemetry. Contract files may contain tool metadata; do not commit secrets in descriptions or schemas.

Keywords

MCP contract testing, Model Context Protocol, MCP server testing, AI agent tooling, JSON Schema, API compatibility, CI.

License

MIT