Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
.github
.github
 
 
aoe4_mcp
aoe4_mcp
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
NOTICE
NOTICE
 
 
README.en.md
README.en.md
 
 
README.md
README.md
 
 
agents.md
agents.md
 
 
config.example.toml
config.example.toml
 
 
pyproject.toml
pyproject.toml
 
 

Repository files navigation

aoe4-mcp

中文 | English

面向 Codex 的《帝国时代 4》Mod 开发 MCP。目标是让 Codex 通过本地索引快速查找官方 SCAR API、官方基础资料、UI、词条和项目代码，并返回精确补丁建议，减少上下文消耗。

本项目默认兼顾中文和英语工作流：工具说明、任务指引、locdb 写入和项目扫描都会识别中英文内容。英文 CSV 使用 Text 列；简体中文、繁体中文和多数其他语言 CSV 使用 SourceText,TranslatedText 列。

发布边界

  • 公开仓库只包含源码、schema、测试 fixture、文档和示例配置。
  • 不提交完整 SQLite DB、缓存、session、本地配置或任何私有资源。
  • 完整 DB 使用脱敏版本分发，且不得包含酒馆项目代码或酒馆 locdb 内容。
  • 酒馆项目只能作为人工总结经验的来源，不能进入索引 DB。

License 和署名

本项目使用 Apache-2.0。派生仓库、再分发包，以及包含 aoe4-mcp 源码、生成 scaffold、模板或可复用补丁输出的项目，需要保留 LICENSE 和 NOTICE，并标明：

Built with aoe4-mcp by heart&move
https://github.com/heartmove/aoe4-mcp

单纯使用 MCP 查询资料或辅助开发、不包含本项目源码或生成 scaffold 的模组，通常不属于 aoe4-mcp 的派生作品；但仍建议在 README 或鸣谢中保留上述署名。

赞助

如果 aoe4-mcp 对你的 AoE4 模组开发有帮助，可以通过 Ko-fi 一次性赞助：

https://ko-fi.com/heartmove

赞助用于支持 MCP 维护、中英文文档、AoE4 模组工作流研究、脱敏 DB 构建工具和 Codex 集成改进。私有 DB 作为安装便利产物分发，不作为单独商品售卖。

安装

开发或源码安装：

git clone <repo-url>
cd aoe4-mcp
python -m pip install -e .[dev]

Codex MCP 配置示例：

{
  "mcpServers": {
    "aoe4": {
      "command": "python",
      "args": ["-m", "aoe4_mcp.server"],
      "cwd": "<path-to-aoe4-mcp>"
    }
  }
}

配置

配置文件不是必需项。启动时按以下优先级解析：

  1. 环境变量
  2. 本地 aoe4-mcp.toml
  3. 自动发现常见路径
  4. 缺失降级

复制 config.example.toml 为 aoe4-mcp.toml 后可以手动填写路径。未配置路径时 MCP 仍会启动，相关工具会返回 missing_source 或 missing_db。

项目扫描时会识别：

  • *.scar: 代码函数、调用、网络事件、delegate、loc key、蓝图和卡牌引用。
  • *.lua: 官方/项目 SCAR 树中的 Lua 脚本，例如 terrainlayout 生成地图代码。
  • *.scar 内联 XAML: 识别字符串中的 Name、Command、Binding、DataTemplate 和资源 key。
  • *.rdo: 游戏模式入口和配置，例如 m_scarWinConditionFile、m_scarMissionFile、m_tuningModGUID、选项 key、默认值和 loc entry id。
  • *.xaml: 项目 UI 名称、命令、binding、模板和资源 key。
  • *.locdb: locdb 元数据中的语言集合和存储位置。
  • locdb/*.csv: 项目词条，自动区分英文 CSV 和中文 CSV 列结构。

XAML 绑定 context/DataContext 属性时，属性名需要放在 [] 内，例如 {Binding [RoundLabel]}，不要写成 {Binding RoundLabel}。

公开使用配置只需要 DB、session 和可选项目根目录。DB 构建/训练流程和官方资料源配置是本地维护流程，不通过公开 MCP 使用入口暴露。

使用脱敏 DB

如果已经拿到脱敏后的完整 DB，不需要初始化索引。只要把 DB 文件路径提供给 MCP，它会直接读取该 DB。

当前脱敏 DB 下载地址：

https://1drv.ms/u/c/f538831fdb67aef6/IQCQzMypoPrtSaO76Xo_lMWEAUMsQ3_0ngPD6mq5wW-ErzM?e=2p3Oap

下载后建议保存为：

<path-to-aoe4-mcp>/data/index.sanitized.sqlite3

注意：db_path 填本地 .sqlite3 文件路径，不填 OneDrive URL。

配置文件方式：

[paths]
db_path = "<path-to-aoe4-mcp>/data/index.sanitized.sqlite3"
session_dir = "<path-to-aoe4-mcp>/data/sessions"

环境变量方式：

$env:AOE4_MCP_DB_PATH = "<path-to-aoe4-mcp>/data/index.sanitized.sqlite3"
python -m aoe4_mcp.server

可用 doctor 检查：

  • db.ready = true：DB 已存在，查询工具会直接使用它，不需要任何初始化。
  • db.index_required = true：DB 不存在，需要检查路径，或改成已有脱敏 DB 地址。
  • db.sanitized = true：当前 DB 带有脱敏元数据，适合作为私有分发 DB 使用。

主要工具

  • doctor: 查看使用配置和 DB 状态。
  • api_context: 一次返回 API 文档、可信度和官方使用片段；查 API 用法时优先用它，减少 MCP 往返。
  • find_api, find_usage, inspect_symbol: 分别查 API、调用和符号状态。
  • find_base_data: 查单位、科技、建筑、能力、升级等基础资料。
  • find_ui: 查 UI 模板、资源、名称和 binding。
  • find_generated_map, explain_generated_maps: 查生成地图 terrainlayout 代码，并返回官方教程链接、关键概念和实现顺序。
  • trace_ui_binding: 追踪项目/官方 XAML 的 Name、Command、Binding 与相关 SCAR UI 调用。
  • plan_ui_interaction: 按中文或英文需求规划 UI 交互，判断是否需要 locdb 和网络同步。
  • lookup_official_loc, search_locdb, translate_official: 查官方/项目词条，并用官方词条给翻译候选。
  • explain_locdb_usage: 解释模组 locdb 词条如何存储，并追踪 RDO/SCAR/UI 中的使用位置。
  • scan_project, find_project_symbol, find_identifier_refs: 扫描并查询当前 Mod 项目。
  • inspect_project_layout: 只读检查项目 .rdo 入口配置和 locdb 语言集合。
  • explain_rdo_config: 解释 .rdo 里的 DataObject/DataProperty，输出入口 SCAR、配置 key、默认值、loc entry id 和字段说明。
  • explain_rdo_options: 解释 WinCondition Options 的 section、Boolean/Enumeration/Integer 选项、枚举项、loc 显示字段和 SCAR 读取路径。
  • plan_locdb_languages, plan_project_term_bundle: 规划 locdb 语言增减、缺失 CSV、多语言词条包。
  • find_module, trace_network_event, trace_delegate: 追踪模块、网络事件和 delegate。
  • draft_solution: 根据需求给出官方优先的实现思路和候选引用。
  • prepare_scar_edit, prepare_scar_patch: 为 Codex 生成精确替换建议、import/helper/call-site/network 注册补丁和 apply_patch 预览。
  • prepare_ui_patch: 为 UI 属性更新、命令入口、DataContext 和 XAML 锚点替换生成补丁建议，默认不写文件。
  • check_code: 检查未知调用、低可信 API 和缺失 locdb 引用。
  • apply_edit_script, upsert_locdb_bundle: 显式 write=true 时才写文件。

使用和训练分离

公开 MCP 入口 python -m aoe4_mcp.server 只暴露使用工具：查询、项目分析、任务规划和补丁建议。DB 构建、脱敏、审计属于本地训练/维护流程，不在公开 MCP 工具列表中暴露。

使用者拿到脱敏 DB 后只配置 db_path 即可工作；训练/维护者在本地使用内部配置生成原始 DB，再产出脱敏 DB 作为分发物。

UI 和交互工作流

推荐顺序：

  1. scan_project：索引当前 Mod 的 .scar、.rdo、.xaml 和 locdb。
  2. trace_ui_binding：用按钮名、binding、command 或模板名定位 UI 入口。
  3. plan_ui_interaction：让工具判断这是属性更新、命令、DataContext，还是混合交互；同时标记是否需要 locdb 和网络同步。
  4. plan_project_term_bundle：如果是玩家可见文本，先规划英文和中文词条。
  5. prepare_ui_patch：生成 SCAR helper、import、网络事件注册和可选 XAML 精确替换建议。
  6. check_code：检查未知 API、低置信 API 和缺失 loc key。

UI 文本默认按中英双语考虑。涉及玩法状态、资源、单位、胜负或多人共享状态时，优先通过 Network_RegisterEvent 和 Network_CallEvent 做同步；纯展示型 UI 更新可以保持本地。

如果已有 Lua 原生字符串必须传给需要 LocString 的 UI 属性，可以使用：

local locStr = LOC(str)
locStr.LocString = str

prepare_ui_patch 在传入 text_value 或 value_is_lua_string=true 时会按这个模式生成建议；玩家可见文本仍优先走 locdb。

生成地图工作流

官方教程入口：

推荐顺序：

  1. explain_generated_maps：拿到官方教程链接、terrainLayoutResult、玩家起点、资源分布、地形类型等结构化提示。
  2. find_generated_map：只在 terrainlayout 路径下查官方/项目地图脚本，减少无关 SCAR 结果。
  3. api_context / find_base_data：补齐脚本里调用的 API 和单位、资源、地形相关基础资料。
  4. prepare_scar_patch：生成项目地图脚本的精确补丁建议，默认不写文件。
  5. check_code：检查未知调用、低置信 API 和缺失 loc key。

如果已有私有 DB 且其中包含 terrainlayout 记录，只配置 db_path 即可使用这些工具；不需要重新初始化索引。

RDO 配置说明

游戏模式入口和配置通常在 scar/**/*.rdo。explain_rdo_config 可以直接读取项目根目录或单个 .rdo 文件，不要求先建索引。官方 Win Condition 编辑说明见：

https://support.ageofempires.com/hc/en-us/articles/4421721200532-Editing-a-Win-Condition

重点字段：

  • m_scarWinConditionFile / m_scarMissionFile: 入口 SCAR 路径，通常相对 scar/，不带 .scar 后缀。
  • m_tuningModGUID: Mod GUID；推断 loc key 时会移除连字符。
  • m_key: 配置项稳定 key；改名前要查 SCAR/UI 引用。
  • m_defaultValue: 配置项默认值；要和选项类型、UI 控件、SCAR 读取逻辑一致。
  • m_locStringKey: 玩家可见名称/标签的 entry id；完整 loc key 通常是 $<guid>:<id>。
  • m_descriptionLocStringKey: 描述/提示文本 entry id，同样需要补齐所有发布语言。

未知字段会以 rdo_unknown_property 返回，工具不会猜测语义；应参考官方样例或相邻项目结构后再改。

官方 Win Condition 文档中的关键配置概念已经内置到 explain_rdo_config.official_win_condition_reference：

  • Display: 显示名、描述、选中图标；自定义图片按官方建议使用 PNG、428x428、32-bit。
  • Modifiers: 开局建筑替换、开局单位、全局升级、开局销毁 egroup；单位专属升级通常应交给 SCAR。
  • Options: 房主可配置项，包含 Boolean、Enumeration、Integer；选项 section key 和 option key 会被 SCAR 读取。
  • Scripts/Setup: Win Condition Script、Scenario Script、DevOnly、MaxTeams、PrecacheList、PermittedInventoryItemCategories、TuningModGUID。

这些是概念层说明；具体 .rdo 字段名仍以项目导出的文件和 Content Editor 为准。

explain_rdo_options 结合官方文档、酒馆项目和 BANG 项目的结构参考确认了这套 Options 层级：

  • WinCondition::OptionsUIDescriptor 通过 m_optionSections 挂载选项分组。
  • WinCondition::OptionSectionUIDescriptor 使用 m_key 作为 SCAR 里的 section table key，并通过 m_options 挂载具体选项。
  • WinCondition::BooleanOptionUIDescriptor 使用 m_key 和 m_defaultValue。
  • WinCondition::EnumerationOptionUIDescriptor 通过 m_enumItems 挂载 WinCondition::OptionEnumItemUIDescriptor；枚举项使用 m_key 和 m_isDefaultValue。
  • WinCondition::IntegerOptionUIDescriptor 使用 m_defaultValue、m_minValue、m_maxValue、m_stepValue；官方提示 AoE4 UI 展示不如布尔/枚举。
  • m_feName、m_feDescriptionTooltip、m_feSummaryName 通常通过 util::ReflectLocString 连接 locdb。

这些参考只保留字段名、对象类型和层级关系，不保存酒馆或 BANG 的具体 key、文本、loc id、代码或原始 .rdo 片段。

Locdb 词条使用方式

模组词条的完整 loc key 通常是 $<mod_guid_without_hyphens>:<entry_id>。.rdo 里的 m_locStringKey、m_descriptionLocStringKey 一般只写 entry_id，工具会结合 m_tuningModGUID 或 .aoe4mod 推断完整 loc key。

常见使用方式：

  • RDO 配置名/描述：在 .rdo 使用 m_locStringKey 或 m_descriptionLocStringKey，并在所有发布语言 CSV 中补齐对应 ID。
  • SCAR 静态文本：使用 Loc_GetString("$guid:id")。
  • SCAR 动态文本：把模板放入 locdb，使用 Loc_FormatText("$guid:id", value)，保留占位符顺序和语义。
  • UI 属性：需要 LocString 时优先传 Loc_GetString 或 Loc_FormatText 的返回值；已有 Lua 字符串才用 LOC(str) 后设置 locStr.LocString = str。

CSV 列结构需要区分语言：

  • 英文：ID,Pipeline,PipelineStage,Notes,TranslationNotes,Tags,Text
  • 简体中文：ID,SourceText,TranslatedText

explain_locdb_usage 可以按 entry_id 或完整 loc_key 查询：返回项目 CSV 中的各语言文本、缺失语言、RDO 字段引用、SCAR 中 Loc_GetString/Loc_FormatText 引用，以及可能的 XAML 直接引用。

置信度

搜索结果会尽量带上 confidence_detail：

  • overall: 综合置信度，含 level 和 score。
  • source: 来源置信度，例如官方 API、官方 SCAR、官方 UI、官方词条、官方基础资料、当前项目扫描。
  • match: 匹配置信度，例如 exact、prefix、contains、token overlap。
  • api_documentation: 仅 API 结果会额外说明该 API 是否在官方 SCAR 中见过实际使用。

优先使用 api_context 查 API，因为它会一次返回 API 文档、官方使用片段和 confidence_summary，比连续调用多个工具更快、更省 token。

测试

python -m pytest

About

No description, website, or topics provided.

Resources

Readme
Apache-2.0 license
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors