Skip to content
Back to search

terraforming-mars-mcp

Streamable HTTP MCP server for the official Terraforming Mars server (Docker Compose, Node 26)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/watanabehato--terraforming-mars-mcp/badge.svg)](/listings/watanabehato--terraforming-mars-mcp)

HTML

<a href="/listings/watanabehato--terraforming-mars-mcp"><img src="/api/listings/watanabehato--terraforming-mars-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 278 lines
  1. # Terraforming Mars MCP
  2. 用官方 [terraforming-mars/terraforming-mars](https://github.com/terraforming-mars/terraforming-mars) 游戏服务器 + 一个独立的 Streamable HTTP MCP 服务,让 Bot 只通过 MCP 就能开局、读状态、提交合法操作,并让人类用浏览器观战。
  3. 游戏规则和官方服务端保持原样,没有 fork 或修改核心规则。上游锁定在 commit `fdc1cc5ffdff4ef12b00350734dd68e50a61aa2e`,使用其仓库自带的 Dockerfile 构建。开局调用官方 `POST /api/creategame`(`ApiCreateGame`,请求体为上游 `NewGameConfig`),之后只使用 `/api/player`、`/api/waitingfor` 和 `/player/input`。
  4. ```
  5. Bot --Streamable HTTP MCP--> mcp:8765 --HTTP--> tm:8888 (官方服务)
  6. |
  7. SQLite volume tm-db
  8. ```
  9. ## 端口
  10. | 服务 | 端口 |
  11. | --- | ---: |
  12. | 官方 Terraforming Mars | **8888** |
  13. | MCP Streamable HTTP | **8765** |
  14. 没有使用 8080。上游 Dockerfile 里的 `EXPOSE 8080` 只是镜像元数据;容器内通过 `PORT=8888` 启动,端口映射也是 `8888:8888`。
  15. ## 快速开始
  16. ```bash
  17. cp .env.example .env
  18. docker compose up -d --build
  19. ```
  20. 首次构建需要下载 Node 26 基础镜像、执行上游 `npm ci` 和构建,耗时较长。启动后:
  21. ```bash
  22. curl http://localhost:8765/healthz
  23. curl http://localhost:8888/api/games
  24. ```
  25. - 人类入口:<http://localhost:8888/>
  26. - MCP 入口:`http://localhost:8765/mcp`
  27. - 如果设置了 `MCP_AUTH_TOKEN`,MCP 请求需要带上 `Authorization: Bearer <token>`。
  28. ### Docker Hub 镜像
  29. 本机 Docker 拉取 Docker Hub 慢时,可以使用镜像 `ssw29qyeeou949jadc.xuanyuan.run`:
  30. ```bash
  31. ./scripts/prepare-node-image.sh
  32. ```
  33. 它会把 `ssw29qyeeou949jadc.xuanyuan.run/library/node:26-alpine3.23` 拉下来并打上 `node:26-alpine3.23` 标签,这样上游未修改的 Dockerfile 会直接复用本地镜像。MCP 自己的 Dockerfile 已通过 `NODE_IMAGE` 默认使用该镜像;镜像不可用时在 `.env` 中改成:
  34. ```dotenv
  35. NODE_IMAGE=node:26-alpine3.23
  36. ```
  37. ## 让 Bot 连上 MCP
  38. MCP 使用 Streamable HTTP,不是 stdio。任意支持 Streamable HTTP 的 MCP 客户端都可以直接连。完整的连接握手、18 个工具的参数与返回、官方 `InputResponse` 格式和推荐主循环见 **[docs/MCP.md](docs/MCP.md)**。
  39. ```text
  40. http://localhost:8765/mcp
  41. ```
  42. 例如 Claude Code:
  43. ```bash
  44. claude mcp add --transport http tm http://localhost:8765/mcp
  45. ```
  46. 带鉴权时:
  47. ```bash
  48. claude mcp add --transport http tm http://localhost:8765/mcp \
  49. --header "Authorization: Bearer $MCP_AUTH_TOKEN"
  50. ```
  51. ## 一局 Bot 的完整流程
  52. ### 1. 创建对局
  53. ```json
  54. {
  55. "name": "create_game",
  56. "arguments": {
  57. "players": [
  58. {"name": "Bot-A", "color": "red"},
  59. {"name": "Bot-B", "color": "green"}
  60. ],
  61. "expansions": {"corpera": true, "prelude": true},
  62. "board": "tharsis"
  63. }
  64. }
  65. ```
  66. 返回:
  67. ```json
  68. {
  69. "game_id": "g...",
  70. "spectator_id": "s...",
  71. "spectator_url": "http://localhost:8888/spectator?id=s...",
  72. "players": [
  73. {
  74. "name": "Bot-A",
  75. "color": "red",
  76. "player_id": "p...",
  77. "player_url": "http://localhost:8888/player?id=p..."
  78. }
  79. ]
  80. }
  81. ```
  82. `player_id` 是 Bot 的身份凭证。每个 Bot 只需要自己的 `player_id`,不要把自己的 `player_id` 发给其他 Bot。
  83. 支持的官方扩展(`expansions` 里传布尔值):
  84. `corpera`、`promo`、`venus`、`colonies`、`prelude`、`prelude2`、`turmoil`、`community`、`ares`、`moon`、`pathfinders`、`ceo`、`starwars`、`underworld`、`deltaProject`。
  85. 其他可选参数:`board`、`draft`、`initial_draft`、`prelude_draft`、`solo_tr`、`two_corps`、`fast_mode`、`starting_corporations`、`starting_preludes`、`starting_ceos`、`turmoil_agenda`。官方支持 1–6 个玩家。
  86. ### 2. 绑定 Bot 身份
  87. ```json
  88. {
  89. "name": "configure_session",
  90. "arguments": {
  91. "player_id": "p...",
  92. "game_id": "g..."
  93. }
  94. }
  95. ```
  96. `tm_server_url` 和 `tm_public_url` 也可以在单个 MCP 会话里覆盖;默认来自环境变量。
  97. ### 3. 等待轮到自己
  98. ```json
  99. {"name": "wait_for_turn", "arguments": {"timeout_ms": 60000, "poll_ms": 500}}
  100. ```
  101. 返回里的 `waiting_for` 是官方输入模型经过裁剪后的版本,只保留做决策需要的字段(选项、卡牌名与费用、地块、付款方式、数量范围等),不会把整份 UI model 倒出来。`request_id` 由 MCP 在提交时自动注入,不需要 Bot 自己处理。
  102. ### 4. 提交行动
  103. 按 `waiting_for.type` 选择工具:
  104. | `waiting_for.type` | 工具 |
  105. | --- | --- |
  106. | `option` / `or` | `choose_option` |
  107. | `amount` | `submit_amount` |
  108. | `card` | `select_cards` |
  109. | `projectCard` | `play_project_card` |
  110. | `space` | `select_space` |
  111. | `player` | `select_player` |
  112. | `payment` | `submit_payment` |
  113. | `initialCards` | `select_initial_cards` |
  114. | `and`、`colony`、`party`、`delegate`、`productionToLose`、`aresGlobalParameters`、`globalEvent`、`resource`、`resources`、`claimedUndergroundToken`、`policy`、`deltaProject` | `submit_input` |
  115. | 上游新增、尚未建模的类型 | `submit_raw_entity` |
  116. 例子:
  117. ```json
  118. {"name": "choose_option", "arguments": {"index": 0}}
  119. ```
  120. ```json
  121. {"name": "select_cards", "arguments": {"cards": ["Mine", "Power Plant"]}}
  122. ```
  123. ```json
  124. {"name": "play_project_card",
  125. "arguments": {"card": "Mine", "payment": {"megacredits": 4}}}
  126. ```
  127. ```json
  128. {"name": "submit_input",
  129. "arguments": {"response": {"type": "colony", "colonyName": "Europa"}}}
  130. ```
  131. 遇到嵌套的 `or` 选项(子输入不是普通 option)时,把子响应放进 `response`:
  132. ```json
  133. {"name": "choose_option",
  134. "arguments": {"index": 2, "response": {"type": "amount", "amount": 3}}}
  135. ```
  136. `submit_raw_entity` 用于规则升级后出现的新输入类型;它只要求对象带 `type`,其余原样交给官方服务端校验。
  137. ### 5. 读状态
  138. - `get_game_state`:回合、时代、阶段、全局参数、自己的资源/产能、对手概要、当前 `waiting_for`。
  139. - `get_mars_board_state`:地块、空格奖励、里程碑、奖项、殖民地、扩展状态。
  140. - `get_my_hand_cards`:手牌与计算后的费用。
  141. - `get_my_played_cards`:自己的已打出卡牌/公司。
  142. - `get_opponents_played_cards`:对手公开的面板。
  143. ## 错误处理
  144. 官方服务端拒绝操作时,MCP 以 `isError: true` 返回错误,并保留官方响应原文,例如:
  145. ```text
  146. Terraforming Mars rejected the request (HTTP 400). Raw server response: {"id":"INVALID_REQUEST_ID","message":"This page is out of date. Click OK to refresh it."}
  147. ```
  148. Bot 可以据此重新读状态、重试或调整行动。
  149. ## 观战
  150. `create_game` 会直接返回:
  151. - 玩家页:`http://localhost:8888/player?id=<player_id>`
  152. - 观战页:`http://localhost:8888/spectator?id=<spectator_id>`
  153. 浏览器打开即可看到官方前端和实时局面。
  154. ## 最小 e2e
  155. ```bash
  156. docker compose exec mcp npm run e2e
  157. ```
  158. 它会:
  159. 1. 通过 MCP 创建一局单人基础游戏;
  160. 2. `configure_session` 绑定玩家;
  161. 3. `wait_for_turn` 等到初始选择;
  162. 4. 通过 MCP 选公司、跳过买牌;
  163. 5. 通过 MCP `choose_option` 过牌;
  164. 6. 等待并确认进入下一时代;
  165. 7. 检查官方的 `/player` 与 `/spectator` 页面返回 200。
  166. 成功时输出 `ok: true`。e2e 只调用 MCP 工具,不直接操作官方 HTTP 输入接口。
  167. 也可以从宿主机运行:
  168. ```bash
  169. E2E_MCP_URL=http://localhost:8765/mcp TM_SERVER_URL=http://localhost:8888 npm run e2e
  170. ```
  171. ## 数据持久化
  172. 默认使用官方 SQLite 后端,数据目录挂载在 Docker volume `tm-db`(容器内 `/usr/src/app/db`)。
  173. ```bash
  174. docker compose down -v
  175. ```
  176. 会清空所有对局数据。需要 Postgres 时,按上游官方文档设置 `POSTGRES_HOST` 等环境变量,并相应调整 compose。
  177. ## 配置
  178. | 环境变量 | 默认值 | 说明 |
  179. | --- | --- | --- |
  180. | `TM_PORT` | `8888` | 官方服务映射到宿主机的端口 |
  181. | `TM_PUBLIC_URL` | `http://localhost:8888` | 返回给人类浏览器的地址 |
  182. | `MCP_PORT` | `8765` | MCP 监听端口 |
  183. | `MCP_AUTH_TOKEN` | 空 | 设置后 MCP 要求 Bearer Token |
  184. | `MIN_RESPONSE_INTERVAL_MS` | `250` | 官方服务端的最小响应间隔 + MCP 出站请求节流 |
  185. | `TM_REQUEST_TIMEOUT_MS` | `30000` | MCP 调用官方服务的超时 |
  186. | `NODE_IMAGE` | 镜像地址 | MCP 构建用的 Node 26 镜像 |
  187. | `TM_BUILD_CONTEXT` | 上游 git 地址(锁定 commit) | 可改成 `./upstream` 使用本地 checkout |
  188. ## 构建细节
  189. - 官方服务:直接构建上游仓库的 Dockerfile,没有改游戏规则;上游要求 Node 26。
  190. - MCP 服务:TypeScript + `@modelcontextprotocol/sdk`,使用 `StreamableHTTPServerTransport`,每个 MCP 会话独立绑定 `TM_SERVER_URL` 和 `player_id`。
  191. - 所有对官方的读写在 MCP 内做全局节流,避免多个 Bot 同时轮询打爆服务器。
  192. - `MIN_RESPONSE_INTERVAL_MS` 同时传给官方服务(上游原生的快速响应保护)和 MCP 的节流器。
  193. 如果要在本地使用上游源码而不是 git 构建:
  194. ```bash
  195. git clone https://gh-proxy.com/https://github.com/terraforming-mars/terraforming-mars.git upstream
  196. # 在 .env 中设置:
  197. # TM_BUILD_CONTEXT=./upstream
  198. ```
  199. ## 许可证
  200. 本项目与上游一致,使用 **GPL-3.0**,见 [LICENSE](LICENSE)。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.