MCP-Fehlerbehebung [In Arbeit]
⚠️ WICHTIG : Dieses Paket befindet sich derzeit in der Entwicklung und ist noch nicht für den Produktionseinsatz bereit. Die aktuelle Version ist noch in Arbeit und kann unvollständige Funktionen oder wichtige Änderungen enthalten.
Ein Selbstdiagnose-Framework für KI-Modelle, das es ihnen ermöglicht, MCP-bezogene Probleme zu diagnostizieren und zu beheben.
Architektur
Überblick
MCP Troubleshooter ist ein spezialisierter MCP-Server, der die Fehlerbehebung von einer reinen Entwickleraufgabe in eine Funktion verwandelt, die die KI selbst nutzen kann, sodass KI-Modelle Folgendes können:
- Analysieren Sie MCP-Protokolle – scannen Sie automatisch nach häufigen Fehlermustern und stellen Sie aufschlussreiche Diagnosen bereit
- Konfigurationen validieren – Serverkonfigurationen anhand bewährter Methoden prüfen und Probleme identifizieren
- Testverbindungen – Überprüfen der Netzwerkkonnektivität und Serververfügbarkeit
- Vorlagen generieren - Erstellen Sie funktionierende MCP-Serverkonfigurationen für eine schnelle Einrichtung
- Beheben Sie häufige Probleme – Aktualisieren Sie Konfigurationen und implementieren Sie Lösungen direkt
Installation
# Install the package globally
npm install -g @devlimelabs/mcp-troubleshooter
# Start the server
mcp-troubleshooter
Verwendung
Konfiguration für Claude Desktop
Fügen Sie dies zu Ihrer Claude Desktop-Konfiguration hinzu:
{
"mcpServers": {
"troubleshooter": {
"command": "mcp-troubleshooter"
}
}
}
Werkzeuge
- read-mcp-logs : Ruft MCP-Protokolldateien ab und zeigt sie an
- analyze-mcp-logs : Verwendet Mustererkennung, um häufige Fehlersignaturen zu identifizieren
- read-mcp-config : Extrahiert und validiert die MCP-Konfiguration von Claude Desktop
- update-mcp-config : Aktualisiert Konfigurationen sicher mit geeigneten Sicherungsmechanismen
- validate-mcp-server-config : Führt eine gründliche Validierung der Serverkonfigurationen durch
- test-port-availability : Überprüft, ob die erforderlichen Ports für MCP-Server verfügbar sind
- check-mcp-server-process : Überprüft, ob MCP-Serverprozesse korrekt ausgeführt werden
- generate-mcp-server-template : Erstellt benutzerdefinierte Servervorlagen für verschiedene Sprachen
- generate-claude-desktop-config : Erstellt optimierte Konfigurationsdateien für Claude Desktop
Ressourcen
- common-mcp-issues : Ein umfassender Leitfaden zu häufigen MCP-Problemen und deren Lösungen
- mcp-config-templates : Konfigurationsvorlagen für verschiedene MCP-Server-Setups
Beispiel-Anwendungsfälle
Diagnose eines defekten MCP-Servers
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?
Validieren der MCP-Konfiguration
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 : Zugriff auf Protokolle und Konfigurationen in
%APPDATA%\Claude\ - macOS : Greift auf Protokolle in
~/Library/Logs/Claude/ und Konfigurationen in ~/Library/Application Support/Claude/ - Linux : Zugriff auf Protokolle in
~/.local/share/Claude/logs/ und Konfigurationen in ~/.config/Claude/
Entwicklung
# 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
Lizenz
MIT