Dungeon MCP Server

🚀 Dungeon MCP Server

Dungeon MCP Serverは、Model Context Protocol (MCP) を用いたサーバーで、テキストベースのダンジョンクローリングアドベンチャーシステムを提供します。プレイヤーは、一連のMCPツールを通じて、神秘的なダンジョンを探索し、NPCと対話し、宝物を集め、モンスターと戦うことができます。

🚀 クイックスタート

このサーバーは、Fangライブラリを使用していくつかのCLIパラメータをサポートし、ユーザー体験を向上させています。

./mcp-dungeon [OPTIONS]

✨ 主な機能

• ダンジョン探索：相互に接続された部屋や通路を移動します。
• インタラクティブ要素：様々な場所にNPC、宝物、モンスターが存在します。
• プレイヤー管理：YAMLファイルからプレイヤーデータを読み込み/保存します。
• ビジュアルマップ表示：ダンジョン全体をASCIIアートで表示します。
• RESTful API：MCPプロトコルをサポートするHTTPサーバーです。
• カスタマイズ可能：カスタムダンジョンやプレイヤー設定をサポートします。

📦 インストール

このプロジェクトには明示的なインストール手順が記載されていないため、このセクションは省略されます。

💻 使用例

コマンドラインインターフェイス

サーバーは、Fangライブラリを使用していくつかのCLIパラメータをサポートしています。

./mcp-dungeon [OPTIONS]

CLIパラメータ

例

# デフォルト設定でサーバーを起動
./mcp-dungeon

# カスタムプレイヤーとポートで起動
./mcp-dungeon --player-file my_player.yaml --port 8080

# 別のダンジョンファイルを使用
./mcp-dungeon --dungeon-file my_dungeon.yaml

# サンプルのプレイヤーファイルを生成
./mcp-dungeon --generate-player --player-file hero.yaml

# ヘルプを表示
./mcp-dungeon --help

サーバーエンドポイント

サーバーが起動すると、以下のエンドポイントが提供されます。

• MCPエンドポイント: http://localhost:PORT/mcp - 主要なMCPプロトコルエンドポイント
• ヘルスチェック: http://localhost:PORT/health - サーバーのヘルスステータス

📚 ドキュメント

プレイヤー設定

プレイヤーYAML形式

プレイヤーの設定は templates/player_sample.yaml を参照してください。

サンプルプレイヤーの生成

サンプルのプレイヤー設定を作成するには、以下のコマンドを実行します。

./mcp-dungeon --generate-player

これにより、デフォルト値を持つ player_sample.yaml が作成されます。

ダンジョン設定

ダンジョンYAML形式

ダンジョンの設定は、通常 templates/crystal_caverns.yaml のYAMLファイルで定義されます。

MCPツール

サーバーは以下のMCPツールを提供します。

1. say_hello

ユーザーに挨拶をする。

パラメータ:

• name (文字列, 必須): 挨拶するユーザーの名前

例:

{
  "name": "say_hello",
  "arguments": {
    "name": "Alice"
  }
}

2. get_room_details_by_name

部屋の名前/IDから詳細情報を取得する。

パラメータ:

• room_name (文字列, 必須): 部屋の名前/ID

例:

{
  "name": "get_room_details_by_name",
  "arguments": {
    "room_name": "entrance_cave"
  }
}

3. get_room_details_by_coordinates

部屋の座標から詳細情報を取得する。

パラメータ:

• x (数値, 必須): X座標
• y (数値, 必須): Y座標

例:

{
  "name": "get_room_details_by_coordinates",
  "arguments": {
    "x": 2,
    "y": 5
  }
}

4. move_to_room_by_name

プレイヤーを指定された部屋に移動する。接続された部屋への移動のみ許可されます。

パラメータ:

• target_room (文字列, 必須): 目標の部屋の名前/ID

例:

{
  "name": "move_to_room_by_name",
  "arguments": {
    "target_room": "corridor_1"
  }
}

5. get_player_status

プレイヤーの現在のステータスと情報を取得する。

パラメータ: なし

例:

{
  "name": "get_player_status",
  "arguments": {}
}

6. display_dungeon_map

部屋、通路、およびプレイヤーの現在位置を示すダンジョン全体のASCIIマップを表示する。

パラメータ: なし

例:

{
  "name": "display_dungeon_map",
  "arguments": {}
}

ゲームメカニクス

移動ルール

• プレイヤーは現在の位置に直接接続された部屋にのみ移動できます。
• 移動はダンジョンの接続グラフに基づいて検証されます。
• 移動時にプレイヤーの座標は自動的に更新されます。

部屋の種類

1. 部屋: NPC、宝物、モンスター、またはアイテムを含むことができます。
2. 通路: 部屋間の接続通路です。
3. 入り口: プレイヤーの開始位置です。
4. 出口: ダンジョンをクリアするための目標位置です。

場所の要素

• NPC: 名前と説明を持つ非プレイヤーキャラクター
• 宝物: 金の価値を持つ貴重品
• モンスター: 難易度とヒットポイントを持つ敵
• アイテム: 回復薬などの消耗品

テスト

手動テスト用のテストスクリプトが提供されています。

cd tests
# 部屋の詳細をテスト
./room.tool.call.sh

# プレイヤーの移動をテスト
./move.tool.call.sh

# プレイヤーのステータスをテスト
./status.tool.call.sh

トラブルシューティング

一般的な問題

1. セッションIDが欠落している: Mcp-Session-Id ヘッダを含めることを確認してください。
2. 無効な部屋移動: ダンジョンのYAMLファイルで部屋の接続を確認してください。
3. ポートがすでに使用されている: --port パラメータでポートを変更してください。
4. ファイルが見つからない: ダンジョンとプレイヤーのファイルのパスを確認してください。

ヘルスチェック

サーバーが実行中であることを確認します。

curl http://localhost:9090/health

期待される応答:

{
  "status": "healthy",
  "dungeon_name": "Dungeon of Crystal Caverns"
}