Tavern Battle MCP · 通用战斗系统

0.2.0 已提供 16 个工具。 一条指令行动/开战、固定开局预览和隔离试战见 游戏操作指南。

让 ChatGPT / Dots 和其他 MCP 客户端，以玩家视角操作手机或电脑上的 SillyTavern / TauriTavern 战阵插件。

本仓库是独立的 MCP 服务端，可放在 Linux VPS 上长期运行。手机 TT 的游戏本体继续运行在手机；个人电脑可以关闭。手机须保持战阵页面运行和连接，切到后台或锁屏后能否继续取决于手机系统。

手机 TT 的战阵面板 ── HTTPS + 配对密钥 ── VPS 上的 MCP 服务
                                              ↑
                       Dot / ChatGPT ── MCP 或安全隧道

1. 更新手机 TT 插件

战斗插件仓库：sillytavern-general-battle-system，使用 test 分支。更新后打开 战阵 → 设置 → MCP 玩家操作。

这里提供的服务端仓库不要填入 TT 的“安装扩展”地址。TT 安装的是战斗插件；这个仓库部署在 VPS。

另附 可安装扩展测试包 和 客户端源文件及集成说明。只启用一份战斗扩展。

Related MCP server: Background AI Chat MCP Server

2. 在 Linux VPS 部署

需要 Docker Engine 和 Compose v2，以及解析到 VPS 的域名。放行域名的 TCP 80、443。配置自动 HTTPS 的方式见 Caddy 文档。

git clone https://github.com/smokycamera/tavern-battle-mcp.git
cd tavern-battle-mcp
cp .env.example .env
chmod 600 .env
openssl rand -hex 32
nano .env

修改 .env 的三项：

然后启动：

docker compose up -d --build
docker compose ps
curl --fail https://battle.your-domain.com/health

/health 返回服务名称即表明 HTTP 服务正常。Caddy 自动配置 HTTPS；Node 服务的 8766 端口只映射到 VPS 的本机回环地址。

如果 VPS 已经用 Nginx/Caddy/宝塔占用了 80/443，可只启动服务：

docker compose up -d --build mcp

用已有的 HTTPS 站点把请求反向代理到 http://127.0.0.1:8766，保留请求路径、Authorization、Origin 和请求体。无需把 8766 暴露到公网。

3. 手机 TT 连接 VPS

进入 战阵 → 设置 → MCP 玩家操作：

• 桥接地址填 https://battle.your-domain.com，不带 /mcp。

• 配对密钥填 VPS .env 中的 TB_MCP_TOKEN。

• 点击“连接 MCP”，保持面板运行。

手机不能填写 127.0.0.1 来连接 VPS。出现 403 时，将手机面板显示的实际页面来源加入 TB_MCP_ORIGINS，再运行 docker compose up -d mcp 使新环境配置生效。

4. Dot / ChatGPT 使用

支持 Bearer 的 MCP 客户端

• Streamable HTTP 地址：https://battle.your-domain.com/mcp

• 请求头：Authorization: Bearer <TB_MCP_TOKEN>

• 优先调用 battle_state；多个面板时先用 battle_sessions 选择。原界面流程仍可用 battle_observe。配对后能列出手机面板，就代表连接成立。

本地 stdio 客户端也可以连接同一台 VPS，而不创建另一份服务：

npm ci
export TB_MCP_URL=https://battle.your-domain.com/mcp
export TB_MCP_TOKEN='你的配对密钥'
node stdio-proxy.mjs

把这条进程命令配置到支持本地 stdio 的客户端即可。不要用 server.mjs --stdio 连接一个已运行的 VPS 实例：它会创建第二个独立服务。stdio-proxy.mjs 才会转发到手机已连接的服务。

ChatGPT 个人插件与 Dots

Dots 可以使用账户已安装、启用且受支持的插件。官方说明。此仓库使用 Bearer 鉴权，不内置 OAuth。 如果你的插件创建界面不能填写 Bearer 请求头，使用以下安全隧道路径；保持 HTTPS 服务的鉴权开启。

1. 按 Secure MCP Tunnel 官方文档，在 Platform 创建隧道并关联目标 ChatGPT 工作区，在 VPS 安装 tunnel-client。

2. 在 VPS 配置隧道所需的运行密钥。配置它的 MCP command，假设仓库位于 /opt/tavern-battle-mcp：

   docker compose -f /opt/tavern-battle-mcp/compose.yaml exec -T mcp node stdio-proxy.mjs

   这条命令进入已经运行的容器，用相同密钥连接相同服务，不另占端口。隧道通过标准输入/输出调用它。

3. 按隧道文档运行 tunnel-client doctor 和 tunnel-client run，保持运行。

4. 在 ChatGPT 开发者模式的 Plugins → ＋ → Connection → Tunnel 中选择隧道，建立个人插件，检查能发现 16 个工具。然后让 Dot 使用这个已启用的插件。官方连接步骤。

建议给 Dot 的第一条指令：

使用通用战斗系统插件，先列出已连接的战阵面板并读取当前玩家视图。暂时只检查连接和介绍可用操作。

本仓库测试了 MCP 协议和工具转发；具体账户的 Dots/插件/隧道权限，以及 VPS 域名和 TLS，需要在实际部署时验证。

工具

游戏状态、连续行动、军令、自动/暂停、完整准备/固定预览、一键开战、战后恢复与隔离试战可使用新游戏工具。原界面工具继续用于所有原有页面。默认不连接；不开放引擎后门，不读取隐藏敌人、原始快照、随机数或密钥。按键仍受回合、行动点、技能消耗、冷却、视野和存档规则约束。

原界面操作须使用最近 battle_observe 返回的 viewId / controlId。聊天、存档修订或界面改变后旧指令失效；超时写操作不会自动重放。dispatched 只代表已发出操作，是否成功以新界面、feedback、saveStatus 为准。

战前配置示例

先在手机任务设置中选好环境，再调用 battle_prepare：

{
  "sessionId": "battle_sessions 返回的值",
  "viewId": "battle_observe 返回的值",
  "commanders": {
    "ally": { "ability": "skilled", "style": "flanking", "preferences": { "risk": 3, "reserve": 1 } },
    "enemy": { "ability": "regular", "style": "cautious" }
  },
  "battlefield": {
    "scene": "field",
    "layout": "lanes",
    "landmarks": [{ "kind": "hill", "anchor": "center_left", "label": "西侧高地" }]
  }
}

准备后仍需点击“开始交战”。只作用于下一场，复用本体地图生成和部署校验；不会额外调用副 API。详细格子地图用于小战，会战保留阵位规则。可用 clear:true 清除准备。

更新、日志与测试

git pull --ff-only
docker compose up -d --build
docker compose logs --tail=100 mcp

服务重启后，手机需要重新配对。服务不持久保存玩家档案；存档仍在 TT 中。

不用 Docker 时可安装 Node.js 20+，运行 npm ci && npm start。Windows 有 start.ps1；本地开发默认监听 127.0.0.1:8766。

npm ci
npm test

GitHub Actions 在 Node 20/22/24 测试协议、鉴权、取消、stdio 和代理，并构建 Linux 容器、校验 HTTPS 配置。客户端的游戏集成及浏览器测试由战斗插件仓库执行。

许可证：GPL-3.0-only，见 LICENSE。服务使用官方 @modelcontextprotocol/sdk 和 Zod，依赖遵循各自许可证。