AI 会写代码、能改文案，可一旦你让它"看看我本地这个项目为什么跑不起来"或者"把我桌面上那份表格的第二列汇总一下"，它立刻变哑巴——因为模型本身没有手，也没有眼睛，它只能看见你粘贴进对话框的那点文字。MCP（Model Context Protocol）就是给模型装手装眼的协议层：一套标准的、跨客户端的接口，让模型能够以受控的方式调用你本地的工具、读取你本地的数据。这篇东西记录的是我在本地把一整条 MCP 服务链从零搭起来的过程：从写第一个能跑的 Server，到把三四个 Server 串成一条真正干活的链路，再到中间遇到的那几个能把人卡一整天的坑。适合已经会写点 Python、想把 AI 接进自己工作流的人看，也适合只是好奇"MCP 到底是个啥"的读者，前面两节会把概念讲透，后面全是能直接抄的配置和代码。
1. MCP 要解决的从来不是"能不能调用"，而是"换个人还得重写一遍"
很多人第一次听到 MCP，第一反应是"这不就是 function calling 吗，我早就在用了"。这话对一半。函数调用是模型侧的能力，MCP 是工程侧的约定，两者压根不在一个层面上。我一开始也这么想，直到我把同一个查数据库的工具，在三个不同客户端里各写了一遍适配代码，才真正理解这个协议在省什么。
1.1 函数调用的隐性成本：每换一个客户端就重写一次胶水
自己手搓 function calling 的流程大概是这样的：定义一个 JSON Schema 描述工具入参，把这坨 schema 塞进每次请求的上下文，解析模型返回的 tool_call 字段，在本地执行函数，再把结果按特定格式回填给模型。这一套跑通不难，难的是它和宿主强绑定。
你在 A 客户端写的工具定义、调用分发、结果序列化逻辑，换到 B 客户端基本要重来一遍，因为两边对 tool_call 的字段命名、多轮会话的拼接方式、错误信息的表达习惯都不一样。三个工具还好，等你手上有十几个工具、四五个客户端，维护成本就失控了。MCP 做的事情很朴素：把"工具长什么样、怎么被发现、怎么被调用、结果怎么返回"这四个问题用一套 JSON-RPC 2.0 的消息格式定死，工具方只实现一次，客户端方只适配协议，两边解耦。
这里有个容易混淆的点：MCP 本身不负责让模型"决定"调用哪个工具，决策仍然是模型自己做的。MCP 负责的是工具的描述怎么送到模型眼前、调用怎么落到你本地的那段代码上。协议管的是管道，不是大脑。
1.2 Host、Client、Server 三个角色，落到本地长什么样
协议文档里那三个角色，用一台机器上的实际进程来对应会清楚很多：
| 角色 | 在本地是什么 | 干的活 |
|---|---|---|
| Host | 你正在用的那个 AI 客户端进程 | 管理连接、把工具清单喂给模型、执行模型给出的调用意图 |
| Client | Host 内部为每个 Server 起的一个连接器 | 维持一对一连接，负责 JSON-RPC 消息收发 |
| Server | 你自己写的那个脚本或服务 | 声明能力、实现具体函数、返回结果 |
一个 Host 可以同时挂多个 Client，每个 Client 连一个 Server。所以"服务链"这个词在 MCP 语境下不是一个 Server 内部调另一个 Server，而是 Host 同时握着好几条连接，模型在一次对话里可以先后用到不同 Server 提供的工具。这个理解很关键，后面第五节编排服务链的时候会反复用到。
我第一次搭的时候误解成 Server 要互相调用，于是硬把两个工具塞进同一个进程里，结果依赖冲突搞得一团糟。后来才反应过来：拆成两个独立 Server，让 Host 同时连上，桥接的事交给模型自己的推理，干净得多。
1.3 什么场景值得上 MCP，什么场景纯属给自己找事
MCP 不是万金油。判断标准其实就一条：这个能力是不是需要被复用在多个对话、多个客户端里。
如果只是临时查一次数据，直接粘贴或者写个一次性脚本更快。但如果这个能力你每天要用十几次，而且希望换客户端时不重写，那就值得封装成 Server。我自己的划分是：文件系统读写、内部知识库检索、定时任务查询这三类，全部做成常驻 Server；而一次性的数据清洗脚本，写个临时函数就完了，做成 Server 反而增加了启动开销和排查成本。
还有一类特别容易被忽略——涉及本机状态的操作，比如"看看当前哪些端口在监听""读一下本地的环境配置文件"。这类工具用传统方式几乎没法让模型碰，因为你要么手动贴输出，要么开个远程 shell 给它。MCP 的 stdio 传输天然适合这种场景：Server 就跑在本机，权限边界和你自己的终端一样，不用额外开放端口。
2. 开工前的环境盘点：传输方式选错，后面全是返工
动手写代码之前有两个决定必须先定下来，因为它们会贯穿整个工程结构：用什么传输方式，以及依赖怎么隔离。这两个决定一旦选反，后面改起来不是改几行代码的事，是要重搭架子。
2.1 stdio 和 HTTP 两种传输，边界比你想的清晰
MCP 支持多种传输，本地最常用的是两种。
stdio的意思是 Host 把你的 Server 当成子进程拉起来，双方通过标准输入输出走 JSON-RPC 消息。这种方式的优点是显而易见的：不需要监听端口，不需要鉴权，进程生命周期跟着 Host 走，Host 一关子进程自动退出，不会留一堆僵尸进程。缺点也明显：一个 Server 进程只服务一个 Host 连接，而且启动开销每次都要付。
HTTP 类传输（早期是 SSE，后来的方案更偏向流式 HTTP）则是 Server 独立跑在一个端口上，Host 通过 URL 连过去。适合需要被多个客户端共享、或者本身要访问网络资源的场景。代价是你得自己管进程、管端口、管访问控制。
我自己的选择标准很简单：
- 只给本机的一个客户端用，涉及本地文件、本地命令 →stdio
- 要被多个客户端连，或者 Server 本身要长时间跑着做后台任务 →HTTP
- 拿不准 →先 stdio，因为改造成本最低
新手最常犯的错是上来就搞 HTTP，觉得"服务"听起来更正式。结果调试的时候要同时盯 Server 日志、端口占用、客户端连接状态三个地方，出问题根本定位不到。stdio 模式下你至少可以手动跑一遍脚本，报错直接打在终端上。
2.2 用 uv 把依赖关进笼子，别污染全局环境
这个坑我踩得特别深。第一次搭的时候图省事，直接全局装依赖，结果那个 Server 依赖的一个库版本和我另一个项目冲突，两个都不能跑了。后来我就固定用隔离环境。
Python 侧我推荐 uv，启动快、锁文件干净。初始化流程大概是这样：
uv init mcp-demo cd mcp-demo uv add "mcp[cli]"mcp[cli]里那个 cli 附加包很关键，它带来一个mcp命令行工具，后面调试要用。装完之后项目里会有pyproject.toml和.venv，所有东西都在里面，不碰系统环境。
Node 侧的写法是：
mkdir mcp-demo-ts && cd mcp-demo-ts npm init -y npm install @modelcontextprotocol/sdk两端选哪个都行，但我建议工具实现语言和你日常最熟的语言保持一致。因为写 Server 这件事，调试时间远大于编码时间，用不熟的语言排查问题会多花好几倍功夫。
2.3 目录结构先定好，别等到三个 Server 互相 import
单个 Server 怎么写都行，但你要做的是"服务链"，那就得提前想清楚文件怎么放。我现在的习惯是这样：
mcp-workspace/ ├── servers/ │ ├── fs-tools/ # 文件相关工具 │ │ ├── pyproject.toml │ │ └── src/server.py │ ├── db-tools/ # 数据查询工具 │ │ ├── pyproject.toml │ │ └── src/server.py │ └── shell-tools/ # 命令执行工具 │ ├── pyproject.toml │ └── src/server.py ├── configs/ │ └── mcp.json # 客户端配置片段，集中管理 └── logs/ # 所有 Server 的日志落这里每个 Server 一个独立目录、独立虚拟环境、独立依赖。看着有点重，但换来的是：任何一个 Server 出问题不会连累其他，升级依赖也不会互相打架。configs/mcp.json单独放一份是为了方便在不同客户端之间拷来拷去，不用每次翻客户端自己的配置文件路径。
那个logs/目录是后来加的，理由第七节会细说——日志不落盘，排查基本靠猜。
3. 第一个 MCP Server：从能跑到能被模型正确调用，中间隔着一条鸿沟
代码层面的第一个 Server 十分钟就能写出来，真正花时间的是让它"被模型正确调用"。工具函数签名怎么写、文档字符串怎么写、返回什么格式，这些细节直接决定模型会不会用错工具、用错参数。我第一版写完之后，模型十次调用有六次传错参数类型，改了半天才发现问题出在注释上。
3.1 最小可运行骨架，先跑通再谈优雅
Python 侧现在最省事的写法是用官方 SDK 内置的 FastMCP 装饰器风格。骨架长这样：
from mcp.server.fastmcp import FastMCP mcp = FastMCP("demo-server") @mcp.tool() def add(a: int, b: int) -> int: """把两个整数相加并返回结果。""" return a + b if __name__ == "__main__": mcp.run()mcp.run()默认就是 stdio 传输，不用额外传参。这段代码跑起来之后，进程会安静地等标准输入上的 JSON-RPC 消息，终端上什么都不打印——这是正常的，第一跑的人往往会慌，以为卡住了。
装饰器做的事不止是注册函数。它会从函数签名里提取参数名和类型注解，生成 JSON Schema，再从文档字符串里抽描述，最后打包成工具声明。所以那几个类型注解不是装饰，是协议的一部分。
3.2 类型注解和文档字符串，决定了模型调用的准确率
这是整篇文章里我最想强调的一段。模型的工具选择完全依赖你提供的元信息，元信息模糊，调用就一定乱。
对比一下两版写法。第一版我是这么写的：
@mcp.tool() def query(sql): """查询数据""" ...结果模型经常传进来一个自然语言句子，或者干脆传个表名，因为它不知道参数要求是 SQL 语句。改成这样之后准确率立刻上去了：
@mcp.tool() def query_readonly(sql: str, limit: int = 100) -> str: """在只读副本上执行一条 SELECT 语句。 仅支持单条 SELECT，禁止任何写操作。 sql: 完整的 SQL 查询语句，不要传表名。 limit: 返回的最大行数，默认 100，上限 1000。 """ ...差别在哪？类型注解让 Schema 里有了type: string和type: integer，默认值让模型知道这个参数可省略，文档字符串里明确了参数语义和约束边界。模型读到的就是这些文本，它没有被隐藏的先验知识。
我总结出三条硬规则，一直在用：
- 参数名要自解释，
sql比q好，file_path比p好； - 文档字符串第一行写"这个工具干什么"，后面分行写每个参数的约束；
- 能加默认值就加，减少模型必须填的必填项数量，降低出错面。
还有一点，工具名尽量用动词开头，read_file、list_dir、search_docs这种。名词命名的工具，模型经常把它当成数据源而不是动作，调用意愿会下降。
3.3 不接客户端也能自测：先把协议层的问题挡在门外
很多人接上客户端之后发现没反应，就开始怀疑客户端配置，实际上问题在 Server 自身的逻辑。我现在的习惯是分两步验证。
第一步，纯函数级别测试。把工具函数当普通函数调用一遍：
if __name__ == "__main__": print(add(1, 2), file=__import__("sys").stderr) mcp.run()注意这里打到 stderr 而不是 stdout，原因下一节会讲，这是 stdio 模式最重要的红线。
第二步，用官方 CLI 起一个交互式调试环境：
uv run mcp dev src/server.py这个命令会拉起一个本地调试界面，能看到当前 Server 声明了哪些工具、每个工具的 Schema 长什么样，还能手动填参数发一次调用，看返回结果。这一步能挡掉八成的问题：Schema 生成错了、函数抛异常没被捕获、返回值不是可序列化类型，全在这暴露。
一个实战提醒：
mcp dev起来的进程和你实际在客户端里跑的是同一个脚本，但环境变量可能不一样。如果你的 Server 依赖某个路径配置，记得在两边都设好，别一边能跑一边跑不了。
4. 把 Server 接进 Host：配置文件写对只是及格线，连不上才是常态
配置这一步看起来最简单，实际是最劝退的环节。我第一次配的时候，改完配置文件重启客户端，工具列表里空空如也，没有任何报错，也没有任何提示。折腾了快两个小时才发现是解释器路径写错了。这节把配置文件的关键字段和排查链路讲清楚。
4.1 配置文件的四个关键字段，每个都有坑
主流客户端的 MCP 配置基本是同一个结构，一个 JSON 对象，里面一个mcpServers段，每个键是 Server 的名字，值描述怎么启动它：
{ "mcpServers": { "fs-tools": { "command": "uv", "args": [ "--directory", "/absolute/path/to/servers/fs-tools", "run", "python", "src/server.py" ], "env": { "WORKSPACE_ROOT": "/absolute/path/to/workspace" } } } }四个字段逐个说。
command必须是可执行文件，且要能被客户端进程找到。这里最大的坑是 GUI 客户端的 PATH 和你终端里的 PATH 不是一回事。你在终端里敲uv能用，不代表客户端能启动uv，因为 GUI 程序继承的环境变量往往更少。稳妥做法是写绝对路径，which uv拿到的结果直接填进去。
args里所有路径也都必须是绝对路径。相对路径的基准目录是客户端进程的工作目录，不是你的项目目录，结果就是找不到文件。
env是用来传配置的。不要把密钥或路径硬编码在脚本里，走环境变量，脚本里用os.environ.get()读。这样同一份代码在不同机器上不用改。
cwd这个字段不是所有客户端都支持，但如果支持一定要写。它决定子进程的启动目录，写了就能用相对路径引资源文件，省很多事。
4.2 连不上时的排查链路：从最外层往里剥
配置文件改完没反应，按这个顺序查，基本不会走冤枉路。
第一层，JSON 本身合法吗。少个逗号、多个逗号、用了单引号，这些低级错误实际占比很高。找个 JSON 校验器过一遍，十秒钟的事。
第二层，command 能不能被找到。在终端里复制配置里的 command 和 args，原样粘到命令行执行一遍。能起来说明命令没问题，起不来就是路径或者环境的锅。
第三层，手动跑脚本报什么错。绕过客户端，直接python src/server.py跑。如果这里就报 ModuleNotFoundError，说明依赖装在了别的环境里，客户端用的解释器和你的虚拟环境不是同一个。
第四层，客户端日志。大部分支持 MCP 的客户端会把子进程的 stderr 输出记录到某个日志文件里，路径一般在应用数据目录下。找不到就去翻客户端文档，这一步能省掉大量瞎猜。
第五层，权限和沙箱。少数客户端会对子进程做沙箱限制，禁止访问某些目录或者禁止网络。如果你的工具访问文件失败但手动跑正常，往这个方向想。
我实际遇到过最诡异的一次是：配置完全正确，手动跑也正常，客户端就是连不上。最后发现是我在那个 Server 的模块顶层写了一行print("loading...")，把协议消息流冲乱了。这就是下一个坑。
4.3 stdout 是协议通道，往里面打一个字符都是灾难
stdio 传输下，标准输出就是 JSON-RPC 的消息通道。你在代码里任何一个print()，都会变成一坨非 JSON 的垃圾插进消息流，客户端解析失败，轻则工具不显示，重则整个连接断掉，而且报错信息往往指向别处，极难定位。
这条红线衍生出几个具体规范：
- 所有调试输出走
sys.stderr，或者用logging配一个 StreamHandler 指向 stderr； - 第三方库的日志也要管住，有些库默认往 stdout 打日志，得在入口处重定向；
- 如果你的 Server 内部调用了会打印进度的库（比如某些下载库、进度条库），要么关掉它的输出，要么把整个 stdout 在进程启动时重定向掉。
我现在的做法是在 Server 入口最前面加一段：
import sys import logging logging.basicConfig( level=logging.INFO, stream=sys.stderr, format="%(asctime)s %(levelname)s %(name)s %(message)s", ) # 保险起见，把 stdout 换成一个指向 stderr 的包装 _original_stdout = sys.stdout sys.stdout = sys.stderr最后那两行看着粗暴，但确实救命。把sys.stdout换成sys.stderr之后，任何漏网的print()都会跑到 stderr 去，协议通道就干净了。代价是如果你有工具需要往 stdout 返回数据，得用_original_stdout，但 MCP 的返回值本来就不是靠 print 传的，所以基本没影响。
这个改动建议所有 stdio 模式的 Server 都加上。我见过太多人卡在这一步，日志里全是"invalid JSON"却怎么也找不到源头。
5. 服务链的真正含义：多个 Server 并行挂载，靠模型自己串联
单个 Server 跑通之后，很自然想的就是"怎么让它调用另一个 Server"。我一开始也是这个思路，试图在 Server A 里通过 HTTP 去调 Server B，绕了一大圈。后来想明白：MCP 的设计里，Server 之间不需要知道彼此存在，串联发生在 Host 层，由模型在对话中按需切换工具完成。
5.1 服务链怎么切分：按权限边界切，不按功能切
拆 Server 的时候最容易犯的错是按功能拆——文件一个、数据库一个、命令一个——这没错，但不够。更实用的切分维度是权限边界。
举个例子。同样是读文件，读项目源码和读系统配置文件的权限等级完全不同。如果放进同一个 Server，那这个 Server 的权限就是两者中更高的那个。拆成两个 Server，一个只开放工作目录，一个只读特定配置文件，模型能碰到的东西就被精确限制了。
我现在的切分原则是三条：
- 同源数据的工具放一起，因为它们共享连接和配置；
- 权限等级不同的分开，因为客户端可能会对某些 Server 单独做信任设置；
- 启动开销大的单独放，避免每次对话都拉起一堆重进程。
按这个原则，我的工作区最终是三个 Server：fs-tools负责工作目录内的文件读写和目录遍历，doc-tools负责本地文档库的检索，ops-tools负责只读的系统状态查询。三个之间没有任何代码依赖，但模型在一次会话里可以自由组合使用。
5.2 工具重名和描述冲突，是服务链最先撞上的墙
Host 同时挂三个 Server，每个 Server 都有自己的工具列表，模型看到的是合并后的一张大表。这时候问题就来了：如果两个 Server 都有个叫search的工具，模型很可能选错。
不同客户端的处理方式不太一样，有的会加 Server 名前缀区分，有的直接展示原名。不管哪种，你自己的描述要写清楚区别。我踩过一次：doc-tools里有个search_docs，fs-tools里有个grep_files，功能其实不一样（前者是语义检索，后者是正则匹配），但我文档字符串写得都很含糊，模型十次有七次用错了。
后来我把描述改成这样：
search_docs：按语义相似度在文档库中检索，适合"找和某个主题相关的段落"这类模糊查询，不支持正则。grep_files：按正则表达式在工作目录内逐行匹配文件内容，适合精确定位某个字符串出现的位置，不支持语义理解。
改完以后选错率明显下降。工具描述里明确写出"什么时候不该用我"，比只写"我能干什么"有效得多。
| 场景 | 该用哪个 | 为什么 |
|---|---|---|
| 想知道某个概念在文档里怎么讲的 | search_docs | 需要语义理解，关键词可能对不上 |
| 想知道某个函数名在哪些文件出现 | grep_files | 精确字符串，正则更可靠 |
| 想找相关内容但不确定用词 | search_docs | 语义检索容忍表述差异 |
| 想排除注释里的匹配 | grep_files | 正则可以加过滤条件 |
5.3 一次真实的多 Server 协作过程长什么样
说个我每天实际在跑的流程，能直观感受服务链的价值。
我写完一段代码，让模型做一次自检。它会先调用fs-tools.read_file把文件内容读进去，然后调用grep_files在这个文件里搜一遍可疑的模式（比如硬编码的路径、没有关闭的文件句柄），发现问题之后调用ops-tools.check_process看看这个项目的服务当前有没有在跑，判断改动是否需要重启。
这里面四个工具来自三个 Server，但它们之间没有任何直接调用关系。整个编排是模型根据每个工具的返回结果动态决定的：如果 grep 没发现问题，后面两步根本不会发生。这种"按结果决定下一步"的灵活性，是硬编码的脚本做不到的。
这也解释了一个常见困惑：为什么我在 Server 里实现不了"先查 A 再查 B"的固定流程。答案是不该在 Server 层做这件事。如果流程是固定的，那它就是一段脚本，不需要 MCP；MCP 的价值恰恰在于流程由模型动态决定。
6. 三个原语别只用 Tools：Resources 和 Prompts 能省掉大量重复调用
官方协议里给了三种能力：Tools、Resources、Prompts。绝大多数人（包括最开始的我）只用 Tools，因为另外两个看起来抽象。实际用下来，Resources 和 Prompts 在特定场景下能显著减少 token 消耗和调用轮次。
6.1 Resources：适合"看一眼就够"的数据，不适合"要算一下"的操作
Tools 的本质是动作，模型调用它、得到结果、再决定下一步。Resources 的本质是数据，它有一个稳定的 URI，客户端可以直接把它当附件挂进上下文，不需要经过一次工具调用。
区别在成本上。如果一个信息模型每次对话都需要知道，那做成 Tool 就是每轮都要调一次，多一次往返、多一份延迟；做成 Resource，客户端可以一次性读进来，模型直接就有。
适合做成 Resource 的典型场景：
- 项目的目录结构快照；
- 一份固定的配置说明；
- 当前环境的元信息（操作系统、Python 版本、装了哪些包）。
Python 侧写法很轻：
@mcp.resource("workspace://tree") def get_tree() -> str: """返回当前工作目录的两层目录树快照。""" ...URI 的 scheme 可以自己定，但要保持稳定和可读。我习惯用workspace://、config://这样的前缀区分数据来源。
有一点要清楚：Resource 的内容在客户端那边可能是被缓存或者按需读取的，不同客户端策略不一样。所以不要放会频繁变化的数据，比如实时进程列表，那种还是用 Tool 更合适。
6.2 Prompts：把反复手写的指令模板固化下来
Prompts 是我用得最少但收益最直接的。它做的事是暴露一组预置的提示词模板，客户端可以列出来让用户选，选中之后带参数展开成完整提示。
我自己用得最多的是一个"代码审查"模板，带一个文件路径参数，展开后是一段结构化的审查指令：先看什么、再看什么、输出什么格式。以前每次都要手打一遍，现在选一下就行。
@mcp.prompt() def review_code(file_path: str) -> str: """生成一段结构化的代码审查提示。""" return f"""请审查 {file_path}，按以下顺序输出： 1. 潜在的空指针或未处理异常 2. 资源未释放的地方 3. 命名与参数校验问题 每一条给出具体行号和修改建议。"""这类模板的价值不在于省那点打字时间，而在于保证每次审查的口径一致。团队里几个人共用同一套 Prompts，输出格式就统一了，后续处理起来方便很多。
6.3 权限收窄：本地 Server 最容易出事的地方
stdio 模式下 Server 的权限就是你当前用户的权限，这一点必须心里有数。模型不会主动干坏事，但它可能误解你的意图，然后顺手删掉一个不该删的目录。
我的做法是三道闸。
第一道，路径白名单。所有涉及文件路径的参数，先用os.path.realpath解析，再判断是否在允许的根目录下面。注意必须是realpath，因为符号链接可以绕过简单的字符串前缀判断。
from pathlib import Path ALLOWED_ROOT = Path("/Users/me/workspace").resolve() def safe_path(p: str) -> Path: target = Path(p).resolve() if not target.is_relative_to(ALLOWED_ROOT): raise ValueError(f"路径超出允许范围: {p}") return target第二道，写操作单独标记。读工具和写工具分开，写工具的描述里明确写"此操作会修改磁盘"，让模型在调用前有更明确的判断依据。有些客户端会对写操作弹确认，这也是个兜底。
第三道，命令执行工具默认禁用。我那个ops-tools里所有命令都是白名单里的固定几个（查进程、查端口、查磁盘），不接受任意命令字符串。一旦开放任意命令执行，前面两道闸等于没有。
这三道闸的成本很低，但能挡掉绝大部分误操作。尤其是路径白名单那十行代码，建议所有涉及文件读写的 Server 都加上，别嫌麻烦。
7. 看不见的地方最难调：日志、Inspector 和一张错误对照表
MCP 的调试体验说实话不算友好。Server 跑在子进程里，报错不一定能透到客户端，客户端日志又藏在各种角落。这节把我攒下来的调试手段集中说一下，能省不少时间。
7.1 日志落盘：出问题时的唯一线索
我现在的每个 Server 入口都会做这么一件事：把日志同时写到 stderr 和一个按日期滚动的文件里。stderr 是给客户端日志用的，文件是给自己看的。
import logging from logging.handlers import RotatingFileHandler import sys from pathlib import Path LOG_DIR = Path("./logs") LOG_DIR.mkdir(exist_ok=True) logger = logging.getLogger("mcp") logger.setLevel(logging.DEBUG) file_handler = RotatingFileHandler( LOG_DIR / "server.log", maxBytes=2_000_000, backupCount=3 ) file_handler.setFormatter( logging.Formatter("%(asctime)s %(levelname)s %(message)s") ) logger.addHandler(file_handler) logger.addHandler(logging.StreamHandler(sys.stderr))关键在于记录入参和返回值。工具调用失败的时候，光看"发生了异常"没有意义，你得知道当时传进来的是什么。我现在每个工具函数第一行都会记一条入参日志，出错的时候直接翻文件就行，不用重现。
代价是日志增长快，所以配了滚动。单个文件 2MB、保留 3 份，对个人使用足够了。
7.2 用 Inspector 把协议层的问题可视化
官方提供了一个调试工具，走 npm 分发，命令是npx加包名，包名里带着协议的全称。它做的事是模拟一个 Host，连上你的 Server，把声明的能力、Schema、调用结果全列出来。
我一般在两个时机用它：
- 接客户端之前，先确认 Server 声明的东西和预期一致；
- 客户端行为异常时，用它对比一下同样一次调用在 Inspector 里是否正常，以此判断问题在 Server 侧还是客户端侧。
这个对比特别有用。有一次模型总是传错参数类型，我用 Inspector 看了一遍 Schema，发现参数被声明成了string而不是integer——原因是我在函数签名里没写类型注解。这种问题在客户端侧完全看不出来，只能通过 Schema 发现。
7.3 常见症状对照表
下面这些是我实际遇到过、并且反复出现的，按症状查能快速定位：
| 症状 | 最可能的原因 | 处理方式 |
|---|---|---|
| 工具列表为空 | 配置的 command 找不到，或 JSON 不合法 | 复制 command 到终端手动执行验证 |
| 工具时有时无 | 启动脚本里有随机失败的初始化逻辑 | 检查模块顶层代码，把耗时初始化移到函数内 |
| 调用后无响应 | stdout 被非协议内容污染 | 重定向 stdout 到 stderr，排查所有 print |
| 报 JSON 解析错误 | 同上，或第三方库往 stdout 打日志 | 检查依赖库的日志配置 |
| 参数类型不对 | 函数签名缺类型注解 | 补全注解，用 Inspector 复核 Schema |
| 手动能跑客户端跑不了 | 两边解释器或工作目录不同 | 配置里改用绝对路径，显式指定 cwd |
| 中文乱码 | 输出编码不是 UTF-8 | 显式设置PYTHONIOENCODING=utf-8 |
这张表覆盖不了所有情况，但能挡掉我在过去几个月里遇到的大概八成问题。剩下的两成，基本都得靠日志加二分法排查——把一个工具禁用，看问题是否还在，逐步缩小范围。
最后分享一个小习惯：每加一个新工具，我都会先在 Inspector 里手动调三次，参数分别给正常值、边界值和明显错误的值。这三调能提前发现九成的参数校验问题，比等模型在真实对话里踩坑高效得多。模型不会告诉你"这个参数我不确定该怎么填"，它只会默默填一个错的，然后你在一堆返回结果里找异常。
这套东西我从零搭起来前后花了大概一周，其中真正写代码的时间不到两天，剩下全在踩配置和调试的坑。如果你现在也要动手，建议顺序反过来：先把一个最简单、只有一个工具、只读的 Server 完整跑通，从配置到调用全链路走一遍，尝到甜头之后再往里加复杂度。一次性把五六个工具全写进去再配，出问题的时候你面对的是一整个黑盒，排查成本是翻倍的。
