2026-10-30 · 技术笔记 · MCP
一百三十行 Python
写一个不用 Node 的 MCP 服务器
现成的 MCP 服务器大多以 npm 包分发,可运行环境里未必有 Node。 剥开协议看本质:客户端拉起一个子进程,一行一个 JSON-RPC 消息; 回答四类请求,它就是一个合格的服务器。
今天的任务是给桌面端加两个本地工具,其中一个要求正好落在环境的短板: 机器上没有 Node,也没打算为两个小功能装一套运行时。 于是干了一件听起来吓人、做起来平常的事——用系统自带的 Python, 从零写一个 MCP 服务器。
协议的本质:一行一条消息
MCP 的 stdio 传输没有魔法。客户端把服务器当普通子进程启动, 双方通过标准输入输出通信,每行一条 JSON-RPC 2.0 消息。 服务器读一行、解析、回答一行,循环往复。 没有握手包、没有帧头,连长度字段都没有——换行符就是消息边界。
整个生命周期里,真正需要处理的方法只有四类: 初始化、列出工具、调用工具、存活探测。 初始化时报告自己支持什么能力;列出工具时给出名字、说明和参数表; 调用时执行具体逻辑、把结果包成文本返回;未知方法礼貌地回一个错误码。 到这就齐了。
核心循环长这样
import json, sys
TOOLS = [{
"name": "hello",
"description": "打个招呼",
"inputSchema": {
"type": "object",
"properties": {"name": {"type": "string"}},
"required": ["name"],
},
}]
def reply(mid, result=None, error=None):
msg = {"jsonrpc": "2.0", "id": mid}
if error is not None:
msg["error"] = error
else:
msg["result"] = result
sys.stdout.write(json.dumps(msg, ensure_ascii=False) + "\n")
sys.stdout.flush()
for line in sys.stdin:
msg = json.loads(line)
method, mid = msg.get("method", ""), msg.get("id")
if method == "initialize":
reply(mid, {"protocolVersion": msg["params"]["protocolVersion"],
"capabilities": {"tools": {}},
"serverInfo": {"name": "demo", "version": "1.0.0"}})
elif method == "tools/list":
reply(mid, {"tools": TOOLS})
elif method == "tools/call":
args = msg["params"].get("arguments") or {}
reply(mid, {"content": [{"type": "text",
"text": "你好," + args.get("name", "朋友")}]})
elif method == "ping":
reply(mid, {})
这是最瘦的骨架,跑起来大约三十行;加上两个真实工具(一个查索引、一个发通知), 每个文件也就一百三十行上下。没有框架、没有依赖树, 拷一个文件到新机器,`python3 server.py` 就能用。
三个会让人排查半天的坑
第一个坑:stdout 是协议通道。用 `print` 打一句调试信息, 等于往 JSON 流里塞了一行垃圾,客户端当场解析失败。 调试输出一律走 stderr——它不影响协议,还能在终端里看见。
第二个坑:中文序列化。`json.dumps` 默认把非 ASCII 字符转成 `\uXXXX`, 虽然协议合法,但日志和排查时会难以阅读;关掉转义、每行写完立刻 flush, 这两件事缺一个,都会表现成“客户端卡住不动”。
第三个坑:超时与崩溃的区别。工具执行失败要返回带错误标记的结果, 而不是让进程退出——服务器一死,客户端整个会话都得重启。 反过来,本身耗时长的调用(比如冷启动时要先做一次向量化,三到八秒) 要把服务器内部的网络超时设宽到三十秒,否则客户端的耐心比工具快。
什么时候值得手写,什么时候不值得
手写适合两种情况:环境里没有合适的运行时; 或者你要的东西本身很小——三五十行的逻辑,不值得引入一个依赖包 和它的整棵依赖树。反过来说,需要复杂认证、多传输方式、 参数校验框架的服务器,直接用官方 SDK 更省心, 省下的时间不在写代码上,在“以后升级不出事”上。
今天这两个服务器都属于前一类:一个是对本地检索服务的薄封装, 一个是把既有通知脚本变成工具。逻辑本来就是几十行, 做成 MCP 之后,多出来的部分全是协议胶水,而这个胶水今天已经被证明可以薄到一页纸。
结论
协议的意义在于约定,不在于复杂度。知道“一行一条消息、 四类请求、stdout 只留给协议”这三件事之后, 任何能读写标准输入输出的语言都可以写 MCP 服务器, Python、Shell、甚至一个静态编译的小程序。 依赖越少,寿命越长——这句话在工具链上是真的。
本文依据 2026-10-30 手写 MCP 服务器的过程整理。骨架代码为示意版本, 实际服务器各自一百三十行左右,仅使用 Python 标准库。 文中不写具体路径、地址与内部标识。 回到笔记