Text Adventure Handler MCP

文本冒险处理程序MCP

MCP（模型上下文协议）服务器，使AI代理能够运行交互式文本冒险，具有持久的游戏状态、基于骰子的动作解析、冒险特定的角色统计和动态世界管理。

特性

• 探险管理：使用可自定义的提示存储多个文本冒险模板
• 角色创建：玩家可以命名他们的角色和滚动统计数据（4d6最低）或使用自定义/默认值
• 游戏会话：跟踪多个并行游戏中的玩家进度
• 动态统计：定义每次冒险的自定义统计数据（例如，D&D类有STR/DEX/INT，科幻类有PILOT/TECH/PERSUADE）
• 骰子系统：基于d20的动作解析，带有属性修饰符和难度等级
• 持续进步：SQLite数据库存储所有游戏状态、历史和世界变化
• 高级世界管理:

- 动态实体：动态创建和管理角色、地点和物品 - 经济系统：跟踪货币、买卖物品和管理交易 - 时间跟踪：管理游戏时间、昼夜周期和基于时间的事件 - 派系制度：跟踪不同组的声誉（从敌对到恢复） - 状态影响：应用带有持续时间跟踪的临时缓冲或去缓冲 - 记忆与感知：NPC目睹事件并形成影响其行为的记忆

• AI旁白工具:

- 内心独白: narrator_thought 允许人工智能私下计划故事节拍 - 批量执行: execute_batch 允许在一个回合内执行多个游戏动作以提高效率 - 单词随机化：用于动态名称和描述的预定义或人工智能生成的单词列表

• MCP简明说明：针对AI上下文使用进行了优化
• Web UI仪表板：用于管理冒险、会话和游戏状态的可视化界面（可选）

安装

快速开始使用uvx

使用此MCP服务器的最简单方法是通过 uvx，它自动获取并运行包：

# Run the MCP server
uvx text-adventure-handler-mcp

# With a custom database path
uvx text-adventure-handler-mcp --db-path /path/to/adventure.db

用pip/uv安装

# Using uv
uv pip install text-adventure-handler-mcp

# Using pip
pip install text-adventure-handler-mcp

Web UI界面

该项目包括一个可选的基于网络的仪表板，为管理您的文本冒险提供了一个可视化界面。web UI与MCP服务器一起运行，允许您：

• 查看和管理活动游戏会话
• 监控玩家状态、库存和统计数据
• 浏览冒险历史和总结
• 管理角色、位置和项目
• 追踪游戏时间和派系关系

注： Web UI需要Docker，并且与PyPI包分开分发。

运行Web UI

选项1：预构建Docker镜像（推荐）

运行Web UI的最简单方法：

# Pull and run the pre-built image
docker run -p 3000:80 \
  -v ~/.text-adventure-handler/adventure_handler.db:/data/adventure.db:ro \
  -e DB_PATH=/data/adventure.db \
  ghcr.io/narrowstacks/text-adventure-handler-mcp:latest

或者使用Docker Compose（需要克隆仓库）：

git clone https://github.com/narrowstacks/text-adventure-handler-mcp.git
cd text-adventure-handler-mcp/web
docker compose up

选项2：从源代码构建

git clone https://github.com/narrowstacks/text-adventure-handler-mcp.git
cd text-adventure-handler-mcp/web
docker compose -f docker-compose.dev.yml up --build

仪表板将在 http://localhost:3000.

Web UI配置

web UI连接到默认数据库路径： ~/.text-adventure-handler/adventure_handler.db

如果您的数据库位于其他位置，请更新 HOST_DB_PATH 环境变量：

export HOST_DB_PATH="/path/to/your/adventure_handler.db"
cd web && docker compose up

开发模式

对于没有Docker的本地开发：

# Backend (port 3001)
cd web/backend
bun install
bun run dev

# Frontend (port 5173)
cd web/frontend
bun install
bun run dev

Claude桌面配置

要将此MCP服务器与Claude Desktop一起使用，请在设置文件中进行配置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

1.基本配置（推荐）

用途 uvx 自动获取并运行最新版本。

{
  "mcpServers": {
    "text-adventure": {
      "command": "uvx",
      "args": ["text-adventure-handler-mcp"]
    }
  }
}

2.从GitHub运行（最新版本）

如果您想直接从存储库运行绝对最新版本：

{
  "mcpServers": {
    "text-adventure": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/narrowstacks/text-adventure-handler-mcp",
        "text-adventure-handler-mcp"
      ]
    }
  }
}

3.自定义数据库位置

如果你想将游戏数据存储在特定位置（而不是默认位置） ~/.text-adventure-handler/)，添加 ADVENTURE_DB_PATH 环境变量：

{
  "mcpServers": {
    "text-adventure": {
      "command": "uvx",
      "args": ["text-adventure-handler-mcp"],
      "env": {
        "ADVENTURE_DB_PATH": "/Users/username/my_games/adventure.db"
      }
    }
  }
}

4.本地开发配置

如果您已克隆存储库并希望使用本地版本：

{
  "mcpServers": {
    "text-adventure-local": {
      "command": "uv",
      "args": ["run", "python", "-m", "adventure_handler"],
      "cwd": "/absolute/path/to/text-adventure-handler-mcp"
    }
  }
}

5.重新启动克劳德桌面

完全退出并重新启动Claude Desktop以使更改生效。

快速开始

1.初始说明

服务器提供了一个帮助工具来理解工作流程：

Tool: initial_instructions()
Returns: Overview of available adventures and how to start.

2.列出可用的冒险

Tool: list_adventures()
Returns: List of adventure metadata (id, title, description)

3.开始游戏会话

Tool: start_adventure(
  adventure_id="fantasy_dungeon",
  character_name="Aragorn",
  roll_stats=True
)

讲述人工作流程

此MCP旨在帮助AI充当称职的游戏大师（GM）。每个回合的推荐工作流程是：

1. 分析用户输入：了解玩家想要做什么。
2. 计划（内部独白）：使用 narrator_thought 致：

- 检查操作是否符合规则。 - 确定必要的统计检查（DC）。 - 计划故事后果。 - 决定工具调用。

1. 执行操作：使用 execute_batch （或单个工具）更新游戏状态（移动、库存、战斗等）。
2. 叙述：根据工具结果向玩家描述结果。

MCP工具参考

核心工作流程

游戏机制

世界管理（模块化）

感知与记忆

状态与信息（综合）

内容生成

冒险示例

1.水晶洞穴(fantasy_dungeon)

经典奇幻地牢爬行。

• 统计力量、灵巧、智慧、魅力。
• 特性怪物、陷阱、魔法和战利品。

2.车站异常(scifi_station)

深空恐怖和神秘。

• 统计：驾驶、技术、战斗、说服。
• 特性：黑客攻击、外星人威胁、系统维修。

3.玉龙案(noir_detective)

大胆的城市谋杀之谜。

• 统计：调查、恐吓、偷偷摸摸、街头购物。
• 特性：审问、线索、道德模糊。

4.检查混沌(checkout_chaos)

大型超市中的后启示录生存喜剧。

• 统计：拾荒者，即兴创作，外交，Cart_Control。
• 特性：从垃圾、过道派系、荒谬的公司公告中制造武器。

5.钟表阴谋(clockwork_conspiracy)

蒸汽朋克政治阴谋。

• 统计：工程学、帕纳什、影步、决斗。
• 特性：小玩意、上流社会晚会、屋顶追逐、秘密阴谋。

6.诅咒海岸的阴影(cursed_shores)

航海恐怖和海盗行为。

• 统计剑术、航海、狡猾、粗砂。
• 特性：船舶管理，幽灵船员，被诅咒的宝藏，海战。

7.无效索赔(void_claim)

在一艘废弃的船上进行科幻保险调查。

• 统计：调查、技术运营、公司协议、生存。
• 特性生物恐怖、公司官僚主义、法医分析。

创建自定义冒险

在中创建JSON文件 src/adventure_handler/adventures/:

{
  "id": "my_adventure",
  "title": "Adventure Title",
  "description": "Short description",
  "prompt": "System prompt for AI...",
  "stats": [ ... ],
  "word_lists": [ ... ],
  "initial_location": "Starting Location",
  "initial_story": "Opening narrative..."
}

有关结构，请参阅现有的JSON文件 stats, word_lists，以及其他配置选项，如 currency_config 或 time_config.

统一工具设计

MCP工具遵循统一的设计模式，以优化上下文使用并简化API：

信息收集- get_session_info()

在一次通话中检索多种类型的游戏信息：

info = get_session_info(
    session_id,
    include_state=True,              # Current location, stats, HP, inventory
    include_history=True,             # Recent action history
    include_character_memories="Merchant",  # NPC memories
    include_nearby_characters=True,   # Characters at current location
    include_available_items=True,     # Items at current location
    history_limit=10,
    memory_limit=10
)

库存管理- manage_inventory()

通过单一工具进行所有库存操作：

# Add item
manage_inventory(session_id, action="add", item_name="Sword", quantity=1)

# Remove item
manage_inventory(session_id, action="remove", item_name="Potion")

# Check if item exists
manage_inventory(session_id, action="check", item_name="Key")

# List all inventory
manage_inventory(session_id, action="list")

# Use/consume item
manage_inventory(session_id, action="use", item_name="Healing Potion")

# Update item properties
manage_inventory(session_id, action="update", item_name="Sword",
                 properties={"enchanted": True})

会议总结- manage_summary()

创建和检索故事摘要以实现长期连续性：

# Create summary when ending a play session
manage_summary(session_id, action="create",
               summary="Player defeated the dragon...",
               key_events=["Found magic sword", "Met wizard"],
               character_changes=["Gained confidence", "Lost innocence"])

# Get all summaries to recap the story
manage_summary(session_id, action="get")

# Get only the latest summary
manage_summary(session_id, action="get_latest")

# Delete a specific summary
manage_summary(session_id, action="delete", summary_id="abc123")

州修改- modify_state()

通过基于操作的API更改所有玩家状态：

# Heal/damage HP
modify_state(session_id, action="hp", value=-10, reason="Fell down stairs")

# Modify stats (temporary or permanent changes)
modify_state(session_id, action="stat", stat_name="Dexterity", value=-1)

# Award/deduct points
modify_state(session_id, action="score", value=100)

# Move to new location
modify_state(session_id, action="location", value="Hospital")

许可证

MIT许可证-有关详细信息，请参阅许可证文件