Terraforming Mars MCP

改造火星mcp

MCP服务器，用于控制现有地球化火星游戏中的玩家。

该项目将代理工具调用连接到Terraforming Mars开源服务器 (tm-oss-server)API，因此兼容MCP的客户端可以检查游戏状态和 提交法律诉讼。

状态：测试版/正在进行中。

快速开始

先决条件

• Python 3.11+
• uv
• Node.js 16-22和 npm （如果您在本地运行TM OSS）

1.安装依赖项

git submodule update --init --recursive
uv sync

# I use the server supply card data. Run a server on a differnet directory to prevent any
# kind of agent cheating.
cd submodules/tm-oss-server/
npm install
npm run build

添加到MCP客户端

克劳德代码

claude mcp add terraforming-mars \
  --env TM_SERVER_URL=http://localhost:8080 \
  -- uv run --directory "$PWD" python -m terraforming_mars_mcp.server

验证：

claude mcp list
claude mcp get terraforming-mars

克劳德桌面版

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "terraforming-mars": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/terraforming-mars-mcp",
        "python",
        "-m",
        "terraforming_mars_mcp.server"
      ],
      "env": {
        "TM_SERVER_URL": "http://localhost:8080"
      }
    }
  }
}

法典

codex mcp add terraforming-mars \
  --env TM_SERVER_URL=http://localhost:8080 \
  -- uv run --directory "$PWD" python -m terraforming_mars_mcp.server

验证：

codex mcp list
codex mcp get terraforming-mars

可选：

添加以下内容 ~/.codex/config.toml 要增加超时时间：

[mcp_servers.terraforming-mars]
tool_timeout_sec = 600

开始游戏

启动你选择的代理，让它玩一个地球化火星的游戏， 并为其提供游戏ID的URL，如 http://localhost:8080/player?id=pd90e2c66f638 代理人会弄清楚剩下的一切！

运作原理

MCP client (Claude/Codex/etc.)
        |
        | stdio MCP
        v
terraforming-mars-mcp (this repo)
        |
        | HTTP
        v
Terraforming Mars Open Source Server
  - GET  /api/player?id=

  - GET  /api/waitingfor?id=
&gameAge=&undoCount=
  - POST /player/input?id=

工具表面

状态和检查工具：

• configure_session
• get_game_state
• wait_for_turn
• get_mars_board_state
• get_my_hand_cards
• get_my_played_cards
• get_opponents_played_cards

行动工具：

• choose_or_option, confirm_option, submit_and_options
• select_amount, select_cards, select_space, select_player, select_party, select_colony
• pay_for_action, pay_for_project_card
• select_delegate_target, select_policy, select_global_event
• select_resource, select_resources, select_production_to_lose
• select_initial_cards, shift_ares_global_parameters, select_claimed_underground_tokens
• submit_raw_entity （无支撑/新颖输入形状的逃生口）

发展

手动运行MCP服务器

TM_SERVER_URL=http://localhost:8080 \
uv run python -m terraforming_mars_mcp.server

运行测试：

uv run pytest -q

运行静态检查：

uv run zuban check
uv run ruff check .

注意：这是一个活动的WIP存储库；静态检查输出可以在提交之间变化。

存储库布局

• terraforming_mars_mcp/：MCP服务器实现和工具处理程序
• tests/：用于状态整形和工具行为的Python测试套件
• submodules/tm-oss-server/：上游Terraforming Mars服务器源
• agent-prompts/：提示工件和策略说明
• scripts/tm_learning.py：用于游戏学习数据集维护的辅助脚本

故障排除

• 错误 player_id is not set. Call configure_session first.

- 集 TM_PLAYER_ID 开始前，或致电 configure_session(player_id=...).

• 错误 Cannot reach server at ...

- 验证TM OSS服务器是否正在运行 TM_SERVER_URL 匹配它。

• 响应中缺少/空卡元数据

- 确保TM OSS子模块已初始化并构建 src/genfiles/cards.json 存在。

参考文献

• 上游TM OSS项目：https://github.com/terraforming-mars/terraforming-mars

许可证

该项目已获得GPL-3.0许可，上游TM OSS项目也是如此。