MCP Inspector怎么调试工具？列参数、执行调用和定位错误

MCP 服务器能启动，不代表工具能被发现；工具能列出来，也不代表参数与返回结果正确。MCP Inspector 的命令行模式可以把这三件事拆开验证。本文用一个加法工具展示列参数、正常调用、故意传错参数以及检查退出码，适合已经有服务器、准备接入 AI 应用的开发者。

确认 Inspector 与运行环境

本文在 2026 年 10 月 1 日核对并运行了 @modelcontextprotocol/inspector@2.9.0，官方包声明要求 Node.js >=22.19.0；测试机使用 Node 24.14.1。Python 服务器采用 Python 3.11 和 mcp==2.2.0。不要把旧版 CLI 截图里的选项当成当前命令。

node --version
npx.cmd --version

以下是 Windows PowerShell 命令，使用 npx.cmd；macOS/Linux 改为 npx，并使用对应虚拟环境 Python 路径。首次运行 npx 会下载指定版本包，需要能够访问 npm。本文只测试本地 stdio 工具，无远端 OAuth 登录测试。

准备一个可控的调试对象

已有服务器可直接用自己的命令与参数。要复现本文，在测试目录创建虚拟环境并安装 mcp==2.2.0，然后把下面内容保存为 server.py：

from mcp.server import MCPServer

mcp = MCPServer("LocalCalc")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two integers and return their exact sum."""
    return a + b

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

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install "mcp==2.2.0"
$py = (Resolve-Path .\.venv\Scripts\python.exe).Path
$server = (Resolve-Path .\server.py).Path

示例先采用固定、无副作用的整数运算。这样返回值可以直接核对；如果调试一开始就连接真实数据库或收费 API，很难区分协议错误和外部业务故障。

第一层：发现工具并检查输入 Schema

npx.cmd -y @modelcontextprotocol/inspector@2.9.0 --cli $py $server --method tools/list --format json

运行后应在 JSON 的 result.tools 中找到 add。核对 inputSchema.properties 中 a、b 都是 integer，required 包含这两个字段。没有需要的工具时，先检查装饰器、实际启动的文件和工具名；不要跳到模型提示词调优。

Inspector 输出使用协议字段 inputSchema。Python SDK v2 对象属性使用 input_schema；它们属于不同表示方式，不能在 Python 代码中照搬 JSON 的驼峰字段。

第二层：执行有确定结果的正常调用

npx.cmd -y @modelcontextprotocol/inspector@2.9.0 --cli $py $server --method tools/call --tool-name add --tool-arg a=2 --tool-arg b=3 --format json
$LASTEXITCODE

本文实际得到的关键输出是：

{"result":{"content":[{"type":"text","text":"5"}],"structuredContent":{"result":5},"isError":false}}

退出码为 0。一次成功验收要同时看工具名、参数、isError 与返回值；单看命令完成或页面显示“连接成功”不够。--tool-arg 可以重复，值会尝试按 JSON 解释，所以 a=2 会成为数值。

第三层：故意制造错误，检查失败是否被识别

npx.cmd -y @modelcontextprotocol/inspector@2.9.0 --cli $py $server --method tools/call --tool-name add --tool-arg a=oops --tool-arg b=3 --format json
$LASTEXITCODE

这次测试得到 isError:true，CLI 退出码为 5，stderr 中包含 tool_is_error。SDK 的具体参数校验文本可能随版本变化；验收关注点是错误没有被伪装成成功数值。读取结构化输出和进程退出码，两层证据都要保留。

如果某个真实工具参数必须保留前导零，例如编码 "012"，逐个 key=value 的自动解析可能不符合你的预期。官方 v2 CLI 提供 --tool-args-json 整体传入 JSON，且不能与 --tool-arg 同时使用。需要复杂 JSON 时，优先生成参数文件内容或使用 SDK 客户端，避免在不同 shell 中反复猜引号。

根据哪一层失败定位问题

stdio 的 stdout 留给协议；日志写 stderr。把命令输出复制到 CI 时，失败退出码必须让后续步骤停下来，不能因为 stdout 里有 JSON 就判为成功。远端 HTTP 还要单独验证地址、认证和超时，这些没有被本地加法实验覆盖。

还需要图形界面吗？

CLI 适合保存可重复的连接、工具列表和调用结果。需要人工查看资源、提示模板或复杂交互时，可以运行 npx.cmd -y @modelcontextprotocol/inspector@2.9.0 启动 Web 模式，再按终端给出的本地入口连接。本文没有把 Web 界面点击操作列为实测，CLI 结果也不能证明远端登录或模型选择工具的效果。

参考：官方 CLI 方法、参数与退出语义；官方连接、发现、调用和断言流程；Inspector 项目及 Node 版本要求。