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:
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")
|
||||
```
|
||||
Reference in New Issue
Block a user