mcp-example

# 🎯 MCP Examples - Enterprise Edition > **🚀 FastMCP 2.0 powered examples for building sophisticated Model Context Protocol servers** Welcome to the ultimate MCP examples repository! Build enterprise-grade AI servers with our **living Minesweeper example** and comprehensive FastMCP 2.0 templates. [](https://github.com/jlowin/fastmcp) [](https://python.org) [](https://modelcontextprotocol.io) ## ✨ What's New in This Edition 🎮 **Living Game Example**: Watch LLMs master Minesweeper through logical reasoning 🚀 **FastMCP 2.0**: Enterprise features with multiple transport protocols 🏢 **Production Ready**: Authentication, sessions, real-time data, WebSocket support 🤖 **AI Agent Friendly**: Complete templates and guides for automated server generation ## 🎯 Featured: Minesweeper MCP Server **The ultimate demonstration of AI logical reasoning!** ```bash # Start the Minesweeper server mcp dev examples/servers/minesweeper_server.py # Or run as HTTP server python examples/servers/minesweeper_server.py --transport http --port 8000 ``` **Watch an LLM play Minesweeper:** ```python # Start a new expert game new_game("expert") # 30x16 grid, 99 mines! # Get AI-powered strategic hints get_hint(game_id) # Returns probability analysis # Make strategic moves reveal(game_id, x, y) # Uncover cells flag(game_id, x, y) # Mark mines # Analyze the board analyze_board(game_id) # Full probability matrix ```  ## 🚀 Quick Start ### Prerequisites - **Python 3.10+** (FastMCP 2.0 requirement) - **Poetry** (recommended) or pip ### Installation ```bash # Clone the repository git clone https://github.com/yourusername/mcp-examples.git cd mcp-examples # Install with Poetry (recommended) poetry install # Or with pip pip install -e . ``` ### 🎮 Try the Minesweeper Server ```bash # Development mode with MCP inspector mcp dev examples/servers/minesweeper_server.py # HTTP server for web integration python examples/servers/minesweeper_server.py --transport http --port 8000 # Test with the basic client python examples/clients/basic_client.py ``` ## 📁 Project Structure ``` examples/ ├── servers/ │ ├── template_server.py # 📄 Clean template - your starting canvas! │ ├── minesweeper_server.py # 🎯 Complex example - learn from this! │ ├── basic_server.py # Simple MCP server (official SDK) │ ├── filesystem_server.py # File operations server │ └── comprehensive_server.py # Full feature showcase ├── clients/ │ └── basic_client.py # MCP client examples └── configs/ ├── claude_desktop_config.json └── README.md # Documentation ├── FASTMCP_AI_AGENT_GUIDE.md # Complete FastMCP 2.0 guide ├── AI_AGENT_INSTRUCTIONS.md # Instructions for AI agents └── CLAUDE.md # Project guidelines ``` ## 🎮 Minesweeper Server Features ### 🧠 AI-Powered Gameplay - **Strategic Tools**: `new_game()`, `reveal()`, `flag()`, `get_hint()` - **Analysis Tools**: `analyze_board()`, probability calculations - **Learning Resources**: Strategy guides, pattern libraries, tutorials ### 🏢 Enterprise Features - **Multiple Transports**: stdio, HTTP, WebSocket ready - **Session Management**: Multiple concurrent games - **Real-time Updates**: Live game state streaming - **Authentication Ready**: OAuth 2.0 support built-in - **Statistics**: Global leaderboards and analytics ### 📚 Educational Resources - **Strategy Guide**: Master-level Minesweeper techniques - **Pattern Library**: Common configurations and solutions - **AI Prompts**: Teaching assistant for learning players - **Probability Analysis**: Mathematical approach to decision making ## 🔧 Server Examples ### 🎯 Minesweeper (FastMCP 2.0) ```python from fastmcp import FastMCP mcp = FastMCP("🎯 Minesweeper Pro") @mcp.tool def new_game(difficulty: str = "beginner") -> dict: """🎮 Start a new Minesweeper game!""" game_id = game_engine.create_game(difficulty) return {"game_id": game_id, "message": "Good luck! 🎯"} @mcp.resource("game://state/{game_id}") def get_game_state(game_id: str) -> str: """Real-time game state resource.""" return format_game_display(game_id) @mcp.prompt def strategy_guide(situation: str) -> str: """Generate strategic analysis for current situation.""" return f"Strategic guidance for: {situation}..." ``` ### 🔧 Basic Server (Official SDK) ```python from mcp.server.fastmcp import FastMCP mcp = FastMCP("Basic Example Server") @mcp.tool() def add_numbers(a: float, b: float) -> float: """Add two numbers together.""" return a + b @mcp.resource("info://server") def get_server_info() -> str: """Server information resource.""" return "Basic MCP Server Example..." ``` ## 🤖 For AI Agents **This repository is optimized for AI agents to build MCP servers!** ### 🎯 Perfect Learning Setup - **📄 [template_server.py](examples/servers/template_server.py)** - Clean starting canvas with all boilerplate - **🎮 [minesweeper_server.py](examples/servers/minesweeper_server.py)** - Complex working example to learn from - **📚 Complete Guides** - Step-by-step instructions and patterns ### 🚀 Quick Start for AI Agents ```bash # Copy the template and start building cp examples/servers/template_server.py my_awesome_server.py # Study the complex example for patterns cat examples/servers/minesweeper_server.py # Read the building guides cat FASTMCP_AI_AGENT_GUIDE.md ``` ### 📖 Complete Documentation - **[FastMCP 2.0 AI Agent Guide](FASTMCP_AI_AGENT_GUIDE.md)** - Enterprise server building - **[AI Agent Instructions](AI_AGENT_INSTRUCTIONS.md)** - Step-by-step templates - **[Template Server](examples/servers/template_server.py)** - Ready-to-use starting point ### 🎯 Use Cases - **Game Servers**: Interactive entertainment with real-time state - **Data Processing**: Complex analysis with streaming results - **API Integration**: External service coordination - **Educational Tools**: Interactive learning systems - **Productivity Apps**: Task management and automation ## 🏢 Enterprise Features (FastMCP 2.0) ### 🚀 Multiple Transports ```python # Development: stdio (default) mcp.run() # Production: HTTP with streaming mcp.run(transport="streamable-http", host="0.0.0.0", port=8000) # WebSocket support ready mcp.run(transport="websocket", host="127.0.0.1", port=8080) ``` ### 🔐 Authentication & Security ```python @mcp.set_auth_config def auth_config(): return { "authorization_url": "https://your-auth.com/oauth/authorize", "token_url": "https://your-auth.com/oauth/token", "client_id": os.getenv("CLIENT_ID"), "scopes": ["read", "write", "admin"] } ``` ### 📊 Real-time Data & Sessions ```python @mcp.tool async def create_session(user_id: str, data: dict) -> dict: """Create stateful user sessions.""" session_id = str(uuid.uuid4()) _sessions[session_id] = {"user": user_id, "data": data} return {"session_id": session_id} @mcp.resource("stream://live-data") async def live_data() -> str: """Streaming real-time data.""" return f"Live update: {time.time()}" ``` ## 🔧 Development Commands ```bash # Development & Testing mcp dev examples/servers/minesweeper_server.py mcp dev examples/servers/basic_server.py # HTTP Servers python examples/servers/minesweeper_server.py --transport http --port 8000 python examples/servers/comprehensive_server.py --http --port 8080 # Install for Claude Desktop mcp install examples/servers/minesweeper_server.py # Run tests poetry run pytest poetry run pytest --cov=examples # Code quality poetry run black . poetry run isort . poetry run ruff check . poetry run mypy . ``` ## 🎯 Claude Desktop Integration 1. **Copy configuration** from `examples/configs/claude_desktop_config.json` 2. **Update server paths** to match your setup: ```json { "mcpServers": { "minesweeper": { "command": "python", "args": ["/path/to/examples/servers/minesweeper_server.py"] }, "filesystem": { "command": "python", "args": ["/path/to/examples/servers/filesystem_server.py"] } } } ``` 3. **Restart Claude Desktop** and start playing! 🎮 ## 🎮 Minesweeper Gameplay Examples ### 🎯 Start Playing ```python # Create a new game result = new_game("intermediate") # 16x16, 40 mines game_id = result["game_id"] # Make your first move reveal(game_id, 8, 8) # Start in the center # Get strategic advice hint = get_hint(game_id) # Returns: {"action": "reveal", "x": 5, "y": 3, "reason": "0% mine probability"} ``` ### 🧮 Advanced Analysis ```python # Full probability analysis analysis = analyze_board(game_id) # Returns probability matrix for all hidden cells # Strategic guidance prompt = analyze_strategy(game_id, "stuck on complex constraint") # Returns step-by-step strategic guidance ``` ### 📊 Statistics & Learning ```python # Check your progress stats = list_games() # Shows win rate, best times, active games # Learn from the masters guide = get_strategy_guide() # Comprehensive strategy documentation ``` ## 🧪 Testing Your Servers ### 🔍 MCP Inspector ```bash # Test any server interactively mcp dev examples/servers/minesweeper_server.py mcp dev examples/servers/basic_server.py ``` ### 🤖 Programmatic Testing ```python # Test with FastMCP's built-in testing from fastmcp.testing import create_test_client async def test_minesweeper(): client = create_test_client(mcp) # Test game creation result = await client.call_tool("new_game", {"difficulty": "beginner"}) assert result["success"] == True # Test resources info = await client.get_resource("stats://global") assert "Statistics" in info ``` ## 🌟 What Makes This Special ### 🎮 Living Examples - **Interactive Gameplay**: Watch LLMs learn and strategize - **Real-time State**: See decision-making processes unfold - **Educational Value**: Understand AI reasoning through play ### 🏢 Enterprise Ready - **Production Deployment**: HTTP servers, authentication, sessions - **Scalable Architecture**: Multiple transports, WebSocket support - **Monitoring & Analytics**: Built-in statistics and performance tracking ### 🤖 AI Agent Optimized - **Complete Templates**: Copy-paste server generators - **Comprehensive Docs**: Everything needed for autonomous building - **Best Practices**: Security, error handling, testing patterns ## 📚 Learn More - **[FastMCP Documentation](https://gofastmcp.com)** - Official FastMCP 2.0 docs - **[MCP Specification](https://spec.modelcontextprotocol.io)** - Protocol specification - **[Official MCP SDK](https://github.com/modelcontextprotocol/python-sdk)** - Python SDK - **[MCP Community](https://github.com/modelcontextprotocol)** - Community resources ## 🤝 Contributing We welcome contributions! Whether it's: - 🎮 **New game examples** (Chess, Tic-tac-toe, Sudoku) - 🏢 **Enterprise patterns** (Authentication, monitoring, deployment) - 🤖 **AI agent tools** (Templates, generators, testing) - 📚 **Documentation** (Tutorials, guides, examples) ### Guidelines - Keep examples **practical and educational** - Include **comprehensive documentation** - Follow **security best practices** - Add **proper error handling** - Use **type hints** throughout ## 🏆 Showcase **Built something cool with these examples?** We'd love to feature it! - Enterprise MCP deployments - Educational AI systems - Interactive game servers - Creative LLM applications ## 📄 License MIT License - build whatever you want! See [LICENSE](LICENSE) for details. ## 🙏 Acknowledgments - **[Anthropic](https://anthropic.com)** - For creating MCP and making AI better - **[Jeremiah Lowin](https://github.com/jlowin)** - For the amazing FastMCP framework - **[MCP Community](https://github.com/modelcontextprotocol)** - For the excellent ecosystem - **Contributors** - Who make this repository awesome --- ## 🎯 Ready to Build? ```bash # 📄 Start with the clean template (recommended) cp examples/servers/template_server.py my_server.py mcp dev my_server.py # 🎮 Study the complex example mcp dev examples/servers/minesweeper_server.py # 📚 Read the building guides cat FASTMCP_AI_AGENT_GUIDE.md # 🚀 Test your creation python my_server.py --transport http --port 8000 ``` **🚀 Happy building! Let's make MCP servers that are both powerful and fun!** 🎮