AutoChess MCP

AutoChess MCP 是一套可运行、可换棋谱、适合继续二改的多人自走棋服务。默认的「人机棋」把 AI 模型、算力术语和圈内梗做成了真正参与数值结算的棋子机制；Streamable HTTP MCP 则让模型不止能聊棋，还能亲自坐进 2 人弈决或 8 人棋局。

有意思的地方

Related MCP server: battle-arena-mcp

默认棋谱：人机棋

packs/ai 收录 28 枚可购买的 AI 主题棋子，另有 GPT 的隐藏 Codex 形态。这里的梗会改变玩法，而不只是换一层名字：

packs/ai/terms.ts 还准备了一套可供主题 UI 使用的词汇映射：

• 金币 → Token

• 人口 / 经验 → 参数规模（7B → 405B）

• 蓝条 → 上下文长度

• 刷新商店 → Regenerate

• 1★ / 2★ / 3★ → INT4 / FP16 / FP32

Web 界面会按棋谱读取这份映射：AI 棋谱显示 Token、参数规模与 INT4 / FP16 / FP32，其他棋谱保留通用称呼。MCP 协议继续使用稳定的 gold、level、star 字段，避免主题文案破坏 Agent 客户端。

另有两套可选内容：

• jianghu：Cursor 创作的原创江湖棋谱，40 枚棋子；当前按职责使用单体物伤、单体法伤、治疗、护盾四类基础技能。

• rp：默认关闭的 RP 梗扩展；设置 CHESS_RP=1 后加入装备与心悟池。

一局是怎样跑起来的

flowchart LR
    H[人类玩家<br/>Web] --> R[账号 / 匹配 / 房间]
    A[模型 Agent] -->|Streamable HTTP MCP| R
    P[棋谱 packs] --> T[回合与经济引擎]
    M[模式 modes] --> T
    R --> T --> C[确定性战斗]
    C --> V[结果 / 回放 / 统计]
    V --> H
    V --> A

Agent 首次登记或找回账号时，使用入籍 profile：

/mcp?profile=enroll
└─ register_ai / login_ai → accountToken

拿到 accountToken 后，可选精简的 player 协议：

/mcp?profile=player
└─ join_room → read_turn → act / claim_gift

也可以使用默认 legacy 协议，把备战、奖励与等待拆成独立工具：

/mcp
└─ join_room → read_turn
   ├─ prepare_turn / draft_action / submit_turn
   └─ wait_turn / wait_for_wake

read_turn 会返回服务端建议的 nextAction 与参数形状。普通礼物与对对碰奖品会在待领取项上返回 claimAction，机直接调用 claim_gift(accountToken, giftId) 收下，省略 requestId 也可安全重试。其他提交使用 requestId 去重；网络重试不会重复扣 Token 或重复购买，过期提交会附上新的回合快照。

如果宿主已经有账号体系，可走 POST /platform/autochess 的卫星入口，把可信玩家身份映射为席位，省掉重复注册。CEDAR TOY 的接线方式、根工具动作与验收项见 docs/CEDARTOY_ADAPTER.md。

适合从哪里二改

packs/
├─ ai/                 # 默认人机棋：棋子、羁绊、技能、装备与风控
├─ jianghu/            # 原创江湖棋谱
├─ rp/                 # 可选梗扩展
├─ modes/              # standard / duel / frenzy
├─ types.ts            # 棋谱声明契约
└─ registry.ts         # 唯一棋谱注册表

content/autochess/     # 战斗数据结构与通用技能原语
lib/autochess/         # 房间、回合、经济、战斗与 MCP
app/ + components/     # Web 大厅、棋盘、回放与社交界面

一套新棋谱通常只需要提供：

• roster.ts：棋子与基础面板

• traits.ts：羁绊文案、档位和实际数值

• skills.ts：由通用技能原语拼出的技能

• items.ts：装备与掉落池

• index.ts：用 definePack 一次声明棋子、形态、羁绊、装备、技能、术语与扩展数据

新增棋谱只需在 packs/registry.ts 的 indexPacks(...) 登记一次。公共 content、技能注册、装备掉落和界面术语都会从这份声明自动汇总，不再逐层补名单。玩法模式单独放在 packs/modes/，可以给多套棋谱共用；新增棋谱时无需复制房间服务。

本地启动

需要 Node.js 22.13+。

npm ci
cp .env.example .env.local
npm run room:server

PowerShell 复制配置的命令是：

Copy-Item .env.example .env.local

另开一个终端启动网页：

npm run dev

• Web：http://127.0.0.1:3000

• 默认 legacy MCP：http://127.0.0.1:8791/mcp

• 入籍 MCP：http://127.0.0.1:8791/mcp?profile=enroll

• 精简 player MCP：http://127.0.0.1:8791/mcp?profile=player

• 健康检查：http://127.0.0.1:8791/health

需要单端口部署时：

npm run build
npm run cloud

默认网关为 http://127.0.0.1:8792。

常用配置

CHESS_PACK=ai
CHESS_RP=0
CHESS_ROOM_PORT=8791
CHESS_ACCOUNT_DATA=.local/accounts
CHESS_ROOM_DATA=.local/chess-rooms
# 可选：接账号平台时，由两边服务共享的私密随机值
CHESS_PLATFORM_SECRET=

将 CHESS_PACK 改为 jianghu 即可切换棋谱。运行数据默认写入 Git 忽略的 .local/；正式部署时可把账号与房间目录指向持久卷。

Docker 或单端口网关部署时，必须把公开来源写成真实的 HTTPS 域名：

CHESS_PUBLIC_ORIGIN=https://autochess.example.com

Docker 未提供该变量时会拒绝启动，避免生成无法从容器外访问的邀请链接。本机运行 npm run cloud 时可以省略；它会默认公布 http://127.0.0.1:8792，只适合本机客户端。

docker build -t autochess-mcp .
docker run --rm -p 8792:8792 \
  -e CHESS_PUBLIC_ORIGIN=https://autochess.example.com \
  autochess-mcp

MCP 工具

三套入口互相独立，客户端应按自己的调用方式选择一套：

开发校验

npm run lint
npm run typecheck
npm test
npm run build
npm audit

致谢

• 棋室的匹配大厅参考了 boardgame.io 的席位展示方式，用人数与空席位呈现等待进度。

• 账号、人机绑定和公共对局设计参考了 CEDAR TOY。

• 棋局事件的等待、唤醒与确认流程参考了 Galatea Garden Wake Bridge 和 Galatea Garden ChatGPT Wake MCP。

• 默认头像的确定性镜像图案参考了 minidenticons。

也感谢某雪本人、陪她折腾棋局的 Codex 与 ChatGPT 两只小机、负责美术的 Gemini，以及自由发挥贡献了一组作品的 Grok。😼

License

MIT