MCP 故障排除程序 [正在进行中]
⚠️重要提示：此软件包目前处于开发阶段，尚未准备好投入生产使用。当前版本尚在开发中，可能包含不完整的功能或重大更改。
人工智能模型的自我诊断框架，使其能够诊断和修复与 MCP 相关的问题。
建筑学
概述
MCP Troubleshooter 是一个专门的 MCP 服务器，它将故障排除从仅限开发人员的任务转变为 AI 本身可以利用的功能，从而使 AI 模型能够：
- 分析 MCP 日志- 自动扫描常见错误模式并提供深刻的诊断
- 验证配置- 根据最佳实践检查服务器配置并识别问题
- 测试连接- 验证网络连接和服务器可用性
- 生成模板- 创建有效的 MCP 服务器配置以便快速设置
- 修复常见问题- 更新配置并直接实施解决方案
安装
# Install the package globally
npm install -g @devlimelabs/mcp-troubleshooter
# Start the server
mcp-troubleshooter
用法
Claude 桌面配置
将其添加到您的 Claude Desktop 配置中：
{
"mcpServers": {
"troubleshooter": {
"command": "mcp-troubleshooter"
}
}
}
工具
日志管理工具
- read-mcp-logs ：检索并显示 MCP 日志文件
- analyze-mcp-logs ：使用模式识别来识别常见的错误特征
配置工具
- read-mcp-config ：提取并验证 Claude Desktop 的 MCP 配置
- update-mcp-config ：使用适当的备份机制安全地更新配置
- valid-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 服务器
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?
平台支持
- Windows ：访问
%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
执照
麻省理工学院