Model Context Protocol (MCP) Example

🎯 MCP 示例 - 企业版

🚀 由 FastMCP 2.0 驱动的示例，助您构建复杂的 Model Context Protocol 服务

欢迎来到终极 MCP 示例仓库！使用我们的动态扫雷示例和全面的 FastMCP 2.0 模板，构建企业级 AI 服务。

✨ 本版本的新内容

🎮 动态游戏示例：观看大模型通过逻辑推理掌握扫雷
🚀 FastMCP 2.0：具备多种传输协议的企业级功能
🏢 可用于生产环境：支持身份验证、会话、实时数据和 WebSocket
🤖 适合 AI Agent：提供完整模板和指南，支持自动生成服务

🎯 精选：扫雷 MCP 服务

AI 逻辑推理的终极演示！

# 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

观看大模型玩扫雷：

# 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

🚀 快速开始

前置条件

• Python 3.10+（FastMCP 2.0 的要求）
• Poetry（推荐）或 pip

安装

# 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 .

🎮 试用扫雷服务

# 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

📁 项目结构

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

🎮 扫雷服务功能

🧠 AI 驱动的游戏玩法

• 策略工具：new_game()、reveal()、flag()、get_hint()
• 分析工具：analyze_board()、概率计算
• 学习资源：策略指南、模式库、教程

🏢 企业级功能

• 多种传输方式：支持 stdio、HTTP、WebSocket
• 会话管理：支持多个并发游戏
• 实时更新：实时推送游戏状态
• 支持身份验证：内置 OAuth 2.0 支持
• 统计数据：全球排行榜和分析

📚 教育资源

• 策略指南：掌握高级扫雷技巧
• 模式库：常见布局和解决方案
• AI 提示词：帮助玩家学习的教学助手
• 概率分析：用数学方法辅助决策

🔧 服务示例

🎯 扫雷（FastMCP 2.0）

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}..."

🔧 基础服务（官方 SDK）

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..."

🤖 面向 AI Agent

本仓库针对构建 MCP 服务的 AI Agent 进行了优化！

🎯 理想的学习配置

• 📄 template_server.py - 简洁的起始模板，包含所有样板代码
• 🎮 minesweeper_server.py - 可供学习的复杂可运行示例
• 📚 完整指南 - 分步骤说明和模式

🚀 AI Agent 快速开始

# 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

📖 完整文档

• FastMCP 2.0 AI Agent Guide - 构建企业级服务
• AI Agent Instructions - 分步骤模板
• Template Server - 开箱即用的起点

🎯 使用场景

• 游戏服务：提供实时状态的互动娱乐
• 数据处理：通过流式结果进行复杂分析
• API 集成：协调外部服务
• 教育工具：互动学习系统
• 效率应用：任务管理和自动化

🏢 企业级功能（FastMCP 2.0）

🚀 多种传输方式

# 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)

🔐 身份验证与安全

@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"]
    }

📊 实时数据与会话

@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 & 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 集成

1. 复制配置：从 examples/configs/claude_desktop_config.json 复制
2. 更新服务路径，使其与你的设置一致：

{
  "mcpServers": {
    "minesweeper": {
      "command": "python",
      "args": ["/path/to/examples/servers/minesweeper_server.py"]
    },
    "filesystem": {
      "command": "python", 
      "args": ["/path/to/examples/servers/filesystem_server.py"]
    }
  }
}

3. 重启 Claude Desktop，开始畅玩！🎮

🎮 扫雷游戏示例

🎯 开始游玩

# 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"}

🧮 高级分析

# 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

📊 统计与学习

# Check your progress
stats = list_games()
# Shows win rate, best times, active games

# Learn from the masters
guide = get_strategy_guide()
# Comprehensive strategy documentation

🧪 测试你的服务

🔍 MCP Inspector

# Test any server interactively
mcp dev examples/servers/minesweeper_server.py
mcp dev examples/servers/basic_server.py

🤖 程序化测试

# 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

🌟 特别之处

🎮 生动的示例

• 互动游戏：观察大模型学习并制定策略
• 实时状态：查看决策过程如何展开
• 教育价值：通过游戏理解 AI 推理

🏢 面向企业就绪

• 生产部署：HTTP 服务、身份验证、会话
• 可扩展架构：多种传输方式，支持 WebSocket
• 监控与分析：内置统计信息和性能跟踪

🤖 针对 AI Agent 优化

• 完整模板：可直接复制粘贴的服务生成器
• 全面文档：提供自主构建所需的一切内容
• 最佳实践：安全、错误处理、测试模式

📚 了解更多

• FastMCP 文档 - FastMCP 2.0 官方文档
• MCP 规范 - 协议规范
• 官方 MCP SDK - Python SDK
• MCP 社区 - 社区资源

🤝 参与贡献

欢迎贡献！无论是：

• 🎮 新游戏示例（Chess、井字棋、数独）
• 🏢 企业模式（身份验证、监控、部署）
• 🤖 AI Agent 工具（模板、生成器、测试）
• 📚 文档（教程、指南、示例）

指南

• 保持示例实用且有教育意义
• 提供全面的文档
• 遵循安全最佳实践
• 添加适当的错误处理
• 全面使用类型提示

🏆 展示

用这些示例做出了很棒的东西？ 我们很乐意展示！

• 企业级 MCP 部署
• 教育类 AI 系统
• 互动游戏服务
• 创意大模型应用

📄 许可证

MIT 许可证——随心构建！详情请参阅 LICENSE。

🙏 致谢

• Anthropic - 感谢创建 MCP，让 AI 变得更好
• Jeremiah Lowin - 感谢打造出色的 FastMCP 框架
• MCP 社区 - 感谢提供优秀的生态系统
• 贡献者 - 感谢你们让这个代码库如此出色

---

🎯 准备好开始构建了吗？

# 📄 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

🚀 祝构建愉快！让我们打造强大又有趣的 MCP 服务！ 🎮