Overview — MCP Server Conformance Test Kit

A black-box conformance suite for remote MCP servers. Point it at your

Streamable-HTTP /mcp endpoint and it verifies the server behaves per the Model

Context Protocol: initialize handshake, tools/list shape, tools/call

success + error contracts, JSON-RPC framing, and tool-schema validity. Run it in

CI so a refactor can't silently break your agent integration.

Why you need it

MCP clients (Claude, Cursor, Cline, agent frameworks) are strict about the

protocol. A server that returns a slightly wrong shape "works on my machine" and

then fails in a real client. This kit catches those before your users' agents do.

What it checks

• Transport: a plain GET returns something sane; POST speaks JSON-RPC 2.0.
• initialize: returns protocolVersion, capabilities, serverInfo.
• tools/list: every tool has a name, description, and a valid JSON-schema

inputSchema (object type, properties present).

• tools/call: a read-only tool returns content[]; an invalid-args call returns

an error result (not a crash / 500).

• Annotations: side-effecting tools are not marked readOnlyHint: true

(honesty check — clients gate on this).

• Error handling: unknown method / malformed body yield JSON-RPC errors, not

HTML stack traces.

What's inside

• src/client.ts — a tiny MCP-over-HTTP client (SSE-aware JSON parsing).
• src/conformance.ts — the suite; returns a structured pass/fail report.
• src/run.ts — CLI: MCP_URL=https://you/mcp node run.js → prints report, exits

non-zero on failure (CI-ready).

• test/conformance.test.ts — runs the suite against a built-in mock MCP server so

the kit itself is tested.

Usage

npm install
MCP_URL=https://your-server.example/mcp npm run check   # gates on conformance

Requirements

Node 18+ (global fetch). No external deps.