人工智能MCP 服务MCP Clients【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址https://gitcode.com/gh_mirrors/pythonsd/python-sdk点击查看免费下载这篇指南围绕官方 Python SDK本仓库 src/mcp/server/mcpserver/server.py 中的MCPServer展开系统梳理服务器向客户端暴露的三种核心原语——工具tools、资源resources与提示词prompts以及围绕它们的自动补全、媒体返回与错误处理能力。读完你将掌握谁有权调用什么这一 MCP 服务器设计的主线明确各原语的声明方式、协议行为与适用场景并知道下一步该阅读哪份参考文档。一张图理解服务器三种原语三种决策者MCPServer向已连接的客户端暴露三种原语它们的根本区别在于谁决定使用它们工具tool由模型挑选并调用的动作。这是大多数人最先需要的页面其配套参考是结构化输出Structured Output——它回答工具返回值的形状是什么。资源resource由应用决定读取的只读数据。其配套参考是URI 模板URI templates——完整的寻址语法与路径安全规则。提示词prompt由人通过菜单或斜杠命令按名称调用的消息模板。在三大原语之外服务器还会声明其余能力自动补全Completions为提示词参数和资源模板参数提供服务器端补全建议。图像、音频与图标Media覆盖工具在文本之外还能返回的一切内容以及客户端在服务器旁展示的图标。错误处理Handling errors解释模型可以从中恢复的错误与模型绝不应看到的错误之间的差别。从源码结构看这一设计落在 src/mcp/server/mcpserver/ 下的tools/、prompts/与resources/三个子包中MCPServer构造时分别创建ToolManager、PromptManager与ResourceManager来登记和管理三类原语见 server.py 附近并在Settings中提供了warn_on_duplicate_tools、warn_on_duplicate_resources、warn_on_duplicate_prompts三个去重告警开关。工具Tools模型挑选并调用的动作工具是模型可以直接调用的函数。声明方式极为简单——在普通 Python 函数上加上mcp.tool()装饰器这就是全部 APIfrom 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}).完整可运行版本见 docs_src/tools/tutorial001.py。没有 schema、没有 JSON、没有协议细节SDK 从函数中读取三样东西名称函数名即search_books描述docstring模型看到的说明允许传入的参数类型注解如query: str和limit: int。输入 schema 的生成与校验SDK 从类型注解生成 JSON Schema并在tools/list期间发送给客户端。两个参数都没有默认值因此都出现在required中。值得强调这里的类型注解不是文档而是契约——如果客户端发送limit: tenSDK 会在你的函数运行之前就拒绝它。给参数一个默认值它就不再是必填项并自动获得default: 10。用Annotated[..., Field(...)]可以附加参数级描述与约束Field(description...)模型在阅读 docstring 之外还能看到的逐参数描述Field(ge1, le50)数值边界落入 schema 的minimum: 1, maximum: 50Literal[fiction, non-fiction, poetry]枚举模型只能从中选择。约束不是装饰。调用limit999时SDK 会在函数执行前以工具错误应答Input should be less than or equal to 50该错误作为工具结果回到模型模型读到后会用合法值重试——你只写了一次le50就免费得到了会自我纠错的 Agent。这与 FastAPI/Pydantic 完全是同一套Field、Annotated与校验机制没有 MCP 特有的新知识。参数模型、异步与元信息参数超过两三个时可以把它们收进一个 Pydantic 模型Book的 schema 会作为$defs引用嵌套进工具的输入 schema模型以 JSON 对象填充你的函数收到的是一个已经过校验的真实Book实例带有.title、.author、.year属性。执行 I/O 的工具应声明为async def并在内部awaitSDK 会等待它普通def工具同样可用SDK 会在线程中运行它以免阻塞服务器无需额外配置。装饰器里还可以覆盖 SDK 推断出的一切title是给 UI 的可读名称annotations是对客户端的行为提示例如read_only_hintTrue表示该工具不改变任何状态、open_world_hintFalse表示它作用于封闭集合该目录而非开放网络。行为良好的客户端会据此决定运行前是否需要询问用户——但它们只是提示不是安全机制。name与description同样可以直接传给mcp.tool()。关于工具返回值的形状content文本通道、structured_content结构化数据通道、output_schema契约见 结构化输出参考。资源Resources应用决定读取的只读数据资源是供应用读取的数据配置文件、记录、文档等应用将其加载并作为上下文放到模型面前。声明方式与工具同构只多了一样东西——URI资源按地址寻址客户端请求的是config://app而不是get_config。mcp.resource(config://app) def get_config() - str: The active shop configuration. return themedark\nlanguageenSDK 仍然从函数读取名称、docstring 与返回值。在resources/list中客户端得到{name: get_config, uri: config://app, description: ..., mimeType: text/plain}当它读取config://app时你的函数才运行返回文本。关键行为详见 资源参考列出是廉价的resources/list期间函数不会被调用只在resources/read且仅对请求的那个 URI 调用。暴露一千个资源只为被打开的那些付费。URI 模板URI 中的{placeholder}与函数同名参数一一对应即成为资源模板从resources/list迁移到resources/templates/list一个函数服务所有匹配 URI如users://42/profile。占位符与参数必须一致名字对不上会在导入期直接报ValueError: Mismatch between URI parameters ...让 bug 无法带着错误启动服务器。模板语法遵循 RFC 6570完整操作符集与路径安全检查见 URI 模板与路径安全。返回值类型决定传输方式str原样作为文本bytes转为 base64 编码的BlobResourceContents其余 JSON 可序列化对象dict、Pydantic 模型、dataclass、列表序列化为 JSON 文本。mime_type由你声明默认text/plainSDK 从不猜测。没有可写的函数时src/mcp/server/mcpserver/ 下的resources模块提供了现成的TextResource、BinaryResource、FileResource、HttpResource、DirectoryResource类通过mcp.add_resource(...)注册。客户端还可以订阅资源并在其变化时收到通知那是客户端的另一半故事见 客户端章节。提示词Prompts人从菜单中挑选的消息模板工具服务模型提示词则相反用户从客户端菜单中选择斜杠命令、按钮填写参数渲染出的消息像用户自己输入一样进入对话。mcp.prompt() def review_code(code: str) - str: Review a piece of code. return fPlease review this code:\n\n{code}可运行版本见 docs_src/prompts/tutorial001.py。SDK 读取的仍然是函数名、docstring 和参数。与工具不同提示词参数没有 JSON Schema——它们是扁平的命名字符串值列表是供人填写的表单而非模型构造的载荷。prompts/list返回{name: review_code, description: ..., arguments: [{name: code, required: true}]}。提示词的生命周期极短按名称列出、按需渲染、丢进聊天。prompts/get渲染时函数返回的str变成一条 user 消息。required在函数运行前强制执行渲染缺少code的review_code会让整个请求以 JSON-RPC 错误失败因为没有模型在回路里调用直接抛出原因记录在服务器日志。返回str之外返回UserMessage/AssistantMessage列表来自mcp.server.mcpserver.prompts.base可以种下一整段多轮对话——预填一条assistant消息是在不替用户打字的前提下引导模型下一句回复的手法。title与Annotated[str, Field(description...)]提供给客户端绘制表单所需的一切。消息还可以携带EmbeddedResource附上带 URI 与 MIME 类型的文档或Image/Audiobase64 图片/音频块完整示例见 提示词参考。提示词列表还可以在客户端已连接时动态变更mcp.add_prompt(Prompt.from_function(...))与mcp.remove_prompt(name)用于增删随后await ctx.notify_prompts_changed()通知 2026-07-28 客户端、await ctx.session.send_prompt_list_changed()通知旧版客户端详见 服务旧版客户端 与 订阅。自动补全Completions提示词与资源模板的参数建议基于你的服务器构建 UI 的客户端希望在用户输入时自动补全参数值语言名、仓库名、文件路径。自动补全正是服务器提供这些建议的机制。它只作用于两处提示词的参数与资源模板的参数。服务器只需注册一个mcp.completion()处理器必须是async defSDK 会 await 它所有补全请求都汇聚到这里你通过参数分派ref被补全的是哪个提示词或资源模板以PromptReference或ResourceTemplateReference呈现用isinstance区分argumentargument.name是被补全的参数名argument.value是用户已输入的前缀context已解析的参数用于依赖参数见下。返回Completion(values[...])或无事可offer 时返回None。注意 SDK不会替你过滤——values里放什么 UI 就显示什么startswith逻辑要自己写。None表示没有建议永远不会是错误UI 会退回普通文本框。注册处理器即声明能力连接客户端后client.server_capabilities.completions会变成CompletionsCapability()。每个可选能力都这样运作——处理器本身就是声明而三大原语不是可选的MCPServer始终声明它们。没有处理器时请求会以Method not found失败能力字段为None——这正是能力声明的意义行为良好的客户端会先检查再发送。context.arguments携带用户已解析的参数如资源模板github://repos/{owner}/{repo}中先选定的owner客户端以context_arguments提供实现依赖补全。Completion还接受total与has_more用于 values 只是长列表切片时提示 UI还有 200 个。完整示例与客户端调用方式见 自动补全参考。媒体返回与图标Media文本之外的一切文本不是工具能返回的唯一内容。SDK 为二进制结果提供两个助手Image与Audio以及一个Icon类型用于给服务器、工具、资源、提示词在客户端 UI 中一张脸。返回图片/音频把返回类型注解为Image指向文件路径path或原始字节data返回即可。MIME 类型按后缀推断Image.png、.jpg、.jpeg、.gif、.webpAudio.wav、.mp3、.ogg、.flac、.aac、.m4a不认识的类型回退到application/octet-stream。在线上返回值变成ImageContent/AudioContent块——字节 base64 编码加 MIME 类型。Image是 SDK 便利类型而非协议类型没有输出 schemastructured_content为None因为图像是给模型看的内容不是给应用解析的数据。data时必须给format没有文件名就没有后缀可猜忘记format会回退到image/png/audio/wav默认值——用 MP3 字节这样构建Audio客户端会被告知audio/wav然后忠实解码失败。内嵌资源返回EmbeddedResource文本或 base64 blob 连同 URI 与 MIME 类型客户端可以把它显示为附件或识别已认识的资源只发送指针则返回ResourceLink。图标Icon是元数据而非内容它通过srcURI 指向图片https:或无需额外抓取的data:URI可选mime_type、sizes如48x48或可缩放的any与themelight/dark。icons[...]关键字被MCPServer(...)、mcp.tool()、mcp.resource()、mcp.prompt()共同接受客户端分别在server_info.icons、tools/list的Tool、resources/list的Resource、prompts/list的Prompt上找到它们。详见 图像、音频与图标参考。错误处理Handling errors三种失败三种去处工具可能以三种方式失败SDK 对每种区别对待实现位于 src/mcp/server/mcpserver/exceptions.py抛出ToolError模型看到你的消息。调用仍然成功——存在结果调用方没有异常——但is_errorTrue你的消息前缀工具名就在模型读取的content中structured_content为None。这是工具告诉模型出事了的标准方式几乎总是你想要的模型读到No book titled Nothing in the catalog.意识到猜错了书名再用正确书名重试。服务器端只是一条无 traceback 的INFO日志。抛出MCPError协议看到它。它是工具包装器唯一不捕获的异常会向上传播使整个tools/call请求以 JSON-RPC 错误失败如{code: -32602, message: ...}没有结果、没有is_error主机应用像工具不存在一样收到它。code、message、data原样传递mcp.types以常量导出各错误码INVALID_PARAMS等不必手写魔法数字。抛出任何其他异常是一次崩溃。调用仍返回is_errorTrue模型知道失败并可以继续但模型只得到Error executing tool name——内部异常文本可能描述服务器内部细节所以绝不离开服务器。traceback 以ERROR级别进入你的日志。选择标准一句话一个更聪明的模型本可以避免这个错误吗能 →ToolError不能 →MCPError。执行层面的失败拼错书名、上游超时、行不存在是工具错误请求本身应被拒绝客户端缺能力、服务器状态不可服务、调用方跳过了必要步骤是协议错误。资源画着同一条线资源模板匹配任何标题但URI 合法与书存在是两回事只有你的函数能回答后者。回答不了时抛出ResourceNotFoundErrorSDK 将其转为规范指定的协议错误-32602并把请求的 URI 放进data{code: -32602, message: ..., data: {uri: books://Nothing}}。资源没有is_errorTrue半结果——读取要么返回内容要么失败。ResourceError是非未找到失败的同一机制-32603两者都只是一条INFO日志其他异常MCPError除外是崩溃。导入方式from mcp import MCPErrorfrom mcp.server.mcpserver.exceptions import ToolError, ResourceError, ResourceNotFoundError。还有一类你永远不需要写 raise的错误坏参数在进入函数前就被输入 schema 拒之门外以同样的is_errorTrue工具错误形式让模型可读、可纠正——不要重复校验自己的类型注解。完整对照与日志行为见 错误处理参考。下一步从索引页出发的阅读路径本节每个页面都自足可以直接跳到你需要的那一页还没建过服务器先从 快速上手First steps 开始而不是本节页面。你注册的函数内部发生什么——Context、依赖注入、调用中途向用户索要更多信息——属于下一节 Inside your handler处理器内部。各参考页面工具、结构化输出、资源、URI 模板与路径安全、提示词、自动补全、图像/音频与图标、错误处理均以可运行的docs_src/教程代码为骨架配套测试位于 tests/docs_src/如 test_tools.py、test_prompts.py可对照阅读验证行为。赞分享人工智能MCP 服务MCP Clients【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址https://gitcode.com/gh_mirrors/pythonsd/python-sdk点击查看免费下载相关推荐Zotero文献管理界面单调zotero-style插件让你的学术工作流焕然一新Zotero文献管理界面单调zotero style插件让你的学术工作流焕然一新 如果你是一名科研工作者、学生或学术研究者正在使用Zotero管理文献资料人工智能MCP 服务MCP Clientspython-sdk 服务端开发指南MCPServer 三大原语、可选能力与错误处理全解析python sdk 服务端开发指南MCPServer 三大原语、可选能力与错误处理全解析 MCPModel Context Protocol服务端向已连人工智能MCP 服务MCP ClientsEchoSet数据集深度解析TIGER-DnR如何应对复杂声学环境下的语音分离挑战EchoSet数据集深度解析TIGER DnR如何应对复杂声学环境下的语音分离挑战 TIGER DnRTime Frequency Interleaved人工智能MCP 服务MCP Clients创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 python-sdk 服务器端开发指南：MCPServer 的三大原语与配套能力全景
人工智能MCP 服务MCP Clients【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址https://gitcode.com/gh_mirrors/pythonsd/python-sdk点击查看免费下载这篇指南围绕官方 Python SDK本仓库 src/mcp/server/mcpserver/server.py 中的MCPServer展开系统梳理服务器向客户端暴露的三种核心原语——工具tools、资源resources与提示词prompts以及围绕它们的自动补全、媒体返回与错误处理能力。读完你将掌握谁有权调用什么这一 MCP 服务器设计的主线明确各原语的声明方式、协议行为与适用场景并知道下一步该阅读哪份参考文档。一张图理解服务器三种原语三种决策者MCPServer向已连接的客户端暴露三种原语它们的根本区别在于谁决定使用它们工具tool由模型挑选并调用的动作。这是大多数人最先需要的页面其配套参考是结构化输出Structured Output——它回答工具返回值的形状是什么。资源resource由应用决定读取的只读数据。其配套参考是URI 模板URI templates——完整的寻址语法与路径安全规则。提示词prompt由人通过菜单或斜杠命令按名称调用的消息模板。在三大原语之外服务器还会声明其余能力自动补全Completions为提示词参数和资源模板参数提供服务器端补全建议。图像、音频与图标Media覆盖工具在文本之外还能返回的一切内容以及客户端在服务器旁展示的图标。错误处理Handling errors解释模型可以从中恢复的错误与模型绝不应看到的错误之间的差别。从源码结构看这一设计落在 src/mcp/server/mcpserver/ 下的tools/、prompts/与resources/三个子包中MCPServer构造时分别创建ToolManager、PromptManager与ResourceManager来登记和管理三类原语见 server.py 附近并在Settings中提供了warn_on_duplicate_tools、warn_on_duplicate_resources、warn_on_duplicate_prompts三个去重告警开关。工具Tools模型挑选并调用的动作工具是模型可以直接调用的函数。声明方式极为简单——在普通 Python 函数上加上mcp.tool()装饰器这就是全部 APIfrom 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}).完整可运行版本见 docs_src/tools/tutorial001.py。没有 schema、没有 JSON、没有协议细节SDK 从函数中读取三样东西名称函数名即search_books描述docstring模型看到的说明允许传入的参数类型注解如query: str和limit: int。输入 schema 的生成与校验SDK 从类型注解生成 JSON Schema并在tools/list期间发送给客户端。两个参数都没有默认值因此都出现在required中。值得强调这里的类型注解不是文档而是契约——如果客户端发送limit: tenSDK 会在你的函数运行之前就拒绝它。给参数一个默认值它就不再是必填项并自动获得default: 10。用Annotated[..., Field(...)]可以附加参数级描述与约束Field(description...)模型在阅读 docstring 之外还能看到的逐参数描述Field(ge1, le50)数值边界落入 schema 的minimum: 1, maximum: 50Literal[fiction, non-fiction, poetry]枚举模型只能从中选择。约束不是装饰。调用limit999时SDK 会在函数执行前以工具错误应答Input should be less than or equal to 50该错误作为工具结果回到模型模型读到后会用合法值重试——你只写了一次le50就免费得到了会自我纠错的 Agent。这与 FastAPI/Pydantic 完全是同一套Field、Annotated与校验机制没有 MCP 特有的新知识。参数模型、异步与元信息参数超过两三个时可以把它们收进一个 Pydantic 模型Book的 schema 会作为$defs引用嵌套进工具的输入 schema模型以 JSON 对象填充你的函数收到的是一个已经过校验的真实Book实例带有.title、.author、.year属性。执行 I/O 的工具应声明为async def并在内部awaitSDK 会等待它普通def工具同样可用SDK 会在线程中运行它以免阻塞服务器无需额外配置。装饰器里还可以覆盖 SDK 推断出的一切title是给 UI 的可读名称annotations是对客户端的行为提示例如read_only_hintTrue表示该工具不改变任何状态、open_world_hintFalse表示它作用于封闭集合该目录而非开放网络。行为良好的客户端会据此决定运行前是否需要询问用户——但它们只是提示不是安全机制。name与description同样可以直接传给mcp.tool()。关于工具返回值的形状content文本通道、structured_content结构化数据通道、output_schema契约见 结构化输出参考。资源Resources应用决定读取的只读数据资源是供应用读取的数据配置文件、记录、文档等应用将其加载并作为上下文放到模型面前。声明方式与工具同构只多了一样东西——URI资源按地址寻址客户端请求的是config://app而不是get_config。mcp.resource(config://app) def get_config() - str: The active shop configuration. return themedark\nlanguageenSDK 仍然从函数读取名称、docstring 与返回值。在resources/list中客户端得到{name: get_config, uri: config://app, description: ..., mimeType: text/plain}当它读取config://app时你的函数才运行返回文本。关键行为详见 资源参考列出是廉价的resources/list期间函数不会被调用只在resources/read且仅对请求的那个 URI 调用。暴露一千个资源只为被打开的那些付费。URI 模板URI 中的{placeholder}与函数同名参数一一对应即成为资源模板从resources/list迁移到resources/templates/list一个函数服务所有匹配 URI如users://42/profile。占位符与参数必须一致名字对不上会在导入期直接报ValueError: Mismatch between URI parameters ...让 bug 无法带着错误启动服务器。模板语法遵循 RFC 6570完整操作符集与路径安全检查见 URI 模板与路径安全。返回值类型决定传输方式str原样作为文本bytes转为 base64 编码的BlobResourceContents其余 JSON 可序列化对象dict、Pydantic 模型、dataclass、列表序列化为 JSON 文本。mime_type由你声明默认text/plainSDK 从不猜测。没有可写的函数时src/mcp/server/mcpserver/ 下的resources模块提供了现成的TextResource、BinaryResource、FileResource、HttpResource、DirectoryResource类通过mcp.add_resource(...)注册。客户端还可以订阅资源并在其变化时收到通知那是客户端的另一半故事见 客户端章节。提示词Prompts人从菜单中挑选的消息模板工具服务模型提示词则相反用户从客户端菜单中选择斜杠命令、按钮填写参数渲染出的消息像用户自己输入一样进入对话。mcp.prompt() def review_code(code: str) - str: Review a piece of code. return fPlease review this code:\n\n{code}可运行版本见 docs_src/prompts/tutorial001.py。SDK 读取的仍然是函数名、docstring 和参数。与工具不同提示词参数没有 JSON Schema——它们是扁平的命名字符串值列表是供人填写的表单而非模型构造的载荷。prompts/list返回{name: review_code, description: ..., arguments: [{name: code, required: true}]}。提示词的生命周期极短按名称列出、按需渲染、丢进聊天。prompts/get渲染时函数返回的str变成一条 user 消息。required在函数运行前强制执行渲染缺少code的review_code会让整个请求以 JSON-RPC 错误失败因为没有模型在回路里调用直接抛出原因记录在服务器日志。返回str之外返回UserMessage/AssistantMessage列表来自mcp.server.mcpserver.prompts.base可以种下一整段多轮对话——预填一条assistant消息是在不替用户打字的前提下引导模型下一句回复的手法。title与Annotated[str, Field(description...)]提供给客户端绘制表单所需的一切。消息还可以携带EmbeddedResource附上带 URI 与 MIME 类型的文档或Image/Audiobase64 图片/音频块完整示例见 提示词参考。提示词列表还可以在客户端已连接时动态变更mcp.add_prompt(Prompt.from_function(...))与mcp.remove_prompt(name)用于增删随后await ctx.notify_prompts_changed()通知 2026-07-28 客户端、await ctx.session.send_prompt_list_changed()通知旧版客户端详见 服务旧版客户端 与 订阅。自动补全Completions提示词与资源模板的参数建议基于你的服务器构建 UI 的客户端希望在用户输入时自动补全参数值语言名、仓库名、文件路径。自动补全正是服务器提供这些建议的机制。它只作用于两处提示词的参数与资源模板的参数。服务器只需注册一个mcp.completion()处理器必须是async defSDK 会 await 它所有补全请求都汇聚到这里你通过参数分派ref被补全的是哪个提示词或资源模板以PromptReference或ResourceTemplateReference呈现用isinstance区分argumentargument.name是被补全的参数名argument.value是用户已输入的前缀context已解析的参数用于依赖参数见下。返回Completion(values[...])或无事可offer 时返回None。注意 SDK不会替你过滤——values里放什么 UI 就显示什么startswith逻辑要自己写。None表示没有建议永远不会是错误UI 会退回普通文本框。注册处理器即声明能力连接客户端后client.server_capabilities.completions会变成CompletionsCapability()。每个可选能力都这样运作——处理器本身就是声明而三大原语不是可选的MCPServer始终声明它们。没有处理器时请求会以Method not found失败能力字段为None——这正是能力声明的意义行为良好的客户端会先检查再发送。context.arguments携带用户已解析的参数如资源模板github://repos/{owner}/{repo}中先选定的owner客户端以context_arguments提供实现依赖补全。Completion还接受total与has_more用于 values 只是长列表切片时提示 UI还有 200 个。完整示例与客户端调用方式见 自动补全参考。媒体返回与图标Media文本之外的一切文本不是工具能返回的唯一内容。SDK 为二进制结果提供两个助手Image与Audio以及一个Icon类型用于给服务器、工具、资源、提示词在客户端 UI 中一张脸。返回图片/音频把返回类型注解为Image指向文件路径path或原始字节data返回即可。MIME 类型按后缀推断Image.png、.jpg、.jpeg、.gif、.webpAudio.wav、.mp3、.ogg、.flac、.aac、.m4a不认识的类型回退到application/octet-stream。在线上返回值变成ImageContent/AudioContent块——字节 base64 编码加 MIME 类型。Image是 SDK 便利类型而非协议类型没有输出 schemastructured_content为None因为图像是给模型看的内容不是给应用解析的数据。data时必须给format没有文件名就没有后缀可猜忘记format会回退到image/png/audio/wav默认值——用 MP3 字节这样构建Audio客户端会被告知audio/wav然后忠实解码失败。内嵌资源返回EmbeddedResource文本或 base64 blob 连同 URI 与 MIME 类型客户端可以把它显示为附件或识别已认识的资源只发送指针则返回ResourceLink。图标Icon是元数据而非内容它通过srcURI 指向图片https:或无需额外抓取的data:URI可选mime_type、sizes如48x48或可缩放的any与themelight/dark。icons[...]关键字被MCPServer(...)、mcp.tool()、mcp.resource()、mcp.prompt()共同接受客户端分别在server_info.icons、tools/list的Tool、resources/list的Resource、prompts/list的Prompt上找到它们。详见 图像、音频与图标参考。错误处理Handling errors三种失败三种去处工具可能以三种方式失败SDK 对每种区别对待实现位于 src/mcp/server/mcpserver/exceptions.py抛出ToolError模型看到你的消息。调用仍然成功——存在结果调用方没有异常——但is_errorTrue你的消息前缀工具名就在模型读取的content中structured_content为None。这是工具告诉模型出事了的标准方式几乎总是你想要的模型读到No book titled Nothing in the catalog.意识到猜错了书名再用正确书名重试。服务器端只是一条无 traceback 的INFO日志。抛出MCPError协议看到它。它是工具包装器唯一不捕获的异常会向上传播使整个tools/call请求以 JSON-RPC 错误失败如{code: -32602, message: ...}没有结果、没有is_error主机应用像工具不存在一样收到它。code、message、data原样传递mcp.types以常量导出各错误码INVALID_PARAMS等不必手写魔法数字。抛出任何其他异常是一次崩溃。调用仍返回is_errorTrue模型知道失败并可以继续但模型只得到Error executing tool name——内部异常文本可能描述服务器内部细节所以绝不离开服务器。traceback 以ERROR级别进入你的日志。选择标准一句话一个更聪明的模型本可以避免这个错误吗能 →ToolError不能 →MCPError。执行层面的失败拼错书名、上游超时、行不存在是工具错误请求本身应被拒绝客户端缺能力、服务器状态不可服务、调用方跳过了必要步骤是协议错误。资源画着同一条线资源模板匹配任何标题但URI 合法与书存在是两回事只有你的函数能回答后者。回答不了时抛出ResourceNotFoundErrorSDK 将其转为规范指定的协议错误-32602并把请求的 URI 放进data{code: -32602, message: ..., data: {uri: books://Nothing}}。资源没有is_errorTrue半结果——读取要么返回内容要么失败。ResourceError是非未找到失败的同一机制-32603两者都只是一条INFO日志其他异常MCPError除外是崩溃。导入方式from mcp import MCPErrorfrom mcp.server.mcpserver.exceptions import ToolError, ResourceError, ResourceNotFoundError。还有一类你永远不需要写 raise的错误坏参数在进入函数前就被输入 schema 拒之门外以同样的is_errorTrue工具错误形式让模型可读、可纠正——不要重复校验自己的类型注解。完整对照与日志行为见 错误处理参考。下一步从索引页出发的阅读路径本节每个页面都自足可以直接跳到你需要的那一页还没建过服务器先从 快速上手First steps 开始而不是本节页面。你注册的函数内部发生什么——Context、依赖注入、调用中途向用户索要更多信息——属于下一节 Inside your handler处理器内部。各参考页面工具、结构化输出、资源、URI 模板与路径安全、提示词、自动补全、图像/音频与图标、错误处理均以可运行的docs_src/教程代码为骨架配套测试位于 tests/docs_src/如 test_tools.py、test_prompts.py可对照阅读验证行为。赞分享人工智能MCP 服务MCP Clients【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址https://gitcode.com/gh_mirrors/pythonsd/python-sdk点击查看免费下载相关推荐Zotero文献管理界面单调zotero-style插件让你的学术工作流焕然一新Zotero文献管理界面单调zotero style插件让你的学术工作流焕然一新 如果你是一名科研工作者、学生或学术研究者正在使用Zotero管理文献资料人工智能MCP 服务MCP Clientspython-sdk 服务端开发指南MCPServer 三大原语、可选能力与错误处理全解析python sdk 服务端开发指南MCPServer 三大原语、可选能力与错误处理全解析 MCPModel Context Protocol服务端向已连人工智能MCP 服务MCP ClientsEchoSet数据集深度解析TIGER-DnR如何应对复杂声学环境下的语音分离挑战EchoSet数据集深度解析TIGER DnR如何应对复杂声学环境下的语音分离挑战 TIGER DnRTime Frequency Interleaved人工智能MCP 服务MCP Clients创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考