自己写一个 MCP Server：从一个能跑的工具，到别人敢装的服务

你大概已经这样用过 AI 编程工具：让它读代码、改文件、跑命令。也大概装过别人写的 MCP 服务器——数据库的、浏览器的、任务系统的，配置一贴，工具就出现在对话里。

但总有一类事情，装不到。比如公司内网那份只有跳板机能访问的运维手册，比如你自己攒了三年的笔记目录，比如那套没人会做成产品的内部工单接口。这些事你现在的做法多半是：把内容复制粘贴进对话，或者写个脚本然后每次手动运行、再把输出贴回去。

复制粘贴的问题不是麻烦，是过期。你贴进去的是那一刻的快照，模型下一轮就不知道数据变了。脚本的问题也不是麻烦，是模型不会主动用它——它不知道那个脚本存在，不知道该传什么参数，更不知道什么时候该调用。

MCP（Model Context Protocol）要解决的就是这一段：把「一件只有你能做的事」变成「任何支持 MCP 的 AI 应用都能发现、能调用、能拿到实时结果的能力」。写一个 MCP Server，本质上就是把你的函数交给模型，并且用一份契约告诉它：这个工具叫什么、什么时候该用、要传什么、会返回什么、有没有副作用。

这份教程要带你走完的，不是「五分钟跑通 hello world」。跑通很容易，官方最小示例只有十几行。真正难的是后面那一大段：为什么模型看得见你的工具却不调用它；参数传错了该返回什么模型才会自己改；数据库连接该在哪里建；它没反应的时候你从哪里看；怎么从本地进程变成能给同事用的远程服务；以及最后那个问题——别人凭什么敢把你的 server 装进他的开发环境。

读完你会有一个真正做完的产物：一个笔记库服务。它能搜索、能读取、能追加，有输入校验、有错误设计、有状态管理、有安全边界，能接进 Claude Code 和 Codex CLI，能部署成远程服务，能发给别人。这十二章就是把它一步步做出来的过程。

先说清楚三件事，它们会决定你后面少走多少弯路。

第一，MCP 在 2026 年 7 月 28 日发布的规范版本是一次破坏性重构。它移除了沿用一年多的 initialize 握手和 HTTP 会话，改成了无状态模型。你在网上搜到的绝大多数中文文章讲的是旧形态。

第二，官方 Python SDK 已经进入 2.x。最著名的那个类 FastMCP 被改名成了 MCPServer，旧的 import 语句现在会直接抛异常。这意味着你复制任何一篇 2026 年年中之前的教程代码，大概率跑不起来。

第三，本教程所有代码都在 mcp 2.1.1 上实际跑过，文中出现的每一段 JSON 往返都是真实抓下来的输出。但版本还会变——所有版本号、命令语法、配置字段，动手前请用官方文档核对一遍。教程教的是判断方法，不是可以永远照抄的常量。

技术栈：Python 3.12，依赖与命令统一用 uv。