Gamemaster MCP

🚀 ゲームマスターMCP 🐉

モデルコンテキストプロトコルMCPを基に構築された包括的なサーバーで、**FastMCP 2.9.0+**を使用して、AI支援付きのダンジョン&ドラゴンズのキャンペーンを管理します。

ゲームマスターMCP 🐉 は、DnD 5eの究極のAI支援付きダンジョンマスターを目指し、以下の機能を提供します。

• グループ向け：ユーザーがキャンペーンをより効果的に進行できる包括的なツールキット
• ソロプレイヤー向け：没入型のソロプレイを容易にする完全な仮想DnD体験
• ワールドビルダー向け：豊かで相互に関連するゲームワールドの作成を支援する強力なツール

FastMCPに基づいて構築されたこのサーバーは、構造化されたデータモデルとインテリジェントなツールを提供し、D&Dキャンペーンのすべての側面を管理すると同時に、MCPクライアントを通じた自然言語対話を可能にします。

🚧 建設中 🚧

✨ 主な機能

🌍 キャンペーン管理

D&Dの世界の基盤です。各キャンペーンには以下が含まれます。

• コアメタデータ：名前、説明、設定、DMの名前
• キャラクター：すべてのプレイヤーキャラクターとそのシート
• NPC：世界に存在するすべてのノンプレイヤーキャラクター
• 場所：都市、ダンジョン、興味深い場所
• クエスト：進行中と完了したストーリーライン
• ゲーム状態：現在のセッション、パーティの場所、世界の状況

すべてのデータは自動的に保存され、セッション間で共有できます。

• 複数のキャンペーンを作成および管理
• キャンペーン間をシームレスに切り替え
• キャンペーンのメタデータ（名前、説明、DM、設定）を追跡

📑 キャラクター管理

完全なD&D 5eキャラクターシートで、以下が含まれます。

• コア属性：自動計算される修正値付きの能力値
• 戦闘統計：HP、AC、セービングスロー、耐性
• インベントリ：重量と価値を追跡する装備
• 魔法使用：準備された魔法、スロット、DC
• 成長：自動的な特典解放付きのレベルアップ

キャラクターはプレイ中に進化します。ダメージを受け、アイテムを獲得し、レベルアップします。

• D&D 5eのステータスを持つ完全なキャラクターシート
• 自動修正値計算付きの能力値
• ヒットポイント、アーマークラス、戦闘統計
• インベントリと装備管理
• 魔法使用のサポート

🧝 NPC管理

以下の特徴を持つ豊かなNPCで世界を生き生きとさせます。

• 説明：外見、性格、声のメモ
• 関係：他のキャラクター/派閥とのつながり
• 場所：住んでいる場所やよく訪れる場所
• 秘密：隠された動機と知識
• 統計：必要に応じた戦闘用のクイックリファレンス

NPCはクエストや場所にリンクでき、簡単に参照できます。

• ノンプレイヤーキャラクターを作成および追跡
• 関係と場所を管理
• 説明とメモを保存

🗺️ 場所/ワールドビルディング

以下を持つ没入型の設定を作成します。

• 詳細な説明：感覚的な詳細と地図
• 注目すべき特徴：ランドマーク、秘密、危険
• つながり：移動経路のためのリンクされたエリア
• 住人：存在するNPCとモンスター
• ロア：地元の歴史と伝説

場所はパーティが探索するにつれて更新され、発見したエリアが追加され、状況が変化します。

• 詳細な場所（都市、ダンジョンなど）を作成
• 人口、政府、注目すべき特徴を追跡
• 場所を接続し、地理を管理

💎 クエスト管理

以下を持つストーリーアークとミッションを追跡します。

• 目的：完了までの明確な手順
• ステータス追跡：進行中/完了/失敗
• 依頼者と報酬：関連するNPCと賞品
• 時間制限：オプションの期限
• 分岐パス：代替解決策

クエストの進捗は自動的にゲーム状態とアドベンチャーログを更新します。

• 目的と報酬を持つクエストを作成
• クエストのステータスと完了を追跡
• クエストをNPCや場所にリンク

⚔️ 戦闘管理

以下を持つ動的な戦闘エンカウンターを追跡および進行します。

• イニシアチブ順序：手動オーバーライド付きの自動ソート
• ターン追跡：現在のアクターのハイライトとターンのリマインダー
• 状態管理：持続時間追跡付きのステータスエフェクト
• ダメージ/回復：自動HP計算付きで適用
• 敵の統計：モンスター/NPCのクイックリファレンス

戦闘データは以下に流れます。

• キャラクターシート（HP、状態）

• ゲーム状態（現在のエンカウンター）

• アドベンチャーログ（戦闘イベント）

• イニシアチブ追跡

• ターンベースの戦闘フロー

• 戦闘エンカウンターの計画

⏰ セッション管理

以下を持つゲームセッションを整理します。

• セッションノート：重要なイベントと決定
• 出席追跡：出席したプレイヤー
• XP報酬：キャラクターの成長を追跡
• 戦利品分配：見つかった宝と獲得した宝
• ゲーム日付：ゲーム内の時間経過を追跡

セッションデータは以下を更新します。

• キャラクターシート（XP、アイテム）

• ゲーム状態（現在のセッション番号）

• アドベンチャーログ（セッションの要約）

• セッションノートと要約

• 経験値と戦利品の追跡

• キャラクターの出席

🏕️ アドベンチャーログ

キャンペーンの生きた歴史です。

• イベントタイプ：戦闘、ロールプレイ、探索など
• タイムラインビュー：時系列のストーリー進行
• 検索可能：重要な瞬間をすばやく見つける
• タグと重要度：主要なプロットポイントを強調
• セッションリンク：イベントをゲームセッションに接続

ログは以下に接続されます。

• クエスト（進捗更新）

• 場所（イベントが発生した場所）

• NPC（関係するキャラクター）

• 包括的なイベントロギング

• イベントタイプ（戦闘、ロールプレイ、探索など）で分類

• 検索とフィルタリング可能

• 重要度評価

🎮 ゲーム状態追跡

世界の現在のスナップショットです。

• パーティの状態：場所、リソース、状態
• 進行中のクエスト：現在の目的と進捗
• 世界の状況：天候、政治的な状況
• 時間追跡：ゲーム内の日付と時間
• 戦闘状態：現在のエンカウンターの詳細

ゲーム状態は他のすべてのモデルに接続されます。

• キャラクターの行動からの更新

• 世界のシミュレーションを駆動

• AI DMの決定に情報を提供

• 現在の場所とセッション

• パーティのレベルと資金

• 戦闘状態

• ゲーム内の日付追跡

🎲 ユーティリティツール

• D&D表記（例："1d20", "3d6+2"）でのダイスロール
• エンカウンターのXP分配の計算
• D&D 5eのメカニクスサポート

📦 インストール

前提条件

• Python 3.12+
• uv（システムのPATHに含まれている必要があります）

ユーザーインストール

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

git clone https://github.com/study-flamingo/gamemaster-mcp.git
cd gamemaster-mcp

2. 仮想環境を作成し、依存関係をインストールします：

uv venv
uv pip install .

🚀 クイックスタート

コマンドラインからの実行

サーバーを直接実行するには、まず仮想環境をアクティブ化します。

# macOS/Linuxの場合
source .venv/bin/activate

# Windowsの場合
.venv\Scripts\activate

次に、実行可能ファイルを実行します。

gamemaster-mcp

あるいは、仮想環境をアクティブ化せずにuvを使用してスクリプトを実行することもできます。

uv run gamemaster-mcp

MCPクライアント（例：Claude Desktop）を使用する場合

MCPクライアントを構成して、uvを使用してサーバーを実行します。作業ディレクトリとしてプロジェクトフォルダのパスを指定するだけです。

{
  "mcpServers": {
    "gamemaster-mcp": {
      "command": "uv",
      "args": [
        "run",
        "gamemaster-mcp"
      ],
      "cwd": "C:\\path\\to\\your\\gamemaster-mcp"
    }
  }
}

注：C:\\path\\to\\your\\gamemaster-mcpをプロジェクトディレクトリの絶対パスに置き換えてください。

🎛️ システムプロンプトの推奨

最適なパフォーマンスを得るには、LLMが知識豊富なダンジョンマスターのアシスタントとして行動するように準備するシステムプロンプトを使用してください。このプロンプトは、D&Dキャンペーン管理のコンテキストを理解し、提供されたツールを効果的に活用するようにモデルを導く必要があります。

📜 システムプロンプトの例

あなたは、ゲームマスターMCPサーバーによって動作するマスターダンジョンマスター（DM）またはダンジョンマスターのアシスタントです。あなたの主な役割は、高度な専用ツールの豊富なセットを使用して、ユーザーがダンジョン&ドラゴンズのキャンペーンのすべての側面を管理するのを支援することです。あなたは状態を持つエンティティであり、常に単一の現在アクティブなキャンペーンで動作します。

**コア原則**：

1. **キャンペーン中心**：すべてのデータ（キャラクター、NPC、クエスト、場所）は単一のアクティブな`キャンペーン`内に保存されます。常に現在のキャンペーンのコンテキストを意識してください。ユーザーの要求が別のキャンペーンを参照しているように見える場合、`list_campaigns`と`load_campaign`ツールを使用してコンテキストを切り替えてください。
2. **構造化データ**：あなたは構造化データモデル（`キャラクター`, `NPC`, `クエスト`, `場所`など）を扱っています。これらのエンティティを作成または更新するときは、できるだけ多くの詳細を入力するように努めてください。ユーザーが曖昧な場合、具体的な情報を尋ねてください（例：「キャラクターのクラスと種族は何ですか？能力値は何ですか？」）。
3. **積極的な支援**：単一のコマンドを実行するだけでなく、ツールを連鎖させて複雑なユーザー要求を満たしてください。たとえば、「パーティに新しいキャラクターを追加する」には、`create_character`を使用してから、おそらく`add_item_to_character`を使用して初期装備を与えます。
4. **情報収集**：行動する前に、`list_`と`get_`ツールを使用して現在の状態を理解してください。たとえば、クエストを追加する前に、`list_npcs`を使用して誰がクエストの依頼者になり得るかを確認することができます。
5. **状態管理**：`get_game_state`と`update_game_state`ツールを使用して、パーティの現在の場所、ゲーム内の日付、戦闘状態を追跡してください。
6. **ストーリーテラーになる**：主な機能はデータ管理ですが、応答をD&Dゲームのコンテキストで表現してください。あなたは単なるデータベースではなく、キャンペーンの世界の守護者です。

**インタラクティブなセッションゼロ**：

ユーザーが新しいキャンペーンを開始したい場合、インタラクティブな「セッションゼロ」を開始します。ユーザーを手順を追ってセットアッププロセスを案内し、質問をしてツールを使用して共同で世界を構築します。以下のフレームワークを*緩やかな*ガイドラインとして使用してください：ユーザーの指示に従うことがより重要です。ただし、各ツール呼び出しの必要なパラメータを確立することを確認してください。

1. **キャンペーンを確立する**：
    * **あなた**：「冒険の世界へようこそ！新しいキャンペーンの名前は何にしましょう？」（ユーザーの入力を待つ）
    * **あなた**：「素晴らしい！そして、'キャンペーン名'の中心的なテーマまたは説明は何ですか？」（ユーザーの入力を待つ）
    * その後、収集した情報を使用して`create_campaign`を使用します。

2. **パーティを構築する**：
    * **あなた**：「さて、ヒーローたちを集めましょう。パーティには何人のプレイヤーがいますか？」
    * 各プレイヤーについて、キャラクターを作成するための対話を行います：
    * **あなた**：「最初のキャラクターを作成しましょう。彼らの名前、種族、クラスは何ですか？」
    * **あなた**：「素晴らしい。彼らの能力値（筋力、器用さなど）は何ですか？」
    * 各ヒーローのコア詳細を収集した後、`create_character`を使用します。

3. **世界を充実させる**：
    * **あなた**：「私たちの物語はどこから始まりますか？始まりの町または場所を説明してください。」
    * `create_location`を使用します。
    * **あなた**：「パーティが最初に会う人は誰ですか？NPCを作成しましょう。」
    * `create_npc`を使用します。

4. **冒険を開始する**：
    * **あなた**：「世界のセットアップが完了しました。パーティが最初に直面する挑戦またはクエストは何ですか？」
    * `create_quest`を使用します。
    * **あなた**：「セッションゼロは完了です！最初のセッションの開始を記録しました。冒険を始める準備はできていますか？」
    * `add_session_note`を使用します。

あなたの目標は、ダンジョンマスターにとって欠かせないパートナーになり、キャンペーンの基盤を共同で構築して、彼らが素晴らしい物語を語ることに集中できるようにすることです。

**キャンペーン中のガイダンス**：

キャンペーンが開始された後、あなたの焦点は動的な管理と物語的なサポートに移ります。

1. **動的な世界**：プレイヤーの行動とツールの出力に応答して、`ゲーム状態`, `NPC`のステータス, `場所`の詳細, `クエスト`の進捗を動的に更新します。
2. **イベントロギング**：すべての重要なインタラクション、戦闘ラウンド、ロールプレイエンカウンター、またはクエストのマイルストーンは、`add_event`を使用して包括的な`アドベンチャーログ`に記録する必要があります。
3. **積極的なDMサポート**：DMのニーズを予測してください。キャラクターがダメージを受けた場合、`update_character_hp`を提案します。新しいエリアに入った場合、`get_location`の詳細を提供します。
4. **物語の一貫性**：物語の一貫性を維持します。`アドベンチャーログ`または`セッションノート`から過去のイベントを参照して、説明を豊かにし、連続性を確保します。
5. **挑戦と結果**：プレイヤーが行動を試みるとき、潜在的な結果を考慮し、適切なツールを使用して成功、失敗、または部分的な成功を反映し、キャラクターのステータスまたはゲーム状態を更新します。
6. **ツール駆動型の応答**：ツールの成功した実行を中心に物語的な応答を構築します。たとえば、「キャラクターのHPは現在15です」ではなく、「あなたは[キャラクター名]を正常に回復させました。彼らのヒットポイントは現在15です」と言います。

利用可能なツール（25以上のFastMCPツール）

キャンペーン管理

• create_campaign - 新しいキャンペーンを作成
• get_campaign_info - 現在のキャンペーン情報を取得
• list_campaigns - 利用可能なすべてのキャンペーンをリスト
• load_campaign - 別のキャンペーンに切り替え

キャラクター管理

• create_character - 新しいプレイヤーキャラクターを作成
• get_character - キャラクターシートの詳細を取得
• update_character - キャラクターのプロパティ（名前、ステータス、HPなど）を更新
• bulk_update_characters - 複数のキャラクターを一度に更新（例：すべてにダメージを適用）
• add_item_to_character - インベントリにアイテムを追加
• list_characters - すべてのキャラクターをリスト

NPC管理

• create_npc - 新しいNPCを作成
• get_npc - NPCの詳細を取得
• list_npcs - すべてのNPCをリスト

場所管理

• create_location - 新しい場所を作成
• get_location - 場所の詳細を取得
• list_locations - すべての場所をリスト

クエスト管理

• create_quest - 新しいクエストを作成
• update_quest - クエストのステータスまたは目標を更新
• list_quests - クエストをリスト（オプションでステータスでフィルタリング）

ゲーム状態管理

• update_game_state - 現在のゲーム状態を更新
• get_game_state - 現在のゲーム状態を取得

戦闘管理

• start_combat - イニシアチブ順序で戦闘を開始
• end_combat - 戦闘エンカウンターを終了
• next_turn - 次の参加者のターンに進む

セッション管理

• add_session_note - セッションノートと要約を追加
• get_sessions - すべてのセッションノートを取得

アドベンチャーログ

• add_event - アドベンチャーログにイベントを追加
• get_events - イベントを取得（フィルタリングと検索付き）

ユーティリティツール

• roll_dice - D&D表記（例："1d20", "3d6+2"）でダイスを振る
• calculate_experience - エンカウンターのXP分配を計算

💽 データ構造

ゲームマスターMCPサーバーは、すべてのキャンペーンデータを中央のキャンペーンモデルを中心に整理しています。このモデルは、ゲーム世界全体の主要なコンテナとして機能します。この設計により、一貫性のある相互接続されたデータ構造が確保され、さまざまなゲーム要素の簡単な管理と相互作用が可能になります。

システムは、キャンペーンモデルを中心とした階層的なデータ構造を持っています。他のすべてのモデルは、アクティブなキャンペーンに関連付けられています。以下に示すように：

graph TD
    A[Campaign] --> B[GameState]
    A --> C[Character]
    A --> D[NPC]
    A --> E[Location]
    A --> F[Quest]
    A --> G[CombatEncounter]
    A --> H[SessionNote]
    B --> I[AdventureEvent]
    
    C --> J[Item]
    C --> K[Spell]
    C --> L[AbilityScore]
    C --> M[CharacterClass]
    C --> N[Race]
    
    style A fill:#f9f,stroke:#333,stroke-width:4px

src/gamemaster_mcp/models.pyのコアデータモデルがどのように相互作用するかを以下に示します。

• Campaign：基礎となるモデルです。すべてのキャンペーン固有のデータをカプセル化し、以下を含みます。

  • characters：Characterモデルの辞書で、プレイヤーキャラクターを表します。各Characterは、CharacterClass, Race, AbilityScore（コアステータス用）, Item（インベントリと装備用）, Spell（知っている魔法用）で構成される複雑なモデルです。
  • npcs：NPCモデルの辞書で、ノンプレイヤーキャラクターを表します。NPCはLocationモデルにリンクできます。
  • locations：Locationモデルの辞書で、キャンペーン世界内の場所を定義します。場所は関連するNPCをリストし、他の場所への接続を持つことができます。
  • quests：Questモデルの辞書で、進行中と完了したミッションを追跡します。クエストはNPCを依頼者として参照できます。
  • encounters：CombatEncounterモデルの辞書で、計画されたまたはアクティブな戦闘シナリオを詳細に記述します。エンカウンターは特定の場所に関連付けることができます。
  • sessions：SessionNoteモデルのリストで、キャンペーン内で行われた各ゲームセッションの要約と詳細を提供します。
  • game_state：単一のGameStateモデルで、キャンペーンの動的なリアルタイムの状態を捕捉します。現在の場所、アクティブなクエスト、パーティの資金などです。このモデルは、ゲームの即時コンテキストを理解するために重要です。

• GameState：Campaignの一部ですが、世界の現在の状態を反映する重要な役割を果たします。他のモデルに影響を与え、また影響を受けます。

  • current_locationはLocationモデルを指すことができます。
  • active_questsはQuestのタイトルを参照します。
  • Characterの状態（例：hit_points_current）またはQuestの状態（active, completed）の変更は、直接GameStateに影響を与えます。

• AdventureEvent：このモデルは、キャンペーン全体の重要な出来事を記録するために使用されます。Campaign内に直接ネストされているわけではなく（グローバルに保存されます）、AdventureEventのインスタンスはしばしばCampaignのデータの要素を参照します。characters_involvedやlocationなどです。これにより、過去のイベントと物語の進行を理解するための歴史的なログが提供されます。

🖥️ 開発

開発ワークフロー

プロジェクトに貢献したい場合は、セットアップが少し異なります。

1. ユーザーインストールの手順に従って、リポジトリをクローンし、仮想環境をセットアップします。

2. 開発用の依存関係を含めて編集可能なモードでインストールします：

uv pip install -e .[dev]

これにより、コードの変更が再インストールすることなくすぐに反映されるようにプロジェクトがインストールされます。また、テストとリント用のツールもインストールされます。

テストの実行

テストスイートを実行するには、以下のコマンドを使用します。

uv run pytest

📄 ライセンス

MITライセンス