Dungeon MCP Server

🚀 地下城MCP服務器

地下城MCP服務器 是一個基於模型上下文協議（MCP）的服務器，它提供了一個基於文本的地下城冒險系統。玩家可以通過一系列MCP工具探索神秘的地下城，與NPC互動，收集寶藏，並與怪物戰鬥。

✨ 主要特性

• 地下城探索：在相互連接的房間和走廊中穿梭。
• 互動元素：在不同位置設有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格式

地下城配置定義在YAML文件中，通常為 templates/crystal_caverns.yaml。

MCP工具

服務器提供以下MCP工具：

基礎用法

1. say_hello

向用戶打招呼。

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

參數：

• name（字符串，必需）：要打招呼的用戶姓名。

2. get_room_details_by_name

根據房間名稱/ID獲取房間詳細信息。

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

參數：

• room_name（字符串，必需）：房間的名稱/ID。

3. get_room_details_by_coordinates

根據房間座標獲取房間詳細信息。

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

參數：

• x（數字，必需）：X座標。
• y（數字，必需）：Y座標。

4. move_to_room_by_name

將玩家移動到指定名稱的房間。僅允許移動到相連的房間。

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

參數：

• target_room（字符串，必需）：目標房間的名稱/ID。

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