使用说明

文本冒险处理程序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）。每个回合的推荐工作流程是：

分析用户输入：了解玩家想要做什么。
计划（内部独白）：使用 narrator_thought 致：
- 检查操作是否符合规则。
- 确定必要的统计检查（DC）。
- 计划故事后果。
- 决定工具调用。
执行操作：使用 execute_batch （或单个工具）更新游戏状态（移动、库存、战斗等）。
叙述：根据工具结果向玩家描述结果。

MCP工具参考

核心工作流程

工具	目的
`initial_instructions()`	开始指南和冒险列表。
`get_rules(section_name?)`	检索特定的规则部分（指南、机制等）。
`narrator_thought(...)`	关键的：在行动之前记录内部想法、故事状态和计划。
`execute_batch(commands)`	关键的：一次性执行多个状态更改工具。
`start_adventure(...)`	开始新的游戏会话。
`continue_adventure(session_id)`	恢复现有会话。

游戏机制

工具	目的
`take_action(...)`	执行一般技能检查或叙述动作。
`combat_round(...)`	解决一轮战斗（玩家对敌人）。
`roll_check(...)`	进行特定的统计检查或原始d20滚动。
`modify_state(...)`	修改HP、统计数据、分数或位置。
`update_quest(...)`	开始、更新或完成任务。

世界管理（模块化）

工具	目的
`manage_character(...)`	创建、读取、更新、删除、列出NPC/角色。
`manage_location(...)`	创建、读取、更新、删除、列出位置。
`manage_item(...)`	创建、读取、更新、删除、列出世界中的项目。
`manage_faction(...)`	创建派系并管理声誉/关系。
`manage_economy(...)`	处理货币、购买、出售和物品转移。
`manage_time(...)`	提前时间、设置时间或获取当前游戏时间/天。
`manage_status_effect(...)`	应用、删除或列出临时状态效果（增益/去增益）。

感知与记忆

工具	目的
`record_event(...)`	在某个位置记录公共事件。自动更新证人的记忆。
`add_character_memory(...)`	将特定的记忆（谣言/秘密）植入NPC。
`interact_npc(...)`	简单关系更新（已弃用，支持 `manage_faction` 或 `record_event` 对于复杂的交互，但对于简单的更改仍然有用）。

状态与信息（综合）

工具	目的
`get_session_info(...)`	在一次通话中获取状态、历史、角色记忆和附近的实体。
`manage_inventory(...)`	添加、删除、更新、检查、列出或使用库存项目。
`manage_summary(...)`	创建、获取或删除会话摘要以实现长期连续性。

内容生成

工具	目的
`randomize_word(...)`	从预定义列表或AI生成中获取随机名称/地点/项目。
`generate_initial_content(...)`	在开始之前生成自定义打开场景的助手。

冒险示例

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许可证-有关详细信息，请参阅许可证文件