JinDaGe - dungeon-mcp-server MCP Details

article

README

🚀 地下城MCP服务器

地下城MCP服务器 是一个基于模型上下文协议（MCP）的服务器，它提供了一个基于文本的地下城冒险系统。玩家可以通过一系列MCP工具探索神秘的地下城，与NPC互动，收集宝藏，并与怪物战斗。

✨ 主要特性

地下城探索：在相互连接的房间和走廊中穿梭。
互动元素：在不同位置设有NPC、宝藏和怪物。
玩家管理：可从YAML文件加载/保存玩家数据。
可视化地图展示：以ASCII艺术形式展示整个地下城。
RESTful API：支持MCP协议的HTTP服务器。
可定制：支持自定义地下城和玩家配置。

📦 安装指南

文档未提及安装步骤，故跳过此章节。

💻 使用示例

命令行界面

服务器使用Fang库支持多个CLI参数，以提升用户体验：

./mcp-dungeon [OPTIONS]

CLI参数

| 参数 | 描述 | 默认值 | 是否必需 | |------|------|--------|----------| | --dungeon-file | 地下城YAML文件的路径 | crystal_caverns.yaml | 否 | | --player-file | 玩家YAML文件的路径 | 无（使用默认玩家） | 否 | | --port | HTTP服务器端口 | 9090 | 否 | | --generate-player | 生成示例玩家YAML文件 | false | 否 | | --help, -h | 显示帮助信息 | | 否 | | --version, -v | 显示版本信息 | | 否 |

示例

# 使用默认设置启动服务器
./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": {}
}

参数：无

游戏机制

移动规则

玩家只能移动到与当前位置直接相连的房间。
移动会根据地下城的连接图进行验证。
移动时玩家的坐标会自动更新。

房间类型

房间：可包含NPC、宝藏、怪物或物品。
走廊：房间之间的连接通道。
入口：玩家的起始位置。
出口：完成地下城的目标位置。

位置元素

NPC：有姓名和描述的非玩家角色。
宝藏：有金币价值的贵重物品。
怪物：有难度等级和生命值的敌人。
物品：如治疗药水等消耗品。

测试

提供了用于手动测试的脚本：

cd tests
# 测试房间详情
./room.tool.call.sh

# 测试玩家移动
./move.tool.call.sh

# 测试玩家状态
./status.tool.call.sh

🔧 技术细节

常见问题排查

常见问题

会话ID缺失：确保包含 Mcp-Session-Id 头部。
无效的房间移动：检查地下城YAML文件中的房间连接。
端口已被占用：使用 --port 参数更改端口。
文件未找到：验证地下城和玩家文件的路径。

健康检查

验证服务器是否正在运行：

curl http://localhost:9090/health

预期响应：

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

dungeon-mcp-server