地牢探险服务器

地牢MCP服务器

🚧 这是一项正在进行的工作

概述

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

特性

• 地下城探索：在相互连接的房间和走廊中导航
• 交互式元素：不同地点的NPC、宝藏和怪物
• 玩家管理：从YAML文件加载/保存玩家数据
• 可视化地图显示：整个地牢的ASCII艺术表现
• RESTful API：支持MCP协议的HTTP服务器
• 可定制的：支持自定义地牢和玩家配置

用法

命令行接口

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

./mcp-dungeon [OPTIONS]

CLI参数

例子

# Start server with default settings
./mcp-dungeon

# Start with custom player and port
./mcp-dungeon --player-file my_player.yaml --port 8080

# Use a different dungeon file
./mcp-dungeon --dungeon-file my_dungeon.yaml

# Generate a sample player file
./mcp-dungeon --generate-player --player-file hero.yaml

# Show help
./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.你好

向用户问好。

参数：

• name （string，必填）：要问候的用户的名称

例子：

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

2.get_room_details_by_name

按房间名称/ID获取有关房间的详细信息。

参数：

• room_name （string，必填）：房间的名称/ID

例子：

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

3.获取房间的详细坐标

通过坐标获取房间的详细信息。

参数：

• x （数字，必填）：X坐标
• y （数字，必填）：Y坐标

例子：

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

4.移动_房间_名字

按名称将玩家移动到指定的房间。只允许移动到连接的房间。

参数：

• target_room （string，必填）：目标房间的名称/ID

例子：

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

5.get_player_status

获取玩家的当前状态和信息。

参数： 无

例子：

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

6.显示_地图

显示整个地牢的ASCII地图，显示房间、走廊和玩家的当前位置。

参数： 无

例子：

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

游戏机制

移动规则

• 玩家只能移动到与其当前位置直接相连的房间
• 根据地牢的连接图验证移动
• 移动时，玩家坐标会自动更新

房型

1. 房间：可以包含NPC、宝藏、怪物或物品
2. 走廊：连接房间之间的通道
3. 入口：玩家的起始位置
4. 退出：完成地牢的目标位置

位置元素

• 前体细胞：带有名称和描述的非玩家角色
• 宝藏：具有黄金价值的贵重物品
• 怪物：具有难度级别和命中点的敌人
• 物品：治疗药水等消耗品

测试

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

cd tests
# Test room details
./room.tool.call.sh

# Test player movement
./move.tool.call.sh

# Test player status
./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"
}