MCP Diagnosis Tool

MCP诊断工具

MCP诊断工具是一个基于浏览器的检查工具 模型上下文协议（MCP） 服务器。它使握手自动化，列出工具/提示/资源，捕获握手元数据，并为测试工具提供快速操作。您可以加载完整的MCP配置（JSON或Codex风格的TOML），合并其他服务器定义，并在格式之间进行转换。

目录

• 特性
• 快速开始
• 诊断单个服务器
• 使用MCP配置

- 加载配置（JSON或TOML） - 添加服务器代码段 - 保存/转换配置 - 配置如何正常化

• 工具测试和报告
• REST API
• 实施概述
• 免责声明

特性

• 连接诊断 用于stdio、流式HTTP和SSE传输，具有超时处理和丰富的错误分类。
• 能力发现 显示工具/提示/资源、握手元数据和协议版本。
• 工具试验机 它呈现参数模式，通过模态形式收集输入，运行该工具，并生成Markdown报告（包括计时和输出）。
• 配置管理UI 负载 mcp.json 或Codex config.toml，合并其他代码段，并导出任一格式——非常适合格式转换工作流。
• 后端正常化 确保一致的数据结构、确定性合并和格式保持导出。

快速开始

git clone 
cd mcp-diagnosis-tool
npm install
npm start

打开 http://localhost:3000 在您的浏览器中。要更改端口，请使用 PORT=4000 npm start.

先决条件： Node.js≥18，npm，用于Streamable HTTP诊断的网络访问，以及您想要测试的任何MCP服务器。

诊断单个服务器

1. 选择 超文本传输协议 或 工作室 在UI顶部的表单中。
2. 提供MCP URL（HTTP）或命令行以启动stdio服务器。
3. 点击 诊断。该条目出现在“已知MCP服务器”列表中：

- 琥珀色圆点→ 进行中 - 绿色→ 工具/提示/资源计数成功 - Red → 错误，具有可扩展的详细信息

1. 单击V形图标查看：

- 握手元数据（传输、协议版本、服务器信息、功能、指令） - 工具（带有模式摘要、“测试”按钮、最后状态） - 提示和资源列表

1. 对于stdio条目，命令会重新显示，参数会被拆分。

使用MCP配置

加载配置（JSON或TOML）

• 加载标准mcp.json： 按照OpenAI MCP客户端模式选择JSON文件(mcpServers 对象）。
• 加载mcp.toml： 选择Codex风格的TOML配置(mcp_servers 表和可选的顶级标志）。

加载配置时：

• 后端对字段名进行标准化(bearer_token_env_var → bearerTokenEnvVar等等）。
• UI对每个服务器条目重新运行诊断并显示结果。
• 状态标签显示文件名、格式和服务器计数。
• 根据源格式启用“另存为”按钮。

添加服务器代码段

使用 添加服务器（JSON） 或 添加服务器（TOML） 按钮：

• 一个模态以指令和文本区域打开。
• 粘贴包含以下内容之一的代码段 mcpServers 对象（JSON）或 [mcp_servers.*] 桌子（TOML）。
• 点击 合并 将代码段发送到后端。
• 服务器将新定义合并到现有配置中（按名称覆盖），重新诊断完整列表，并刷新UI。

模态合并到当前加载的任何配置上。如果没有加载，则代码段将成为新的配置。

保存/转换配置

• 另存为JSON 产生规范 mcp.json 与顶级 mcpServers 对象。
• 另存为TOML 使用嵌套转换为Codex样式的TOML [mcp_servers.] 桌子。
• 保存按钮在已采用该格式时禁用，以防止冗余导出。

转换由标准化的配置表示提供动力(format, topLevel, servers)，确保：

• 顶级按键，如 experimental_use_rmcp_client, tool_timeout_sec等等。
• 服务器条目包括一致的密钥(command, args, env, url, bearer_token_env_var等等）。

配置如何正常化

在内部，配置表示为：

{
  "format": "json" | "toml",
  "topLevel": { ... },           // Non-server keys
  "servers": [
    {
      "name": "playwright",
      "mode": "stdio" | "http",
      "command": "...",           // stdio only
      "args": ["..."],            // stdio only
      "env": { "KEY": "VALUE" },
      "url": "...",               // http only
      "bearerTokenEnvVar": "...", // http optional
      "bearerTokenFile": "...",
      "startupTimeoutSec": 15,
      "toolTimeoutSec": 60,
      "enabled": true,
      "extra": {...}              // unrecognised fields retained
    }
  ]
}

序列化器在导出时重建精确的JSON或TOML模式，因此您可以在不丢失元数据的情况下往返。

工具测试和报告

• 点击 测试 在工具旁边打开工具模式。
• 如果服务器暴露 inputSchema，模态呈现关于类型、枚举和所需标志的表单字段。
• 提交跑步记录 tools/call 并捕获开始/结束时间戳、持续时间、传输和握手。
• 下载报告 （运行后启用）生成 MCPDiagnois_Report___.md 带有降价内容：

- 握手总结 - 序列化服务器规范和参数 - 工具输出或错误详细信息

报告非常适合审计或与团队成员分享诊断结果。

REST API

UI后面是一个Express API，您可以通过编程集成：

响应遵循UI中使用的相同形状。看 server.js 获取完整的请求/响应详细信息。

实施概述

• server.js –Express服务器公开诊断/配置端点并托管静态资产。
• mcpDoctor.js –通过以下方式连接 @modelcontextprotocol/sdk，处理超时/错误分类，规范配置，合并添加，并序列化JSON/TOML。
• public/ –香草JS UI，带有：

- 配置管理栏(public/index.html, public/style.css) - 带有可扩展卡的诊断服务器仪表板 - 工具测试器和配置合并模块(public/script.js)

• 测试 – node:test 套房在 test/mcpDoctor.test.js 涵盖解析、合并和诊断。

版本历史

1.0.1

• 添加了应用内配置管理控件：查看/编辑服务器配置片段，通过模态合并更新，以及在不离开UI的情况下从活动配置中删除服务器。
• 统一的保存按钮，因此JSON和TOML导出始终可用，无论源格式如何，只需单击一下即可进行格式转换。
• 改进了对每台服务器元数据（代码段、规范化条目）的后端支持，并公开了用于添加/删除服务器的专用端点。
• 更新了UI，以显示特定于配置的控件以及诊断，与上面屏幕截图中的布局相匹配。

1.0.0

• 初始版本包含核心诊断（stdio/HTTP/SSE）、功能列表、错误分类以及带有Markdown报告生成的工具测试模式。
• 介绍了JSON/TOML配置加载、规范化和转换流程。
• 交付了黑暗主题的仪表板，用于在单个会话中跟踪多个MCP服务器。

免责声明

此实用程序取决于MCP服务器实现的稳定性和 @modelcontextprotocol/sdk这是最好的努力，可能需要调整以匹配服务器特定的行为（超时、传输、模式变化）。欢迎投稿和问题报告！

诊断愉快！ 🚀