lmiranda
2d51df7a42
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>
140 lines
2.8 KiB
Markdown
140 lines
2.8 KiB
Markdown
# 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")
|
|
```
|