BLACK SOULS MCP

简体中文 · English

一个 BLACK SOULS 的 MCP。最直白的说法：让 Claude Code / Codex 这类 agent 直接接入这款游戏。纯娱乐。

原理很简单：读游戏内部对象拿状态，再把动作送进游戏自带的按键输入循环。不截图、不模拟鼠标、也不需要图片模型，所以非图像模型也能用。寻路、对话、菜单、战斗都在真机上校准过，不是概念 demo。

能干嘛？

接入后，MCP 客户端能拿到：

• 场景、地图、坐标、朝向、通行信息

• 附近事件、消息、选项菜单

• 队伍等级、生命、魔力、异常状态、金钱

• 战斗阶段、双方单位、当前可用指令

也能操控角色：移动、确认、取消、翻页、冲刺，或者一次提交一整套连续动作，比如"往前走三步，再打开菜单看装备"。

输入只经过游戏自身的移动 / 事件 / 菜单 / 战斗处理逻辑，接口不会直接改生命、物品、变量或剧情开关。命令带着进程 ID、启动代次、帧号和命令编号，旧状态和重复命令会被拒绝；快照损坏会自动跳过；游戏在后台被 RPG Maker 暂停时，桥接能恢复键盘循环，不抢前台窗口。

Related MCP server: GachaMCP

跟截图 OCR和鼠标模拟比，差在哪？

更准、更快、更不容易翻车，而且不需要多模态

MCP 工具

共 36 个工具，按用途分组：

工作原理

MCP 客户端
    │ stdio
    ▼
Node.js / TypeScript 服务
    │ 原子文件 + 启动令牌
    ▼
BridgeRuntime
    │ RGSS3 Input 与游戏对象
    ▼
使用者准备的 BLACK SOULS 独立副本

桥接脚本每秒约更新 10 次状态；地图仅在位置或地图变化时生成新快照。命令由游戏主线程逐帧处理，不依赖窗口焦点，也不依赖视觉识别。查询类命令（变量、开关、背包、全图等）走同一条通道即时应答，不占用帧步进。

项目状态

开始之前

需要准备：

1. Windows 10/11

2. Node.js 18 或更新版本

3. 自己的 BLACK SOULS 游戏副本

4. Python 3.11+（仅用于桥接脚本写入工具）

5. 已从自己的副本准备好 Data/Scripts.rvdata2；本项目不会自动下载或解包游戏资源

快速开始

1. 获取源码并检查

git clone https://github.com/yk4464/black-souls-mcp.git
Set-Location .\black-souls-mcp
npm.cmd ci
npm.cmd run check

2. 准备独立运行目录

默认目录结构：

runtime/
├─ game/
│  ├─ Game.exe
│  ├─ Game.ini
│  ├─ Game.rgss3a~
│  └─ Data/Scripts.rvdata2
└─ backup/

runtime/ 已被 Git 忽略。准备步骤概述：把自己的游戏副本复制到 runtime/game/，确保 Data/Scripts.rvdata2 已解出（可用 scripts/extract_rgss3a_file.py），然后用桥接写入工具把 rgss/BlackSoulsBridge.rb 注入脚本档：

python .\scripts\patch_rvdata2_binary.py .\runtime\game\Data\Scripts.rvdata2 .\rgss\BlackSoulsBridge.rb --backup .\runtime\backup\Scripts.rvdata2.bak

patch_rvdata2_binary.py 只用 Python 标准库，保持原字节布局，优先使用；备选的 patch_rvdata2.py 需要先 python -m pip install -r requirements-tools.txt。

3. 安装到 Codex

Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1

使用外部目录：

.\install.ps1 `
  -RuntimeRoot 'D:\BlackSoulsRuntime' `
  -GameDir 'D:\BlackSoulsRuntime\game'

安装脚本会先备份当前用户的 Codex config.toml，再写入 black_souls MCP 注册。完成后重启 Codex。

4. 验证

重启 Codex 后先调用：

请调用 black_souls_status，检查游戏文件和桥接状态。

随后可以依次调用：

black_souls_launch
black_souls_get_state
black_souls_get_map

连续动作参数示例：

{
  "steps": [
    { "action": "move_up" },
    { "wait_frames": 12 },
    { "action": "confirm" }
  ]
}

游戏版本指纹

获取自己的 Game.exe SHA-256：

(Get-FileHash -Algorithm SHA256 -LiteralPath '.\runtime\game\Game.exe').Hash

然后在当前终端指定：

$env:BLACK_SOULS_GAME_EXE_SHA256 = '<YOUR_SHA256>'

设为空字符串会跳过指纹比较，但仍会检查必需文件是否存在。只有在确认游戏文件来源后才应这样做。

环境变量

测试

npm.cmd run check              # 构建、MCP 握手、工具发现与合成测试
npm.cmd run test:integration   # 需要已准备的运行目录
npm.cmd run test:live          # 启动游戏并执行真实键盘输入
.\check.ps1 -IncludeRuntime    # 检查源码、游戏副本和 Codex 注册
node evals\runner.mjs menu_navigation   # 运行一个评测场景（需要真实游戏）

真实测试会改变当前游戏会话中的位置或菜单，但不会主动保存。运行前仍建议保留自己的存档副本。

限制与故障提示

• 游戏资源准备与解包方式取决于发行版本，因此未做成自动下载流程

• RPG Maker 在后台可能暂停键盘循环；服务使用已核对进程和路径的 Windows 消息恢复循环，不模拟鼠标，也不把窗口切到前台

• 命令超时后若提示"游戏可能已经接收"，应先读取最新状态，再决定是否重试，避免重复动作

• 本项目仅面向本机可信目录，不应把 BridgeRuntime 放到其他用户可写的位置

卸载与回滚

.\uninstall.ps1
.\rollback.ps1

两者只处理 Codex 注册及其配置备份，不删除游戏或存档。指定某个备份进行回滚：

.\rollback.ps1 -ConfigBackup 'D:\BlackSoulsRuntime\backup\config.toml.before-black-souls-....bak'

安全与隐私

• 服务只使用本地 stdio，不会监听网络端口

• 命令动作使用固定白名单，并限制队列、步骤和总帧数

• 仓库忽略游戏、存档、运行快照、日志、依赖缓存和构建产物

• 提交问题前请移除个人路径、存档内容和游戏文件

安全问题请通过 GitHub Security Advisory 私下报告；其他问题使用 Issues。

参与贡献

请先阅读 CONTRIBUTING.md。package.json 中保留 private: true，用于防止误发布到 npm；这不影响 GitHub 上的 MIT 开源源码。

许可证与声明

本仓库源码采用 MIT License。

BLACK SOULS、RPG Maker、相关名称和游戏资产归各自权利人所有；本项目是非官方社区工具，与游戏作者、发行商及引擎厂商无隶属关系。