Civ5 MCP

🚀 Civ 5 MCP

Civ 5 MCP 可藉助 MCP 將你的《文明 5》遊戲與智能體連接起來。此模組會創建一個進程間通信（IPC）通道，將你的即時遊戲與 MCP 服務器相連，讓智能體能夠與之交互。

查看一些示例。

該模組的設計理念是僅提供人類玩家在合理情況下能夠知曉的信息。例如，我們會避免洩露奇觀的位置或未接觸過的玩家的信息。其核心目標是打造一個超級遊戲顧問，助力你提升遊戲水平。

本項目由兩部分構成：遊戲模組（即橋樑）和 MCP 服務器。要使用此模組，你必須同時使用這兩部分。

⚠️ 重要提示

此模組僅在 Windows 系統的《文明 5：勇敢新世界》版本上進行過測試。

🚀 快速開始

操作步驟

1. 下載最新版本並將內容解壓到你的 MODS 目錄。通常該目錄為 %USERPROFILE%\Documents\My Games\Sid Meier's Civilization 5\MODS。
   • 目錄結構應如下所示：

MODS/
  Civ5MCP_Bridge (v VERSION)/
      Civ5MCP_Bridge.modinfo
      ... 一堆 .lua 文件 ...

2. 啟動遊戲。
3. 選擇“MODS”。
4. 點擊小按鈕啟用此模組。
5. 配置你的遊戲。
6. 配置你的智能體以運行 server/civ5_mcp_server.py。
7. 盡情享受遊戲！

🛠️ 開發

構建

模組信息和常量文件會在構建時生成。mod_config.json 描述了模組以及將以《文明 5》所需格式導出的文件。

# 所有目標都有對應的 docker 變體，例如 make docker-lint

# 進行代碼檢查
make lint

# 運行單元測試
make test

# 生成《文明 5》可讀取的目錄
make build

# 可選操作：自動部署到你的《文明 5》MODS 文件夾
./tools/deploy.ps1

版本控制

Lua rockspec 和《文明 5》的版本格式有所不同。《文明 5》要求版本號為無點號或破折號的字符串。因此，《文明 5》的版本號會去掉修訂號，並將主版本號和次版本號合併為 主版本號 * 10 + 次版本號。

🌉 橋樑模塊

遊戲狀態會在每回合開始時記錄，並寫入 SQLite 數據庫。每個新遊戲會作為一個新會話存儲。會話和回合數將作為狀態的 ID。回合歷史和初始遊戲配置會使用此會話 ID 進行存儲。

⚠️ 重要提示

data 字段是一個 JSON 數據塊，其格式不穩定！

橋樑模塊在 Lua 5.1.4 的沙盒環境中運行，可使用的 API 非常有限。遊戲僅暴露了此 API，我們也只能使用這些。

💻 運行服務器

cd server

# 測試服務器是否可以啟動
uv run civ5_mcp_server.py

如果沒有看到任何錯誤，你可以使用類似以下的配置將此服務器添加到 Claude 等工具中。如果 uv 啟動失敗，請嘗試直接使用 uv 的虛擬環境 Python 二進制文件。

{
  "mcpServers": {
    "civ5": {
      "command": "uv",
      "args": ["run", "path/to/civ5_mcp_server.py"],
    }
  }
}