# 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"）
- **离线**：所有数据落地本地，同步增量进行，使用时无需联网

## 数据源（仅官方）

- `lua-api.factorio.com`：`runtime-api.json` / `prototype-api.json` / `archive.zip`（多版本）
- `wube/factorio-data`：含 `changelog.txt`

## 安装

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

要求：

- **Node.js ≥ 22**（依赖内置 `node:sqlite`）
- **git**（`fdocs sync` 需调用 git 同步 factorio-data 仓库，请确保 `git` 在 `PATH` 中）

## 使用

### 1. 同步文档

```bash
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 配置：

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

## MCP 工具（8 个）

| 工具 | 用途 |
|------|------|
| `list_versions` | 列出已索引版本 |
| `search_api` | 按名称/描述模糊搜索 API 条目 |
| `get_api_entry` | 精确获取某条目完整定义（未命中返回建议） |
| `diff_api` | 对比某条目在两版本间的差异 |
| `search_docs` | 全文检索散文文档 |
| `get_doc` | 按 slug 获取整篇文档 |
| `list_changes` | 列出两版本间的迁移/breaking 变更清单 |
| `sync_docs` | 检查或触发同步 |

## 架构

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

## 开发

```bash
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