fastmcp-builder

# FastMCP Builder - Claude Code Skill A comprehensive Claude Code skill for building production-ready MCP (Model Context Protocol) servers using the FastMCP Python framework. This skill provides complete reference implementations, working examples, and proven patterns for creating robust MCP servers with tools, resources, prompts, OAuth authentication, and comprehensive testing. ## What is FastMCP? **FastMCP** is the official high-level Python framework for building MCP servers. It's simpler, faster to develop with, and more maintainable than the low-level MCP SDK. This skill focuses exclusively on FastMCP-based development. ## What's Included This skill contains everything you need to build production-ready FastMCP servers: ### 1. Reference Documentation (`reference/`) Six comprehensive guides covering all aspects of FastMCP development: - **[fastmcp_overview.md](./reference/fastmcp_overview.md)** - Introduction, when to use FastMCP, key features - **[project_structure.md](./reference/project_structure.md)** - Recommended structure, file organization, DRY patterns - **[tool_patterns.md](./reference/tool_patterns.md)** - 6 tool patterns with complete examples - **[resource_patterns.md](./reference/resource_patterns.md)** - 4 resource types (static, dynamic, template, wildcard) - **[oauth_integration.md](./reference/oauth_integration.md)** - Complete Google OAuth setup guide - **[testing_guide.md](./reference/testing_guide.md)** - FastMCP Client testing, patterns, best practices ### 2. Code Examples (`examples/`) Runnable examples from minimal to complete servers: - **[minimal_server.py](./examples/minimal_server.py)** - Absolute simplest FastMCP server (28 lines) - **[complete_server_structure.py](./examples/complete_server_structure.py)** - Full-featured single-file example with all patterns - **[test_examples.py](./examples/test_examples.py)** - Comprehensive testing examples ### 3. Complete Reference Project (`reference-project/`) A full production implementation demonstrating best practices: - **6 production-ready tools** - Various patterns (sync, async, stateful, with context) - **7 resource instances** - 4 types (static, dynamic, template, wildcard) - **1 universal prompt** - Reusable prompt template - **145 passing tests** - Comprehensive test coverage - **OAuth integration** - Complete Google OAuth setup - **Dual-mode architecture** - `main.py` (with OAuth) + `main_noauth.py` (local testing) - **DRY principle** - Uses `common.py` for component registration ## When to Use This Skill Use this skill when you need to: - Build MCP servers with FastMCP (Python-based 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) ## Installation ### Option 1: Install via Plugin Marketplace (Recommended) 1. **Register this marketplace** in Claude Code: ``` /plugin marketplace add husniadil/fastmcp-builder ``` 2. **Browse and install:** - Select "Browse and install plugins" - Choose "fastmcp-builder-skill" - Select "fastmcp-builder" - Click "Install now" 3. **Or install directly:** ``` /plugin install fastmcp-builder@fastmcp-builder-skill ``` ### Option 2: Manual Installation Clone or download this repository to your Claude Code skills directory: ```bash cd ~/.claude/skills git clone https://github.com/husniadil/fastmcp-builder.git ``` ### Using the Skill Once installed, simply reference the skill in your request: ``` Use the fastmcp-builder skill to create a new MCP server with OAuth authentication ``` ## Quick Start ### Simple Example Create a minimal FastMCP server: ```python from fastmcp import FastMCP mcp = FastMCP("my-server") @mcp.tool() def greet(name: str) -> str: """Greet someone by name""" return f"Hello, {name}!" if __name__ == "__main__": mcp.run() ``` ### Try the Included Examples Navigate to the skill directory and run the examples: ```bash # Navigate to skill directory cd ~/.claude/plugins/marketplaces/fastmcp-builder-skill # Try the minimal server python examples/minimal_server.py # Try the complete server structure python examples/complete_server_structure.py # Run with HTTP mode python examples/complete_server_structure.py --http ``` ## Building Your First Server ### Phase 1: Planning & Setup 1. **Review FastMCP Overview** - Load `reference/fastmcp_overview.md` 2. **Understand Requirements** - What tools, resources, prompts do you need? 3. **Review Project Structure** - Load `reference/project_structure.md` 4. **Set Up Project** - Create directory structure and install dependencies ```bash mkdir my-mcp-server && cd my-mcp-server mkdir -p app/tools app/resources app/prompts tests uv add fastmcp==2.13.0.1 python-dotenv==1.2.1 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 1. **Implement Configuration** (`app/config.py`) - Environment variables, settings 2. **Implement Tools** (`app/tools/`) - Follow patterns from `reference/tool_patterns.md` 3. **Implement Resources** (`app/resources/`) - Follow patterns from `reference/resource_patterns.md` 4. **Implement Prompts** (`app/prompts/`) - Reusable prompt templates 5. **Create Common Registration** (`app/common.py`) - DRY principle for registering components 6. **Create Server Entry Points** - `main_noauth.py` (local) + `main.py` (OAuth) ### Phase 3: OAuth Integration (Optional) Follow `reference/oauth_integration.md` for: 1. Setting up Google OAuth credentials 2. Implementing GoogleProvider 3. Testing with ngrok 4. Configuring Claude Desktop ### Phase 4: Testing Follow `reference/testing_guide.md` for: 1. Setting up test structure (`tests/conftest.py`) 2. Writing tool tests 3. Writing resource tests 4. Writing integration tests 5. Running tests: `uv run pytest tests/ -v` ### Phase 5: Documentation & Deployment 1. Write comprehensive README 2. Create .env.example template 3. Test OAuth flow 4. Deploy to production (Railway, Fly.io, VPS) ## Project Structure Recommended structure for FastMCP projects: ``` my-mcp-server/ ├── app/ │ ├── __init__.py │ ├── config.py # Configuration & environment variables │ ├── common.py # Shared component registration (DRY) │ ├── main.py # Server with OAuth │ ├── main_noauth.py # Server without OAuth (local testing) │ ├── tools/ # Tool implementations │ │ ├── __init__.py │ │ ├── my_tool.py │ │ └── ... │ ├── resources/ # Resource implementations │ │ ├── __init__.py │ │ ├── static.py │ │ └── ... │ └── prompts/ # Prompt templates │ ├── __init__.py │ └── explain.py ├── tests/ │ ├── __init__.py │ ├── conftest.py # Test fixtures │ ├── test_tools.py │ ├── test_resources.py │ └── test_integration.py ├── pyproject.toml # Project dependencies ├── .env.example # Environment variable template ├── .env # Actual environment variables (gitignored) └── README.md ``` ## Tool Patterns This skill includes 6 proven tool patterns: 1. **Basic Sync Tools** - Simple synchronous functions (health checks, queries) 2. **Data Processing Tools** - Text analysis, transformations 3. **Tools with Context** - Logging, progress tracking, better UX 4. **Stateful Tools** - Counters, session management 5. **API Integration Tools** - External service calls 6. **Advanced Async Tools** - Complex workflows, parallel processing See `reference/tool_patterns.md` for complete examples. ## Resource Patterns This skill includes 4 resource types: 1. **Static Resources** - Fixed content (status, features, documentation) 2. **Dynamic Resources** - Generated content (current time, computed data) 3. **Template Resources** - Path parameters (`user://{user_id}`) 4. **Wildcard Resources** - Multi-segment paths (`docs://{path*}`) See `reference/resource_patterns.md` for complete examples. ## OAuth Integration Complete guide for adding Google OAuth authentication: - Setting up Google Cloud Console - Implementing GoogleProvider - Testing with ngrok - Configuring Claude Desktop Connectors - Production deployment considerations See `reference/oauth_integration.md` for the complete guide. ## Testing Comprehensive testing guide using FastMCP Client: - Fast, in-memory testing (no server startup required) - Tool testing patterns - Resource testing patterns - Integration testing patterns - Achieving >80% test coverage See `reference/testing_guide.md` for complete examples. ## Best Practices 1. **Use FastMCP** - Simpler than MCP SDK for most use cases 2. **Follow project structure** - Use `common.py` pattern (DRY principle) 3. **Dual-mode servers** - `main.py` (OAuth) + `main_noauth.py` (local) 4. **Comprehensive testing** - Use FastMCP Client, aim for >80% coverage 5. **Clear documentation** - Docstrings, README, usage examples 6. **Error handling** - Graceful failures, informative error messages 7. **Context usage** - Logging, progress for better UX 8. **Security** - Environment variables, never commit secrets ## Common Workflows ### Creating a New Tool 1. Create `app/tools/my_tool.py` 2. Implement tool function 3. Add to `app/common.py` registration 4. Write tests in `tests/test_tools.py` 5. Run tests: `uv run pytest tests/test_tools.py -v` ### Adding OAuth 1. Review `reference/oauth_integration.md` 2. Set up Google OAuth credentials 3. Update `app/config.py` with OAuth settings 4. Modify `app/main.py` to use GoogleProvider 5. Test with ngrok 6. Configure Claude Desktop Connectors ### Debugging 1. Use `main_noauth.py` for faster local testing 2. Add logging with Context: `await ctx.debug(...)` 3. Write tests to isolate issues 4. Check tool/resource registration in `common.py` 5. Verify environment variables loaded ## Reference Project Details The `reference-project/` directory contains a complete production implementation: - **Name:** `mcp-auth-demo` - **Version:** 1.0.0 - **Tools:** 6 (ping, counter, process_text, analyze_text, get_forecast, request_info) - **Resources:** 7 instances across 4 types - **Prompts:** 1 universal prompt template - **Tests:** 145 passing tests with comprehensive coverage - **Features:** OAuth, dual-mode architecture, DRY principle, comprehensive error handling Use this as a reference when building your own servers. ## Additional Resources - **FastMCP Documentation:** https://gofastmcp.com/ - **FastMCP GitHub:** https://github.com/jlowin/fastmcp - **MCP Specification:** https://modelcontextprotocol.io/ - **Google OAuth Guide:** https://developers.google.com/identity/protocols/oauth2 - **Claude Code Skills:** https://docs.claude.com/en/docs/claude-code/skills.md ## Requirements - Python 3.11+ - FastMCP 2.13.0.1 - python-dotenv 1.2.1 For testing: - pytest 8.4.2 - pytest-asyncio 1.2.0 - pytest-mock 3.15.1 - httpx 0.28.1 ## Contributing This is a Claude Code skill. To contribute: 1. Test changes with the reference project 2. Ensure all examples run successfully 3. Update documentation as needed 4. Add tests for new patterns ## License MIT License - Copyright 2025 Husni Adil Makmur This skill is provided as-is for use with Claude Code. See [LICENSE](./LICENSE) file for details. The FastMCP framework itself is licensed separately - see the [FastMCP repository](https://github.com/jlowin/fastmcp) for details. ## Notes - This skill focuses on **FastMCP**, not the low-level MCP SDK - All examples use **Python 3.11+** - OAuth examples use **Google OAuth** (other providers possible) - Testing uses **FastMCP Client** (in-memory, fast) - Deployment examples are production-ready Happy building!