AI导哈

交互式小说游戏服务

一个支持AI助手通过标准化接口玩文本冒险游戏的模型上下文协议服务器，支持Glulx和Z-machine游戏格式，具有自动游戏状态持久化和可选日志模式功能。

  • by davidar
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 davidar/mcp-server-if

使用说明

mcp服务器如果

用于玩交互式小说游戏的MCP（模型上下文协议）服务器。使像克劳德这样的人工智能助手能够通过标准化的界面玩文字冒险游戏。

特性

  • 玩Glulx（.ulx，.gblorb）和Z-machine（.z3-.z8，.zblorb）游戏
  • 自动游戏状态持久化（会话之间的保存/恢复）
  • 直接从IF档案下载游戏
  • 可选日志模式，用于反射式游戏
  • 适用于Claude Desktop、Claude Code和其他MCP客户端
  • 捆绑式解释器（glulxe代表Glulx，bocfel代表Z-machine）

安装

# Using uvx (recommended)
uvx mcp-server-if

# Or install with pip
pip install mcp-server-if

该软件包包括预编译的解释器。无需额外设置。

配置

环境变量

变量 描述 默认值
IF_GAMES_DIR 存储游戏的目录 ~/.mcp-server-if/games
IF_GLULXE_PATH 覆盖glulxe二进制文件的路径 捆绑二进制文件
IF_BOCFEL_PATH 覆盖bocfel二进制文件的路径 捆绑二进制文件
IF_REQUIRE_JOURNAL 需要日志反思 false

命令行参数

mcp-server-if --help

Options:
  --games-dir PATH       Directory to store games
  --glulxe-path PATH     Path to glulxe binary (overrides bundled)
  --require-journal      Require journal reflections between turns

使用Claude Desktop

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS或 %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

{
  "mcpServers": {
    "interactive-fiction": {
      "command": "uvx",
      "args": ["mcp-server-if"]
    }
  }
}

使用Claude代码

claude mcp add interactive-fiction -- uvx mcp-server-if

可用工具

play_if

播放一轮互动小说。

play_if(game="zork", command="go north")
play_if(game="zork", command="", journal="...reflection...")  # with journaling

list_games

列出可用游戏及其保存状态。

download_game

从IF档案或任何URL下载游戏。

download_game(name="advent", url="advent.ulx")
download_game(name="bronze", url="https://example.com/Bronze.gblorb")

reset_game

重置游戏以重新开始（清除保存状态，保留日志）。

read_journal

阅读游戏日志。

read_journal(game="zork", recent=10)  # last 10 entries

search_journal

按关键字搜索日记条目。

search_journal(game="zork", query="treasure")

支持的游戏格式

Glulx （现代，使用glulxe解释器）：

  • .ulx -原始Glulx游戏文件
  • .gblorb -Blorb容器与Glulx游戏

Z型机 （经典的Infocom格式，使用bocfel解释器）：

  • .z3, .z4, .z5, .z7, .z8 -Z代码游戏文件
  • .zblorb -带有Z机器游戏的Blorb容器

在IF档案中查找游戏： Glulx游戏, Z码游戏.

日志模式

启用 --require-journal 或 IF_REQUIRE_JOURNAL=true在此模式下：

  1. 播放第一个命令后，后续回合需要日记条目
  2. 日记条目必须至少100字
  3. 条目保存到 {game}/journal.jsonl
  4. 使用 read_journal 和 search_journal 复习你的游戏

这鼓励深思熟虑、反思性的游戏，而不是匆匆忙忙地完成。

运作原理

  1. 游戏存储在 ~/.mcp-server-if/games/{name}/

  2. 每个游戏目录包含：

    • 游戏文件(.ulx, .gblorb, .z5等等）
    • state/ -自动保存数据（在会话之间保持不变）
    • metadata.json -会话元数据
    • journal.jsonl -播放日志（如果启用）

  3. 服务器根据文件格式选择合适的解释器：

    • Glulx游戏→ 胶
    • Z机器游戏→ 波菲尔

  4. 两个解释器都使用RemGlk进行基于JSON的I/O

  5. 游戏状态在每次回合后自动保存

发展

需要 紫外线，C编译器（gcc或clang），C++编译器（g++或clang++），make和git。

git clone --recursive https://github.com/davidar/mcp-server-if.git
cd mcp-server-if
uv sync --group dev
uv run pytest -v

uv sync 自动从源代码编译捆绑的解释器（glulxe和bocfel）。如果新克隆后缺少二进制文件，请运行 uv sync --reinstall-package mcp-server-if 强制重新编译。

故障排除

“未找到glulxe二进制文件”

这不应该发生在pip/uvx安装中。如果是这样：

  • 尝试重新安装： pip install --force-reinstall mcp-server-if 或 uv sync --reinstall-package mcp-server-if
  • 或设置 IF_GLULXE_PATH 手动安装的胶水

“找不到游戏文件”

使用 list_games 查看可用游戏，或 download_game 以获得新的。

保存/恢复命令不起作用

游戏中的保存/恢复会触发不支持的文件对话框。请改用自动保存系统-您的游戏状态会在会话之间自动保持。

许可证

MIT许可证-请参阅 许可证 了解详情。

学分

  • 胶 -Andrew Plotkin的Glulx VM解释器
  • 波菲尔 -Z机器翻译Chris Spiegel
  • RemGlk -JSON I/O的远程Glk库
  • 主控程序 -基于Anthropic的模型上下文协议

相关 MCP