内容
# CS2MCP — 城市：天际线 II 的 MCP 服务器
**简体中文**
给予克劳德（或任何 MCP 客户端）对正在运行的城市：天际线 II 游戏的**完全控制**：读取城市数据、控制摄像头、截图、建造道路和建筑、绘制分区、管理财务和政策、控制模拟时间。
> 44 种 MCP 工具，涵盖五个维度 — 观察 / 建造 / 调整 / 管理 / 时间 — 所有工具均在游戏中验证。AI 可以使用它们选择地点、建造高架立交、分区住宅区，然后运行模拟并观察结果。它像玩家一样玩游戏。
## 架构
```
克劳德代码 / 克劳德桌面 (任何 MCP 客户端)
│ MCP (stdio)
▼
cs2-mcp (mcp-server/, Node.js 进程)
│ HTTP, 本地仅限 127.0.0.1:8642
▼
CS2MCP 桥接模组 (CS2MCP.Bridge/, 在游戏进程内)
│ 所有 ECS 读取/写入操作都在模拟主线程上运行
▼
城市：天际线 II
```
- **游戏内模组** (C#)：在游戏进程内运行一个最小的 HTTP 服务器，绑定到 127.0.0.1。请求由监听线程队列并在 `SystemUpdatePhase.UIUpdate` 注册的 ECS 系统的模拟主线程上执行（在暂停时有效）。建设通过自定义的 `ToolBaseSystem` 使用游戏的原生定义/验证/应用管道；拆除通过推土机管道进行 — 没有绕过游戏验证的实体突变。
- **MCP 服务器** (TypeScript)：将 MCP 工具调用转换为针对桥接模组的 HTTP 请求，通过 stdio 传输。
## 要求
- Windows + 城市：天际线 II (Steam)
- .NET SDK 8.0+ （用于构建模组）
- Node.js 18+ （用于运行 MCP 服务器）
## 构建和安装
```powershell
# 1. 构建游戏内模组（自动部署到游戏的本地 Mods 文件夹）
dotnet build CS2MCP.Bridge\CS2MCP.Bridge.csproj
# 2. 构建 MCP 服务器
cd mcp-server
npm install
npm run build
```
模组部署到 `%USERPROFILE%\AppData\LocalLow\Colossal Order\Cities Skylines II\Mods\CS2MCP\` 并在游戏启动时自动加载 — 无需 Paradox Mods 发布。要暂时禁用它，将文件夹重命名为 `.CS2MCP`。
### 游戏路径配置
构建模组时引用游戏文件夹中的程序集。解析顺序（第一个匹配项获胜）：
1. 命令行：`dotnet build -p:GamePath="X:\...\Cities Skylines II"`
2. **`CS2_PATH`** 环境变量
3. `CSII_INSTALLATIONPATH` 环境变量（由官方模组工具链设置）
4. 常见 Steam 库位置的自动探测（`C:\Program Files (x86)\Steam`，`Steam` / `SteamLibrary` 在常见驱动器字母上）
如果找不到游戏，构建将失败并显示清晰的错误。例如：
```powershell
setx CS2_PATH "D:\Steam\steamapps\common\Cities Skylines II"
```
### 运行时环境变量（支持 .env）
MCP 服务器通过 [dotenv](https://github.com/motdotla/dotenv) 加载 `mcp-server/.env`（参见 `.env.example`）：
| 变量 | 范围 | 默认值 | 描述 |
|---|---|---|---|
| `CS2_BRIDGE_URL` | MCP 服务器 | `http://127.0.0.1:8642` | 桥接模组的地址 |
| `CS2MCP_PORT` | 游戏进程 | `8642` | 桥接监听端口（同时更改两者） |
| `CS2_PATH` | 构建时 | 自动探测 | 游戏安装文件夹 |
## 与克劳德一起使用
**克劳德代码**：存储库根目录中的 [.mcp.json](.mcp.json) 注册了 `cs2` 服务器 — 只需在项目目录中打开克劳德代码（首次使用时需要信任）。从其他目录注册：
```powershell
claude mcp add cs2 -- node <repo-path>\mcp-server\dist\index.js
```
**克劳德桌面**（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"cs2": {
"command": "node",
"args": ["<repo-path>\\mcp-server\\dist\\index.js"]
}
}
}
```
启动游戏，加载存档，然后问克劳德：“我的城市财务状况如何？”，“在河边划分一个住宅区”，“建造一条连接工业区和高速公路的道路”。
## 工具参考（44 种工具）
**状态和视图**
| 工具 | 描述 |
|---|---|
| `cs2_ping` | 桥接活跃度，模组版本，游戏模式（即使加载中也响应） |
| `cs2_game_state` | 模式，城市名称，暂停/速度，游戏内日期和时间 |
| `cs2_city_overview` | 人口，幸福度，健康度，资金，经验值，日期 |
| `cs2_screenshot` | 当前视图为 PNG（帧末捕获，默认 1280px 宽） |
| `cs2_get_camera` / `cs2_set_camera` | 摄像头读取/写入（旋转/角度/缩放）— 结合截图，AI 的自有视角 |
**城市数据**
| 工具 | 描述 |
|---|---|
| `cs2_demand` | RCI 需求 + 需求因素（内部 0-255 比例；仅在模拟时刷新） |
| `cs2_budget` | 预算明细：14 个收入 / 15 个支出来源 |
| `cs2_city_services` | 电力，供水和污水，垃圾状态 |
| `cs2_labor` | 就业率，失业率，按教育程度和年龄结构划分的工作岗位 |
| `cs2_statistics` | 60 多项统计数据的时间序列（每游戏日 32 个样本） |
| `cs2_terrain` | 全地图高程图 + 水深网格 |
| `cs2_gridmap` | 原生单元格图层：土地价值，地面/空气/噪声污染，地下水 |
| `cs2_zoning` | 分区摘要（按分区类型划分的占用/空置） |
| `cs2_notifications` | 所有游戏内警告图标（无电力/水，废弃...）及其目标实体 |
| `cs2_inspect` | 单实体详情（居民/员工/状态标志） |
**建设**
| 工具 | 描述 |
|---|---|
| `cs2_find_prefabs` | 按名称搜索建筑/道路/网络/树 prefab |
| `cs2_place_building` | 放置建筑/树（采样高度，旋转，原生验证） |
| `cs2_build_road` | 任意网络段：直 / 曲通过 `cx,cz` / 高架通过 `e1,e2`（桥梁，坡道） |
| `cs2_upgrade_road` | 道路升级：草/树/宽 sidewalk/声障/停车/照明/中间隔离带 |
| `cs2_zone_area` / `cs2_list_zones` | 绘制分区（`None` 清除）和列出分区类型 |
| `cs2_demolish` | 拆除建筑/路段/树/区（推土机管道） |
| `cs2_list_buildings` / `cs2_list_roads` / `cs2_list_objects` | 实体列表（ID，坐标） |
**财务和政策**
| 工具 | 描述 |
|---|---|
| `cs2_get_taxes` / `cs2_set_tax` | 四个分区类别的税率（限制在游戏限制内） |
| `cs2_policies` / `cs2_set_policy` | 城市政策（带有本地化名称） |
| `cs2_service_budgets` / `cs2_set_service_budget` | 每项服务预算滑块 50-150% |
| `cs2_get_fees` / `cs2_set_fee` | 服务费用（电力/水/医疗保健/教育...） |
| `cs2_get_loan` / `cs2_set_loan` | 借款 / 还款贷款 |
| `cs2_list_districts` / `cs2_create_district` | 列出区 / 绘制区多边形 |
| `cs2_district_policies` / `cs2_set_district_policy` | 区政策 |
| `cs2_tiles_info` | 已拥有的地图瓷砖 / 维护信息 |
**时间和元**
| 工具 | 描述 |
|---|---|
| `cs2_set_simulation` | 暂停 / 设置速度（0-8） |
| `cs2_run_simulation` | 计时运行：模拟 N 游戏小时，然后自动暂停 |
| `cs2_save_game` | 触发保存（在大型 AI 操作前推荐） |
## 故障排除
- **`cs2_ping` 无法访问**：模组未加载。检查 `%USERPROFILE%\AppData\LocalLow\Colossal Order\Cities Skylines II\Logs\CS2MCP.log`（应包含 `bridge listening on ...`）；如果文件丢失，检查同一文件夹中的 `Player.log`。
- **409 无城市加载**：仍在主菜单 — 首先加载存档。
- **锁定状态看起来不正确**：加载后短暂解除暂停（锁定相关的端点在模拟点击之前返回 `stalenessWarning`）。
- **端口冲突**：为游戏进程设置 `CS2MCP_PORT` 并更新 `.env` 中的 `CS2_BRIDGE_URL` 以匹配。
## 已知限制 / 路线图
- 地图瓷砖购买，交通线路规划和地形改造尚未实现（计划在 v0.9 中实现）
- 坡道只能在路段端点（节点）连接；不支持中间路段平滑合并
- 截图捕捉游戏的当前渲染：打开道路工具面板时，游戏以白色轮廓模式渲染道路
## 免责声明和致谢
- 这是一个非官方的社区模组，不隶属于 Colossal Order 或 Paradox Interactive。
- `CS2MCP.Bridge/CreateDefinitions.cs` 源自 [LineTool-CS2](https://github.com/algernon-A/LineTool-CS2)（Apache-2.0，© algernon），包含从反编译的游戏代码中派生的部分，须遵守 Paradox Interactive 用户协议。
- 感谢 CS2 模组社区 — LineTool、InfoLoom、Traffic、unity-mcp 等公开代码使本项目成为可能。
## 许可证
[Apache-2.0](LICENSE)
MCP 市场