AI导哈

MCP诊断工具

基于浏览器的工具，用于检查和诊断Model Context Protocol (MCP)服务器，支持自动化握手、工具测试和配置管理。

  • by Jens-AIMLX
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 Jens-AIMLX/mcp-diagnosis-tool

使用说明

MCP诊断工具

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

目录

特性

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

快速开始

git clone <repository-url>
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 → 错误，具有可扩展的详细信息
  4. 单击V形图标查看：
    • 握手元数据（传输、协议版本、服务器信息、功能、指令）
    • 工具（带有模式摘要、“测试”按钮、最后状态）
    • 提示和资源列表
  5. 对于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.<name>] 桌子。
  • 保存按钮在已采用该格式时禁用，以防止冗余导出。

转换由标准化的配置表示提供动力(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_<timestamp>_<server>_<tool>.md 带有降价内容：
    • 握手总结
    • 序列化服务器规范和参数
    • 工具输出或错误详细信息

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

REST API

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

端点 方法 描述
/api/diagnose POST 诊断单个服务器(`{ mode: "stdio"
/api/config/diagnose POST 规范和诊断MCP配置(configText，可选 configFormat).返回每台服务器的规范化配置+结果。
/api/config/add-server POST 将配置片段合并到现有的规范化配置中(baseConfig, additionText, additionFormat).
/api/config/export POST 将规范化配置转换为JSON或TOML(targetFormat).
/api/tools/call POST 调用 tools/call 在规格上（有效载荷与 /api/diagnose 加 toolName, toolArgs).

响应遵循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这是最好的努力，可能需要调整以匹配服务器特定的行为（超时、传输、模式变化）。欢迎投稿和问题报告！

诊断愉快！ 🚀

相关 MCP