jratiwanich/mcp-boilerplate

FastMCP Server Boilerplate

A comprehensive boilerplate for building MCP (Model Context Protocol) servers using FastMCP. This boilerplate includes example tools, resources, and prompts to help you get started quickly.

Features

• 🛠️ Example Tools: Ready-to-use tools for text analysis, calculations, and more
• 📚 Resources: Sample resource endpoints for data access
• 💬 Prompts: Predefined prompt templates for common tasks
• 🐳 Docker Support: Fully containerized with optimized Dockerfile
• ⚡ uv Package Manager: Fast dependency management with uv
• 🔧 Type Hints: Full type annotation support for better IDE experience

What's Included

Tools

• get_greeting: Generate personalized greetings
• calculate_sum: Perform mathematical calculations
• analyze_text: Analyze text and return statistics

Resources

• info://server/info: Server information and metadata
• data://example/stats: Example statistics data

Prompts

• code_review_prompt: Generate code review templates
• data_analysis_prompt: Generate data analysis templates

Prerequisites

• Python 3.12 or higher
• uv package manager
• Docker (optional, for containerized deployment)

Installation

Using uv (Recommended)

1. Clone or copy this boilerplate:

cd /path/to/mcp-boilerplate

2. Install dependencies:

uv sync

3. Run the server:

uv run server.py

Using pip

1. Install dependencies:

pip install "mcp[cli]>=1.6.0"

2. Run the server:

python server.py

Docker Deployment

Build the Docker image:

docker build -t mcp-boilerplate .

Run the container:

docker run -i mcp-boilerplate

Using docker-compose (create docker-compose.yml):

version: '3.8'
services:
  mcp-server:
    build: .
    stdin_open: true
    tty: true

Then run:

docker-compose up

Project Structure

mcp-boilerplate/
├── server.py           # Main MCP server implementation
├── pyproject.toml      # Project dependencies and metadata
├── Dockerfile          # Docker configuration
├── README.md           # This file
└── .gitignore          # Git ignore patterns

Usage Example

The MCP server communicates via stdio (standard input/output). Here's how to interact with it:

Testing Tools

Tools can be called by LLM clients or testing frameworks that support MCP:

# Example: Using the calculate_sum tool
{
    "method": "tools/call",
    "params": {
        "name": "calculate_sum",
        "arguments": {
            "numbers": [1, 2, 3, 4, 5]
        }
    }
}

Accessing Resources

Resources provide read-only data access:

# Example: Accessing server info
{
    "method": "resources/read",
    "params": {
        "uri": "info://server/info"
    }
}

Customization

Adding New Tools

1. Add a new function with the @mcp.tool() decorator:

@mcp.tool()
async def your_custom_tool(param: str) -> Dict[str, Any]:
    """
    Your tool description here.
    
    Args:
        param: Parameter description
        
    Returns:
        Result description
    """
    # Your implementation
    return {"result": "value"}

Adding New Resources

1. Add a new function with the @mcp.resource() decorator:

@mcp.resource("custom://your/resource")
async def your_custom_resource() -> str:
    """
    Your resource description here.
    
    Returns:
        Resource data as string
    """
    return "your data"

Adding New Prompts

1. Add a new function with the @mcp.prompt() decorator:

@mcp.prompt()
async def your_custom_prompt(param: str = "default") -> str:
    """
    Your prompt description here.
    
    Args:
        param: Parameter description
        
    Returns:
        Formatted prompt string
    """
    return f"Your prompt template with {param}"

Development

Install development dependencies:

uv sync --extra dev

Run tests (if you add them):

uv run pytest

Format code:

uv run black .

Lint code:

uv run ruff check .

Configuration

You can configure the server by modifying server.py:

• Server Name: Change the name in FastMCP("Your Server Name")
• Transport: Currently uses stdio, can be changed to sse for HTTP transport
• Environment Variables: Add custom env vars in the Dockerfile

Troubleshooting

Server not responding

• Ensure Python 3.12+ is installed
• Check that all dependencies are installed correctly
• Verify stdin/stdout are not being used by other processes

Docker build fails

• Ensure Docker is running
• Check network connectivity for downloading uv and dependencies
• Verify pyproject.toml syntax is correct

Import errors

• Run uv sync to ensure all dependencies are installed
• Check Python version compatibility

Resources

• FastMCP Documentation
• MCP Specification
• uv Package Manager

License

This boilerplate is provided as-is for educational and development purposes.

Contributing

Feel free to customize this boilerplate for your specific use case. Common modifications include:

• Adding database connections
• Integrating external APIs
• Adding authentication
• Implementing custom business logic

Next Steps

1. Customize the example tools to match your use case
2. Add your own resources and prompts
3. Configure the server name and metadata
4. Add tests for your custom functionality
5. Deploy using Docker or your preferred method

Happy building! 🚀