Number Guessing Game MCP Server

数字当てゲーム MCP サーバー

TypeScript で実装された Model Context Protocol（MCP）サーバーのデモです。各ユーザーが独自のツールとリソースを利用でき、それらを中央コントローラーが管理する、動的なセッションベースのアーキテクチャを紹介します。このサーバーでは、シンプルな数字当てゲームを提供します。

アクセス先：https://mcp.number-guessing-game.portal.one/mcp

その他のリモートサーバーはこちら：https://remote-mcp-servers.com/

動的な MCP サーバーのメリットについての記事をご覧ください：

https://portal.one/blog/dynamic-mcp-servers-tame-complexity/

以下は、サーバーを手動で操作する例です。現在のゲーム状態によってツールが変化することに注目してください。

https://github.com/user-attachments/assets/8bb15870-2adc-4412-a072-4fc4eb14bbef

こちらは、エージェントがサーバーを操作する動画です。動画では確認できませんが、ゲームの状態に応じて、エージェントが利用できるツールも変化しています。

https://github.com/user-attachments/assets/d7d338a2-8a93-46c3-b4a9-1a6b4caf9dc0

このプロジェクトは、動的なマルチユーザー MCP アプリケーションを構築するための学習リソースおよび実践的な例として作成されています。

目次

1. 主な機能
2. アーキテクチャの概要
3. 前提条件
4. はじめに
5. サーバーの実行
6. サーバーの操作
7. プロジェクト構成
8. 紹介する主な概念
9. コントリビューション
10. ライセンス

主な機能

• 真のマルチユーザーセッション： 接続する各ユーザーに、それぞれ分離されたゲーム状態と MCP エンティティのセットが割り当てられます。
• 動的な MCP ツール： ツール（start_game、guess_number、give_up）は、各ユーザーのゲーム状態に応じて有効または無効になります。
• 動的な MCP リソース： game_state リソースは、各ユーザーがゲームを開始すると作成され、終了すると破棄されます。
• シンプルで拡張性の高いアーキテクチャ：
  • 単一のグローバルな McpServer がすべての接続を処理します。
  • Express.js コントローラーが各ユーザーセッションのライフサイクルを管理します。
  • セッションスコープのエンティティ（ツール、リソース、ゲームロジック）は必要に応じて作成されます。
  • ステートパターン： ユーザーごとのゲームの進行状況（ロビー、プレイ中）を管理します。
• TypeScript による実装： 保守性と開発者エクスペリエンスを高めるため、完全に型付けされています。
• Firestore との統合： ゲーム状態とハイスコアを永続化することで、ステートレスでスケーラブルなサーバーを実現します。

アーキテクチャの概要

このサーバーは、中央コントローラーが一時的なセッション固有のリソースを管理する、最新のスケーラブルなパターンに従っています。

1. グローバルサーバー設定（src/mcp_setup/index.ts）： アプリケーションの起動時に McpServer インスタンスが作成されます。これは「白紙」の接続マネージャーとして機能し、ツールやリソースは自身に含みません。

2. HTTP コントローラー（src/controllers/mcp.controller.ts）： アプリケーションの中核です。

   • /mcp エンドポイントへのすべての受信 HTTP リクエストを処理します。
   • 新しいユーザーが接続すると、StreamableHTTPServerTransport を作成します。
   • トランスポートのライフサイクルフック（onsessioninitialized と onclose）を使用して、ユーザーのセッションを管理します。

3. セッションの初期化（onsessioninitialized）： ユーザーのトランスポートの準備ができると、コントローラーは次の処理を行います。

   • src/mcp_setup/tools と src/mcp_setup/resources のセットアップ関数を呼び出し、そのユーザー専用の 新しい一意の MCP エンティティ一式 を作成します。
   • 新しい GameContext インスタンスを作成し、ユーザーのセッション ID と、そのユーザー専用の MCP エンティティを関連付けます。
   • GameSessionService を介してユーザーの状態を Firestore から読み込み、State パターン（LobbyState または PlayingState）を使用して、そのセッションで適切なツールを有効化または無効化します。

4. セッションの破棄（onclose）： ユーザーが切断すると、コントローラーは次の処理を行います。

   • そのユーザー専用に作成されたすべてのツールとリソースを 登録解除して破棄 し、メモリリークを防ぎます。
   • アクティブな接続のリストからトランスポートを削除します。

このアーキテクチャにより、各ユーザーの UI 状態（有効なツールなど）が完全に分離され、状態を保持しながら動的に管理される一方、サーバー自体はスケーラブルな状態を保てます。

前提条件

• Node.js（v18.x 以降を推奨）
• npm または yarn
• Firestore が有効になっている Google Cloud プロジェクトへのアクセス権

はじめに

インストール

1. リポジトリをクローンします：

   git clone https://github.com/portal-labs-infrastructure/number-guessing-game-mcp-server
   cd number-guessing-game-mcp-server
   

2. 依存関係をインストールします：

   npm install
   # or
   yarn install
   

設定

1. Google Cloud 認証を設定します： お使いの環境が Google Cloud プロジェクトに対して認証されていることを確認してください。ローカル開発では、gcloud CLI を使用できます。

   gcloud auth application-default login
   

2. .env ファイルを作成します： サンプルファイルをコピーします。

   cp .env.example .env
   

3. .env を編集します： 必須の環境変数を設定します。
   • PORT：サーバーを実行するポート（例：8083）。
   • GCP_PROJECT_ID：Google Cloud プロジェクト ID。
   • BASE_URL：サーバーの公開 URL（例：http://localhost:8083）。
   • OAUTH_ISSUER_URL：OAuth プロバイダーのベース URL。
   • DOCS_URL：サービスのドキュメントへのリンク。

サーバーの実行

開発モード（ホットリロードを使用した開発向け）：

npm run dev

本番モード：

TypeScript をコンパイルします：

npm run build

サーバーを起動します：

npm start

サーバーが実行中で、Firestore に接続されていることを示す出力が表示されます。

サーバーとのやり取り

ライブサーバー

次の機能に対応する MCP クライアントが必要です。

• OAuth2（動的クライアント登録対応）
• ツール通知
• リソース通知

MCP Inspector を使用できますが、ツール通知とリソース通知には対応していないため、ツールとリソースを手動で更新する必要があります。

Portal One のウェブクライアントを使用し、利用可能な MCP サーバーの一覧からこのサーバーを見つけて「connect」をクリックします。

動的な MCP ツールとリソースの検出に対応するその他のクライアントについては、MCP SDK Example Clients をご覧ください。

ローカル

クライアントからサーバーにアクセスできることを確認してください。サーバーをローカルで実行していて、ウェブベースのクライアントを使用している場合は、ngrok などのツールを使ってサーバーをインターネットに公開できます。

ngrok http http://localhost:8083

localhost 上のクライアントを使用する場合は、http://localhost:8083/mcp に直接接続できます。

プロジェクト構成

src/
├── config/
│   └── index.ts                # Loads and exports environment variables
├── controllers/
│   └── mcp.controller.ts       # Manages session lifecycles and creates entities on-demand
├── game/
│   ├── commands/               # Command Pattern: Encapsulates user actions
│   │   ├── command.interface.ts
│   │   ├── give-up.command.ts
│   │   ├── guess-number.command.ts
│   │   └── start-game.command.ts
│   ├── core/
│   │   ├── game-context.ts       # Central game logic coordinator for a SINGLE session
│   │   ├── game-session-service.ts # Handles all Firestore interactions (get/set state)
│   │   ├── game-types.ts       # Core TypeScript interfaces for the game
│   │   ├── resource-factory.ts # (Not used in current setup, but available)
│   │   └── tool-factory.ts     # (Not used in current setup, but available)
│   ├── states/                 # State Pattern: Manages game flow (Lobby, Playing)
│   │   ├── game-state.interface.ts
│   │   ├── lobby.state.ts
│   │   └── playing.state.ts
│   └── utils/
│       └── game-constants.ts   # Shared game constants
├── index.ts                    # Main application entry point (Express server setup)
├── mcp_setup/
│   ├── index.ts                # Creates the single, global McpServer instance
│   ├── resources/              # Factory functions for creating MCP resources
│   │   ├── index.ts            # Barrel file for exporting all resource setups
│   │   └── ... (setup-banner-image-resource.ts, etc.)
│   └── tools/                  # Factory functions for creating MCP tools
│       ├── index.ts            # Barrel file for exporting all tool setups
│       └── ... (setup-guess-number-tool.ts, etc.)
├── routes/
│   └── mcp.routes.ts           # Defines the Express routes for /mcp
└── services/
    └── firestore.service.ts    # Initializes the global Firestore client

実演する主な概念

• 動的なセッションスコープの MCP： このアーキテクチャの中核です。ツールとリソースはグローバルではなく、各ユーザーセッションごとに作成され、破棄されます。
• ライフサイクル管理： トランスポートフック（onsessioninitialized、onclose）を使用して、セッションリソースのセットアップと破棄を管理します。
• HTTP 経由のステートフルサービス： ステートレスなプロトコル上で、永続的かつ分離されたユーザーセッションを実装します。
• 状態パターン： 各ユーザーのゲームフローにおける複雑な状態遷移を管理します。
• 状態の永続化に Firestore を使用： サーバーのランタイムをゲームの状態から分離し、水平スケーリングと耐障害性を実現します。
• TypeScript のベストプラクティス： 型を使用して、実用的でスケーラブルなアプリケーション構造に堅牢なコードを実装します。

コントリビューション

コントリビューションを歓迎します。改善案や新機能のアイデアがある場合、またはバグを見つけた場合は、お気軽にイシューまたはプルリクエストを作成してください。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。