vic3-mcp

读取本机 Victoria 3 存档（.v3）的 MCP 服务器。Agent 可以列出存档、解析国家数据，并给出建设 / 法案 / 外交建议。

默认测试存档：~/Documents/Paradox Interactive/Victoria 3/save games/Qing_MCP.v3（1836 大清）。

存档从哪来

路径	用途
`~/Documents/Paradox Interactive/Victoria 3/save games/`	`.v3` 存档
`~/Library/Application Support/Steam/steamapps/common/Victoria 3/game/`	本地化与定义（国名、法案、建筑）

游戏默认写入 二进制 zip。服务器用随附的 rakaly 把存档融化成文本后再抽数据。融化结果缓存在 ~/Library/Caches/vic3-mcp/。

uv sync
chmod +x scripts/run-mcp.sh vendor/rakaly

vendor/rakaly 是 macOS ARM64 的 rakaly 0.8.19。别的平台请从 https://github.com/rakaly/cli/releases 下载，放到 vendor/rakaly 或设置 RAKALY。

项目里已经有 .grok/config.toml。也可以：

grok mcp add vic3 -- /Users/i/myCode/vicroria/.venv/bin/python -m vic3_mcp

工作目录要能 import 到包：用上面的 venv，或 scripts/run-mcp.sh。

手动冒烟：

uv run python scripts/smoke.py Qing_MCP

cp .env.example .env
# 编辑 .env：填 VIC3_LLM_BASE_URL、VIC3_LLM_API_KEY，模型默认 kimi-k3
uv sync
./scripts/run-web.sh

工具	作用
`list_saves`	列出本机存档
`load_save`	载入（默认 `Qing_MCP`）
`overview`	日期、GDP、金库、列强
`analyze_situation`	风险 + 建议
`country` / `economy` / `politics` / `pops`	国家切片
`diplomacy` / `military` / `technology` / `journal`	外交/军事/科技/日志
`buildings` / `states` / `rankings`	建筑、省份、排行
`compare_countries`	多国对比
`search_save`	在融化文本里搜原始字段
`localize`	查游戏 loc

country 参数：player、CHI、GBR 或数字 id。

复制 .env.example 为 .env 后填写。.env 已在 .gitignore 中，不要提交。

变量	说明
`VIC3_LLM_BASE_URL`	OpenAI 兼容接口，需含 `/v1`
`VIC3_LLM_API_KEY`	接口密钥
`VIC3_LLM_MODEL`	模型名，默认 `kimi-k3`
`VIC3_SAVE_DIR` / `VIC3_USER_DIR` / `VIC3_GAME_DIR`	覆盖存档/游戏路径
`VIC3_MCP_CACHE`	融化缓存目录
`RAKALY`	rakaly 可执行文件路径