SuperAPI AI 工具集
合作ENAI 行业资讯收藏
全部工具AI开发平台mcp-triage

mcp-triage

mcp-triage 是一个用于排查和修复 MCP（Model Context Protocol）客户端配置问题的命令行工具，同时也可作为 stdio MCP 服务器运行。它能够扫描机器上 8 种代理客户端的 MCP 配置，发现损坏或不稳定的配置项，用通俗英语解释问题，并在安全的前提下自动修复。检查内容包括 JSON 语法错误（如尾随逗号）、命令是否能在 PATH 中找到、缺失的环境变量引用、相对路径参数、明文 http:// 远程 URL、传输方式与配置项是否一致，以及同名服务器在不同客户端之间的配置漂移。可选的 --fix 只能机械性地修复解析失败的文件，并保留备份，其余问题仅给出提示，不会擅自修改。该项目零运行时依赖，采用 MIT 许可。

访问官网

工具介绍

mcp-triage 是一个面向 MCP（Model Context Protocol）客户端配置的诊断与修复工具，由 NeufAgents 开发。它的核心用途是帮助用户快速定位并解决因配置错误导致的 MCP 客户端无法启动或运行异常的问题。

主要能力

mcp-triage 可以扫描 8 种代理客户端的 MCP 配置：Claude Desktop、Claude Code（包括从 ~/.claude.json 中发现的项目级服务器）、Codex、Cursor、VS Code、Windsurf、OpenClaw 和 dsh。扫描过程中会执行以下检查（v0.1 版本）：

  • JSON 语法检查，包括经典的尾随逗号问题。
  • Codex 风格的 TOML 表基础检查。
  • 命令是否能在 PATH 中解析。
  • 缺失的 ${VAR} 或 process.env.VAR 引用。
  • 相对路径参数。
  • 明文 http:// 远程 URL。
  • 传输方式与配置项一致性（stdio 需要 command，HTTP 传输需要 url，dsh 条目需要 serverName）。
  • 同名服务器在不同客户端之间的配置漂移。

此外，OpenClaw 的 openclaw.json 文件是 JSON5 格式（允许注释和尾随逗号），工具会将其按 JSON5 解析，避免误报语法错误。

使用方式

mcp-triage 提供两种使用模式：

  1. CLI 模式：可直接在终端运行，即使客户端无法启动时也可使用。支持 --fix 选项进行机械性修复，仅针对解析失败的文件，会去除 JSON 注释和尾随逗号，并在写入前保存备份为 <file>.mcp-triage.bak（已有备份不会被覆盖）。修复后的文件必须能被解析为 JSON，否则不会写入。其他问题会以提示形式上报，不会猜测性修改。
  2. MCP 服务器模式：通过 mcp-triage serve 命令以 stdio MCP 服务器方式运行，提供 triage_scan（只读扫描）和 triage_fix（默认 dry-run，需显式传入 dry_run: false 才会写入）两个工具，让任何 MCP 客户端都能自行运行排查。

退出码说明：0 表示没有错误发现，1 表示至少有一个错误发现（使用 --fix 后为修复后的状态）。

适用场景

  • 当 MCP 客户端因配置问题无法启动或行为异常时，用于快速定位问题。
  • 在迁移或部署前，检查配置的健壮性。
  • 需要跨多个客户端统一管理 MCP 配置时，检测配置漂移。
  • 希望以只读方式了解配置健康状况时，使用 triage_scan。

限制与已知限制（v0.1）

  • 所有 8 个客户端路径均经过官方文档和/或真实机器验证（仓库中有验证日志 docs/verification-log.md）。OpenClaw 路径还会遵循 OPENCLAW_CONFIG_PATH；VS Code 包括 remote/WSL 用户配置（~/.vscode-server/data/User/mcp.json）。
  • JSON 客户端支持完整解析（OpenClaw 为 JSON5-light，即支持注释和尾随逗号；更复杂的 JSON5 特性仍会解析失败）。
  • TOML（Codex）仅支持基础检查，即 [mcp_servers.*] 表。
  • YAML（dsh cordis profiles）为轻量解析，仅提取 @deepseek-ai/dsh-mcp-client 补丁条目（serverName、transport、command、args、env、cwd；!!js 表达式保留为文本用于引用检查）。
  • 对无法归属到某个客户端的文件使用 --file 时，如果仅能按 JSON5 解析，会给出信息提示（而非错误），因为严格 JSON 客户端会拒绝此类文件。
  • 修复功能仅处理机械性删除（注释、尾随逗号），不涉及其他配置问题。

其他信息

  • 该项目零运行时依赖（包括服务器模式），采用 ESM 模块。
  • 开发和测试脚本直接导入 .ts 文件，需要 Node 22.18+；发布的包支持 Node 20+，扫描/--fix/serve 流程在 Node 20.19 上经过冒烟测试。
  • CI 在每次推送和拉取请求时，会在 Node 22 上运行完整测试套件，并在 Node 20 上运行构建和 --version 冒烟测试。
  • 库入口为 src/index.ts，可导入 discoverFiles、parseConfigFile、runChecks、applyFixes；CLI 二进制为 src/cli.ts；stdio MCP 服务器为 src/serve.ts，同时也从库入口重新导出。
  • 对于 --fix 无法处理的问题（如清洁扫描后客户端仍拒绝启动、需要在故障前加固配置、跨机器迁移），NeufAgents 提供付费修复服务，可将排查报告发送至 hi@neufagents.com，会在开始工作前提供书面范围说明。
  • 许可证为 MIT © NeufAgents (neufagents.com)。

同类工具

查看分类