python-sdk 服务器端开发指南MCPServer 三大原语Tool、Resource、Prompt与周边能力总览【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdk导读本文是 python-sdk 中MCPServer服务器端开发的知识地图。一个 MCP 服务器向客户端暴露三种核心原语——工具Tool、资源Resource、提示模板Prompt——它们之间的本质区别在于由谁决定使用模型、应用程序还是人。读完本文你将掌握三原语的分工逻辑、各自的声明方式与典型代码形态并了解与之配套的 Autocompletar服务端补全、多媒体返回与图标、错误处理等周边能力从而在动手前对整个服务器端 API 面形成完整认知。三种原语由谁决定使用MCPServer向已连接的客户端暴露三种原语。理解 MCP 服务器端 API 的钥匙就是回答同一个问题——是谁决定调用它原语决定者一句话定位配套参考工具Tool模型模型自主选择和调用的动作Saída estruturada / 结构化输出工具返回内容的形状资源Resource应用程序应用程序选择读取的只读数据Templates de URI / URI 模板完整寻址语法与路径安全规则提示Prompt人用户从菜单或斜杠命令中按名字调用消息模板的渲染与多消息会话三者都通过 Python 装饰器声明源码见 src/mcp/server/mcpserver/server.py 中tool、resource、prompt三个方法的定义但对谁能碰它有着完全不同的语义。工具Tool模型自主调用的动作工具是模型选择并调用的动作也是大多数开发者最先寻找的页面。声明一个工具的全部 API 就是在普通 Python 函数上放一个mcp.tool()from mcp.server import MCPServer mcp MCPServer(Bookshop) mcp.tool() def search_books(query: str, limit: int) - str: Search the catalog by title or author. return fFound 3 books matching {query!r} (showing up to {limit}).无需手写 Schema、JSON 或协议细节。SDK 从函数上自动读取三样东西名称 函数名search_books描述 docstring模型会看到它参数 类型注解query: str、limit: intSDK 据此生成 JSON Schema 并在tools/list时发给客户端。类型注解在这里不是文档而是契约如果客户端发送limit: tenSDK 会在你的函数运行之前就拒绝它。工具调用的返回值也会被拆成两个通道content模型阅读的文本与structured_content给客户端应用的结构化数据。返回类型注解本身就是输出 Schema详细规则见 结构化输出。在源码层面mcp.tool()支持name、title等参数src/mcp/server/mcpserver/server.py允许你在需要时覆盖函数名作为对外暴露的工具名。资源Resource应用程序读取的只读数据资源是应用程序决定加载的数据配置文件、记录、文档并作为上下文放到模型面前。与工具不同资源是**按地址寻址URI**而非按名称寻址客户端请求config://app而不是get_config。mcp.resource(config://app) def get_config() - str: The active shop configuration. return themedark\nlanguageenmcp.resource(uri)接受一个 URI 参数src/mcp/server/mcpserver/server.py。当 URI 中包含{占位符}时它就升级为资源模板从resources/list移入resources/templates/list客户端填充占位符后读取具体 URI如users://42/profile匹配到的值以同名参数传入函数。占位符语法遵循 RFC 6570{path}捕获多段路径值、{?q,lang}表示可选查询参数等。SDK 默认还会对提取的值施加路径安全检查。需要特别注意的是占位符与函数参数必须一致——若 URI 写{user_id}而函数参数改名为user装饰器会在导入期直接抛出ValueError从根上杜绝因不匹配导致的启动故障。完整语法与安全规则见 URI 模板与路径安全。资源列表是廉价的你的函数在resources/list时不会被调用只有resources/read且只针对被请求的那个 URI 才会执行。暴露一千个资源只为被打开的那些买单。提示Prompt人按名字调用的消息模板提示与工具恰好相反工具属于模型提示属于人——用户从客户端菜单斜杠命令、按钮中选择一个提示填入参数渲染出的消息就像用户亲手输入一样进入对话。mcp.prompt() def review_code(code: str) - str: Review a piece of code. return fPlease review this code:\n\n{code}SDK 从函数读取的信息与工具相同名称 函数名描述 docstring参数 函数参数无默认值即必填。但注意这里没有 JSON Schema——提示参数是扁平的具名字符串值列表是人填的表单而不是模型构造的载荷。渲染时客户端调用prompts/get传入参数你的函数运行返回的str成为一条 user 消息。若返回UserMessage/AssistantMessage的列表来自mcp.server.mcpserver.prompts.base则可以一次播种整段多轮对话。required参数在函数运行前就会被强制校验缺失时请求本身以 JSON-RPC 错误-32603失败——因为没有模型在循环里无法返回工具风格的错误结果调用直接抛出异常。三大原语之外的服务器声明围绕三种原语服务器还可以声明其余能力让工具、资源、提示真正可用Autocompletar补全当用户在客户端 UI 中键入参数值时服务器提供服务端自动补全建议——语言名、仓库名、文件路径。补全只作用于两类对象提示的参数与资源模板的参数。注册方式是在服务器上添加一个mcp.completion()处理器所有补全请求都汇聚到这里用isinstance(ref, ...)区分是PromptReference还是ResourceTemplateReference根据argument.name分支处理返回Completion(values[...])或None表示无建议绝不代表错误。处理器必须是async def。值得注意的实现细节注册处理器本身就是能力声明。连接客户端后查看client.server_capabilities.completions会发现你从未手动列出completions能力——SDK 看到处理器就自动声明了。所有可选能力都遵循这一规律而三大原语并不可选MCPServer无条件声明它们无论是否有处理器。Imagens, áudio e ícones图像、音频与图标覆盖工具除文本外能返回的一切以及客户端在服务器旁显示的图标。SDK 提供两个二进制结果助手——Image和Audio各接受path文件路径或data原始字节二选一以及一个Icon类型让服务器、工具、资源、提示在客户端 UI 中拥有面孔。返回的Image在线上成为ImageContent块字节 base64 编码 MIME 类型Audio同理成为AudioContent。注意structured_content为None——二进制内容是给模型看的不是给应用解析的数据因此没有输出 Schema。MIME 类型从后缀猜测Image支持.png/.jpg/.jpeg/.gif/.webpAudio支持.wav/.mp3/.ogg/.flac/.aac/.m4a未知后缀回退到application/octet-streamdata模式无文件名可猜默认image/png与audio/wav。Tratamento de erros错误处理解释模型能恢复的错误与模型绝不该看到的错误之间的差别。工具失败有三种方式SDK 区别对待抛出ToolError来自mcp.server.mcpserver.exceptions——模型能看到你的消息请求成功返回is_errorTrue消息前缀工具名进入content。这是工具与模型的对话回合模型读到没有这本书后会修正参数重试。这是大多数情况下你想要的。抛出MCPError——协议看到它这是 SDK 的协议错误是工具包装器唯一不捕获的异常整个tools/call请求以 JSON-RPC 错误失败如-32602INVALID_PARAMS没有结果、没有content、没有is_error宿主应用收到错误。mcp.types导出了这些错误码常量无需手写魔法数字。抛出任何其他异常——崩溃模型只知道调用失败你的日志里留下 traceback。判断标准只有一个一个更聪明的模型本可以避免这个错误吗能 →ToolError不能 →MCPError。另有一条铁律永远不要从工具return一条错误消息——返回的字符串is_errorFalse模型和客户端 UI 都会以为工具成功且这就是答案。用raise标志位才是信号。如何继续页面独立性、起点与下一步每个页面都是自包含的可以直接跳到你需要的那一页。本文列出的全部参考页面与源码位置如下三大原语工具 docs/servers/tools.md、资源 docs/servers/resources.md、提示 docs/servers/prompts.md配套参考结构化输出 docs/servers/structured-output.md、URI 模板 docs/servers/uri-templates.md周边能力补全 docs/servers/completions.md、媒体与图标 docs/servers/media.md、错误处理 docs/servers/handling-errors.md可运行的教程代码docs_src/tools/、docs_src/resources/、docs_src/prompts/、docs_src/completions/、docs_src/media/、docs_src/handling_errors/等目录下的tutorial*.py装饰器与处理器注册的源码实现src/mcp/server/mcpserver/server.py更完整的可运行服务器示例examples/servers/simple-tool/、examples/servers/simple-resource/、examples/servers/simple-prompt/等各含pyproject.toml与 README。如果你还没有构建过服务器请先阅读 Primeiros passos / 入门第一步。而你在注册的函数内部发生的事情——Context上下文、依赖注入、调用中途向用户索取更多信息——属于下一节的内容Dentro do seu handler / 深入你的处理器。【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考