MCP Troubleshooter

MCP故障排除程序\[正在进行中\]

⚠️ 重要：该软件包目前正在开发中，尚未准备好投入生产使用。当前版本正在开发中，可能包含不完整的功能或破坏性更改。

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

建筑

flowchart TB
    Client["AI Model\n(e.g., Claude)"]
    
    subgraph "MCP Troubleshooter Server"
        LogTools["Log Management"]
        ConnTools["Connection Testing"]
        ConfigTools["Configuration Analysis"]
        FixTools["Fix Implementation"]
        
        subgraph "Log Analysis Engine"
            LogReader["Log Reader"]
            LogParser["Pattern Recognition"]
            ErrorClassifier["Issue Classification"]
        end
        
        subgraph "Connection Diagnostics"
            ConnTester["Transport Testing"]
            PortScanner["Port Availability"]
            HandshakeTester["Protocol Validation"]
        end
        
        subgraph "Configuration Manager"
            ConfigReader["Config Parser"]
            ConfigValidator["Schema Validation"]
            TemplateLibrary["Template Repository"]
        end
    end

    FileSystem["Host File System\n(Logs & Configs)"]
    OtherMCPs["Target MCP Servers"]
    
    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 Troubleshooter是一个专门的MCP服务器，它将故障排除从仅限开发人员的任务转换为AI本身可以利用的功能，允许AI模型：

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

安装

# Install the package globally
npm install -g @devlimelabs/mcp-troubleshooter

# Start the server
mcp-troubleshooter

用法

Claude桌面配置

将此添加到您的Claude Desktop配置中：

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

工具

日志管理工具

• 读取mcp日志：检索并显示MCP日志文件
• 分析mcp日志：使用模式识别来识别常见的错误特征

配置工具

• 读取mcp配置：提取并验证Claude Desktop的MCP配置
• 更新mcp配置：使用适当的备份机制安全地更新配置
• 验证mcp服务器配置：执行服务器配置的深度验证

连接测试工具

• 测试端口可用性：检查所需端口是否可用于MCP服务器
• 检查mcp服务器进程：验证MCP服务器进程是否正常运行

修复实施工具

• 生成mcp服务器模板：为不同语言创建自定义服务器模板
• 生成claude桌面配置：为Claude Desktop构建优化的配置文件

资源

• 常见的mcp问题：常见MCP问题及其解决方案的综合指南
• mcp配置模板：各种MCP服务器设置的配置模板

示例用例

诊断损坏的MCP服务器

User: My MCP server isn't connecting properly to Claude Desktop. Can you help diagnose it?

Claude: I'll help diagnose your MCP server connection issue. First, let me run some diagnostics.

[Uses check-mcp-server-process tool with the command from the user]

I've identified several possible issues with your MCP server:

1. **Connection Timeout**: The server isn't responding within the expected timeframe.
2. **JSON-RPC Format Error**: There seems to be a format issue in the JSON-RPC responses.
3. **Transport Mismatch**: Claude Desktop is expecting stdio transport, but your server might be using SSE.

Let me run a more specific connection test to confirm:

[Uses test-port-availability tool]

The connection test confirms that your server is starting, but it's timing out during the handshake phase. This is likely due to incorrect JSON-RPC message formatting in your server implementation.

Recommended fixes:
1. Ensure your server returns properly formatted JSON-RPC 2.0 responses
2. Check your transport implementation, it should be using proper stdio pipes
3. Verify that your server is correctly handling the initialize method

Would you like me to analyze a specific log file or check your server's code for these issues?

验证MCP配置

User: Can you validate my Claude Desktop MCP configuration?

Claude: I'd be happy to validate your Claude Desktop MCP configuration.

[Uses read-mcp-config tool]

I've analyzed your Claude Desktop configuration file. Here are my findings:

✅ **Valid Configuration Structure**: The overall structure of your configuration is valid.

⚠️ **Path Issues**: 2 servers have invalid paths:
- "code-llm": The file path "/usr/local/bin/code-llm" doesn't exist
- "database-tool": The command "db-tool" is not in the PATH

❌ **Environment Variables**: 1 server has missing required environment variables:
- "firebase-mcp": Missing required FIREBASE_API_KEY

✅ **Transport Configuration**: All servers properly specify transport options

Recommended fixes:
1. Update the path for "code-llm" to the correct location
2. Install "db-tool" or correct its path
3. Add the missing FIREBASE_API_KEY to the "firebase-mcp" server configuration

Would you like me to help you implement any of these fixes?

平台支持

• 视窗：访问中的日志和配置 %APPDATA%\Claude\
• macOS：访问登录 ~/Library/Logs/Claude/ 并配置 ~/Library/Application Support/Claude/
• Linux：访问登录 ~/.local/share/Claude/logs/ 并配置 ~/.config/Claude/

发展

# Clone the repository
git clone https://github.com/devlimelabs/master-mcps.git
cd master-mcps

# Install dependencies
pnpm install

# Build the package
pnpm -F @devlimelabs/mcp-troubleshooter build

# Run tests
pnpm -F @devlimelabs/mcp-troubleshooter test

许可证

麻省理工学院