MCP Server Scaffolding

Scaffold production-ready Python MCP servers with FastMCP.

Quick Start

Generate a new MCP server:

bash

python scripts/scaffold.py my-server --output ./my-server

This creates a complete project structure with:

•server.py - Main server with example tool, resource, and prompt
•requirements.txt - Dependencies (fastmcp, pydantic)
•README.md - Usage instructions

Scaffolding Options

Minimal Server (Tools Only)

bash

python scripts/scaffold.py my-server --template basic

Full Server (All Primitives)

bash

python scripts/scaffold.py my-server --template full

With Specific Features

bash

python scripts/scaffold.py my-server \
  --tools \
  --resources \
  --prompts \
  --lifespan \
  --output ./servers/my-server

Validation

Validate an existing MCP server:

bash

python scripts/validate.py path/to/server.py

Checks:

•FastMCP import and initialization
•Tool definitions with proper type hints
•Resource URI patterns
•Pydantic Field usage
•Async function patterns

Project Structure

Generated projects follow this structure:

code

my-server/
├── server.py           # Main MCP server
├── requirements.txt    # Python dependencies
├── README.md          # Usage documentation
└── data/              # Default data directory (gitignored)

Templates

Basic Template

Minimal server with one tool:

python

from fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool
def hello(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run()

Full Template

Complete server with tools, resources, prompts, and lifespan. See assets/templates/full-server.py.

Reference Documentation

•FastMCP API: See references/FASTMCP-GUIDE.md for decorator syntax, type hints, and patterns
•Common Patterns: See references/PATTERNS.md for database connections, API clients, error handling
•Deployment: See references/DEPLOYMENT.md for stdio, HTTP, and Docker deployment

MCP Primitives Cheatsheet

Tools (Actions)

python

from pydantic import Field

@mcp.tool
def my_tool(
    param: str = Field(description="Parameter description"),
    optional: int = Field(default=10, description="Optional with default")
) -> dict:
    """Tool description shown to LLM."""
    return {"result": param}

Resources (Data)

python

@mcp.resource("myscheme://path/to/resource")
def static_resource() -> str:
    """Resource description."""
    return json.dumps({"data": "value"})

@mcp.resource("myscheme://items/{item_id}")
def dynamic_resource(item_id: str) -> str:
    """Dynamic resource with URI template."""
    return json.dumps({"id": item_id})

Prompts (Templates)

python

@mcp.prompt(name="my_prompt", tags={"category"})
def my_prompt(
    topic: str = Field(description="What to analyze")
) -> str:
    """Prompt description."""
    return f"Please analyze {topic} and provide insights."

Workflow

•Scaffold - Generate project structure
•Customize - Add your tools, resources, prompts
•Validate - Check for common issues
•Test - Run locally with python server.py
•Deploy - Add to Claude Code with claude mcp add