Solucionador de problemas de MCP [en progreso]
⚠️ IMPORTANTE : Este paquete se encuentra actualmente en desarrollo y aún no está listo para producción. La versión actual está en desarrollo y puede contener funciones incompletas o cambios importantes.
Un marco de autodiagnóstico para modelos de IA que les permite diagnosticar y solucionar problemas relacionados con MCP.
Arquitectura
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
Related MCP server: MCPfinder Server
Descripción general
MCP Troubleshooter es un servidor MCP especializado que transforma la resolución de problemas de una tarea exclusiva para desarrolladores en una capacidad que la propia IA puede aprovechar, lo que permite a los modelos de IA:
Analice los registros de MCP : escanee automáticamente en busca de patrones de errores comunes y proporcione diagnósticos detallados
Validar configuraciones : comprobar las configuraciones del servidor según las mejores prácticas e identificar problemas
Probar conexiones : verificar la conectividad de la red y la disponibilidad del servidor
Generar plantillas : cree configuraciones de servidor MCP funcionales para una configuración rápida
Solucione problemas comunes : actualice las configuraciones e implemente soluciones directamente
Instalación
# Install the package globally
npm install -g @devlimelabs/mcp-troubleshooter
# Start the server
mcp-troubleshooter
Uso
Configuración para Claude Desktop
Añade esto a tu configuración de Claude Desktop:
{
"mcpServers": {
"troubleshooter": {
"command": "mcp-troubleshooter"
}
}
}
Herramientas
Herramientas de gestión de registros
Herramientas de configuración
read-mcp-config : extrae y valida la configuración MCP de Claude Desktop
update-mcp-config : actualiza de forma segura las configuraciones con mecanismos de respaldo adecuados
validate-mcp-server-config : Realiza una validación profunda de las configuraciones del servidor
Herramientas de prueba de conexión
test-port-availability : comprueba si los puertos requeridos están disponibles para los servidores MCP
check-mcp-server-process : verifica si los procesos del servidor MCP se están ejecutando correctamente
Herramientas de implementación de arreglos
Recursos
Ejemplos de casos de uso
Diagnóstico de un servidor MCP dañado
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?
Validación de la configuración de 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?
Soporte de plataforma
Windows : accede a registros y configuraciones en %APPDATA%\Claude\
macOS : accede a los registros en ~/Library/Logs/Claude/ y a las configuraciones en ~/Library/Application Support/Claude/
Linux : accede a los registros en ~/.local/share/Claude/logs/ y a las configuraciones en ~/.config/Claude/
Desarrollo
# 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
Licencia
Instituto Tecnológico de Massachusetts (MIT)
