1. 从聊天机器人到工具服务器这个项目到底在做什么1.1 一个聊天窗口怎么就成了工具服务器最开始我做这个项目的动机特别朴素我手上有一堆零散的小工具比如查天气的脚本、读本地文件的函数、查数据库的封装、跑单元测试的命令行平时用的时候得一个个手动去调烦得很。后来我想既然聊天机器人已经能理解自然语言了那为什么不干脆让它变成一个“调度中心”——我说一句话它自己去判断该调哪个工具、传什么参数、把结果拿回来再组织成人话告诉我。这个思路听起来简单但真正落地的时候核心问题就冒出来了聊天机器人本身只会“说话”它不会“做事”。你要让它做事就得给它一套标准化的接口让它知道“有哪些工具可用”“每个工具需要什么参数”“调用之后返回什么”。这套接口就是现在大家常说的tool server工具服务器概念而在 Claude 生态里它有一个更具体的名字叫MCP serverModel Context Protocol Server。所以这个项目的本质是把一个只会闲聊的聊天机器人改造成一个能挂载外部工具、能执行真实操作、能把结果回传给模型的“工具调度中枢”。它解决的不是“聊天”问题而是“聊天之后怎么干活”的问题。适合谁来参考如果你已经用过 Claude、写过一点 Python 或 Node.js、手里有一堆想自动化的零碎操作那这个内容就是给你准备的。1.2 为什么不是“写个插件”那么简单很多人第一反应是不就是给机器人加个插件吗我一开始也这么想但实际做下来发现插件模式和 tool server 模式有本质区别。插件模式通常是“我预先知道用户会点什么按钮我提前把逻辑写死”。但 tool server 模式是“模型自己决定要不要调工具、调哪个、传什么参数”。这意味着工具的描述必须足够清晰参数 schema 必须足够严谨返回结果必须足够结构化否则模型要么不调要么调错要么拿到结果不知道怎么用。另一个关键点是解耦。工具服务器是独立进程聊天机器人是另一个进程两者通过标准协议通信。这样做的好处是工具可以随时增删改不用重启聊天机器人工具可以用任何语言写只要遵守协议工具服务器可以部署在本地也可以部署在远端。这种架构上的灵活性是插件模式给不了的。1.3 整体架构长什么样我用一张文字版的架构图来说明避免画图工具带来的排版问题最上层用户输入自然语言比如“帮我看看今天北京的天气然后读一下我桌面上那个 config.json 的前十行”。中间层聊天机器人Claude 客户端接收输入结合当前挂载的工具列表判断需要调用哪些工具、按什么顺序调用。协议层通过 MCP 协议客户端把工具调用请求发给 tool server。工具层tool server 收到请求执行对应的函数查天气 API、读文件把结果按协议格式返回。回传层客户端拿到结果再交给模型组织成自然语言回复给用户。整个链路里最容易被低估的是协议层。很多人以为随便定个 JSON 格式就行但实际做下来你会发现参数类型、错误码、超时处理、并发调用、结果截断这些细节如果一开始没设计好后面会反复返工。2. 核心细节拆解工具服务器到底怎么写2.1 工具描述模型能不能调对全看这一段工具描述是整个项目里最关键的“人机接口”。模型看不到你的代码它只能看到你提供的工具名称、描述、参数 schema。如果描述写得含糊模型就会乱调。我踩过的坑是这样的我写了一个工具叫read_file描述只写了“读取文件”。结果模型经常把目录路径传进来然后报错。后来我把描述改成“读取指定文件的文本内容参数必须是完整文件路径不能是目录”并且把参数 schema 里的path字段加上description: 完整文件路径例如 /home/user/config.json调用准确率立刻上来了。这里有个经验工具描述要写成“给一个从没看过你代码的人看他能不能一次调对”。如果连人都要猜模型更会猜错。参数 schema 我建议用 JSON Schema 来写字段类型、是否必填、默认值、枚举范围都写清楚。比如{ name: get_weather, description: 查询指定城市的当前天气返回温度和天气状况, inputSchema: { type: object, properties: { city: { type: string, description: 城市名称例如 北京、上海 }, unit: { type: string, enum: [celsius, fahrenheit], default: celsius, description: 温度单位 } }, required: [city] } }注意required字段一定要写。我见过有人漏写结果模型传了个空对象进来工具直接崩了。2.2 通信方式stdio 还是 HTTPMCP server 支持多种通信方式最常见的是stdio标准输入输出和HTTP/SSE。选哪种取决于你的使用场景。stdio 的优点是简单、无需网络配置、进程生命周期由客户端管理。缺点是只能本地用客户端和服务器必须在一台机器上。我本地开发阶段全部用 stdio调试起来最省心。HTTP 的优点是支持远程调用、可以多客户端共享。缺点是要处理端口、鉴权、超时、重连。如果你要把工具服务器部署到另一台机器上给团队共用那就得用 HTTP。我个人的选择是本地工具用 stdio团队共享工具用 HTTP。不要一上来就搞 HTTP除非你确实有远程需求否则光是调试网络问题就能耗掉你半天。2.3 工具服务器的生命周期管理stdio 模式下工具服务器是客户端启动时拉起的子进程。这意味着服务器启动要快不能有太重的初始化逻辑。服务器要能处理客户端突然断开的情况不能变成僵尸进程。服务器崩溃后客户端要能感知并给出明确错误而不是静默失败。我遇到过一次服务器启动时去连数据库结果数据库没起来服务器卡在那里客户端等了 30 秒超时报了个很模糊的错。后来我把数据库连接改成懒加载——第一次调用工具时才连启动阶段只做参数校验。这样启动时间从 3 秒降到 200 毫秒体验好很多。2.4 错误处理别让一个工具崩掉整个会话工具执行失败是常态文件不存在、API 限流、参数格式错、网络超时。关键是要把错误结构化地返回给模型而不是直接抛异常。我的做法是统一返回格式{ success: false, error_type: FILE_NOT_FOUND, message: 文件 /home/user/config.json 不存在, suggestion: 请检查路径是否正确或先列出目录内容 }这样模型拿到之后可以自己决定是重试、换参数还是告诉用户“文件没找到你要不要先看看目录里有什么”。如果你直接抛异常客户端可能直接中断整个对话用户体验很差。实操心得错误信息里带上suggestion字段模型的自愈能力会明显提升。我实测下来加了 suggestion 之后模型自动重试成功的比例大概从 40% 提到了 70%。3. 实操过程从零搭一个可用的工具服务器3.1 环境准备与依赖安装我以 Python 为例因为生态最成熟调试也方便。Node.js 也可以逻辑类似。首先确认 Python 版本建议 3.10 以上因为要用到一些新的类型注解特性python3 --version然后建一个独立虚拟环境避免污染全局python3 -m venv mcp-env source mcp-env/bin/activate安装 MCP 官方 SDKpip install mcp如果你要用 HTTP 模式再加一个pip install starlette uvicorn注意不要用系统自带的 Python 直接装很多系统 Python 是 3.8 甚至更早SDK 装不上或者行为不一致。我在这上面浪费过一个下午。3.2 写第一个工具从“读文件”开始先写一个最简单的工具服务器只提供一个read_file工具。完整代码如下import asyncio from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent app Server(my-tool-server) app.list_tools() async def list_tools(): return [ Tool( nameread_file, description读取指定文件的文本内容参数必须是完整文件路径, inputSchema{ type: object, properties: { path: { type: string, description: 完整文件路径例如 /home/user/config.json }, max_lines: { type: integer, default: 100, description: 最多读取的行数 } }, required: [path] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name read_file: path arguments[path] max_lines arguments.get(max_lines, 100) try: with open(path, r, encodingutf-8) as f: lines f.readlines()[:max_lines] return [TextContent(typetext, text.join(lines))] except FileNotFoundError: return [TextContent( typetext, textf错误文件 {path} 不存在。建议先列出目录内容确认路径。 )] except Exception as e: return [TextContent( typetext, textf错误{str(e)} )] async def main(): async with stdio_server() as (read, write): await app.run(read, write, app.create_initialization_options()) if __name__ __main__: asyncio.run(main())这段代码有几个细节值得说list_tools返回的是工具清单模型每次对话都会拿到这份清单。call_tool是实际执行入口根据name分发到不同逻辑。错误没有抛异常而是包装成TextContent返回这样模型能看到错误内容。max_lines有默认值模型不传也能跑。3.3 把工具服务器挂到 Claude 客户端写完之后要在 Claude 客户端里配置。以 Claude Desktop 为例配置文件通常在macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json配置内容如下{ mcpServers: { my-tool-server: { command: /path/to/mcp-env/bin/python, args: [/path/to/server.py] } } }这里有个坑command一定要写虚拟环境里的 Python 绝对路径不要写python3。因为客户端启动子进程时环境变量可能和你终端里不一样写python3很可能找不到或者找到系统 Python导致依赖缺失。配置完重启客户端如果一切正常你会在工具列表里看到read_file。然后你就可以在对话里说“帮我读一下 /tmp/test.txt 的前 20 行”模型会自动调用这个工具。3.4 加一个需要外部 API 的工具光读文件不够我再加一个查天气的工具演示怎么处理外部 API 调用和超时。import httpx app.call_tool() async def call_tool(name: str, arguments: dict): if name get_weather: city arguments[city] unit arguments.get(unit, celsius) try: async with httpx.AsyncClient(timeout5.0) as client: resp await client.get( https://api.example.com/weather, params{city: city, unit: unit} ) resp.raise_for_status() data resp.json() return [TextContent( typetext, textf{city} 当前温度 {data[temp]} 度天气 {data[condition]} )] except httpx.TimeoutException: return [TextContent( typetext, textf错误查询 {city} 天气超时请稍后重试。 )] except Exception as e: return [TextContent( typetext, textf错误{str(e)} )]超时时间我设了 5 秒。为什么是 5 秒因为模型调用工具时用户是在等回复的。如果工具卡 30 秒用户早就以为程序死了。5 秒是个平衡点大部分正常请求能返回异常情况也能快速失败。实操心得外部 API 调用一定要设超时而且要比你直觉的更短。我一开始设 30 秒结果遇到 API 挂掉的时候整个对话卡住体验极差。改成 5 秒后失败快、重试也快。3.5 多工具协同让模型自己编排工具服务器真正的威力是多个工具可以协同。比如用户说“读一下我的配置文件然后根据里面的城市查天气”。模型会先调read_file拿到配置内容解析出城市名再调get_weather。整个过程不需要你写编排逻辑模型自己会做。但这里有个前提工具返回的结果要足够干净。如果你read_file返回一大堆无关内容模型可能提取不出城市名。我的做法是对于配置文件读取额外提供一个read_config_value工具直接返回指定 key 的值而不是让模型去解析整个文件。app.list_tools() async def list_tools(): return [ Tool( nameread_config_value, description读取 JSON 配置文件中指定 key 的值, inputSchema{ type: object, properties: { path: {type: string, description: 配置文件路径}, key: {type: string, description: 要读取的 key 名称} }, required: [path, key] } ) ]这样模型调一次就能拿到城市名不用自己解析 JSON准确率和速度都上去了。4. 常见问题与排查技巧实录4.1 工具不显示、不调用、调用报错这是最高频的三类问题我整理成一张速查表现象可能原因排查方法客户端看不到工具配置文件路径错、JSON 格式错检查配置文件语法重启客户端工具列表有但模型不调工具描述太模糊把描述改具体加参数说明调用后报参数错误schema 类型不匹配检查 required 和 type 定义调用后无响应服务器启动慢或卡死看客户端日志检查初始化逻辑调用后返回乱码编码问题统一用 UTF-8读文件指定 encoding我遇到最多的是“工具列表有但模型不调”。原因几乎都是描述写得太泛。比如我写“处理数据”模型根本不知道什么时候该用。改成“读取 CSV 文件并返回前 N 行数据”调用率立刻上来了。4.2 日志怎么看问题怎么定位stdio 模式下工具服务器的标准输出会被客户端接管你直接 print 是看不到的。正确做法是写到文件import logging logging.basicConfig( filename/tmp/mcp-server.log, levellogging.DEBUG, format%(asctime)s %(levelname)s %(message)s )然后在关键位置打日志logging.debug(f收到调用: {name}, 参数: {arguments}) logging.debug(f返回结果: {result})排查问题时先看日志里有没有收到调用。如果没收到说明是客户端配置问题如果收到了但报错说明是工具逻辑问题。这个二分法能帮你快速缩小范围。4.3 性能与稳定性几个容易忽略的点第一工具服务器不要做重初始化。每次客户端启动都会拉起服务器如果你在启动时加载大模型或者连数据库启动时间会很长。改成懒加载。第二返回结果要截断。如果工具返回几万行文本模型上下文会被撑爆。我一般限制返回 4000 字符以内超出部分截断并提示“结果过长已截断”。第三并发调用要小心。模型有时会同时调多个工具。如果你的工具服务器是单线程的可能会阻塞。用 asyncio 的话天然支持并发但要注意共享资源的锁。第四版本兼容。MCP 协议还在演进SDK 版本不同行为可能有差异。建议锁定版本升级前先看 changelog。踩坑记录我有一次升级 SDK 后call_tool的返回格式要求变了从返回字符串变成必须返回TextContent列表。没看 changelog结果所有工具都报错。后来养成习惯升级前先跑一遍回归测试。4.4 安全边界工具服务器能做什么不能做什么工具服务器本质上是在给模型“授权”。你挂什么工具模型就能做什么。所以有几条红线不要挂载能执行任意命令的工具除非你做了严格的参数白名单。不要挂载能删除文件、修改系统配置的工具除非有二次确认机制。不要挂载能访问敏感数据的工具除非你确认调用来源可信。我的做法是所有“写操作”工具都加一个dry_run参数默认true只返回“将会做什么”不实际执行。用户明确说“执行”时才传false。这样即使模型误判也不会造成实际破坏。5. 工具服务器的扩展玩法与个人体会5.1 把常用操作都封装成工具项目跑通之后我开始把日常重复操作一个个封装进去查 Git 状态、跑单元测试、查数据库、发 HTTP 请求、格式化 JSON、计算表达式。现在我的聊天窗口基本成了一个“自然语言终端”我说“看看当前分支有没有未提交的改动”它就调git_status工具返回结果。这种体验和传统命令行最大的区别是我不需要记住命令和参数。我只需要描述意图模型负责翻译成工具调用。对于不常用的操作这个优势特别明显。5.2 工具粒度的取舍工具不是越细越好也不是越粗越好。太细模型要调很多次慢且容易出错太粗参数复杂模型传不对。我的经验是一个工具对应一个明确的动作参数不超过 5 个。比如read_file是一个动作write_file是另一个动作不要合并成file_operation然后靠一个mode参数区分。模型对枚举值的理解不如对工具名的理解准确。5.3 后续可以怎么扩展如果你已经跑通了基础版本可以考虑这几个方向加缓存层对频繁调用的只读工具缓存结果减少重复计算。加权限层不同用户挂载不同工具集。加审计日志记录每次工具调用的输入输出方便回溯。把工具服务器容器化一键部署到任意环境。我个人在实际操作中的体会是这个项目最大的价值不在于技术多复杂而在于它改变了我和机器协作的方式。以前是我适应工具现在是我描述意图工具来适应我。这个转变一旦体验过就回不去了。最后再分享一个小技巧工具描述里可以加一些“示例调用”比如在 description 里写“例如get_weather(city北京)”模型看到示例后参数格式的准确率会更高。这个细节很小但实测有效。
从聊天机器人到工具服务器：MCP协议实战指南
1. 从聊天机器人到工具服务器这个项目到底在做什么1.1 一个聊天窗口怎么就成了工具服务器最开始我做这个项目的动机特别朴素我手上有一堆零散的小工具比如查天气的脚本、读本地文件的函数、查数据库的封装、跑单元测试的命令行平时用的时候得一个个手动去调烦得很。后来我想既然聊天机器人已经能理解自然语言了那为什么不干脆让它变成一个“调度中心”——我说一句话它自己去判断该调哪个工具、传什么参数、把结果拿回来再组织成人话告诉我。这个思路听起来简单但真正落地的时候核心问题就冒出来了聊天机器人本身只会“说话”它不会“做事”。你要让它做事就得给它一套标准化的接口让它知道“有哪些工具可用”“每个工具需要什么参数”“调用之后返回什么”。这套接口就是现在大家常说的tool server工具服务器概念而在 Claude 生态里它有一个更具体的名字叫MCP serverModel Context Protocol Server。所以这个项目的本质是把一个只会闲聊的聊天机器人改造成一个能挂载外部工具、能执行真实操作、能把结果回传给模型的“工具调度中枢”。它解决的不是“聊天”问题而是“聊天之后怎么干活”的问题。适合谁来参考如果你已经用过 Claude、写过一点 Python 或 Node.js、手里有一堆想自动化的零碎操作那这个内容就是给你准备的。1.2 为什么不是“写个插件”那么简单很多人第一反应是不就是给机器人加个插件吗我一开始也这么想但实际做下来发现插件模式和 tool server 模式有本质区别。插件模式通常是“我预先知道用户会点什么按钮我提前把逻辑写死”。但 tool server 模式是“模型自己决定要不要调工具、调哪个、传什么参数”。这意味着工具的描述必须足够清晰参数 schema 必须足够严谨返回结果必须足够结构化否则模型要么不调要么调错要么拿到结果不知道怎么用。另一个关键点是解耦。工具服务器是独立进程聊天机器人是另一个进程两者通过标准协议通信。这样做的好处是工具可以随时增删改不用重启聊天机器人工具可以用任何语言写只要遵守协议工具服务器可以部署在本地也可以部署在远端。这种架构上的灵活性是插件模式给不了的。1.3 整体架构长什么样我用一张文字版的架构图来说明避免画图工具带来的排版问题最上层用户输入自然语言比如“帮我看看今天北京的天气然后读一下我桌面上那个 config.json 的前十行”。中间层聊天机器人Claude 客户端接收输入结合当前挂载的工具列表判断需要调用哪些工具、按什么顺序调用。协议层通过 MCP 协议客户端把工具调用请求发给 tool server。工具层tool server 收到请求执行对应的函数查天气 API、读文件把结果按协议格式返回。回传层客户端拿到结果再交给模型组织成自然语言回复给用户。整个链路里最容易被低估的是协议层。很多人以为随便定个 JSON 格式就行但实际做下来你会发现参数类型、错误码、超时处理、并发调用、结果截断这些细节如果一开始没设计好后面会反复返工。2. 核心细节拆解工具服务器到底怎么写2.1 工具描述模型能不能调对全看这一段工具描述是整个项目里最关键的“人机接口”。模型看不到你的代码它只能看到你提供的工具名称、描述、参数 schema。如果描述写得含糊模型就会乱调。我踩过的坑是这样的我写了一个工具叫read_file描述只写了“读取文件”。结果模型经常把目录路径传进来然后报错。后来我把描述改成“读取指定文件的文本内容参数必须是完整文件路径不能是目录”并且把参数 schema 里的path字段加上description: 完整文件路径例如 /home/user/config.json调用准确率立刻上来了。这里有个经验工具描述要写成“给一个从没看过你代码的人看他能不能一次调对”。如果连人都要猜模型更会猜错。参数 schema 我建议用 JSON Schema 来写字段类型、是否必填、默认值、枚举范围都写清楚。比如{ name: get_weather, description: 查询指定城市的当前天气返回温度和天气状况, inputSchema: { type: object, properties: { city: { type: string, description: 城市名称例如 北京、上海 }, unit: { type: string, enum: [celsius, fahrenheit], default: celsius, description: 温度单位 } }, required: [city] } }注意required字段一定要写。我见过有人漏写结果模型传了个空对象进来工具直接崩了。2.2 通信方式stdio 还是 HTTPMCP server 支持多种通信方式最常见的是stdio标准输入输出和HTTP/SSE。选哪种取决于你的使用场景。stdio 的优点是简单、无需网络配置、进程生命周期由客户端管理。缺点是只能本地用客户端和服务器必须在一台机器上。我本地开发阶段全部用 stdio调试起来最省心。HTTP 的优点是支持远程调用、可以多客户端共享。缺点是要处理端口、鉴权、超时、重连。如果你要把工具服务器部署到另一台机器上给团队共用那就得用 HTTP。我个人的选择是本地工具用 stdio团队共享工具用 HTTP。不要一上来就搞 HTTP除非你确实有远程需求否则光是调试网络问题就能耗掉你半天。2.3 工具服务器的生命周期管理stdio 模式下工具服务器是客户端启动时拉起的子进程。这意味着服务器启动要快不能有太重的初始化逻辑。服务器要能处理客户端突然断开的情况不能变成僵尸进程。服务器崩溃后客户端要能感知并给出明确错误而不是静默失败。我遇到过一次服务器启动时去连数据库结果数据库没起来服务器卡在那里客户端等了 30 秒超时报了个很模糊的错。后来我把数据库连接改成懒加载——第一次调用工具时才连启动阶段只做参数校验。这样启动时间从 3 秒降到 200 毫秒体验好很多。2.4 错误处理别让一个工具崩掉整个会话工具执行失败是常态文件不存在、API 限流、参数格式错、网络超时。关键是要把错误结构化地返回给模型而不是直接抛异常。我的做法是统一返回格式{ success: false, error_type: FILE_NOT_FOUND, message: 文件 /home/user/config.json 不存在, suggestion: 请检查路径是否正确或先列出目录内容 }这样模型拿到之后可以自己决定是重试、换参数还是告诉用户“文件没找到你要不要先看看目录里有什么”。如果你直接抛异常客户端可能直接中断整个对话用户体验很差。实操心得错误信息里带上suggestion字段模型的自愈能力会明显提升。我实测下来加了 suggestion 之后模型自动重试成功的比例大概从 40% 提到了 70%。3. 实操过程从零搭一个可用的工具服务器3.1 环境准备与依赖安装我以 Python 为例因为生态最成熟调试也方便。Node.js 也可以逻辑类似。首先确认 Python 版本建议 3.10 以上因为要用到一些新的类型注解特性python3 --version然后建一个独立虚拟环境避免污染全局python3 -m venv mcp-env source mcp-env/bin/activate安装 MCP 官方 SDKpip install mcp如果你要用 HTTP 模式再加一个pip install starlette uvicorn注意不要用系统自带的 Python 直接装很多系统 Python 是 3.8 甚至更早SDK 装不上或者行为不一致。我在这上面浪费过一个下午。3.2 写第一个工具从“读文件”开始先写一个最简单的工具服务器只提供一个read_file工具。完整代码如下import asyncio from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent app Server(my-tool-server) app.list_tools() async def list_tools(): return [ Tool( nameread_file, description读取指定文件的文本内容参数必须是完整文件路径, inputSchema{ type: object, properties: { path: { type: string, description: 完整文件路径例如 /home/user/config.json }, max_lines: { type: integer, default: 100, description: 最多读取的行数 } }, required: [path] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name read_file: path arguments[path] max_lines arguments.get(max_lines, 100) try: with open(path, r, encodingutf-8) as f: lines f.readlines()[:max_lines] return [TextContent(typetext, text.join(lines))] except FileNotFoundError: return [TextContent( typetext, textf错误文件 {path} 不存在。建议先列出目录内容确认路径。 )] except Exception as e: return [TextContent( typetext, textf错误{str(e)} )] async def main(): async with stdio_server() as (read, write): await app.run(read, write, app.create_initialization_options()) if __name__ __main__: asyncio.run(main())这段代码有几个细节值得说list_tools返回的是工具清单模型每次对话都会拿到这份清单。call_tool是实际执行入口根据name分发到不同逻辑。错误没有抛异常而是包装成TextContent返回这样模型能看到错误内容。max_lines有默认值模型不传也能跑。3.3 把工具服务器挂到 Claude 客户端写完之后要在 Claude 客户端里配置。以 Claude Desktop 为例配置文件通常在macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json配置内容如下{ mcpServers: { my-tool-server: { command: /path/to/mcp-env/bin/python, args: [/path/to/server.py] } } }这里有个坑command一定要写虚拟环境里的 Python 绝对路径不要写python3。因为客户端启动子进程时环境变量可能和你终端里不一样写python3很可能找不到或者找到系统 Python导致依赖缺失。配置完重启客户端如果一切正常你会在工具列表里看到read_file。然后你就可以在对话里说“帮我读一下 /tmp/test.txt 的前 20 行”模型会自动调用这个工具。3.4 加一个需要外部 API 的工具光读文件不够我再加一个查天气的工具演示怎么处理外部 API 调用和超时。import httpx app.call_tool() async def call_tool(name: str, arguments: dict): if name get_weather: city arguments[city] unit arguments.get(unit, celsius) try: async with httpx.AsyncClient(timeout5.0) as client: resp await client.get( https://api.example.com/weather, params{city: city, unit: unit} ) resp.raise_for_status() data resp.json() return [TextContent( typetext, textf{city} 当前温度 {data[temp]} 度天气 {data[condition]} )] except httpx.TimeoutException: return [TextContent( typetext, textf错误查询 {city} 天气超时请稍后重试。 )] except Exception as e: return [TextContent( typetext, textf错误{str(e)} )]超时时间我设了 5 秒。为什么是 5 秒因为模型调用工具时用户是在等回复的。如果工具卡 30 秒用户早就以为程序死了。5 秒是个平衡点大部分正常请求能返回异常情况也能快速失败。实操心得外部 API 调用一定要设超时而且要比你直觉的更短。我一开始设 30 秒结果遇到 API 挂掉的时候整个对话卡住体验极差。改成 5 秒后失败快、重试也快。3.5 多工具协同让模型自己编排工具服务器真正的威力是多个工具可以协同。比如用户说“读一下我的配置文件然后根据里面的城市查天气”。模型会先调read_file拿到配置内容解析出城市名再调get_weather。整个过程不需要你写编排逻辑模型自己会做。但这里有个前提工具返回的结果要足够干净。如果你read_file返回一大堆无关内容模型可能提取不出城市名。我的做法是对于配置文件读取额外提供一个read_config_value工具直接返回指定 key 的值而不是让模型去解析整个文件。app.list_tools() async def list_tools(): return [ Tool( nameread_config_value, description读取 JSON 配置文件中指定 key 的值, inputSchema{ type: object, properties: { path: {type: string, description: 配置文件路径}, key: {type: string, description: 要读取的 key 名称} }, required: [path, key] } ) ]这样模型调一次就能拿到城市名不用自己解析 JSON准确率和速度都上去了。4. 常见问题与排查技巧实录4.1 工具不显示、不调用、调用报错这是最高频的三类问题我整理成一张速查表现象可能原因排查方法客户端看不到工具配置文件路径错、JSON 格式错检查配置文件语法重启客户端工具列表有但模型不调工具描述太模糊把描述改具体加参数说明调用后报参数错误schema 类型不匹配检查 required 和 type 定义调用后无响应服务器启动慢或卡死看客户端日志检查初始化逻辑调用后返回乱码编码问题统一用 UTF-8读文件指定 encoding我遇到最多的是“工具列表有但模型不调”。原因几乎都是描述写得太泛。比如我写“处理数据”模型根本不知道什么时候该用。改成“读取 CSV 文件并返回前 N 行数据”调用率立刻上来了。4.2 日志怎么看问题怎么定位stdio 模式下工具服务器的标准输出会被客户端接管你直接 print 是看不到的。正确做法是写到文件import logging logging.basicConfig( filename/tmp/mcp-server.log, levellogging.DEBUG, format%(asctime)s %(levelname)s %(message)s )然后在关键位置打日志logging.debug(f收到调用: {name}, 参数: {arguments}) logging.debug(f返回结果: {result})排查问题时先看日志里有没有收到调用。如果没收到说明是客户端配置问题如果收到了但报错说明是工具逻辑问题。这个二分法能帮你快速缩小范围。4.3 性能与稳定性几个容易忽略的点第一工具服务器不要做重初始化。每次客户端启动都会拉起服务器如果你在启动时加载大模型或者连数据库启动时间会很长。改成懒加载。第二返回结果要截断。如果工具返回几万行文本模型上下文会被撑爆。我一般限制返回 4000 字符以内超出部分截断并提示“结果过长已截断”。第三并发调用要小心。模型有时会同时调多个工具。如果你的工具服务器是单线程的可能会阻塞。用 asyncio 的话天然支持并发但要注意共享资源的锁。第四版本兼容。MCP 协议还在演进SDK 版本不同行为可能有差异。建议锁定版本升级前先看 changelog。踩坑记录我有一次升级 SDK 后call_tool的返回格式要求变了从返回字符串变成必须返回TextContent列表。没看 changelog结果所有工具都报错。后来养成习惯升级前先跑一遍回归测试。4.4 安全边界工具服务器能做什么不能做什么工具服务器本质上是在给模型“授权”。你挂什么工具模型就能做什么。所以有几条红线不要挂载能执行任意命令的工具除非你做了严格的参数白名单。不要挂载能删除文件、修改系统配置的工具除非有二次确认机制。不要挂载能访问敏感数据的工具除非你确认调用来源可信。我的做法是所有“写操作”工具都加一个dry_run参数默认true只返回“将会做什么”不实际执行。用户明确说“执行”时才传false。这样即使模型误判也不会造成实际破坏。5. 工具服务器的扩展玩法与个人体会5.1 把常用操作都封装成工具项目跑通之后我开始把日常重复操作一个个封装进去查 Git 状态、跑单元测试、查数据库、发 HTTP 请求、格式化 JSON、计算表达式。现在我的聊天窗口基本成了一个“自然语言终端”我说“看看当前分支有没有未提交的改动”它就调git_status工具返回结果。这种体验和传统命令行最大的区别是我不需要记住命令和参数。我只需要描述意图模型负责翻译成工具调用。对于不常用的操作这个优势特别明显。5.2 工具粒度的取舍工具不是越细越好也不是越粗越好。太细模型要调很多次慢且容易出错太粗参数复杂模型传不对。我的经验是一个工具对应一个明确的动作参数不超过 5 个。比如read_file是一个动作write_file是另一个动作不要合并成file_operation然后靠一个mode参数区分。模型对枚举值的理解不如对工具名的理解准确。5.3 后续可以怎么扩展如果你已经跑通了基础版本可以考虑这几个方向加缓存层对频繁调用的只读工具缓存结果减少重复计算。加权限层不同用户挂载不同工具集。加审计日志记录每次工具调用的输入输出方便回溯。把工具服务器容器化一键部署到任意环境。我个人在实际操作中的体会是这个项目最大的价值不在于技术多复杂而在于它改变了我和机器协作的方式。以前是我适应工具现在是我描述意图工具来适应我。这个转变一旦体验过就回不去了。最后再分享一个小技巧工具描述里可以加一些“示例调用”比如在 description 里写“例如get_weather(city北京)”模型看到示例后参数格式的准确率会更高。这个细节很小但实测有效。