MCP Tool Server

A Model Context Protocol (MCP) server implemented from scratch over stdio using JSON-RPC 2.0 — plus a tiny client to drive it. No SDK, no dependencies: ~350 lines that show exactly how MCP handshakes and tool calls work on the wire.

Why MCP

MCP is the emerging standard for connecting LLM agents to external tools and data. This repo demonstrates the protocol mechanics — initialize, notifications/initialized, tools/list, tools/call, ping — so an agent (Claude, Copilot, custom) can discover and invoke tools over a pipe.

Related MCP server: MCP Boilerplate

Architecture

  MCP client  ──JSON-RPC over stdio──▶  mcp_server
  (client.py)      newline-delimited      ├── protocol.py  (errors, envelopes)
                   {jsonrpc,id,method}    ├── server.py    (dispatch + stdio loop)
                                          └── tools.py     (echo, add, sqrt, now_utc)

Quickstart

# run the demo client against a live server subprocess
PYTHONPATH=src python3 client.py

# run the server directly (speak JSON-RPC on stdin)
PYTHONPATH=src python3 -m mcp_server

# tests (in-process dispatch + a real spawned-subprocess handshake)
python3 tests/test_mcp_server.py

Protocol coverage

Malformed JSON → -32700 parse error; unknown method → -32601; bad params → -32602. Notifications never get a reply, as the spec requires.

Design notes

• Handler errors never kill the server — they're converted to JSON-RPC errors or in-band tool results, so one bad call can't take the transport down.

• Injectable streams (serve(lines=..., stdout=...)) make the stdio loop unit-testable without spawning processes; a separate test does the real spawn.

• Tool schemas are JSON Schema, matching MCP's inputSchema contract.

Skills demonstrated

Model Context Protocol (MCP) · JSON-RPC 2.0 · stdio transport · tool schemas · protocol error handling · subprocess integration testing · Python packaging

License

MIT