python-sdk 服务端错误处理指南：ToolError、MCPError 与资源异常的完整选型

python-sdk 服务端错误处理指南ToolError、MCPError 与资源异常的完整选型【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdk导读在基于 python-sdkModel Context Protocol 官方 Python SDK开发 MCP 服务器时如何让工具tool与资源resource的失败以正确的方式呈现给模型、客户端与日志直接决定了智能体的自纠错能力与服务器的可观测性。本文以官方文档《Gérer les erreurs》docs/servers/handling-errors.md为骨架结合 SDK 源码src/mcp/server/mcpserver/exceptions.py、src/mcp/server/mcpserver/tools/base.py与配套测试tests/docs_src/test_handling_errors.py系统讲解三种失败路径的差异、判别准则、资源异常映射与 schema 预校验机制。读完本文你将能精准回答该抛哪种异常并写出可自我纠错、日志可诊断的 MCP 服务器。一个工具可以以三种方式失败SDK 文档开宗明义一个工具可以以三种方式失败而 SDK 对每一种的处理都截然不同抛出ToolError——模型看到你的消息抛出MCPError——协议看到它整条请求以 JSON-RPC 错误失败抛出任何其他异常——这是一次崩溃crash模型只知道调用失败而你的日志拿到完整 traceback。因此错误处理的核心不是怎么捕获而是**怎么选择**。下面逐一展开三种路径并用官方教程示例docs_src/handling_errors/验证每个结论。模型可以修正的错误ToolError最小示例先看一个执行查找的工具让它查找失败from mcp.server import MCPServer from mcp.server.mcpserver.exceptions import ToolError mcp MCPServer(Bookshop) CATALOG {Dune: Frank Herbert, Neuromancer: William Gibson} mcp.tool() def get_author(title: str) - str: Look up the author of a book in the catalog. if title not in CATALOG: raise ToolError(fNo book titled {title!r} in the catalog.) return CATALOG[title]完整代码见 docs_src/handling_errors/tutorial001.py。ToolError来自mcp.server.mcpserver.exceptions是工具向模型表达出了问题的通道。失败时的调用结果用一个目录里不存在的书名调用它观察返回结果result.is_error # True result.content # [TextContent(textError executing tool get_author: No book titled Nothing in the catalog.)] result.structured_content # None关键事实由 tests/docs_src/test_handling_errors.py 中的test_tool_error_becomes_a_tool_error_the_model_reads逐一断言请求是成功的。存在一个结果调用方没有抛出任何异常。is_error为True你的消息前缀了工具名出现在content里——正是模型读取的位置。structured_content为None。一次失败的调用没有返回值可供结构化。这就是工具错误tool error而且几乎总是你想要的。为什么这能造出自我纠错的智能体调用工具的是模型参数是它自己选的。所以一次工具错误就是对话中的一个回合模型读到No book titled Nothing in the catalog.意识到自己猜错了书名然后用一个更好的书名再次调用。你只写了一个raise就得到了一个会自我纠错的智能体。配套测试test_a_title_the_catalog_knows_is_an_ordinary_result验证了正常路径titleDune时is_error为False且structured_content {result: Frank Herbert}。服务端的日志表现在服务端一次ToolError只是一行INFO日志没有 traceback。测试test_tool_error_is_one_info_line精确断言服务端日志只有一条(INFO, None)记录exc_info为空且没有任何WARNING及以上级别的记录。因为你预见到了这次失败自然没什么需要排查的。不要把错误消息return出去!!! tip 永远不要用return从工具返回一条错误消息。返回的字符串is_errorFalse对模型以及所有客户端界面而言工具看起来成功运行了而这个字符串就是答案。请用raise。标志位is_error才是信号。模型无法修正的错误MCPError示例现在把ToolError换成MCPErrorfrom mcp import MCPError from mcp.server import MCPServer from mcp.types import INVALID_PARAMS mcp MCPServer(Bookshop) CATALOG {Dune: Frank Herbert, Neuromancer: William Gibson} mcp.tool() def get_author(title: str) - str: Look up the author of a book in the catalog. if title not in CATALOG: raise MCPError(codeINVALID_PARAMS, messagefNo book titled {title!r} in the catalog.) return CATALOG[title]完整代码见 docs_src/handling_errors/tutorial002.py。MCPError是 SDK 的协议错误protocol error定义于 src/mcp/shared/exceptions.py。它是工具包装器唯一不捕获的异常它会向外传播导致整条tools/call请求以一个 JSON-RPC 错误失败而不是返回结果{ code: -32602, message: No book titled Nothing in the catalog. }与 ToolError 的三个本质差异没有任何结果。没有content、没有is_error——模型无内容可读。收到错误的是宿主应用host就像这个工具根本不存在一样。code、message、data原样送达。INVALID_PARAMS即-32602mcp.types将它与其余 JSON-RPC 错误码INVALID_REQUEST、INTERNAL_ERROR……一起作为常量导出你永远不必手写魔法数字。mcp/types/__init__.py通过from mcp_types import *再导出这些常量。客户端的视角同样的查找、同样的失败但这次客户端抛出的是一次异常而非拿到结果mcp.shared.exceptions.MCPError: No book titled Nothing in the catalog.测试test_mcp_error_makes_the_call_itself_fail验证pytest.raises(MCPError)捕获到异常且code INVALID_PARAMS、message No book titled Nothing in the catalog.。第一版ToolError给了模型一句可以回应的句子这一版什么都没给它。对get_author而言这是严格更差的——这正是下一节要讲的选型问题。!!! infoMCPError通过from mcp import MCPError导入接受code、message以及可选的data载荷。你放进这些字段的内容就是客户端收到的内容SDK 会原样转发抛出的MCPError而不是净化它。从源码可见MCPError.__init__内部把三者组装成ErrorData(code, message, data)存入self.error并提供code/message/data只读属性。到底该抛哪一种一条判别准则两条路径回答的是两个不同的问题抛ToolError针对执行层面的失败——你的工具尝试去做的事没做成。模型选择了这次调用它理应看到后果并有机会补救。拼错的书名、上游 API 超时、不存在的数据库行——这些都是工具错误。抛MCPError当请求本身应当被拒绝时——客户端缺少你的工具所依赖的能力、服务器当前无法服务任何人、调用方跳过了某个必须的步骤。模型的任何重试都无法修复这些把消息交给它毫无收益。一个判断问题即可定夺一个更聪明的模型本来能避免这次失败吗能 → 抛ToolError不能 → 抛MCPError按这个标准get_author的第二版MCPError就做出了错误的选择换一个更好的书名就能解决模型理应看到这条消息。它存在的意义是展示机制而非示范最佳实践。任何其他异常一次崩溃现在移除检查让字典查找自己失败from mcp.server import MCPServer mcp MCPServer(Bookshop) CATALOG {Dune: Frank Herbert, Neuromancer: William Gibson} mcp.tool() def get_author(title: str) - str: Look up the author of a book in the catalog. return CATALOG[title]完整代码见 docs_src/handling_errors/tutorial004.py。CATALOG[title]抛出KeyError。你没有预料到它所以 SDK 把它当作一次崩溃result.is_error # True result.content # [TextContent(textError executing tool get_author)]模型看到的 vs. 你看到的调用仍然返回is_errorTrue模型知道它失败了可以去做别的事。但它拿不到异常文本来自你代码的KeyError或从三层之下的某个数据库驱动冒上来的 SQL 堆栈都可能描述你服务器的内部结构所以这段文本永远不会离开服务器。拿到它的是你。服务器以ERROR级别记录这次崩溃及完整 traceback标题为Tool get_author raised an unexpected exception。测试test_any_other_exception_is_a_crash_the_model_sees_generically精确断言了这一点日志中只有一条(ERROR, Tool get_author raised an unexpected exception)记录exc_info非空且其__cause__是KeyError。由此带来一个可观测性的优雅结果一个设置为WARNING的生产日志会对每一次ToolError保持沉默而一旦真有东西坏了就立刻出声。底层机制工具包装器的双层捕获从源码 src/mcp/server/mcpserver/tools/base.py 的Tool.run可以看清实现原理调用链被分成两层try每层都有针对MCPError的except MCPError: raise直通分支——这正是协议错误不被包装的实现基础其余异常按类型分流参数校验失败ValidationError→ 包装为ToolError(fError executing tool {name}: {exc})视为模型可读、可纠正的工具错误工具/解析器故意抛出的ToolError、ResourceError→ 保留原文本仅加前缀其他任何异常 → 包装为UnexpectedToolError(fError executing tool {name})丢弃原始文本仅通过__cause__保留给服务端日志这就是崩溃文本不离开服务器的代码级保证。UnexpectedToolError与UnexpectedResourceError的定义见 src/mcp/server/mcpserver/exceptions.pySDK 自己抛、你永远不抛专门用于区分崩溃与有意的ToolError。不存在的资源ResourceNotFoundError资源划出了同一条分界线并为最常见的情况准备了一个专门命名的异常。from mcp.server import MCPServer from mcp.server.mcpserver.exceptions import ResourceNotFoundError mcp MCPServer(Bookshop) CATALOG {Dune: Frank Herbert, Neuromancer: William Gibson} mcp.resource(books://{title}) def book(title: str) - str: The catalog entry for one book. if title not in CATALOG: raise ResourceNotFoundError(fNo book titled {title!r} in the catalog.) return f{title} by {CATALOG[title]}完整代码见 docs_src/handling_errors/tutorial003.py。模板 URI 的两问分离books://{title}是一个模板template。它匹配任意标题因此URI 格式良好与这本书存在是两个不同的问题而只有你的函数能回答第二个问题模板与 URI 的完整讲解见 docs/servers/resources.md。当它回答不了时抛出ResourceNotFoundError。SDK 把它转换为规范赋予缺失资源的协议错误-32602并把请求的 URI 放进data让客户端知道哪一次读取失败了{ code: -32602, message: No book titled Nothing in the catalog., data: {uri: books://Nothing} }测试test_resource_not_found_error_maps_to_invalid_params逐字段断言exc_info.value.error ErrorData(codeINVALID_PARAMS, messageNo book titled Nothing in the catalog., data{uri: books://Nothing})。资源只有协议这一条路注意这里没有is_errorTrue这种半截结果。资源读取要么返回内容、要么失败资源只有协议路径。ResourceError是非找不到类失败的对应物-32603携带你的消息例如读取权限或格式错误ResourceNotFoundError是ResourceError的-32602变体两者在源码中是继承关系src/mcp/server/mcpserver/exceptions.py两者在日志中都只是一行INFO除MCPError之外的任何其他异常都是一次崩溃客户端收到只提到 URI 的-32603traceback 以ERROR级别进入你的日志。类文档还揭示了另一个细节UnexpectedResourceError继承自ResourceError因此用except ResourceError包住MCPServer.read_resource()可以捕获一切读取失败——无论是有意的还是崩溃。你永远不需要抛的错误参数校验一个坏参数永远到不了你的函数。给get_author传一个不是字符串的titleSDK 会在调用你之前依据输入 schema 拒绝它并产生与模型可读、可纠正的ToolError同类的is_errorTrue工具错误。测试test_a_bad_argument_never_reaches_the_function用title42验证is_error为Truecontent中的文本包含 Input should be a valid string且函数体从未执行。test_a_bad_argument_is_an_info_line_not_a_crash进一步确认它只是一行无 traceback 的INFO日志。这意味着整整一类raise语句你都不必写不要重新校验你自己的类型注解。想了解用Field(le50)之类的约束触发同一拒绝机制可参考 docs/servers/tools.md。测试视角客户端看到的即断言到的!!! info 本页所有客户端能看到的东西你写测试时用的内存Client也都能看到。即使raise_exceptionsTrue也不会把失败工具的异常交还给调用方等到这个标志有机会起作用时你的异常早已变成了is_errorTrue的结果。所以要对结果做断言。如果你需要崩溃的 traceback它在服务器日志里而 pytest 的caplog能捕获它。该模式详见 docs/get-started/testing.md。test_raise_exceptions_does_not_turn_a_tool_error_into_a_traceback专门验证了这一边界Client(tutorial004.mcp, raise_exceptionsTrue)下崩溃工具仍然返回is_errorTrue的结果而不是抛出异常。速查该抛什么在工具里抛ToolError→ 调用返回is_errorTrue你的消息在content中。模型读到它并可以重试。抛MCPError→ 调用本身以 JSON-RPC 错误失败。模型看不到任何东西由宿主处理。code、message、data原样保留。决定性提问一个更聪明的模型本来能避免这次失败吗能 →ToolError不能 →MCPError。任何其他异常都是一次崩溃 → 模型只拿到Error executing tool name形式的is_errorTrue而你在ERROR记录中得到带 traceback 的完整详情。在资源处理器中抛ResourceNotFoundError→ 协议层的-32602URI 放进data。坏参数会在你的函数运行前被 schema 拒绝你不需要为它们写raise。导入方式from mcp import MCPErrorfrom mcp.server.mcpserver.exceptions import ToolError, ResourceError, ResourceNotFoundError错误码常量来自mcp.types如INVALID_PARAMS、INVALID_REQUEST、INTERNAL_ERROR。延伸阅读错误处理完毕这就是一个服务器对外暴露的全部内容。每个处理器在运行期间能读取什么、能对客户端做什么见 docs/handlers/index.md。你最可能遇到的 SDK 错误原文、各自含义与一键修复方案见 docs/troubleshooting.md。工具的参数校验与约束用法见 docs/servers/tools.md资源模板与 URI 细节见 docs/servers/resources.md。【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考