leo-claude-mktplace/plugins/debug-mcp/commands/debug-mcp-scaffold.md

name, description

name	description
debug-mcp scaffold	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/.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:

   "<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