factorio-docs-mcp

同步 Factorio 官方 mod API 文档到本地 SQLite 索引，并通过 MCP server 为 mod 开发与跨大版本升级迁移提供检索 + 版本对比能力。

能力

• 检索：查询 runtime / prototype API（类、方法、属性、事件、define、prototype）与散文文档

• 版本对比：对比任意 API 条目在两个版本间的差异（成员增删 / 类型变更）

• 迁移清单：从官方 changelog 提取 Modding / Scripting 变更，标记 breaking 级别（如"defines.direction 从 8 个增至 16 个，存储值需乘 2"）

• 离线：所有数据落地本地，同步增量进行，使用时无需联网

Related MCP server: wiki-mcp-hub

数据源（仅官方）

• lua-api.factorio.com：runtime-api.json / prototype-api.json / archive.zip（多版本）

• wube/factorio-data：含 changelog.txt

安装

npm install -g factorio-docs-mcp
# 或用 npx 直接运行

要求：

• Node.js ≥ 22（依赖内置 node:sqlite）

• git（fdocs sync 需调用 git 同步 factorio-data 仓库，请确保 git 在 PATH 中）

使用

1. 同步文档

fdocs sync            # 增量同步缺失版本
fdocs sync --rebuild  # 重建全部索引

同步版本范围由数据目录下 config.json 的 versions 模式控制，默认 ["1.1.110", "2.0.*", "2.1.*"]。

2. 数据目录

• 环境变量 FACTORIO_DOCS_DATA 优先

• 否则用平台用户数据目录（Windows：%APPDATA%/factorio-docs-mcp）

<数据目录>/
├── raw/<版本>/   # 原始下载（可随时重建）
└── index.db      # SQLite 索引

3. 接入 MCP

Claude Code / Claude Desktop 配置：

{
  "mcpServers": {
    "factorio-docs": { "command": "fdocs-mcp" }
  }
}

MCP 工具（8 个）

架构

三层严格隔离：sync/（只写 raw/）→ index/（读写 index.db）→ mcp/（只读 index.db）。检索经 SearchProvider 接口（v1 = SQLite FTS5，预留向量扩展）。数据保真：api_entries.data 原样存储官方 JSON 子树。

开发

npm test          # Vitest
npm run typecheck # tsc --noEmit
npm run lint      # biome check
npm run build     # tsup（双 bin）

详见 AGENTS.md 与设计文档 docs/superpowers/specs/2026-07-29-factorio-docs-mcp-design.md。

License

MIT