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>
2026-02-06 14:52:11 -05:00
parent 5098422858
commit 2d51df7a42
321 changed files with 13582 additions and 1019 deletions
--- a/plugins/debug-mcp/commands/debug-mcp-inspect.md
+++ b/plugins/debug-mcp/commands/debug-mcp-inspect.md
@@ -0,0 +1,129 @@
+---
+name: debug-mcp inspect
+description: Inspect MCP server configuration, dependencies, and tool definitions
+---
+
+# /debug-mcp inspect
+
+Deep inspection of an MCP server's configuration, dependencies, and tool definitions.
+
+## Skills to Load
+
+- `skills/visual-header.md`
+- `skills/venv-diagnostics.md`
+- `skills/mcp-protocol.md`
+
+## Agent
+
+Delegate to `agents/mcp-debugger.md`.
+
+## Usage
+
+```
+/debug-mcp inspect <server_name> [--tools] [--deps] [--config]
+```
+
+**Arguments:**
+- `server_name` - Name of the MCP server from .mcp.json
+
+**Options:**
+- `--tools` - List all registered tools with their schemas
+- `--deps` - Show dependency analysis (installed vs required)
+- `--config` - Show configuration files and environment variables
+- (no flags) - Show all sections
+
+## Instructions
+
+Execute `skills/visual-header.md` with context "Server Inspection".
+
+### Phase 1: Configuration
+
+1. Read `.mcp.json` and extract the server definition
+2. Display:
+   - Server name
+   - Command and arguments
+   - Working directory
+   - Environment variable references
+
+```
+## Server: gitea
+
+### Configuration (.mcp.json)
+- Command: /path/to/mcp-servers/gitea/.venv/bin/python
+- Args: ["-m", "mcp_server.server"]
+- CWD: /path/to/mcp-servers/gitea
+- Env file: ~/.config/claude/gitea.env
+```
+
+### Phase 2: Dependencies (--deps)
+
+Apply `skills/venv-diagnostics.md`:
+
+1. Read `requirements.txt` from the server's cwd
+2. Compare with installed packages:
+   ```bash
+   cd <cwd> && .venv/bin/pip freeze
+   ```
+3. Identify:
+   - Missing packages (in requirements but not installed)
+   - Version mismatches (installed version differs from required)
+   - Extra packages (installed but not in requirements)
+
+```
+### Dependencies
+
+| Package | Required | Installed | Status |
+|---------|----------|-----------|--------|
+| mcp | >=1.0.0 | 1.2.3 | OK |
+| httpx | >=0.24 | 0.25.0 | OK |
+| pynetbox | >=7.0 | — | MISSING |
+
+- Missing: 1 package
+- Mismatched: 0 packages
+```
+
+### Phase 3: Tools (--tools)
+
+Parse the server source code to extract tool definitions:
+
+1. Find Python files with `@mcp.tool` decorators or `server.add_tool()` calls
+2. Extract tool name, description, and parameter schema
+3. Group by module/category if applicable
+
+```
+### Tools (42 registered)
+
+#### Issues (6 tools)
+| Tool | Description | Params |
+|------|-------------|--------|
+| list_issues | List issues from repository | state?, labels?, repo? |
+| get_issue | Get specific issue | issue_number (required) |
+| create_issue | Create new issue | title (required), body (required) |
+...
+```
+
+### Phase 4: Environment Configuration (--config)
+
+1. Locate env file referenced in .mcp.json
+2. Read the file (mask secret values)
+3. Check for missing required variables
+
+```
+### Environment Configuration
+
+File: ~/.config/claude/gitea.env
+| Variable | Value | Status |
+|----------|-------|--------|
+| GITEA_API_URL | https://gitea.example.com/api/v1 | OK |
+| GITEA_API_TOKEN | ****...a1b2 | OK |
+
+File: .env (project level)
+| Variable | Value | Status |
+|----------|-------|--------|
+| GITEA_ORG | personal-projects | OK |
+| GITEA_REPO | leo-claude-mktplace | OK |
+```
+
+## User Request
+
+$ARGUMENTS
--- a/plugins/debug-mcp/commands/debug-mcp-logs.md
+++ b/plugins/debug-mcp/commands/debug-mcp-logs.md
@@ -0,0 +1,98 @@
+---
+name: debug-mcp logs
+description: View recent MCP server logs and error patterns
+---
+
+# /debug-mcp logs
+
+View and analyze recent MCP server log output.
+
+## Skills to Load
+
+- `skills/visual-header.md`
+- `skills/log-analysis.md`
+
+## Agent
+
+Delegate to `agents/mcp-debugger.md`.
+
+## Usage
+
+```
+/debug-mcp logs [--server=<name>] [--lines=<count>] [--errors-only]
+```
+
+**Options:**
+- `--server` - Filter to a specific server (default: all)
+- `--lines` - Number of recent lines to show (default: 50)
+- `--errors-only` - Show only error-level log entries
+
+## Instructions
+
+Execute `skills/visual-header.md` with context "Log Analysis".
+
+### Phase 1: Locate Log Sources
+
+MCP servers in Claude Code output to stderr. Log locations vary:
+
+1. **Claude Code session logs** - Check `~/.claude/logs/` for recent session logs
+2. **Server stderr** - If server runs as a subprocess, logs go to Claude Code's stderr
+3. **Custom log files** - Some servers may write to files in their cwd
+
+Search for log files:
+```bash
+# Claude Code logs
+ls -la ~/.claude/logs/ 2>/dev/null
+
+# Server-specific logs
+ls -la <server_cwd>/*.log 2>/dev/null
+ls -la <server_cwd>/logs/ 2>/dev/null
+```
+
+### Phase 2: Parse Logs
+
+1. Read the most recent log entries (default 50 lines)
+2. Filter by server name if `--server` specified
+3. If `--errors-only`, filter for patterns:
+   - Lines containing `ERROR`, `CRITICAL`, `FATAL`
+   - Python tracebacks (`Traceback (most recent call last)`)
+   - JSON-RPC error responses (`"error":`)
+
+### Phase 3: Error Analysis
+
+Apply patterns from `skills/log-analysis.md`:
+
+1. **Categorize errors** by type (ImportError, ConnectionError, TimeoutError, etc.)
+2. **Count occurrences** of each error pattern
+3. **Identify root cause** using the common patterns from the skill
+4. **Suggest fix** for each error category
+
+### Phase 4: Report
+
+```
+## MCP Server Logs
+
+### Server: gitea
+Last 10 entries:
+[2025-11-15 10:00:01] INFO  Initialized with 42 tools
+[2025-11-15 10:00:05] INFO  Tool call: list_issues (245ms)
+...
+
+### Server: netbox
+Last 10 entries:
+[2025-11-15 09:58:00] ERROR ImportError: No module named 'pynetbox'
+
+### Error Summary
+
+| Server | Error Type | Count | Root Cause | Fix |
+|--------|-----------|-------|------------|-----|
+| netbox | ImportError | 3 | Missing dependency | pip install pynetbox |
+
+### Recommendations
+1. Fix netbox: Reinstall dependencies in venv
+2. All other servers: No issues detected
+```
+
+## User Request
+
+$ARGUMENTS
--- a/plugins/debug-mcp/commands/debug-mcp-scaffold.md
+++ b/plugins/debug-mcp/commands/debug-mcp-scaffold.md
@@ -0,0 +1,138 @@
+---
+name: debug-mcp scaffold
+description: Generate a new MCP server skeleton project with standard structure
+---
+
+# /debug-mcp scaffold
+
+Generate a new MCP server project with the standard directory structure, entry point, and configuration.
+
+## Skills to Load
+
+- `skills/visual-header.md`
+- `skills/server-patterns.md`
+- `skills/mcp-protocol.md`
+
+## Agent
+
+Delegate to `agents/mcp-debugger.md`.
+
+## Usage
+
+```
+/debug-mcp scaffold <server_name> [--tools=<tool1,tool2,...>] [--location=<path>]
+```
+
+**Arguments:**
+- `server_name` - Name for the new MCP server (lowercase, hyphens)
+
+**Options:**
+- `--tools` - Comma-separated list of initial tool names to generate stubs
+- `--location` - Where to create the server (default: `mcp-servers/<server_name>`)
+
+## Instructions
+
+Execute `skills/visual-header.md` with context "Server Scaffold".
+
+### Phase 1: Gather Requirements
+
+1. Ask user for:
+   - Server purpose (one sentence)
+   - External service it integrates with (if any)
+   - Authentication type (API key, OAuth, none)
+   - Initial tools to register (at least one)
+
+### Phase 2: Generate Project Structure
+
+Apply patterns from `skills/server-patterns.md`:
+
+```
+mcp-servers/<server_name>/
+├── mcp_server/
+│   ├── __init__.py
+│   ├── config.py          # Configuration loader (env files)
+│   ├── server.py           # MCP server entry point
+│   └── tools/
+│       ├── __init__.py
+│       └── <category>.py   # Tool implementations
+├── tests/
+│   ├── __init__.py
+│   └── test_tools.py       # Tool unit tests
+├── requirements.txt        # Python dependencies
+└── README.md               # Server documentation
+```
+
+### Phase 3: Generate Files
+
+#### server.py
+- Import FastMCP or raw MCP protocol handler
+- Register tools from tools/ directory
+- Configure stdio transport
+- Add startup logging with tool count
+
+#### config.py
+- Load from `~/.config/claude/<server_name>.env`
+- Fall back to project-level `.env`
+- Validate required variables on startup
+- Mask sensitive values in logs
+
+#### tools/<category>.py
+- For each tool name provided in `--tools`:
+  - Generate a stub function with `@mcp.tool` decorator
+  - Include docstring with description
+  - Define inputSchema with parameter types
+  - Return placeholder response
+
+#### requirements.txt
+```
+mcp>=1.0.0
+httpx>=0.24.0
+python-dotenv>=1.0.0
+```
+
+#### README.md
+- Server name and description
+- Installation instructions (venv setup)
+- Configuration (env variables)
+- Available tools table
+- Architecture diagram
+
+### Phase 4: Register in .mcp.json
+
+1. Read the project's `.mcp.json`
+2. Add the new server entry:
+   ```json
+   "<server_name>": {
+     "command": "mcp-servers/<server_name>/.venv/bin/python",
+     "args": ["-m", "mcp_server.server"],
+     "cwd": "mcp-servers/<server_name>"
+   }
+   ```
+3. Show the change and ask user to confirm before writing
+
+### Phase 5: Completion
+
+```
+## Scaffold Complete
+
+### Created Files
+- mcp-servers/<name>/mcp_server/server.py
+- mcp-servers/<name>/mcp_server/config.py
+- mcp-servers/<name>/mcp_server/tools/<category>.py
+- mcp-servers/<name>/requirements.txt
+- mcp-servers/<name>/README.md
+
+### Next Steps
+1. Create virtual environment:
+   cd mcp-servers/<name> && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
+2. Add credentials:
+   Edit ~/.config/claude/<name>.env
+3. Implement tool logic:
+   Edit mcp-servers/<name>/mcp_server/tools/<category>.py
+4. Restart Claude Code session to load the new server
+5. Test: /debug-mcp test <name> <tool_name>
+```
+
+## User Request
+
+$ARGUMENTS
--- a/plugins/debug-mcp/commands/debug-mcp-status.md
+++ b/plugins/debug-mcp/commands/debug-mcp-status.md
@@ -0,0 +1,101 @@
+---
+name: debug-mcp status
+description: Show all configured MCP servers with health status, venv state, and tool counts
+---
+
+# /debug-mcp status
+
+Display the health status of all MCP servers configured in the project.
+
+## Skills to Load
+
+- `skills/visual-header.md`
+- `skills/venv-diagnostics.md`
+- `skills/log-analysis.md`
+
+## Agent
+
+Delegate to `agents/mcp-debugger.md`.
+
+## Usage
+
+```
+/debug-mcp status [--server=<name>] [--verbose]
+```
+
+**Options:**
+- `--server` - Check a specific server only
+- `--verbose` - Show detailed output including tool lists
+
+## Instructions
+
+Execute `skills/visual-header.md` with context "Server Status".
+
+### Phase 1: Locate Configuration
+
+1. Read `.mcp.json` from the project root
+2. Parse the `mcpServers` object to extract all server definitions
+3. For each server, extract:
+   - Server name (key in mcpServers)
+   - Command path (usually Python interpreter in .venv)
+   - Arguments (module path)
+   - Working directory (`cwd`)
+   - Environment variables or env file references
+
+### Phase 2: Check Each Server
+
+For each configured MCP server:
+
+1. **Executable check** - Does the command path exist?
+   ```bash
+   test -f <command_path> && echo "OK" || echo "MISSING"
+   ```
+
+2. **Virtual environment check** - Apply `skills/venv-diagnostics.md`:
+   - Does `.venv/` directory exist in the server's cwd?
+   - Is the Python binary intact (not broken symlink)?
+   - Are requirements satisfied?
+
+3. **Config file check** - Does the referenced env file exist?
+   ```bash
+   test -f <env_file_path> && echo "OK" || echo "MISSING"
+   ```
+
+4. **Module check** - Can the server module be imported?
+   ```bash
+   cd <cwd> && .venv/bin/python -c "import <module_name>" 2>&1
+   ```
+
+### Phase 3: Report
+
+```
+## MCP Server Status
+
+| Server | Executable | Venv | Config | Import | Status |
+|--------|-----------|------|--------|--------|--------|
+| gitea | OK | OK | OK | OK | HEALTHY |
+| netbox | OK | MISSING | OK | FAIL | ERROR |
+| data-platform | OK | OK | OK | OK | HEALTHY |
+
+### Errors
+
+#### netbox
+- Venv missing: /path/to/mcp-servers/netbox/.venv does not exist
+- Import failed: ModuleNotFoundError: No module named 'pynetbox'
+- Fix: cd /path/to/mcp-servers/netbox && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
+
+### Summary
+- Healthy: 4/5
+- Errors: 1/5
+```
+
+### Phase 4: Verbose Mode
+
+If `--verbose`, additionally show for each healthy server:
+- Tool count (parse server source for `@mcp.tool` decorators or tool registration)
+- Resource count
+- Last modification time of server.py
+
+## User Request
+
+$ARGUMENTS
--- a/plugins/debug-mcp/commands/debug-mcp-test.md
+++ b/plugins/debug-mcp/commands/debug-mcp-test.md
@@ -0,0 +1,103 @@
+---
+name: debug-mcp test
+description: Test a specific MCP tool call by invoking it and displaying the result
+---
+
+# /debug-mcp test
+
+Test a specific MCP tool by invoking it with sample parameters.
+
+## Skills to Load
+
+- `skills/visual-header.md`
+- `skills/mcp-protocol.md`
+
+## Agent
+
+Delegate to `agents/mcp-debugger.md`.
+
+## Usage
+
+```
+/debug-mcp test <server_name> <tool_name> [--params=<json>]
+```
+
+**Arguments:**
+- `server_name` - Name of the MCP server from .mcp.json
+- `tool_name` - Name of the tool to invoke
+- `--params` - JSON object with tool parameters (optional)
+
+## Instructions
+
+Execute `skills/visual-header.md` with context "Tool Test".
+
+### Phase 1: Validate Inputs
+
+1. Read `.mcp.json` and verify the server exists
+2. Check if the server is healthy (run quick executable check)
+3. If tool_name is not provided, list available tools for the server and ask user to select
+
+### Phase 2: Tool Discovery
+
+1. Parse the server source code to find the tool definition
+2. Extract the tool's `inputSchema` (parameters, types, required fields)
+3. Display the schema to the user:
+   ```
+   ## Tool: list_issues
+   Server: gitea
+
+   Parameters:
+   - state (string, optional): "open", "closed", "all" [default: "open"]
+   - labels (array[string], optional): Filter by labels
+   - repo (string, optional): Repository name
+   ```
+
+### Phase 3: Parameter Preparation
+
+1. If `--params` provided, validate against the tool's inputSchema
+2. If no params provided and tool has required params, ask user for values
+3. If no params and all optional, invoke with defaults
+
+### Phase 4: Invocation
+
+Invoke the MCP tool using the available MCP tool functions:
+1. Call the tool with prepared parameters
+2. Capture the response
+3. Measure response time
+
+### Phase 5: Result Display
+
+```
+## Test Result
+
+### Request
+- Server: gitea
+- Tool: list_issues
+- Params: {"state": "open", "repo": "leo-claude-mktplace"}
+
+### Response
+- Status: Success
+- Time: 245ms
+- Result:
+  [formatted JSON response, truncated if large]
+
+### Schema Validation
+- All required params provided: YES
+- Response type matches expected: YES
+```
+
+### Error Handling
+
+If the tool call fails, apply `skills/mcp-protocol.md` error patterns:
+
+```
+### Error
+- Type: ConnectionRefused
+- Message: Could not connect to MCP server
+- Likely Cause: Server not running or venv broken
+- Fix: Run /debug-mcp status to diagnose
+```
+
+## User Request
+
+$ARGUMENTS
--- a/plugins/debug-mcp/commands/debug-mcp.md
+++ b/plugins/debug-mcp/commands/debug-mcp.md
@@ -0,0 +1,17 @@
+---
+description: MCP debugging — inspect servers, test tools, view logs, scaffold new servers
+---
+
+# /debug-mcp
+
+MCP server debugging, inspection, and development toolkit.
+
+## Sub-commands
+
+| Sub-command | Description |
+|-------------|-------------|
+| `/debug-mcp status` | Show all MCP servers with health status |
+| `/debug-mcp test` | Test a specific MCP tool call |
+| `/debug-mcp logs` | View recent MCP server logs and errors |
+| `/debug-mcp inspect` | Inspect MCP server config and dependencies |
+| `/debug-mcp scaffold` | Generate MCP server skeleton project |