内容
# KiBuild MCP
一款专为 FileMaker 打造的 MCP 服务器，为 AI 编程工具提供深入、结构化的 FileMaker 架构访问权限 —— 包括脚本、布局、表格、关系和依赖项 —— 无需 grep，无需读取原始 XML，也无需在运行时拥有 FileMaker 许可证。
与 Claude Code、Cursor、Windsurf、Codex、Antigravity（谷歌）等任何 MCP 兼容的 AI 工具配合使用。
---
## 为什么选择 KiBuild 而不是 grep？
当 AI 使用 `grep` 或读取原始 XML 来回答 FileMaker 问题时，它是在盲目操作。下面是实际操作示例：
| 任务 | 没有 KiBuild | 有 KiBuild |
|---|---|---|
| 查找脚本调用位置 | 在数百个 XML 文件中 `grep -r "Send Email"` —— 噪音大、速度慢、可能漏掉数字 ID | `find_script_references_in_scripts` 返回准确的调用位置，附带文件路径和行号 |
| 查找字段使用位置 | 在计算 XML 中手动正则表达式 —— 可能漏掉布局和关系 | `find_field_references_in_calculations / _in_layouts / _in_relationships` 一次调用即可 |
| 理解脚本 | 读取数百行原始 XML 步步为营 | `find_script` 返回干净的步骤列表，名称已解析 |
| 跟踪关系 | 打开关系图 XML，手动解析连接谓词 | `inspect_relationships` 返回结构化的 JSON 数据 |
| 搜索整个架构 | `grep` 标记所有内容 —— 耗时，上下文填充 | `search_index` 搜索 `workspace_map.md` —— 标记效率高，瞬间完成 |
**谁应该使用此工具：**
- 使用 AI 工具导航、理解或生成架构更改的 FileMaker 开发者
- 进行 AI 辅助的代码审查、影响分析或脚本迁移的团队
- 曾向 AI 询问“这个字段在哪里使用？”却得到缓慢、不完整的答案的任何人
---
## 工作原理
```
您的 FileMaker 文件
│
│ 文件 → 另存为 XML 副本 （FileMaker 2025 及更早版本）
│ 或 文件 → 目录导出 （FileMaker 2026 及更晚版本）
▼
单个 XML 导出 ──→ explode_xml_export ──→ Schema/<db>/
scripts/
layouts/
tables/
relationships/
（每个对象一个文件）
│
▼
generate_schema_map
│
▼
workspace_map.md
（紧凑索引，快速 AI 搜索）
│
▼
32 个 KiBuild 工具实时可用
```
拆分器自动处理两种导出格式：
- **FileMaker 2025 及更早版本** —— `文件 → 另存为 → XML` 生成单个 `.xml` 文件。拆分器将其拆分为每个脚本、布局、表格和关系的文件。
- **FileMaker 2026 及更晚版本** —— 目录导出生成类似的结构。拆分器检测格式并以相同的方式处理。
---
## 快速入门
### 步骤 1 — 安装二进制文件
**macOS / Linux：**
```bash
curl -fsSL https://raw.githubusercontent.com/priyabratasahoo21/kibuild-mcp/main/install.sh | sh
```
**Windows (PowerShell)：**
```powershell
irm https://raw.githubusercontent.com/priyabratasahoo21/kibuild-mcp/main/install.ps1 | iex
```
> **没有 `curl`？** 脚本会自动切换到 `wget`。
>
> **Windows 执行策略错误？** 请先运行以下命令：
> ```powershell
> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
> ```
安装程序下载二进制文件，运行 `kibuild-mcp --setup` 配置 AI 工具的 MCP 配置，并全局安装 AI 指南文件。
---
### 步骤 2 — 导出 FileMaker 架构
您需要一次性从 FileMaker 导出架构。之后，拆分器将其保存为可搜索的文件树。
**FileMaker 2025 及更早版本：**
1. 打开您的 FileMaker 文件
2. 转到 **文件 → 另存为 → XML**
3. 将 `.xml` 文件保存在任意方便的位置
**FileMaker 2026 及更晚版本：**
1. 打开您的 FileMaker 文件
2. 转到 **文件 → 导出 → 目录导出**
3. 保存到一个方便的位置
然后要求您的 AI 工具处理它：
```
将导出文件 /path/to/MyDatabase.xml 拆分为我的项目，然后构建架构映射。
```
AI 调用 `explode_xml_export`（拆分为 `Schema/<db>/`）和 `generate_schema_map`（构建 `workspace_map.md`）。完成此步骤后，所有导航和引用工具都已启用。
> **导出内容：** 脚本（+ 明文清理副本）、表格（含字段）、布局、关系、表格出现、值列表、自定义函数、自定义菜单、帐户、权限集、主题 —— 每个对象一个文件，准备好进行 Git 差异比较。
---
### 步骤 3 — 初始化项目并开始工作
在 AI 工具中打开您的 FileMaker 项目文件夹并运行：
**Claude Code：**
```
/init-kibuild-project
```
这会在项目根目录写入 `CLAUDE.md`、`AGENTS.md`、`GEMINI.md` 和 `.cursor/rules/kibuild.mdc` —— 告诉打开文件夹的 AI 工具优先使用 KiBuild 工具而不是 grep。提交这些文件，以便您的整个团队自动获得相同的行为。
然后提出自然的问题：
```
查找脚本“创建发票”并告诉我它的作用。
哪些脚本调用“发送电子邮件通知”？
字段“状态”在脚本、布局和计算中如何使用？
列出所有引用发票表格出现的布局。
显示联系人表格的关系。
```
---
### 一句命令，零命令（仅限 Claude Code）
在 Claude Code 中打开此仓库的文件夹并输入：
```
帮助我设置 KiBuild MCP
```
Claude 读取项目指南并自动运行完整的设置向导。不需要终端。
---
## 为您的 AI 工具配置
设置向导自动处理 Claude Code。对于其他工具，请手动添加 MCP 服务器条目。替换 `/path/to/your/project` 为 FileMaker 项目文件夹的绝对路径。
### Claude Code
**macOS / Linux** — `~/.claude.json`
```json
{
"mcpServers": {
"kibuild": {
"command": "/usr/local/bin/kibuild-mcp",
"env": {
"KIBUILD_ACTIVE_PROJECT": "/path/to/your/project"
}
}
}
}
```
**Windows** — `C:\Users\<YourName>\.claude.json`
```json
{
"mcpServers": {
"kibuild": {
"command": "C:/Users/<YourName>/AppData/Local/Programs/kibuild-mcp/kibuild-mcp.exe",
"env": {
"KIBUILD_ACTIVE_PROJECT": "C:/Users/<YourName>/Documents/MyFileMakerProject"
}
}
}
}
```
编辑后，重启 Claude Code 或运行 `/mcp` 以重新加载。
---
### Cursor
配置文件：`~/.cursor/mcp.json`
```json
{
"mcpServers": {
"kibuild": {
"command": "/usr/local/bin/kibuild-mcp",
"env": { "KIBUILD_ACTIVE_PROJECT": "/path/to/your/project" }
}
}
}
```
---
### Windsurf
配置文件：`~/.codeium/windsurf/mcp_config.json`
```json
{
"mcpServers": {
"kibuild": {
"command": "/usr/local/bin/kibuild-mcp",
"env": { "KIBUILD_ACTIVE_PROJECT": "/path/to/your/project" }
}
}
}
```
---
### OpenAI Codex CLI
配置文件：`~/.codex/config.toml`
```toml
[mcp_servers.kibuild]
command = "/usr/local/bin/kibuild-mcp"
[mcp_servers.kibuild.env]
KIBUILD_ACTIVE_PROJECT = "/path/to/your/project"
```
---
### Google Antigravity (Agy)
配置文件：`~/.gemini/config/mcp_config.json`
```json
{
"mcpServers": {
"kibuild": {
"command": "/usr/local/bin/kibuild-mcp",
"env": { "KIBUILD_ACTIVE_PROJECT": "/path/to/your/project" }
}
}
}
```
创建文件夹（如果需要）：`mkdir -p ~/.gemini/config`
---
### VS Code（带有 MCP 扩展）
用户 `settings.json` — 通过 `Ctrl+Shift+P` → “打开用户设置 JSON”打开
```json
{
"mcp.servers": {
"kibuild": {
"command": "/usr/local/bin/kibuild-mcp",
"env": { "KIBUILD_ACTIVE_PROJECT": "/path/to/your/project" }
}
}
}
```
---
## 有用的命令
| 命令 | 位置 | 功能 |
|---|---|---|
| `kibuild-mcp --setup` | 终端 | 完整向导：版本检查、配置、工具验证、安装 AI 指南 |
| `kibuild-mcp --version` | 终端 | 打印已安装的版本 |
| `/setup-kibuild` | Claude Code | 由 Claude Code 驱动的相同向导 |
| `/init-kibuild-project` | Claude Code | 将 AI 指南文件写入当前项目文件夹 |
| `/mcp` | Claude Code | 列出连接的 MCP 服务器及其工具数量 |
---
## 工具参考
### 架构导航
| 工具 | 功能 |
|---|---|
| `find_script` | 按名称查找脚本 — 返回清理的步骤列表、文件路径和兄弟脚本 |
| `find_layout` | 查找布局 — 返回绑定的表格出现、引用的脚本和 XML 路径 |
| `find_table` | 查找基本表格 — 返回所有字段及其类型和 XML 路径 |
| `inspect_relationships` | 返回数据库或表格出现的全部关系谓词 |
| `search_index` | 在 `workspace_map.md` 上进行关键词搜索 — 标记效率高，仅返回匹配的行 |
| `generate_schema_map` | 构建或刷新 `workspace_map.md` — 所有架构对象的紧凑索引 |
### 影响分析
| 工具 | 查找内容 |
|---|---|
| `find_script_references_in_scripts` | 脚本通过执行脚本调用的位置 |
| `find_script_references_in_layouts` | 布局通过按钮或脚本触发器触发脚本的位置 |
| `find_script_references_to_layouts` | 脚本中的“转到布局”步骤 |
| `find_script_references_to_valuelists` | 脚本中的值列表引用 |
| `find_field_references_in_scripts` | 读取或写入字段的脚本 |
| `find_field_references_in_layouts` | 显示字段的布局 |
| `find_field_references_in_calculations` | 计算字段、自动输入计算和验证规则引用字段 |
| `find_field_references_in_relationships` | 关系连接谓词使用字段 |
| `find_variable_references_in_scripts` | 设置或读取 `$variable` 的脚本 |
| `find_layout_references_to_scripts` | 布局的按钮或脚本触发器触发的脚本 |
| `find_layout_references_to_valuelists` | 布局上字段控件使用的值列表 |
| `find_layout_references_to_tables` | 布局上字段引用的表格出现 |
| `find_layout_references_in_calculations` | 引用布局名称的计算 |
| `find_valuelist_references_in_calculations` | 引用值列表的计算 |
| `find_to_references` | 每个引用表格出现的布局、脚本和关系 |
| `find_relationship_predicates` | 表格出现的完整连接谓词详细信息 |
### XML 和生成
| 工具 | 功能 |
|---|---|
| `explode_xml_export` | 将 FileMaker XML 导出拆分为每个对象的架构树。自动检测格式。 |
| `xml_extract_steps` | 从 FMXML 片段或文件中列出所有脚本步骤 |
| `xml_lookup_name` | 将数字脚本 ID 解析为其名称 |
| `xml_trace_dependencies` | 从 XML 中提取所有引用的 TO、脚本、布局和字段 |
| `xml_match_revision` | 从 XML 头部读取 FileMaker 版本和修订元数据 |
| `validate_fmxmlsnippet` | 对生成的 FMXML 片段运行 7 规则结构验证 |
| `validate_webviewer_html` | 检查 WebViewer HTML 以防止远程依赖和风险 API |
| `write_outbox_artifact` | 将生成的输出保存到项目输出框作为版本化的工件 |
| `read_xml_guide` | 加载 FileMaker XML 片段参考指南 — 脚本步骤生成的模式和模板 |
### 专业技能
| 工具 | 功能 |
|---|---|
| `load_skill` | 将专业技能加载到 AI 上下文。可用的技能：`pro_scriptwriter`、`script_analysis`、`fm_xml_serializer`、`script_debug` |
---
## 故障排除
**可见工具少于 30 个？**
您的二进制文件已过时（pre-v0.2.0）。请重新安装：
```bash
# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/priyabratasahoo21/kibuild-mcp/main/install.sh | sh
# Windows
irm https://raw.githubusercontent.com/priyabratasahoo21/kibuild-mcp/main/install.ps1 | iex
```
然后完全退出并重启您的 AI 工具 — MCP 客户端缓存了旧进程。
**macOS 二进制文件被 Gatekeeper 阻止？**
```bash
xattr -d com.apple.quarantine /usr/local/bin/kibuild-mcp
```
然后在 **系统设置 → 隐私和安全** 中允许它，如果提示的话。
**服务器未启动？**
检查日志：
```bash
# macOS / Linux
tail -20 ~/.fm_ai_bridge/mcp_server.log
# Windows
Get-Content "$env:USERPROFILE\.fm_ai_bridge\mcp_server.log" -Tail 20
```
常见原因：配置文件中二进制文件路径不匹配、macOS 上 Gatekeeper 阻止、Windows 上 PATH 问题。
---
## 工具数量参考
KiBuild MCP 公开 **32 个工具**。如果您看到少于 28 个工具，二进制文件可能已过时 — 运行 `kibuild-mcp --setup` 以自我更新，然后完全重启 Claude Code。
---
## 从源代码安装
**go install**（需要 Go 1.21+）：
```bash
go install github.com/priyabratasahoo21/kibuild-mcp@latest
kibuild-mcp --setup
```
**从源代码构建：**
```bash
git clone https://github.com/priyabratasahoo21/kibuild-mcp.git
cd kibuild-mcp
go build -ldflags="-s -w -X main.Version=v0.2.0" -o kibuild-mcp .
sudo mv kibuild-mcp /usr/local/bin/
kibuild-mcp --setup
```
**手动下载** — [发布页面](https://github.com/priyabratasahoo21/kibuild-mcp/releases)
| 平台 | 文件 |
|---|---|
| macOS (Apple Silicon) | `kibuild-mcp-darwin-arm64` |
| macOS (Intel) | `kibuild-mcp-darwin-amd64` |
| Linux (x86_64) | `kibuild-mcp-linux-amd64` |
| Linux (ARM64) | `kibuild-mcp-linux-arm64` |
| Windows | `kibuild-mcp-windows-amd64.exe` |
---
## 架构
```
AI 工具（Claude Code、Cursor、Windsurf、VS Code、Codex、Antigravity）
│
│ 在 MCP 连接时启动子进程
▼
kibuild-mcp 二进制文件
│ 通过 stdin/stdout 进行 MCP JSON-RPC
│
└── 32 个工具读取磁盘上的 Schema/XML 文件
不需要在运行时拥有 FileMaker 许可证
架构位置： ~/your-project/files/Schema/<DBName>/
项目索引： ~/your-project/workspace_map.md
日志： ~/.fm_ai_bridge/mcp_server.log
```
---
## 贡献
欢迎拉取请求。对于重大更改，请先打开一个问题。
## 许可证
MIT
