MCP 故障排除工具 [开发中]

⚠️ 重要提示: 该软件包当前正在开发中，尚未准备好用于生产环境。当前版本仍在开发中，可能包含不完整的功能或重大变更。

一个使AI模型能够诊断和修复MCP相关问题的自诊断框架。

架构

mermaid
flowchart TB
Client["AI 模型
（例如，Claude）"]

subgraph "MCP 故障排除服务器"
    LogTools["日志管理"]
    ConnTools["连接测试"]
    ConfigTools["配置分析"]
    FixTools["修复实现"]
    
    subgraph "日志分析引擎"
        LogReader["日志读取器"]
        LogParser["模式识别"]
        ErrorClassifier["问题分类"]
    end
    
    subgraph "连接诊断"
        ConnTester["传输测试"]
        PortScanner["端口可用性"]
        HandshakeTester["协议验证"]
    end
    
    subgraph "配置管理器"
        ConfigReader["配置解析器"]
        ConfigValidator["架构验证"]
        TemplateLibrary["模板库"]
    end
end

FileSystem["主机文件系统

（日志与配置）"]
OtherMCPs["目标MCP服务器"]

Client <--> LogTools
Client <--> ConnTools
Client <--> ConfigTools
Client <--> FixTools

LogTools --> LogAnalysisEngine
ConnTools --> ConnectionDiagnostics
ConfigTools --> ConfigurationManager

LogReader --> FileSystem
ConfigReader --> FileSystem
ConnTester --> OtherMCPs
FixTools --> FileSystem
FixTools --> OtherMCPs

style Client fill:#f9f,stroke:#333,stroke-width:2px
style FileSystem fill:#bbf,stroke:#333,stroke-width:2px
style OtherMCPs fill:#bbf,stroke:#333,stroke-width:2px
style "MCP Troubleshooter Server" fill:#eff,stroke:#333,stroke-width:4px

概述

MCP故障排除工具是一个专门的MCP服务器，它将故障排除从仅由开发者执行的任务转变为AI本身可以利用的能力，允许AI模型：

1. 分析MCP日志 - 自动扫描常见错误模式并提供有见地的诊断
2. 验证配置 - 根据最佳实践检查服务器配置并识别问题
3. 测试连接 - 验证网络连接性和服务器可用性
4. 生成模板 - 创建可快速设置的工作MCP服务器配置
5. 修复常见问题 - 直接更新配置并实施解决方案

安装

bash

全局安装软件包

npm install -g @devlimelabs/mcp-troubleshooter

启动服务器

mcp-troubleshooter

使用

Claude Desktop 的配置

在您的Claude Desktop配置中添加以下内容：

json
{
"mcpServers": {
"troubleshooter": {
"command": "mcp-troubleshooter"
}
}
}

工具

日志管理工具

• read-mcp-logs: 检索并显示MCP日志文件
• analyze-mcp-logs: 使用模式识别来识别常见的错误签名

配置工具

• read-mcp-config: 提取并验证Claude Desktop的MCP配置
• update-mcp-config: 通过适当的备份机制安全地更新配置
• validate-mcp-server-config: 对服务器配置进行深度验证

连接测试工具

• test-port-availability: 检查MCP服务器所需的端口是否可用
• check-mcp-server-process: 验证MCP服务器进程是否正确运行

修复实现工具

• generate-mcp-server-template: 为不同语言创建定制化的服务器模板
• generate-claude-desktop-config: 为Claude Desktop构建优化的配置文件

资源

• common-mcp-issues: 关于常见MCP问题及其解决方案的全面指南- mcp-config-templates: 各种MCP服务器设置的配置模板

示例用例

诊断故障的MCP服务器

用户：我的MCP服务器无法正确连接到Claude Desktop。你能帮我诊断一下吗？

Claude：我将帮助你诊断MCP服务器的连接问题。首先，让我运行一些诊断工具。

[使用check-mcp-server-process工具并执行用户的命令]

我已经识别出你的MCP服务器可能存在以下几个问题：

1. 连接超时：服务器在预期的时间内没有响应。
2. JSON-RPC格式错误：看起来JSON-RPC响应中存在格式问题。
3. 传输不匹配：Claude Desktop期望的是stdio传输，但你的服务器可能正在使用SSE。

让我运行一个更具体的连接测试来确认：

[使用test-port-availability工具]

连接测试确认你的服务器已启动，但在握手阶段超时。这可能是由于你的服务器实现中的JSON-RPC消息格式不正确导致的。

建议的修复措施：

1. 确保你的服务器返回正确格式化的JSON-RPC 2.0响应
2. 检查你的传输实现，它应该使用正确的stdio管道
3. 验证你的服务器是否正确处理了initialize方法

你想让我分析特定的日志文件或检查你的服务器代码以解决这些问题吗？

验证MCP配置

用户：你能验证我的Claude Desktop MCP配置吗？

Claude：我很乐意验证你的Claude Desktop MCP配置。

[使用read-mcp-config工具]

我已经分析了你的Claude Desktop配置文件。以下是发现的问题：

✅ 有效的配置结构：你的配置整体结构是有效的。

⚠️ 路径问题：2个服务器有无效路径：

• "code-llm"：文件路径"/usr/local/bin/code-llm"不存在
• "database-tool"：命令"db-tool"不在PATH中

❌ 环境变量：1个服务器缺少必需的环境变量：

• "firebase-mcp"：缺少必需的FIREBASE_API_KEY

✅ 传输配置：所有服务器都正确指定了传输选项

建议的修复措施：

1. 将"code-llm"的路径更新为正确的路径
2. 安装"db-tool"或修正其路径
3. 在"firebase-mcp"服务器配置中添加缺失的FIREBASE_API_KEY

你需要我帮你实施这些修复措施中的任何一个吗？

平台支持

• Windows：访问位于%APPDATA%Claude的日志和配置
• macOS：访问位于~/Library/Logs/Claude/的日志和位于~/Library/Application Support/Claude/的配置
• Linux：访问位于~/.local/share/Claude/logs/的日志和位于~/.config/Claude/的配置

开发

bash

克隆仓库

git clone https://github.com/devlimelabs/master-mcps.git
cd master-mcps

安装依赖

pnpm install

构建包

pnpm -F @devlimelabs/mcp-troubleshooter build

运行测试

pnpm -F @devlimelabs/mcp-troubleshooter test

许可证

MIT