| name | mcp-builder |
| description | Scaffold and harden a FastMCP 3.1 MCP server with portmanteau tools, REST mirror, and docs |
MCP builder skill
Use when the user asks to create or refactor an MCP server.
Checklist
- Stack: Python 3.12+, FastMCP 3.1+,
pyproject.toml, ruff, optional pytest.
- Tools: Prefer portmanteau tools with an
operation parameter over dozens of thin wrappers.
- Returns: Structured dicts with
success, message or error, and actionable fields.
- Docs: README install, env vars, and one architecture note; link central docs patterns if applicable.
- Safety: No silent destructive defaults; validate paths; Windows vs POSIX notes in scripts.
- MCPB (optional):
mcpb.json + packaging standards if shipping to a marketplace.
Snippet — tool skeleton
from fastmcp import FastMCP
mcp = FastMCP("example")
@mcp.tool()
async def example_ops(operation: str, payload: str = "") -> dict:
"""EXAMPLE_OPS — Portmanteau surface.
Args:
operation: Sub-command name.
payload: JSON or plain text parameter bag.
Returns:
Rich response dict.
"""
return {"success": True, "operation": operation, "echo": payload}
Anti-patterns
- Duplicating the same logic in MCP tool and HTTP route without a shared core module.
- Returning unstructured prose-only replies for machine clients.
- Hard-coded ports outside your org’s registered range (see central WEBAPP_PORTS).
