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.
|
||||
131
plugins/debug-mcp/skills/mcp-protocol.md
Normal file
131
plugins/debug-mcp/skills/mcp-protocol.md
Normal file
@@ -0,0 +1,131 @@
|
||||
# MCP Protocol Skill
|
||||
|
||||
Model Context Protocol (MCP) specification reference for debugging and development.
|
||||
|
||||
## Protocol Overview
|
||||
|
||||
MCP uses JSON-RPC 2.0 over stdio (standard input/output) for communication between Claude Code and MCP servers.
|
||||
|
||||
### Transport Types
|
||||
|
||||
| Transport | Description | Use Case |
|
||||
|-----------|-------------|----------|
|
||||
| **stdio** | JSON-RPC over stdin/stdout | Default for Claude Code |
|
||||
| **SSE** | Server-Sent Events over HTTP | Remote servers |
|
||||
|
||||
## Tool Definitions
|
||||
|
||||
Tools are the primary way MCP servers expose functionality.
|
||||
|
||||
### Tool Registration
|
||||
|
||||
```python
|
||||
@mcp.tool()
|
||||
def list_issues(state: str = "open", labels: list[str] = None) -> str:
|
||||
"""List issues from the repository.
|
||||
|
||||
Args:
|
||||
state: Issue state filter (open, closed, all)
|
||||
labels: Filter by label names
|
||||
"""
|
||||
# implementation
|
||||
```
|
||||
|
||||
### Tool Schema (JSON)
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "list_issues",
|
||||
"description": "List issues from the repository",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"state": {
|
||||
"type": "string",
|
||||
"enum": ["open", "closed", "all"],
|
||||
"default": "open",
|
||||
"description": "Issue state filter"
|
||||
},
|
||||
"labels": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "Filter by label names"
|
||||
}
|
||||
},
|
||||
"required": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Resource Definitions
|
||||
|
||||
Resources expose data that can be read by the client.
|
||||
|
||||
```python
|
||||
@mcp.resource("config://settings")
|
||||
def get_settings() -> str:
|
||||
"""Return current configuration."""
|
||||
return json.dumps(config)
|
||||
```
|
||||
|
||||
## Prompt Definitions
|
||||
|
||||
Prompts provide reusable prompt templates.
|
||||
|
||||
```python
|
||||
@mcp.prompt()
|
||||
def analyze_issue(issue_number: int) -> str:
|
||||
"""Generate a prompt to analyze a specific issue."""
|
||||
return f"Analyze issue #{issue_number} and suggest solutions."
|
||||
```
|
||||
|
||||
## JSON-RPC Message Format
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "list_issues",
|
||||
"arguments": {"state": "open"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response (Success)
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": {
|
||||
"content": [{"type": "text", "text": "..."}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response (Error)
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"error": {
|
||||
"code": -32600,
|
||||
"message": "Invalid Request"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| -32700 | Parse error (invalid JSON) |
|
||||
| -32600 | Invalid request |
|
||||
| -32601 | Method not found |
|
||||
| -32602 | Invalid params |
|
||||
| -32603 | Internal error |
|
||||
139
plugins/debug-mcp/skills/server-patterns.md
Normal file
139
plugins/debug-mcp/skills/server-patterns.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# MCP Server Patterns Skill
|
||||
|
||||
Standard patterns for building Python MCP servers compatible with Claude Code.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
mcp-servers/<name>/
|
||||
├── mcp_server/
|
||||
│ ├── __init__.py # Package marker
|
||||
│ ├── config.py # Configuration loader
|
||||
│ ├── server.py # Entry point (MCP server setup)
|
||||
│ └── tools/
|
||||
│ ├── __init__.py # Tool registration
|
||||
│ └── <category>.py # Tool implementations grouped by domain
|
||||
├── tests/
|
||||
│ ├── __init__.py
|
||||
│ └── test_tools.py
|
||||
├── requirements.txt
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## FastMCP Pattern (Recommended)
|
||||
|
||||
The FastMCP decorator pattern provides the simplest server implementation:
|
||||
|
||||
```python
|
||||
# server.py
|
||||
from mcp.server.fastmcp import FastMCP
|
||||
from .config import load_config
|
||||
|
||||
mcp = FastMCP("server-name")
|
||||
config = load_config()
|
||||
|
||||
# Import tools to register them
|
||||
from .tools import category # noqa: F401
|
||||
|
||||
if __name__ == "__main__":
|
||||
mcp.run()
|
||||
```
|
||||
|
||||
```python
|
||||
# tools/category.py
|
||||
from ..server import mcp, config
|
||||
|
||||
@mcp.tool()
|
||||
def my_tool(param: str) -> str:
|
||||
"""Tool description."""
|
||||
return f"Result for {param}"
|
||||
```
|
||||
|
||||
## Configuration Loader Pattern
|
||||
|
||||
```python
|
||||
# config.py
|
||||
import os
|
||||
from pathlib import Path
|
||||
from dotenv import load_dotenv
|
||||
|
||||
def load_config() -> dict:
|
||||
# System-level config
|
||||
sys_config = Path.home() / ".config" / "claude" / "<name>.env"
|
||||
if sys_config.exists():
|
||||
load_dotenv(sys_config)
|
||||
|
||||
# Project-level overrides
|
||||
project_env = Path.cwd() / ".env"
|
||||
if project_env.exists():
|
||||
load_dotenv(project_env, override=True)
|
||||
|
||||
config = {
|
||||
"api_url": os.getenv("<NAME>_API_URL"),
|
||||
"api_token": os.getenv("<NAME>_API_TOKEN"),
|
||||
}
|
||||
|
||||
# Validate required
|
||||
missing = [k for k, v in config.items() if v is None]
|
||||
if missing:
|
||||
raise ValueError(f"Missing config: {', '.join(missing)}")
|
||||
|
||||
return config
|
||||
```
|
||||
|
||||
## Entry Point Configuration
|
||||
|
||||
In `.mcp.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"<name>": {
|
||||
"command": "mcp-servers/<name>/.venv/bin/python",
|
||||
"args": ["-m", "mcp_server.server"],
|
||||
"cwd": "mcp-servers/<name>"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `-m` flag runs the module as a script, using `__main__.py` or the `if __name__ == "__main__"` block.
|
||||
|
||||
## Requirements
|
||||
|
||||
Minimum dependencies for an MCP server:
|
||||
|
||||
```
|
||||
mcp>=1.0.0
|
||||
python-dotenv>=1.0.0
|
||||
```
|
||||
|
||||
For HTTP-based integrations add:
|
||||
```
|
||||
httpx>=0.24.0
|
||||
```
|
||||
|
||||
## Testing Pattern
|
||||
|
||||
```python
|
||||
# tests/test_tools.py
|
||||
import pytest
|
||||
from mcp_server.tools.category import my_tool
|
||||
|
||||
def test_my_tool():
|
||||
result = my_tool("test")
|
||||
assert "test" in result
|
||||
```
|
||||
|
||||
## Startup Logging
|
||||
|
||||
Always log initialization status to stderr:
|
||||
|
||||
```python
|
||||
import sys
|
||||
|
||||
def log(msg):
|
||||
print(msg, file=sys.stderr)
|
||||
|
||||
log(f"MCP Server '{name}' initialized: {len(tools)} tools registered")
|
||||
```
|
||||
89
plugins/debug-mcp/skills/venv-diagnostics.md
Normal file
89
plugins/debug-mcp/skills/venv-diagnostics.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# Virtual Environment Diagnostics Skill
|
||||
|
||||
Patterns for checking virtual environment health in MCP server directories.
|
||||
|
||||
## Check 1: Venv Exists
|
||||
|
||||
```bash
|
||||
test -d <server_cwd>/.venv && echo "EXISTS" || echo "MISSING"
|
||||
```
|
||||
|
||||
If missing, the server will fail to start. Fix:
|
||||
```bash
|
||||
cd <server_cwd> && python3 -m venv .venv
|
||||
```
|
||||
|
||||
## Check 2: Python Binary Intact
|
||||
|
||||
Venvs can break when the system Python is upgraded (symlink becomes dangling).
|
||||
|
||||
```bash
|
||||
<server_cwd>/.venv/bin/python --version 2>&1
|
||||
```
|
||||
|
||||
If error contains "No such file or directory" despite .venv existing, the symlink is broken.
|
||||
|
||||
Fix:
|
||||
```bash
|
||||
cd <server_cwd> && rm -rf .venv && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
|
||||
```
|
||||
|
||||
**IMPORTANT:** Never delete .venv without explicit user approval. Show the diagnosis and ask user to confirm the fix.
|
||||
|
||||
## Check 3: Requirements Satisfied
|
||||
|
||||
Compare requirements.txt with installed packages:
|
||||
|
||||
```bash
|
||||
cd <server_cwd> && .venv/bin/pip freeze > /tmp/installed.txt
|
||||
```
|
||||
|
||||
Then diff against requirements.txt:
|
||||
- **Missing packages:** In requirements but not installed
|
||||
- **Version mismatch:** Installed version does not satisfy requirement specifier
|
||||
- **Extra packages:** Installed but not in requirements (usually OK, may indicate stale venv)
|
||||
|
||||
Quick check:
|
||||
```bash
|
||||
cd <server_cwd> && .venv/bin/pip check 2>&1
|
||||
```
|
||||
|
||||
This reports broken dependencies (missing or incompatible versions).
|
||||
|
||||
## Check 4: Module Import Test
|
||||
|
||||
Verify the server's main module can be imported:
|
||||
|
||||
```bash
|
||||
cd <server_cwd> && .venv/bin/python -c "import mcp_server.server" 2>&1
|
||||
```
|
||||
|
||||
Common failures:
|
||||
| Error | Cause | Fix |
|
||||
|-------|-------|-----|
|
||||
| `ModuleNotFoundError: No module named 'mcp'` | MCP SDK not installed | `pip install mcp` |
|
||||
| `ModuleNotFoundError: No module named '<pkg>'` | Missing dependency | `pip install -r requirements.txt` |
|
||||
| `ImportError: cannot import name 'X'` | Version mismatch | `pip install --upgrade <pkg>` |
|
||||
| `SyntaxError` | Python version too old | Check `python3 --version` >= 3.10 |
|
||||
|
||||
## Check 5: Broken Symlinks
|
||||
|
||||
Find broken symlinks in the venv:
|
||||
|
||||
```bash
|
||||
find <server_cwd>/.venv -type l ! -exec test -e {} \; -print 2>/dev/null
|
||||
```
|
||||
|
||||
Any output indicates broken symlinks that may cause import failures.
|
||||
|
||||
## Health Summary Format
|
||||
|
||||
```
|
||||
### Venv: <server_name>
|
||||
- Directory: EXISTS
|
||||
- Python: 3.11.2 (OK)
|
||||
- Packages: 12 installed, 10 required, 0 missing
|
||||
- Import: OK
|
||||
- Broken symlinks: 0
|
||||
- Status: HEALTHY
|
||||
```
|
||||
26
plugins/debug-mcp/skills/visual-header.md
Normal file
26
plugins/debug-mcp/skills/visual-header.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# Visual Header Skill
|
||||
|
||||
Standard visual header for debug-mcp commands.
|
||||
|
||||
## Header Template
|
||||
|
||||
```
|
||||
+----------------------------------------------------------------------+
|
||||
| DEBUG-MCP - [Context] |
|
||||
+----------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
## Context Values by Command
|
||||
|
||||
| Command | Context |
|
||||
|---------|---------|
|
||||
| `/debug-mcp status` | Server Status |
|
||||
| `/debug-mcp test` | Tool Test |
|
||||
| `/debug-mcp logs` | Log Analysis |
|
||||
| `/debug-mcp inspect` | Server Inspection |
|
||||
| `/debug-mcp scaffold` | Server Scaffold |
|
||||
| Agent mode | MCP Debugging |
|
||||
|
||||
## Usage
|
||||
|
||||
Display header at the start of every command response before proceeding with the operation.
|
||||
Reference in New Issue
Block a user