feat(marketplace): command consolidation + 8 new plugins (v8.1.0 → v9.0.0) [BREAKING]
Phase 1b: Rename all ~94 commands across 12 plugins to /<noun> <action> sub-command pattern. Git-flow consolidated from 8→5 commands (commit variants absorbed into --push/--merge/--sync flags). Dispatch files, name: frontmatter, and cross-reference updates for all plugins. Phase 2: Design documents for 8 new plugins in docs/designs/. Phase 3: Scaffold 8 new plugins — saas-api-platform, saas-db-migrate, saas-react-platform, saas-test-pilot, data-seed, ops-release-manager, ops-deploy-pipeline, debug-mcp. Each with plugin.json, commands, agents, skills, README, and claude-md-integration. Marketplace grows from 12→20. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
105
plugins/debug-mcp/skills/log-analysis.md
Normal file
105
plugins/debug-mcp/skills/log-analysis.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# Log Analysis Skill
|
||||
|
||||
Common MCP server error patterns, their root causes, and fixes.
|
||||
|
||||
## Error Pattern: ImportError
|
||||
|
||||
```
|
||||
ImportError: No module named 'pynetbox'
|
||||
```
|
||||
|
||||
**Root Cause:** Missing Python package in the virtual environment.
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
cd <server_cwd> && .venv/bin/pip install -r requirements.txt
|
||||
```
|
||||
|
||||
**Prevention:** Always run `pip install -r requirements.txt` after creating or updating a venv.
|
||||
|
||||
## Error Pattern: ConnectionRefused
|
||||
|
||||
```
|
||||
ConnectionRefusedError: [Errno 111] Connection refused
|
||||
```
|
||||
|
||||
**Root Cause:** The external service the MCP server connects to is not running or not reachable.
|
||||
|
||||
**Checks:**
|
||||
1. Is the target service running? (e.g., Gitea, NetBox)
|
||||
2. Is the URL correct in the env file?
|
||||
3. Is there a firewall or VPN issue?
|
||||
|
||||
**Fix:** Verify the service URL in `~/.config/claude/<server>.env` and confirm the service is accessible.
|
||||
|
||||
## Error Pattern: JSONDecodeError
|
||||
|
||||
```
|
||||
json.decoder.JSONDecodeError: Expecting value: line 1 column 1
|
||||
```
|
||||
|
||||
**Root Cause:** The server received non-JSON response from the external API. Usually means:
|
||||
- API returned HTML error page (wrong URL)
|
||||
- API returned empty response (auth failed silently)
|
||||
- Proxy intercepted the request
|
||||
|
||||
**Fix:** Check the API URL ends with the correct path (e.g., `/api/v1` for Gitea, `/api` for NetBox).
|
||||
|
||||
## Error Pattern: TimeoutError
|
||||
|
||||
```
|
||||
TimeoutError: timed out
|
||||
httpx.ReadTimeout:
|
||||
```
|
||||
|
||||
**Root Cause:** Server startup took too long or external API is slow.
|
||||
|
||||
**Checks:**
|
||||
1. Network latency to the external service
|
||||
2. Server doing heavy initialization (loading all tools)
|
||||
3. Large response from API
|
||||
|
||||
**Fix:** Increase timeout in server config or reduce initial tool registration.
|
||||
|
||||
## Error Pattern: PermissionError
|
||||
|
||||
```
|
||||
PermissionError: [Errno 13] Permission denied: '/path/to/file'
|
||||
```
|
||||
|
||||
**Root Cause:** Server process cannot read/write required files.
|
||||
|
||||
**Fix:** Check file ownership and permissions. Common locations:
|
||||
- `~/.config/claude/*.env` (should be readable by user)
|
||||
- Server's `.venv/` directory
|
||||
- Log files
|
||||
|
||||
## Error Pattern: FileNotFoundError (Venv)
|
||||
|
||||
```
|
||||
FileNotFoundError: [Errno 2] No such file or directory: '.venv/bin/python'
|
||||
```
|
||||
|
||||
**Root Cause:** Virtual environment does not exist or was deleted.
|
||||
|
||||
**Fix:** Create the venv:
|
||||
```bash
|
||||
cd <server_cwd> && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Error Pattern: SSL Certificate Error
|
||||
|
||||
```
|
||||
ssl.SSLCertVerificationError: certificate verify failed
|
||||
```
|
||||
|
||||
**Root Cause:** Self-signed certificate on the target service.
|
||||
|
||||
**Fix:** Set `VERIFY_SSL=false` in the env file (not recommended for production).
|
||||
|
||||
## Log Parsing Tips
|
||||
|
||||
1. **Python tracebacks** - Read from bottom up. The last line is the actual error.
|
||||
2. **JSON-RPC errors** - Look for `"error"` key in JSON responses.
|
||||
3. **Startup failures** - First few lines after server spawn reveal initialization issues.
|
||||
4. **Repeated errors** - Same error in a loop means the server is retrying and failing.
|
||||
Reference in New Issue
Block a user