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:
25
plugins/debug-mcp/.claude-plugin/plugin.json
Normal file
25
plugins/debug-mcp/.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,25 @@
|
||||
{
|
||||
"name": "debug-mcp",
|
||||
"version": "1.0.0",
|
||||
"description": "MCP server debugging, inspection, and development toolkit",
|
||||
"author": {
|
||||
"name": "Leo Miranda",
|
||||
"email": "leobmiranda@gmail.com"
|
||||
},
|
||||
"homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/debug-mcp/README.md",
|
||||
"repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"mcp",
|
||||
"debugging",
|
||||
"inspection",
|
||||
"development",
|
||||
"server",
|
||||
"protocol",
|
||||
"diagnostics"
|
||||
],
|
||||
"commands": [
|
||||
"./commands/"
|
||||
],
|
||||
"domain": "debug"
|
||||
}
|
||||
62
plugins/debug-mcp/README.md
Normal file
62
plugins/debug-mcp/README.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# debug-mcp
|
||||
|
||||
MCP server debugging, inspection, and development toolkit.
|
||||
|
||||
## Overview
|
||||
|
||||
This plugin provides tools for diagnosing MCP server issues, testing tool invocations, analyzing server logs, inspecting configurations and dependencies, and scaffolding new MCP servers. It is essential for maintaining and developing MCP integrations in the Leo Claude Marketplace.
|
||||
|
||||
## Commands
|
||||
|
||||
| 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 |
|
||||
|
||||
## Agent
|
||||
|
||||
| Agent | Model | Mode | Purpose |
|
||||
|-------|-------|------|---------|
|
||||
| mcp-debugger | sonnet | default | All debug-mcp operations: inspection, testing, log analysis, scaffolding |
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| mcp-protocol | MCP stdio protocol specification, JSON-RPC messages, tool/resource/prompt definitions |
|
||||
| server-patterns | Python MCP server directory structure, FastMCP pattern, config loader, entry points |
|
||||
| venv-diagnostics | Virtual environment health checks: existence, Python binary, packages, imports |
|
||||
| log-analysis | Common MCP error patterns with root causes and fixes |
|
||||
| visual-header | Standard command output header |
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
plugins/debug-mcp/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json
|
||||
├── commands/
|
||||
│ ├── debug-mcp.md # Dispatch file
|
||||
│ ├── debug-mcp-status.md
|
||||
│ ├── debug-mcp-test.md
|
||||
│ ├── debug-mcp-logs.md
|
||||
│ ├── debug-mcp-inspect.md
|
||||
│ └── debug-mcp-scaffold.md
|
||||
├── agents/
|
||||
│ └── mcp-debugger.md
|
||||
├── skills/
|
||||
│ ├── mcp-protocol.md
|
||||
│ ├── server-patterns.md
|
||||
│ ├── venv-diagnostics.md
|
||||
│ ├── log-analysis.md
|
||||
│ └── visual-header.md
|
||||
├── claude-md-integration.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT License - Part of the Leo Claude Marketplace.
|
||||
95
plugins/debug-mcp/agents/mcp-debugger.md
Normal file
95
plugins/debug-mcp/agents/mcp-debugger.md
Normal file
@@ -0,0 +1,95 @@
|
||||
---
|
||||
name: mcp-debugger
|
||||
description: MCP server inspection, log analysis, and scaffold generation. Use for debugging MCP connectivity issues, testing tools, inspecting server configs, and creating new MCP servers.
|
||||
model: sonnet
|
||||
permissionMode: default
|
||||
---
|
||||
|
||||
# MCP Debugger Agent
|
||||
|
||||
You are an MCP (Model Context Protocol) server specialist. You diagnose MCP server issues, inspect configurations, analyze logs, test tool invocations, and scaffold new servers.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- `skills/visual-header.md`
|
||||
- `skills/mcp-protocol.md`
|
||||
- `skills/server-patterns.md`
|
||||
- `skills/venv-diagnostics.md`
|
||||
- `skills/log-analysis.md`
|
||||
|
||||
## Visual Output Requirements
|
||||
|
||||
**MANDATORY: Display header at start of every response.**
|
||||
|
||||
```
|
||||
+----------------------------------------------------------------------+
|
||||
| DEBUG-MCP - [Context] |
|
||||
+----------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
## Core Knowledge
|
||||
|
||||
### .mcp.json Structure
|
||||
|
||||
The `.mcp.json` file in the project root defines all MCP servers:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server-name": {
|
||||
"command": "path/to/.venv/bin/python",
|
||||
"args": ["-m", "mcp_server.server"],
|
||||
"cwd": "path/to/server/dir"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### MCP Server Lifecycle
|
||||
|
||||
1. Claude Code reads `.mcp.json` at session start
|
||||
2. For each server, spawns the command as a subprocess
|
||||
3. Communication happens over stdio (JSON-RPC)
|
||||
4. Server registers tools, resources, and prompts
|
||||
5. Claude Code makes tool calls as needed during conversation
|
||||
|
||||
### Common Failure Points
|
||||
|
||||
| Failure | Symptom | Root Cause |
|
||||
|---------|---------|------------|
|
||||
| "X MCP servers failed" | Session start warning | Broken venv, missing deps, bad config |
|
||||
| Tool not found | Tool call returns error | Server not loaded, tool name wrong |
|
||||
| Timeout | Tool call hangs | Server crashed, infinite loop, network |
|
||||
| Permission denied | API errors | Invalid token, expired credentials |
|
||||
|
||||
## Behavior Guidelines
|
||||
|
||||
### Diagnostics
|
||||
|
||||
1. **Always start with .mcp.json** - Read it first to understand the server landscape
|
||||
2. **Check venvs systematically** - Use `skills/venv-diagnostics.md` patterns
|
||||
3. **Read actual error messages** - Parse logs rather than guessing
|
||||
4. **Test incrementally** - Verify executable, then import, then tool call
|
||||
|
||||
### Scaffolding
|
||||
|
||||
1. **Follow existing patterns** - Match the structure of existing servers in `mcp-servers/`
|
||||
2. **Use FastMCP** - Prefer the decorator-based pattern for new servers
|
||||
3. **Include config.py** - Always generate a configuration loader with env file support
|
||||
4. **Register in .mcp.json** - Show the user the entry to add, confirm before writing
|
||||
|
||||
### Security
|
||||
|
||||
1. **Never display full API tokens** - Mask all but last 4 characters
|
||||
2. **Check .gitignore** - Ensure credential files are excluded from version control
|
||||
3. **Validate SSL settings** - Warn if SSL verification is disabled
|
||||
|
||||
## Available Commands
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/debug-mcp status` | Server health overview |
|
||||
| `/debug-mcp test` | Test a specific tool call |
|
||||
| `/debug-mcp logs` | View and analyze server logs |
|
||||
| `/debug-mcp inspect` | Deep server inspection |
|
||||
| `/debug-mcp scaffold` | Generate new server skeleton |
|
||||
34
plugins/debug-mcp/claude-md-integration.md
Normal file
34
plugins/debug-mcp/claude-md-integration.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Debug MCP Integration
|
||||
|
||||
Add to your project's CLAUDE.md:
|
||||
|
||||
## MCP Server Debugging (debug-mcp)
|
||||
|
||||
This project uses the **debug-mcp** plugin for diagnosing and developing MCP server integrations.
|
||||
|
||||
### Available Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/debug-mcp status` | Show health status of all configured MCP servers |
|
||||
| `/debug-mcp test` | Test a specific MCP tool call with parameters |
|
||||
| `/debug-mcp logs` | View and analyze recent MCP server error logs |
|
||||
| `/debug-mcp inspect` | Deep inspection of server config, dependencies, and tools |
|
||||
| `/debug-mcp scaffold` | Generate a new MCP server project skeleton |
|
||||
|
||||
### Usage Guidelines
|
||||
|
||||
- Run `/debug-mcp status` when Claude Code reports MCP server failures at session start
|
||||
- Use `/debug-mcp inspect <server> --deps` to diagnose missing package issues
|
||||
- Use `/debug-mcp test <server> <tool>` to verify individual tool functionality
|
||||
- Use `/debug-mcp logs --errors-only` to quickly find error patterns
|
||||
- Use `/debug-mcp scaffold` when creating a new MCP server integration
|
||||
|
||||
### Common Troubleshooting
|
||||
|
||||
| Symptom | Command |
|
||||
|---------|---------|
|
||||
| "X MCP servers failed" at startup | `/debug-mcp status` |
|
||||
| Tool call returns error | `/debug-mcp test <server> <tool>` |
|
||||
| ImportError in server | `/debug-mcp inspect <server> --deps` |
|
||||
| Unknown server errors | `/debug-mcp logs --server=<name>` |
|
||||
129
plugins/debug-mcp/commands/debug-mcp-inspect.md
Normal file
129
plugins/debug-mcp/commands/debug-mcp-inspect.md
Normal file
@@ -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
|
||||
98
plugins/debug-mcp/commands/debug-mcp-logs.md
Normal file
98
plugins/debug-mcp/commands/debug-mcp-logs.md
Normal file
@@ -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
|
||||
138
plugins/debug-mcp/commands/debug-mcp-scaffold.md
Normal file
138
plugins/debug-mcp/commands/debug-mcp-scaffold.md
Normal file
@@ -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
|
||||
101
plugins/debug-mcp/commands/debug-mcp-status.md
Normal file
101
plugins/debug-mcp/commands/debug-mcp-status.md
Normal file
@@ -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
|
||||
103
plugins/debug-mcp/commands/debug-mcp-test.md
Normal file
103
plugins/debug-mcp/commands/debug-mcp-test.md
Normal file
@@ -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
|
||||
17
plugins/debug-mcp/commands/debug-mcp.md
Normal file
17
plugins/debug-mcp/commands/debug-mcp.md
Normal file
@@ -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 |
|
||||
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