内容
# 星际争霸MCP服务器
MCP（模型上下文协议）服务器，允许AI读取游戏状态并向 **星际争霸** （Paradox Interactive）发送命令。为 **星际争霸** 的Cetus V4.3.1版本设计。
## 架构
该系统有三个组件：
```
┌─────────────────┐ game.log ┌─────────────────┐ stdio ┌─────────────┐
│ 星际争霸模组 │ ──────────────────► │ MCP服务器 │ ◄────────────► │ AI（Claude） │
│ （PDXScript） │ │ （TypeScript） │ │ │
│ │ ◄────────────────── │ │ │ │
│ │ ai_commands.txt │ │ │ │
└─────────────────┘ └────────┬────────┘ └──────────────┘
│
│ 解析.sav
▼
┌─────────────────┐
│ 存档文件 │
│ （.sav / ZIP） │
└─────────────────┘
```
1. **星际争霸模组** (`mod/`) — PDXScript模组，钩入`on_monthly_pulse_country`，每游戏月将结构化游戏状态转储到`game.log`。
2. **存档文件解析器** (`src/parser/`) — 使用 [jomini](https://github.com/nickbabcock/jomini) npm包解析`.sav`文件（包含Clausewitz格式文本的ZIP存档）。
3. **MCP服务器** (`src/index.ts`) — stdio传输MCP服务器，为AI提供读取状态和队列命令的工具。
### 关键约束
Clausewitz引擎 **没有外部API** — 没有REST，没有WebSocket，没有IPC。模组只能 **写入** `game.log`（单向观察）。命令通过`ai_commands.txt`，玩家在游戏中通过`run ai_commands.txt`执行。
## MCP工具
| 工具 | 描述 |
|------|-------------|
| `get_game_state` | 从最新的存档或实时日志获取完整的游戏状态 |
| `get_resources` | 资源储备和每月收入（13种资源类型） |
| `get_planets` | 拥有人口、稳定度、建筑、区、犯罪、工作的星球 |
| `get_fleets` | 舰队组成、军事力量、位置 |
| `get_technologies` | 活跃的研究和已完成的科技列表 |
| `get_diplomacy` | 与所有已知帝国的 diplomatic 关系（意见、竞争、条约、战争） |
| `execute_command` | 队列一个单独的控制台命令 |
| `execute_effect` | 队列一个PDXScript效果命令 |
| `queue_commands` | 一次队列多个控制台命令 |
| `list_save_profiles` | 列出可用的存档游戏配置文件 |
| `analyze_situation` | 结合所有数据源的综合战略分析 |
## 模组数据导出
模组每月写入`game.log`，使用管道分隔的行：
| 前缀 | 数据 |
|--------|------|
| `AI_SUMMARY` | 日期、帝国名称、星球、人口、已用/可用海军、军事力量 |
| `AI_RESOURCES` | 每种资源储备和每月收入 |
| `AI_PLANET` | 每个星球：名称、等级、人口、大小、稳定度、设施、住房、工作、犯罪 |
| `AI_FLEET` | 每个舰队：名称、飞船、力量、 MIA 状态 |
| `AI_DIPLO` | 每个帝国：名称、意见、竞争/条约/战争状态 |
| `AI_TECH_OUTPUT` | 物理/社会/工程研究输出 |
| `AI_STATE_END` | 转储结束标记 |
## 设置
### 先决条件
- Node.js 18+
- 星际争霸（非铁人模式用于控制台命令；存档解析适用于铁人模式）
### 安装
```bash
# 克隆并安装依赖
git clone <仓库网址>
cd stellaris-mcp
npm install
# 构建
npm run build
```
### 安装星际争霸模组
```bash
bash scripts/install-mod.sh
```
或手动复制`mod/`内容到：
```
Documents/Paradox Interactive/Stellaris/mod/ai_player_mcp/
```
并创建`Documents/Paradox Interactive/Stellaris/mod/ai_player_mcp.mod`：
```
name="AI玩家MCP桥"
path="mod/ai_player_mcp"
tags={
"实用工具"
}
supported_version="4.3.*"
```
然后在模组启动器中激活 **"AI玩家MCP桥"** 。
### 配置MCP服务器
将以下内容添加到Claude Code或Claude Desktop MCP设置中：
```json
{
"mcpServers": {
"stellaris": {
"command": "node",
"args": ["<项目路径>/dist/index.js"],
"env": {
"STELLARIS_SAVE_PROFILE": "ia"
}
}
}
}
```
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `STELLARIS_DOCUMENTS_PATH` | `~/Documents/Paradox Interactive/Stellaris` | 星际争霸用户数据目录 |
| `STELLARIS_INSTALL_PATH` | `F:/SteamLibrary/steamapps/common/Stellaris` | 游戏安装目录 |
| `STELLARIS_SAVE_PROFILE` | _(空)_ | 存档游戏配置文件文件夹名称 |
## 用法
### 读取游戏状态
AI可以随时调用任何读取工具。数据源：
- **存档文件解析** — 来自最新`.sav`文件的完整游戏状态
- **日志监控** — 来自模组的`game.log`输出的实时更新（需要模组处于活动状态）
### 发送命令
1. AI通过`execute_command`、`execute_effect`或`queue_commands`队列命令
2. 命令写入`Documents/Paradox Interactive/Stellaris/ai_commands.txt`
3. 在游戏中，打开控制台（`~`）并输入：`run ai_commands.txt`
AI可能生成的命令示例：
```
# 直接控制台命令
cash 1000
research_technology tech_lasers_2
influence 100
# 效果命令（自动包装）
effect add_resource = { energy = 500 }
effect every_owned_planet = { limit = { free_jobs > 5 } add_building = building_factory_1 }
```
### 测试解析器
```bash
# 解析所有存档配置文件并打印结果
npm run test:parser
```
## 项目结构
```
stellaris-mcp/
├── mod/ # 星际争霸模组（PDXScript）
│ ├── descriptor.mod
│ ├── common/
│ │ ├── on_actions/ # 每月脉冲钩
│ │ └── scripted_effects/ # 状态转储效果
│ ├── events/ # ai_player事件链
│ └── localisation/english/
├── src/ # MCP服务器（TypeScript）
│ ├── index.ts # 服务器入口点 + 工具定义
│ ├── config.ts # 配置加载
│ ├── parser/
│ │ ├── types.ts # 游戏状态TypeScript接口
│ │ ├── save-parser.ts # .sav文件解析器（jomini）
│ │ ├── log-parser.ts # game.log解析器
│ │ └── test-parser.ts # 解析器测试脚本
│ ├── tools/
│ │ └── get-game-state.ts # MCP响应状态格式化
│ ├── watcher/
│ │ ├── save-watcher.ts # 自动保存目录监视器
│ │ └── log-watcher.ts # game.log尾部监视器
│ └── commands/
│ └── command-writer.ts # 控制台命令文件写入器
├── scripts/
│ └── install-mod.sh # 模组安装脚本
├── package.json
└── tsconfig.json
```
## 限制
- **没有实时命令注入** — Clausewitz引擎无法从外部程序接收命令。命令需要手动控制台执行。
- **本地化键** — 存档文件存储内部键（例如`%ADJECTIVE%`、`NEW_COLONY_NAME_1`）而不是显示名称。游戏在运行时解析这些。
- **每月日志频率** — 模组每游戏月转储状态一次。对于更频繁的更新，请使用存档文件解析和更短的自动保存间隔。
- **非铁人模式要求** — 控制台命令和`run`命令仅在非铁人模式游戏中有效。存档解析适用于两种模式。
## 未来计划
- **第二阶段：通过存档文件标志的命令注入** — 修改存档文件以设置全局标志，模组读取并执行为动作，实现完全自主循环。
- **第三阶段：热重载自动化** — 使用`-debug_mode`启动标志 + 控制台自动化注入和执行命令，无需手动交互。
