mini-mcp

MCP（模型上下文协议），从第一性原理出发，用约 200 行可读代码实现。 一个服务器、一个客户端，以及它们之间的 JSON-RPC 机制——这是每个智能体集成都依赖的工具调用核心，小到可以一口气读完。

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

既然已有 SDK，为什么还要构建这个

框架隐藏了协议，而隐藏的协议会培养出能搭建集成却无法调试的工程师。实现核心能让你学到 SDK 实际在做什么：MCP 是运行在传输层之上的 JSON-RPC 2.0，外加三个关键方法——initialize（握手与能力协商）、tools/list（通过 JSON-Schema 描述进行发现）和 tools/call（经过验证的调用）。一旦理解了这一点，每个 MCP SDK 读起来都只是一个便利封装，而它正是如此。

Related MCP server: mcp-anvil-lite

已实现的内容

范围是有意为之：资源、提示、采样和通知都不在范围内。工具子集是智能体赖以生存的部分，一个完整的小东西胜过不完整的大东西。

值得讨论的设计决策

传输无关的服务器。 handle_line 将一条请求字符串映射为一条响应字符串。同一个服务器可以通过 stdio、套接字或直接调用它的单元测试运行——这正是协议测试不需要子进程、也从不失败的原因。

未知工具参数会被拒绝，而不是被忽略。 一个接收它从未声明参数的参数的工具，是即将进入生产环境的 bug。这里的严格性正是让智能体工具调用可调试的原因。

工具异常会变成协议错误，而不是崩溃。 一个有 bug 的工具绝不能拖垮服务器或会话；客户端会收到带有消息的 -32603，循环继续。

bool 不是 integer。 Python 的 bool 是 int 的子类，因此天真的验证器会在需要计数的地方接受 True。这个不会，并且有测试固定了这一点。

测试

PYTHONPATH=src python3 -m pytest tests -q

覆盖握手、发现、有效和无效调用、每个 JSON-RPC 错误码，以及一个端到端测试，该测试以子进程方式运行真实客户端与真实服务器。

许可证

MIT