`MCPServer` answers an unknown prompt name or a missing required argument with code `0` / `-32603`; the spec uses `-32602`

快速结论：这个报错通常出现在客户端通过 MCP Python SDK 调用 `prompts/get` 时，传入未注册的 prompt 名称或缺少 prompt 的必填参数；根因是 `MCPServer` 把这类参数错误当成普通 `ValueError` 抛出，导致旧协议返回 code `0`、2026-07-28 协议返回 `-32603`，而规范要求返回 `-32602`。优先确认所用 SDK 版本是否已包含对 prompt 参数错误的映射修复。

适用环境：Issue 已确认的环境为 Python 3.13.16，`mcp` 2.3.0（PyPI），并在 main@91941ed 上复现；协议线覆盖 2025-11-25 与 2026-07-28 两种线格式。Issue 未提及操作系统、CUDA、显卡或除 Python/MCP SDK 之外的依赖版本。

最快修复方案：暂无确认的一步修复方案。Issue 讨论中给出的修复思路是在 `MCPServer.get_prompt`（未知 prompt 名称）与 `Prompt.render`（缺少必填参数）两处改为抛出 `MCPError(INVALID_PARAMS)`，使两种协议模式都映射到 `-32602`，并同步更新测试与 `docs/servers/prompts.md`；该修复在讨论中称已在其 fork 中准备，但未在本 Issue 中确认为已合并的正式修复，可优先尝试升级到包含该修复的 SDK 版本，或按此思路在本地修改。

注意事项：不要把所有 prompt 异常都改成 `-32602`。讨论中明确区分：未知 prompt 名称与缺少必填参数属于参数错误，应为 `-32602`；prompt 函数内部真正抛出的运行时异常应保持为内部错误（`-32603`），且 traceback 只在服务端记录。`docs/servers/prompts.md` 目前把缺参情况记为 `-32603`，修复后属于文档行为变更。草稿 PR #2999 与 #1872 目前仍把前两种场景记为 divergence，是否已合并需以仓库实际状态为准。

问题场景

用户使用 MCP Python SDK 的 `MCPServer` 注册 prompt，并通过客户端调用 `get_prompt`。当客户端请求一个未注册的 prompt 名称，或调用已注册 prompt 但漏传必填参数时，期望得到 JSON-RPC `-32602`（Invalid params），实际在 legacy/2025-11-25 模式下收到 code `0`，在 2026-07-28 模式下收到 `-32603`。Issue 中的复现代码同时包含正常调用与 prompt 函数主动抛异常的情况，用于对比。

报错原文

unknown prompt name      -> code 0,  Unknown prompt: does_not_exist
missing required argument -> code 0,  Missing required arguments: {'name'}
prompt raises             -> code 0,  Error rendering prompt boom

2026-07-28 mode:
unknown prompt name      -> -32603, Internal server error
missing required argument -> -32603, Internal server error
prompt raises             -> -32603, Internal server error

原因分析

最可能的原因是 `MCPServer.get_prompt` 在遇到未知 prompt 名称时、`Prompt.render` 在遇到缺少必填参数时，直接抛出普通 `ValueError`，而 dispatcher 没有把这类参数错误转换为 JSON-RPC `-32602`。因此旧协议线把未归类异常映射为 code `0`，2026-07-28 协议线映射为 `-32603`，并且客户端拿不到具体是哪个 prompt 名称错误或缺少哪个参数。另一个可见差异是同一条根因导致两种协议线返回的消息内容不一致。prompt 函数自身抛出的异常属于真正的内部错误，不应归入 `-32602`。

环境排查

确认 `mcp` SDK 版本：Issue 在 `mcp` 2.3.0 与 main@91941ed 上复现。
确认 Python 版本：Issue 使用 Python 3.13.16。
确认客户端协商的协议版本：legacy/2025-11-25 与 2026-07-28 的返回码不同，排错时需分别观察。
确认请求的 prompt 名称是否已通过 `@server.prompt()` 注册，以及调用参数是否覆盖了 prompt 函数签名的全部必填参数。
如果使用自定义异常处理或包装了 dispatcher，确认没有把 `ValueError` 提前吞掉或改写为其他错误码。

解决步骤

先按 Issue 的复现代码确认现象：分别用 legacy 与 2026-07-28 模式调用未知 prompt、缺参调用和正常调用，记录返回的 code 与 message。
定位到 `MCPServer.get_prompt` 的未知 prompt 分支与 `Prompt.render` 的必填参数校验分支，确认它们当前抛出的是普通 `ValueError`。
按讨论中的修复思路，将这两类参数错误改为抛出 `MCPError(INVALID_PARAMS)`，使 dispatcher 在两种协议线下都返回 `-32602`；参考仓库中 `ResourceNotFoundError` 对资源的处理方式。
在错误 `data` 中保留具体 prompt 名称与缺失的参数名；不要为了让 2026-07-28 模式统一而把原因折叠成通用 “Internal server error”。
保持 prompt 函数内部抛出的真实异常仍映射为 `-32603`，traceback 仅记录在服务端，不返回给客户端。
同步更新单元测试、端到端测试和 interaction 测试（覆盖两种协议版本），以及 `docs/servers/prompts.md` 中当前记录为 `-32603` 的缺参行为说明。
如果不想自行修改 SDK，可优先尝试升级到已包含该修复的 `mcp` 版本；升级前先确认目标版本确实改变了 prompt 参数错误的映射。

验证方法

重新运行 Issue 中的复现代码，确认未知 prompt 名称与缺少必填参数在 legacy 和 2026-07-28 两种模式下均返回 `-32602`，且错误信息或 `data` 能指出具体 prompt 名称和缺失参数；正常调用仍返回 `GetPromptResult`；prompt 函数内部抛异常的场景仍返回内部错误（`-32603`），且客户端不暴露 traceback。同时确认 interaction 测试中对应的 divergence 记录已被断言或更新为预期行为。