Model Context Protocol (MCP) Example

🎯 MCP の例 - エンタープライズ版

🚀 FastMCP 2.0 を活用した、高度な Model Context Protocol サーバー構築のための例

MCP の究極のサンプルリポジトリへようこそ！動的なマインスイーパーの例と、FastMCP 2.0 の包括的なテンプレートを使って、エンタープライズグレードの AI サーバーを構築できます。

✨ 今回のエディションの新機能

🎮 動的なゲームの例：LLM が論理的推論を通じてマインスイーパーを攻略する様子を確認できます
🚀 FastMCP 2.0：複数のトランスポートプロトコルに対応したエンタープライズ機能
🏢 本番環境対応：認証、セッション、リアルタイムデータ、WebSocket に対応
🤖 AI エージェントに最適：サーバーの自動生成に使える包括的なテンプレートとガイド

🎯 注目の機能：マインスイーパー 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

LLM がマインスイーパーをプレイする様子をご覧ください：

# 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 エージェント向け

このリポジトリは、AI エージェントによる MCP サーバー構築に最適化されています！

🎯 学習に最適なセットアップ

• 📄 template_server.py - 定型コードが揃った、すぐに始められるシンプルなひな形
• 🎮 minesweeper_server.py - 学習に使える、複雑な動作例
• 📚 完全ガイド - 手順ごとの説明とパターン

🚀 AI エージェント向けクイックスタート

# 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

🌟 このプロジェクトの特長

🎮 生きたサンプル

• インタラクティブなゲームプレイ：LLM が学習し、戦略を立てる様子を見られます
• リアルタイムの状態：意思決定のプロセスを確認できます
• 教育的価値：プレイを通して AI の推論を理解できます

🏢 エンタープライズ対応

• 本番環境へのデプロイ：HTTP サーバー、認証、セッションに対応
• スケーラブルなアーキテクチャ：複数のトランスポート、WebSocket に対応
• モニタリングと分析：統計とパフォーマンスを組み込みで追跡

🤖 AI エージェント向けに最適化

• 完全なテンプレート：コピー＆ペーストでサーバーを生成
• 包括的なドキュメント：自律的な開発に必要な情報をすべて網羅
• ベストプラクティス：セキュリティ、エラー処理、テストのパターン

📚 詳細情報

• FastMCP のドキュメント - FastMCP 2.0 の公式ドキュメント
• MCP 仕様 - プロトコル仕様
• 公式 MCP SDK - Python SDK
• MCP コミュニティ - コミュニティのリソース

🤝 コントリビューション

コントリビューションを歓迎します。たとえば、以下のようなものです。

• 🎮 新しいゲームのサンプル（Chess、Tic-tac-toe、Sudoku）
• 🏢 エンタープライズ向けのパターン（認証、モニタリング、デプロイ）
• 🤖 AI エージェント向けのツール（テンプレート、ジェネレーター、テスト）
• 📚 ドキュメント（チュートリアル、ガイド、サンプル）

ガイドライン

• サンプルは実用的で教育的なものにしてください
• 包括的なドキュメントを含めてください
• セキュリティのベストプラクティスに従ってください
• 適切なエラー処理を追加してください
• 全体を通して型ヒントを使用してください

🏆 活用事例

これらのサンプルを使って何かすてきなものを作りましたか？ ぜひ紹介させてください！

• エンタープライズ向け MCP のデプロイ
• 教育用 AI システム
• インタラクティブなゲームサーバー
• 独創的な LLM アプリケーション

📄 ライセンス

MIT License - 自由に作成してください！詳細はLICENSEをご覧ください。

🙏 謝辞

• Anthropic - MCP を作成し、AI をより良くしてくれたことに感謝します
• Jeremiah Lowin - 素晴らしい FastMCP フレームワークに感謝します
• MCP Community - 優れたエコシステムに感謝します
• 貢献者の皆さん - このリポジトリを素晴らしいものにしてくれています

---

🎯 さあ、開発を始めましょう！

# 📄 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 サーバーを一緒に作りましょう！ 🎮