Skip to main content
Glama
Sign In
deenesjakoruzh
mini-mcp-demo

mini-mcp-demo

by harshadkhetpal
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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: toolbox-mcp

已实现的内容

组件

细节

服务器

通过装饰器实现工具注册、JSON-RPC 分发、正确的错误码（-32700 解析错误、-32600 无效请求、-32601 方法未找到、-32602 无效参数、-32603 内部错误）

Schema 验证

最小 JSON-Schema 子集（type、required、properties），自行编写而非导入

客户端

生成任何 stdio MCP 服务器，握手、发现、调用

演示服务器

三个确定性工具，因此循环可离线运行

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

值得讨论的设计决策

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

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

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

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

测试

PYTHONPATH=src python3 -m pytest tests -q

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

许可证

MIT

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Resources

Related MCP Connectors

Related MCP Servers

  • veriloop

    arvindcr4
    A
    license
    A
    quality
    D
    maintenance
    Exposes a verified tool registry (calculator, sandboxed file read, web fetch) over MCP stdio, enabling any MCP-capable client to reuse the same tools from the inspectable ReAct loop.
    3
    MIT

  • UVG Local MCP Server

    Anggelie
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables local text analysis, statistical calculations, and system information retrieval via the Model Context Protocol over stdio.
    -
  • faraztools-mcp

    faraztools-mcpofficial

    farazmazhar
    A
    license
    A
    quality
    C
    maintenance
    Enables AI clients to call small utility tools like echo and Markdown-to-PDF conversion, running locally over stdio.
    2
    MIT