mini-mcp

MCP (Model Context Protocol), implemented from first principles in ~200 readable lines. A server, a client, and the JSON-RPC mechanics between them — the tool-calling core that every agent integration depends on, small enough to read in one sitting.

git clone https://github.com/harshadkhetpal/mini-mcp
cd mini-mcp
PYTHONPATH=src python3 -m minimcp.client

connected: mini-mcp-demo protocol 2025-06-18
tools discovered: calc.add, text.word_count, text.summarize_naive
calc.add(2, 40) -> 42
word_count -> 6

Why build this when SDKs exist

Frameworks hide the protocol, and hidden protocols produce engineers who can wire an integration but cannot debug one. Implementing the core teaches what the SDKs actually do: MCP is JSON-RPC 2.0 over a transport, plus three methods that matter — initialize (handshake and capabilities), tools/list (discovery with JSON-Schema descriptions), and tools/call (validated invocation). Once that is understood, every MCP SDK reads as a convenience wrapper, which is what it is.

What's implemented

Piece	Detail
Server	Tool registry via decorator, JSON-RPC dispatch, correct error codes (-32700 parse, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal)
Schema validation	Minimal JSON-Schema subset (type, required, properties), written not imported
Client	Spawns any stdio MCP server, handshakes, discovers, calls
Demo server	Three deterministic tools, so the loop runs offline

Scope is deliberate: resources, prompts, sampling and notifications are out. The tools subset is the part agents live on, and a complete small thing beats an incomplete big one.

Design decisions worth arguing with

Transport-agnostic server. handle_line maps one request string to one response string. The same server runs over stdio, a socket, or a unit test calling it directly — which is why the protocol tests need no subprocess and never flake.

Unknown tool arguments are rejected, not ignored. A tool receiving parameters it never declared is a bug on its way to production. Strictness here is what makes agent tool-calling debuggable.

Tool exceptions become protocol errors, not crashes. A buggy tool must not take down the server or the session; the client gets -32603 with the message, and the loop continues.

bool is not an integer. Python's bool subclasses int, so naive validators accept True where a count belongs. This one doesn't, and a test pins it.

Testing

PYTHONPATH=src python3 -m pytest tests -q

Covers the handshake, discovery, valid and invalid calls, every JSON-RPC error code, and one end-to-end test running the real client against the real server as a subprocess.

Licence

MIT