Add automated MCP schema regression testing

[caballeto]

Adds regression test coverage for MCP tool interactions using mcp-recorder -- like VCR.py but for MCP servers. Records the full protocol exchange into a JSON cassette and verifies it hasn't changed on every push.

What this covers

A single cassette (protocol_and_errors.json) captures 7 interactions:

• Protocol handshake -- initialize response with protocol version, capabilities, server info
• Tool schemas -- tools/list with complete input schemas for all 5 tools (50+ parameters total)
• Error handling -- tools/call for search, extract, map, and crawl without an API key, verifying the McpError response

If a tool is renamed, a parameter is removed, or the error format changes, the CI diff shows exactly what broke.

How it works

The server is spawned via stdio with no TAVILY_API_KEY set. initialize and tools/list work normally; tool calls hit the API key guard and return a deterministic error. No network calls, no secrets, no API credits.

Changes

All additive -- no existing files modified.

integration/
  scenarios.yml                          # 4 tool calls + schema listing in ~30 lines of YAML
  cassettes/protocol_and_errors.json     # golden cassette (7 interactions)
  requirements.txt                       # mcp-recorder>=0.4.0
  README.md                              # setup, verify, update instructions
.github/workflows/integration.yml        # CI: build → verify on every push/PR

Run locally

pip install -r integration/requirements.txt
npm run build

mcp-recorder verify \
  --cassette integration/cassettes/protocol_and_errors.json \
  --target-stdio "node build/index.js"

Update after intentional changes

mcp-recorder verify \
  --cassette integration/cassettes/protocol_and_errors.json \
  --target-stdio "node build/index.js" \
  --update

The cassette diff in the PR review shows exactly what changed in the protocol surface.

---

Note

Low Risk
Adds a new CI workflow and snapshot cassette that can fail PRs if the MCP protocol/tool schemas or error messages change unexpectedly, but it doesn’t affect production runtime behavior.

Overview
Adds automated snapshot-based integration tests that verify the MCP server’s public protocol surface on every push/PR to main.

CI now builds the server and runs mcp-recorder verify against a committed golden cassette (integration/cassettes/protocol_and_errors.json) that captures the initialize handshake, tools/list schemas, and deterministic API-key-missing error responses for tools/call on key tools. Includes supporting integration/scenarios.yml, Python requirements, and docs for recording/updating cassettes.

^{Written by Cursor Bugbot for commit c83b363. This will update automatically on new commits. Configure here.}