| name | claude-health-analyzer |
| description | Auto-activate when ANY error message, crash, failure, timeout, disconnection, or degraded performance is detected across Claude Desktop, Claude Code, or Cowork. Triggers on: MCP server errors, connection failures, ENOENT/EACCES/ETIMEDOUT errors, 'server disconnected', 'spawn failed', 'Required parameter error', JSON parse failures, extension install failures, Docker container errors, Node.js version mismatches, PATH resolution failures, OAuth/SSO errors, keychain errors, memory/CPU spikes, tool not available, transport mismatch, and any stderr output from MCP logs. Also use proactively when performing health checks, system diagnostics, or preventive maintenance on Claude product ecosystems. |
Claude Ecosystem Health Analyzer & Fixer v1.0
An intelligent diagnostic skill that automatically detects, analyzes, and resolves issues across Claude Desktop, Claude Code, and Cowork (beta). Operates as an always-on health monitor that activates when errors are detected and provides automated remediation.
Activation Triggers
This skill MUST activate when ANY of these patterns are detected:
Error Message Patterns
# MCP Server Errors
- "server disconnected"
- "spawn ENOENT"
- "EACCES: permission denied"
- "ETIMEDOUT"
- "connection refused"
- "Required parameter error"
- "Invalid arguments for"
- "AbortError: The operation was aborted"
- "Command failed"
- "SyntaxError: The requested module"
- "does not provide an export named"
# Configuration Errors
- "Invalid JSON"
- "Unexpected token"
- "Cannot find module"
- "MODULE_NOT_FOUND"
- "ENOENT: no such file or directory"
# Authentication/Transport Errors
- "401 Unauthorized"
- "OAuth" + "error"
- "SecKeychainSearchCopyNext"
- "keychain" + "not found"
- "transport" + "error"
# Performance/Resource Errors
- "out of memory"
- "heap out of memory"
- "ENOMEM"
- "context window" + "exceeded"
- "rate limit"
- "429"
# Docker/Container Errors
- "docker" + "error"
- "container" + "exited"
- "port" + "already in use"
- "EADDRINUSE"
Proactive Triggers
- User says "health check", "diagnose", "troubleshoot", "fix", "broken", "not working"
- User mentions "MCP" + any negative word (failing, broken, stuck, error, crash)
- User mentions "slow", "timeout", "hang" related to Claude products
- After any system change (new MCP server added, config edited, extension installed)
Diagnostic Framework
Phase 1: DETECT - Error Classification
| Category | Priority | Examples |
|---|
| CRITICAL | P0 | Total MCP failure, all tools broken, data loss risk |
| HIGH | P1 | Specific MCP server down, auth failures, config corruption |
| MEDIUM | P2 | Performance degradation, intermittent failures, warnings |
| LOW | P3 | Deprecated warnings, non-blocking issues, optimization |
Phase 2: DIAGNOSE - Root Cause Analysis
Follow this diagnostic tree IN ORDER:
-
IDENTIFY PRODUCT
- Claude Desktop: Check %APPDATA%\Claude\claude_desktop_config.json (Windows)
- Claude Code: Check ~/.claude.json and .mcp.json
- Cowork: Check application-specific settings
-
CHECK LOGS
- Claude Desktop MCP logs: %APPDATA%\Claude\logs\mcp-server-*.log
- Claude Code: stderr output, terminal logs
- Docker containers: docker logs <container_name>
-
VERIFY DEPENDENCIES
- Node.js version (must be >=18.17 for MCP)
- Python version (if Python MCP servers used)
- Docker daemon status
- Network connectivity
- Disk space / memory availability
-
TEST CONNECTIVITY
- MCP server responds to ping/health check
- Transport type matches server capability (stdio vs http vs sse)
- Authentication tokens valid and not expired
- Port availability for HTTP/SSE transports
Phase 3: FIX - Automated Remediation
MCP Server Connection Failures
# Step 1: Verify config JSON
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" | ConvertFrom-Json
# Step 2: Check if command exists
where.exe node
where.exe npx
where.exe docker
# Step 3: For Docker servers - verify container health
docker ps --filter "name=mcp" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
# Step 4: Test server directly
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' | node server.js
PATH Resolution Failures (ENOENT)
# Find the actual binary location
where.exe node
where.exe npx
where.exe python
# Use the FULL PATH in config instead of just "npx" or "node"
Transport Mismatch Errors
{
"mcpServers": {
"server-name": {
"command": "docker",
"args": ["run", "-i", "--rm", "-p", "8080:8080", "image-name"],
"transport": {
"type": "http",
"url": "http://localhost:8080/mcp"
}
}
}
}
Docker Container Errors
docker ps -a --filter "name=mcp"
docker restart <container_name>
netstat -ano | findstr :<port>
docker build --no-cache -t <image> .
Node.js Version Mismatch
node --version
# Minimum: v18.17.0, Recommended: v22.x LTS
nvm install 22
nvm use 22
Phase 4: VERIFY - Post-Fix Validation
- Restart affected product (Claude Desktop = full quit+relaunch)
- Check MCP server connection (hammer icon in Claude Desktop)
- Test a simple tool call
- Monitor logs for 60 seconds
- Report results with before/after comparison
Auto-Fix Recipes
Recipe 1: MCP Server Not Showing Up
- Validate config JSON syntax
- Check command path exists
- Verify Node.js >= 18.17
- Restart Claude Desktop completely
- Check hammer icon appears
Recipe 2: Required Parameter Error
- Check status.anthropic.com (often upstream)
- Verify tool schemas are valid
- Update Claude Desktop to latest version
Recipe 3: Server Disconnected After 60s
- Check transport type matches server
- For Docker: add -i flag for interactive mode
- For HTTP servers: add transport config
- Check server logs for crashes
Recipe 4: ENOENT / spawn failed
- Find full path: where.exe node
- Replace npx with full path in config
- Ensure Docker daemon is running
Recipe 5: Docker MCP Container Errors
- docker info (check daemon)
- docker ps -a (list containers)
- docker logs (check logs)
- Verify no port conflicts
- Check Docker API not exposed externally
Recipe 6: Performance Degradation
- Check system resources
- Count active MCP servers
- Check for memory leaks
- Review Docker resource limits
Response Format
When this skill activates:
HEALTH ANALYZER ACTIVATED
Product: [Claude Desktop / Claude Code / Cowork]
Severity: [CRITICAL/HIGH/MEDIUM/LOW]
Error: [error message summary]
Root Cause: [identified cause]
Fix: [applied or recommended fix]
Status: [RESOLVED / IN PROGRESS / ESCALATED]
Official Documentation References
