fastmcp-builder

What this skill does

# FastMCP Builder - Production MCP Server Development

## Overview

This skill provides comprehensive, production-ready patterns for building MCP (Model Context Protocol) servers using **FastMCP**, the official high-level Python framework. It includes complete reference implementations, working examples, and best practices proven in production.

**FastMCP** is the recommended approach for building MCP servers in Python - it's simpler, faster to develop, and more maintainable than the low-level MCP SDK.

## What's Included

This skill contains:

1. **Reference Documentation** (`reference/`) - 6 comprehensive guides covering all aspects of FastMCP development
2. **Code Examples** (`examples/`) - Runnable examples from minimal to complete servers
3. **Complete Reference Project** (`reference-project/`) - Full production implementation with:
   - 6 production-ready tools
   - 7 resource instances (4 types)
   - 1 universal prompt
   - 145 passing tests
   - OAuth integration
   - Complete documentation

**💡 Tip:** When in doubt, look at the reference-project for real-world implementation examples.

## When to Use This Skill

Use this skill when you need to:

✅ **Build MCP servers with FastMCP** - Python-based MCP server development
✅ **Add OAuth authentication** - Especially Google OAuth for remote access
✅ **Implement production patterns** - Tools, resources, prompts with best practices
✅ **Set up comprehensive testing** - Using FastMCP Client for fast, in-memory tests
✅ **Structure larger projects** - Proper organization and separation of concerns
✅ **Deploy to production** - With authentication, error handling, monitoring

**Don't use this skill for:**

- ❌ TypeScript/Node.js MCP servers (use mcp-builder skill instead)
- ❌ Low-level MCP protocol work (use MCP SDK directly)
- ❌ Non-FastMCP Python servers (this is FastMCP-specific)

## Consulting Official Documentation

**IMPORTANT:** When encountering questions or issues not covered in this skill's reference materials, you should:

### Primary Method: Use WebSearch (Recommended)

The most reliable way to find FastMCP documentation is using WebSearch with site-specific queries:

```
WebSearch(
    query="site:gofastmcp.com [your specific topic]"
)
```

This will search the official FastMCP documentation site and return relevant pages.

### Alternative: Direct Page Access

If you know the general documentation structure, you can fetch specific pages directly:

```
WebFetch(
    url="https://gofastmcp.com/[section]/[topic]",
    prompt="Your specific question about this topic"
)
```

**Common documentation sections:**

- `/getting-started/` - Installation, quickstart, welcome
- `/servers/` - Tools, resources, prompts, context, logging
- `/deployment/` - Running servers, HTTP deployment, configuration
- `/integrations/` - Auth0, AWS Cognito, Azure, GitHub, Google, WorkOS, OpenAI, etc.
- `/testing/` - Testing guides and best practices

**Tip:** Any page can be accessed as markdown by appending `.md` to the URL.

### When to Consult Official Docs

Consult official documentation when:

- You encounter a feature or API not covered in this skill's references
- You need the latest updates or breaking changes
- User asks about FastMCP capabilities you're unsure about
- You're implementing advanced patterns not in the reference materials
- There are version-specific behaviors or deprecations
- You need clarification on authentication providers beyond Google OAuth
- You want to verify current best practices

### Example Workflows

1. **User asks about OpenAI integration:**

   ```
   WebSearch(query="site:gofastmcp.com openai integration")
   → Find https://gofastmcp.com/integrations/openai
   → Fetch that page for details
   ```

2. **User asks about AWS Cognito authentication:**

   ```
   WebSearch(query="site:gofastmcp.com aws cognito oauth")
   → Find relevant auth documentation
   → Implement based on official guidance
   ```

3. **User asks about testing patterns:**

   ```
   WebSearch(query="site:gofastmcp.com testing")
   → Find testing documentation
   → Apply patterns from official docs
   ```

4. **Exploring what's available:**
   ```
   WebSearch(query="site:gofastmcp.com deployment options")
   WebSearch(query="site:gofastmcp.com authentication providers")
   → Browse results to see available topics
   ```

**Note:** Always try the reference materials in this skill first, then consult official docs if needed.

---

## Workflow - Building a FastMCP Server

### Phase 1: Planning & Setup

**Step 1.1: Review FastMCP Overview**

- Load [fastmcp_overview.md](./reference/fastmcp_overview.md)
- Understand FastMCP vs MCP SDK
- Confirm FastMCP is right choice (it usually is)

**Step 1.2: Understand Requirements**

- What tools does the server need?
- Do you need OAuth authentication?
- Will you have resources? Prompts?
- What's the deployment target?

**Step 1.3: Review Project Structure**

- Load [project_structure.md](./reference/project_structure.md)
- Understand the recommended directory layout
- Learn about the common.py pattern (DRY principle)
- Understand dual-mode pattern (with/without OAuth)

**Step 1.4: Set Up Project**

Create project structure:

```bash
mkdir my-mcp-server
cd my-mcp-server

# Create directories
mkdir -p app/tools app/resources app/prompts tests

# Create initial files
touch app/__init__.py
touch app/main.py
touch app/main_noauth.py
touch app/common.py
touch app/config.py
touch tests/__init__.py
touch pyproject.toml
touch .env.example
touch README.md
```

Initialize with uv:

```bash
# Install FastMCP
uv add fastmcp==2.13.0.1
uv add python-dotenv==1.2.1

# Add test dependencies
uv add --optional test pytest==8.4.2 pytest-asyncio==1.2.0 pytest-mock==3.15.1 httpx==0.28.1
```

---

### Phase 2: Core Implementation

**Step 2.1: Implement Configuration**

Create `app/config.py` based on patterns in [project_structure.md](./reference/project_structure.md):

- Environment variable loading
- Configuration class with validation
- OAuth settings (if needed)
- Server metadata

**Step 2.2: Implement Tools**

Load [tool_patterns.md](./reference/tool_patterns.md) for comprehensive patterns:

1. **Identify tool patterns needed:**
   - Basic sync tools (health checks, simple queries)
   - Data processing tools (analysis, transformation)
   - Tools with Context (logging, progress)
   - Stateful tools (if state management needed)
   - API integration tools (external services)

2. **Create tools in `app/tools/`:**
   - One file per tool or logical group
   - Follow patterns from tool_patterns.md
   - Use proper error handling
   - Add comprehensive docstrings

3. **Example tool structure:**

```python
# app/tools/my_tool.py

async def my_tool(param: str, ctx: Context | None = None) -> dict:
    """
    Tool description

    Args:
        param: Parameter description
        ctx: FastMCP context (auto-injected)

    Returns:
        dict: Result structure
    """
    try:
        if ctx:
            await ctx.info("Processing...")

        # Tool logic here
        result = process(param)

        if ctx:
            await ctx.info("Completed!")

        return {"status": "success", "data": result}

    except Exception as e:
        if ctx:
            await ctx.error(f"Failed: {e}")
        return {"status": "error", "error": str(e)}
```

**Step 2.3: Implement Resources** (if needed)

Load [resource_patterns.md](./reference/resource_patterns.md) for all resource types:

1. **Choose resource types:**
   - Static resources (status, features, documentation)
   - Dynamic resources (generated content)
   - Template resources (with path parameters)
   - Wildcard resources (multi-segment paths)

2. **Create resources in `app/resources/`:**
   - static.py for static resources
   - Separate files for dynamic/template/wildcard

3. **Example resource:**

```python
# app/resources/welcome.py

def get_welcome_message() -> str:
    """Welcome message resource"""
    return "Welcome to my MCP server!"
```

**St