[具身智能-338]：mcp server代码格式详解

编写 MCP Server 的代码格式其实并不复杂但有几个“铁律”必须遵守否则客户端如 Claude Desktop无法识别。结合你之前问的 Python 函数定义我们可以把 MCP Server 的代码格式拆解为三个核心部分通信协议格式、代码结构格式、以及数据定义格式。1. 通信协议格式底层铁律这是 MCP Server 与客户端“对话”的语言。无论你用什么语言写必须遵守JSON-RPC 2.0标准。传输方式通过标准输入stdin读取标准输出stdout写入。数据格式必须是严格的JSON对象。绝对禁忌严禁在 stdout 中打印任何非 JSON 内容如print(debug)这会导致协议解析失败。调试信息必须发到 stderr。消息的基本骨架JSON-RPC 2.0表格类型格式示例说明请求{jsonrpc: 2.0, method: tools/list, id: 1}客户端发来的指令响应{jsonrpc: 2.0, result: {...}, id: 1}服务器返回的结果错误{jsonrpc: 2.0, error: {code: -32601, message: ...}, id: 1}报错信息2. 代码结构格式Python 实战在实际开发中我们通常使用Python SDK (mcp) 来简化开发不需要手写底层的 JSON 解析。一个标准的 MCP Server 代码结构通常包含以下四个步骤第一步导入与初始化必须导入FastMCP类并实例化一个服务器对象。pythonfrom mcp.server.fastmcp import FastMCP # 初始化服务器给它起个名字 mcp FastMCP(MyCustomServer)第二步定义工具核心业务逻辑这是你最熟悉的部分——定义 Python 函数。但在 MCP 中格式上有两个特殊要求装饰器必须使用mcp.tool()装饰器。文档字符串函数内部必须有...注释虽然是注释但非常非常的重要这是 AI 理解工具功能的唯一依据是AI大模型通过自然语言找到该工具的依据包括功能描述输入参数清单和含义。类型提示参数类型如name: str和返回类型- int必须准确AI 依赖这些信息来传参。虽然这些注释对python代码没啥直接的约束力但这些注释对于AI理解函数工具的参数类型和返回值的类型很有意义是AI大模型通过自然语言理解入口参数的依据从编程的角度看看是没有意义的注释对于理解自然语言的AI却非常有意义有作用。是AI大模型通过自然语言找到对应tool的依据pythonmcp.tool() def calculate_tax(price: float, rate: float) - float: 计算商品价格及税率。 Args: price: 商品的原始价格 rate: 税率比例例如 0.1 代表 10% return price * (1 rate)第三步定义资源可选如果你想让 AI 读取某些文件作为上下文类似只读文件使用mcp.resource。pythonmcp.resource(config://app_settings) def get_settings() - str: 提供应用的配置信息 return 当前环境: 生产环境; 版本: 1.0第四步启动入口代码的最后必须有运行入口通常使用stdio传输模式。pythonif __name__ __main__: mcp.run(transportstdio)3. 数据定义格式JSON Schema虽然你在 Python 代码中写的是函数但 MCP Server 最终会将其转换为 JSON Schema 格式发送给客户端。当你定义了上面的calculate_tax函数后MCP 会自动生成如下格式的元数据给 AIjson{ name: calculate_tax, description: 计算商品价格及税率..., inputSchema: { type: object, properties: { price: { type: number, description: 商品的原始价格 }, rate: { type: number, description: 税率比例... } }, required: [price, rate] } }注意这就是为什么 Python 函数中的类型提示float,str和文档字符串如此重要的原因它们直接决定了这个 JSON Schema 的生成质量。4. 完整的标准模板你可以直接复制这个模板作为开发的起点python#!/usr/bin/env python3 # -*- coding: utf-8 -*- MCP Server 标准模板 from mcp.server.fastmcp import FastMCP # 1. 初始化 mcp FastMCP(TemplateServer) # 2. 定义工具 mcp.tool() def my_tool(param_a: str) - str: 这是一个示例工具。 请详细描述这个工具的功能AI 会根据这个描述决定是否调用它。 Args: param_a: 参数的描述 # 你的业务逻辑 return f处理结果: {param_a} # 3. 启动 if __name__ __main__: # 必须使用 stdio 模式与大多数客户端通信 mcp.run()总结MCP 代码格式的“三要三不要”表格类别说明要写类型提示name: str必须写否则 AI 不知道传什么类型。要写文档字符串...必须写这是 AI 的“说明书”。要用 Stdio启动时通常用mcp.run()或transportstdio。不要用 Print严禁在函数里print()调试会破坏 JSON 协议请用sys.stderr.write()。不要缺参数描述尽量把参数解释清楚AI 才能填对参数。不要阻塞主线程工具执行要快不要写死循环否则客户端会卡死。client采用同步阻塞性的方式远程调用tools对应的函数。