[具身智能-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）：

表格

2. 代码结构格式（Python 实战）

在实际开发中，我们通常使用Python SDK (mcp) 来简化开发，不需要手写底层的 JSON 解析。一个标准的 MCP Server 代码结构通常包含以下四个步骤：

第一步：导入与初始化

必须导入FastMCP类，并实例化一个服务器对象。

python

from mcp.server.fastmcp import FastMCP # 初始化服务器，给它起个名字 mcp = FastMCP("MyCustomServer")

第二步：定义工具（核心业务逻辑）

这是你最熟悉的部分——定义 Python 函数。但在 MCP 中，格式上有两个特殊要求：

1. 装饰器：必须使用@mcp.tool()装饰器。
2. 文档字符串：函数内部必须有"""..."""注释，虽然是注释，但非常非常的重要，这是 AI 理解工具功能的唯一依据，是AI大模型通过自然语言找到该工具的依据！！！包括功能描述，输入参数清单和含义。
3. 类型提示：参数类型（如name: str）和返回类型（-> int）必须准确，AI 依赖这些信息来传参。虽然这些注释对python代码没啥直接的约束力，但这些注释对于AI理解函数工具的参数类型和返回值的类型很有意义，是AI大模型通过自然语言理解入口参数的依据！！！！
4. 从编程的角度看，看是没有意义的注释，对于理解自然语言的AI却非常有意义，有作用。是AI大模型通过自然语言找到对应tool的依据！！！

python

@mcp.tool() def calculate_tax(price: float, rate: float) -> float: """ 计算商品价格及税率。 Args: price: 商品的原始价格 rate: 税率比例（例如 0.1 代表 10%） """ return price * (1 + rate)

第三步：定义资源（可选）

如果你想让 AI 读取某些文件作为上下文（类似只读文件），使用@mcp.resource。

python

@mcp.resource("config://app_settings") def get_settings() -> str: """提供应用的配置信息""" return "当前环境: 生产环境; 版本: 1.0"

第四步：启动入口

代码的最后必须有运行入口，通常使用stdio传输模式。

python

if __name__ == "__main__": mcp.run(transport='stdio')

3. 数据定义格式（JSON Schema）

虽然你在 Python 代码中写的是函数，但 MCP Server 最终会将其转换为 JSON Schema 格式发送给客户端。

当你定义了上面的calculate_tax函数后，MCP 会自动生成如下格式的元数据给 AI：

json

{ "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 代码格式的“三要三不要”

表格