gedfire

GedFire

为 AI Agent 提供家谱工具，而不是 GEDCOM 文本编辑器。

GedFire 是一个本地模型上下文协议 （MCP）服务和命令行工具。它可帮助 Agent 查找人物、比较记录、起草带引文的修改，并在写入家族史之前验证修改。它还可以用相同的数据生成静态家族页面网站。

GedFire 仅支持本地 MCP 模式，使用 stdio（标准输入／输出）。你的 MCP 客户端会将已安装的可执行文件作为本地进程启动。它不支持远程 HTTP、Streamable HTTP 或 SSE 传输，也不使用服务 URL 或监听端口。这描述的是 MCP 连接方式，而不是客户端 AI 模型的运行位置。

historical records -> findings -> changesets -> review -> GEDCOM -> website

GedFire 负责处理具体操作。由你和审核者判断证据。服务提供十九个类型化工具；只有 apply_changeset 能修改已绑定的 GEDCOM。其他工具可以将草稿和报告写入单独的文件。 审核与权限限制很重要：GedFire 会验证修改，但不会收集或验证你的批准。

快速开始

使用 .NET 10 SDK 安装：

dotnet tool install --global GedFire
gedfire --version

或者下载独立发布版本，无需安装 .NET。

请从 GEDCOM 文件的副本开始。配置你的 MCP 客户端以启动：

gedfire mcp --input "C:\Genealogy\family.ged" --read-only --enforce-privacy

将输入路径替换为文件的绝对路径。让客户端启动本地 stdio 服务，而不是在终端中运行第二个副本；它通过进程流通信，而非网络连接。

向 Agent 提问：“这个文件中有多少人和家庭？” 它应该调用 get_document_stats 并报告这两个数量。

--read-only 会阻止修改 GEDCOM，但不会阻止生成草稿或报告文件。 --enforce-privacy 会在工具输出中屏蔽受保护以及可能仍在世的个人信息。在了解安全与隐私限制之前，请保留这两个标记。

试用虚构演示

浏览生成的家族页面。 CI 会在每次推送时，从虚构的 Ash 家族数据重新构建此网站。将鼠标悬停在脚注上，即可查看每项事实的引文。

要亲自运行演示，请下载或克隆此仓库。在仓库根目录中运行：

Copy-Item docs\demo\ash-whitfield.ged family.ged
gedfire apply --input family.ged --changes docs\demo\proposed-findings.json --items all --dry-run
gedfire apply --input family.ged --changes docs\demo\proposed-findings.json --items all
gedfire generate --input family.ged --output-dir site --template docs\demo\template.html

第一次应用只会预览修改。第二次应用会将修改写入副本。打开 site/index.html 浏览结果。演示中的所有人物、记录、地点和来源均为虚构。在 Linux 或 macOS 上，请使用 cp 和 / 路径。

为什么选择 GedFire？

在线族谱能提供线索，但无法证明事实。重复的说法可能传播错误，却没有增加证据。GedFire 支持另一种工作流：记录文献所述内容，确认涉及的人物，然后提出带引文的修改。

• 结构化修改，而非直接编辑原始文本。 GedFire 会对解析后的 GEDCOM 文档执行操作。在写入前，它会检查结构、指针和记录数量变化。
• 事实附带引文。 调查结果包含逐字摘录、来源详情和质量评级。拟议的修改和生成的页面也会保留这些内容。
• 确定性的处理机制。 工具会为身份候选项排序、协调相互兼容的调查结果、重复利用来源并标记分歧。Agent 负责提供证据并作出判断。
• 规则由你掌控。 策略文件可以拒绝禁止的文字、要求附上核实说明，并要求提供死亡地点的证据。
• 本地处理。 GedFire 不会发出网络请求，也不会发送遥测数据。工具结果发送到哪里由你的 MCP 客户端控制。
• 单一发布来源。 直接根据经过审核的 GEDCOM 生成家族页面，无需另行维护一份事实副本。

Agent 交换的是精简的调查结果和操作，而不是重写整条记录。Token 用量取决于客户端和任务；本 README 不会声称能量化节省效果。

GedFire 不是图形化族谱编辑器、记录提供方或托管式家谱服务。它无法确认引文是否真实，也无法确认身份识别是否正确。

连接 AI 客户端

如果客户端要求选择 MCP 服务类型，请选择 local 或 stdio。请配置可执行命令及其参数，而不是远程服务 URL。

VS Code / GitHub Copilot

将以下内容添加到工作区中的 .vscode/mcp.json：

{
  "servers": {
    "gedfire": {
      "type": "stdio",
      "command": "gedfire",
      "args": [
        "mcp", "--input", "C:\\Genealogy\\family.ged",
        "--read-only", "--enforce-privacy"
      ]
    }
  }
}

替换输入路径，通过 VS Code 的 MCP 控件启动服务，并在出现提示时批准信任。在聊天中启用其工具。有关用户级配置和工具权限，请参阅 VS Code MCP 指南。

Claude Desktop、Claude Code、Cursor、Windsurf 和 Gemini CLI

这些客户端使用 mcpServers 条目：

{
  "mcpServers": {
    "gedfire": {
      "command": "gedfire",
      "args": [
        "mcp", "--input", "C:\\Genealogy\\family.ged",
        "--read-only", "--enforce-privacy"
      ]
    }
  }
}

客户端	配置文件
Claude Desktop	打开 Settings > Developer > Edit Config，编辑 claude_desktop_config.json。
Claude Code	项目根目录中的 .mcp.json。
Cursor	项目中的 .cursor/mcp.json，或客户端的全局 mcp.json。
Windsurf	~/.codeium/windsurf/mcp_config.json。
Gemini CLI	项目中的 .gemini/settings.json，或 ~/.gemini/settings.json。

Codex

将以下内容添加到项目中的 .codex/config.toml 或 ~/.codex/config.toml：

[mcp_servers.gedfire]
command = "gedfire"
args = ["mcp", "--input", "C:\\Genealogy\\family.ged", "--read-only", "--enforce-privacy"]

选项和故障排除

所有示例都使用 Windows 路径。在 Linux 或 macOS 上，请将输入替换为绝对路径，例如 /home/me/genealogy/family.ged。Windows 路径中的反斜杠在 JSON 和 TOML 双引号字符串中必须转义。

选项	效果
--read-only	拒绝所有 apply_changeset 调用。其他所有工具仍可用，包括草稿和报告输出。
--enforce-privacy	在工具输出中遮蔽受保护的人物和可能仍在世的人物。请参阅隐私限制。
--policy <json>	在变更集验证和应用期间强制执行编辑规则。请参阅策略示例和策略参考。

更改配置后，请重启或重新加载客户端。如果启动失败，请检查：

1. 在新终端中运行 gedfire --version 是否成功。
2. GEDCOM 绝对路径是否存在。
3. 客户端的 MCP 日志中是否没有启动错误。
4. 如果客户端无法在继承的 PATH 中找到 gedfire，command 是否指定了绝对可执行文件路径。

GedFire 无需 API 密钥、凭据或环境变量。

研究工作流

发现记录的是来源所述内容。 保存原文摘录、来源及定位信息、来源类别和信息类别、所声称的事实以及质量等级。保留相互冲突的发现，不要将其简化为单一结论。

关联用于识别个人。 对带有姓名线索的查找使用 find_person；对于家庭、讣告或其他涉及多人的记录，使用 match_record。检查候选项和排除项。确定性的匹配分数不是概率，也不能替代论证过程。

变更集说明要进行的编辑。 draft_changeset 会将发现编译为带类型的操作。它会协调兼容的事实、保留其引文，并将真正的分歧留作 open 决策。如果验证发现缺陷，请修正相关发现并重新起草。

提案呈现供审核的论据。 执行 validate_changeset 和 check_plausibility 后，调用 draft_package。它会根据已完成的变更集生成编号提案，其中包含证据、等级以及作者提供的身份论证。

仅应用审核流程批准的内容。 使用 apply_changeset 选择已批准的项目。写入前，它会再次验证和核查。准备好发布时，再生成网站。

来源类别和信息类别决定引文质量的上限，但不能证明某项主张。死亡证明可能提供有关死亡的一手信息，却只提供有关出生的二手信息。关于 QUAY 上限，请阅读评级与起草参考。

工具

服务绑定到一个 GEDCOM 文件，并会在文件于磁盘上发生变化时重新加载。每个返回的 xref 仅属于该文档；切勿将其用于其他文件或提供方。

工具	用途
get_document_stats	报告个人和家庭数量、GEDCOM 版本以及 GedFire 版本。
find_person	根据姓名匹配进行排序，可选使用出生、死亡、父母和婚姻线索。
find_family	通过具名配偶、父母或子女查找某人。
find_source	按标题、作者或 URL 查找现有来源。
get_record	获取个人、家庭或来源记录，包含引文和可选的来源文本。
get_records	一次获取多条记录，可选择字段。
list_people	按稳定的姓氏／姓名／xref 顺序分页列出个人。
list_unanchored_people	查找本人或直系亲属均无带日期或地点锚点的个人。
match_record	将涉及多人的记录与家谱中的家庭进行比对，并调查同名竞争对象。
research_brief	汇总某人的事实、亲属、信息缺口、备注、重复项和合理性问题。
select_targets	对研究信息缺口评分并抽取目标，或对指定个人评分。
date_calc	规范化双日期、加减年龄或计算经过的时间。
describe_changeset_ops	返回变更集封装、操作架构和完整示例。
draft_changeset	将发现编译为带引文的变更集，并报告尚未解决的决策。
draft_package	根据已完成的变更集编写审核提案。
validate_changeset	预览所选编辑、执行策略，并可选择评估信息缺口的填补情况。
check_plausibility	报告编辑可能引入的时间顺序和生物学问题。
validate_document	检查整个文档是否符合 GEDCOM 7。
apply_changeset	验证、应用并核查所选项目，然后写入 GEDCOM。

确切的参数请参阅公布的 MCP 架构；行为和示例请参阅 MCP 参考。 每个工具都会拒绝缺少必需参数或包含无法识别的参数的请求。 错误信息会指出有问题的字段，并列出可接受的字段。

安全与审核

GedFire 的强制规则

• Dry-run 和 apply 使用相同的验证。如果某项操作未通过验证， GedFire 不会写入任何内容。
• 基于路径的 apply 会从首次读取开始，到完成写入并验证为止，始终持有独占文件锁， 以防止多个 GedFire 写入者发生竞争。
• 创建人物之前，验证会检查现有人物和计划创建的人物，拒绝高置信度的重复项。 存在歧义的候选项不会阻止创建。
• 写入之前，GedFire 会检查字节稳定的重新解析／格式化往返结果、 指针解析情况以及预期的记录数变化。
• 即使客户端批准，--read-only 也会拒绝 apply 调用。
• 配置的策略可以在预览和 apply 阶段拒绝变更集。

请保留备份或版本历史。结构验证无法发现所有家谱错误。

你和客户端可控制的事项

GedFire 不会验证审核者是否已批准。 apply_changeset 会接受调用方选定的项目；它不会验证这些项目是否获得了人工或独立审核者的批准。提案支持征得同意，但不会强制执行。

请使用 MCP 客户端的工具权限来控制 apply 的访问权限。若要彻底阻止 GEDCOM 写入，请保留 --read-only。只有在确实打算允许写入时才移除它。请明确决定是否要求人工批准每项变更，或是否授权自动化审核工作流。GedFire 不要求设置人工审核关卡；独立模型可以审核每个项目。

验证检查的是编辑内容，而非证据是否属实。请自行或通过信任的审核者审查引文、身份论证、来源的独立性以及尚未解决的冲突。

隐私

GedFire 不会发起网络请求，也不会发送遥测数据。你选择的客户端可能会将工具结果发送给模型提供商；本地处理并不意味着整个对话都在本地进行。

--enforce-privacy 使用站点的隐私过滤器。它会屏蔽带有 RESN CONFIDENTIAL 或 RESN PRIVACY 标记的个人，以及可能在世的人：没有死亡类别事实，且出生于最近 100 年内。他们在工具视图中会显示为 Living <Surname> 占位符，不包含日期、地点、备注或媒体。

过滤器依据的是已记录的事实，而非经过核实的在世状态。占位符仍会暴露姓氏。若没有出生年份或明确的限制标记，年龄判断规则不会屏蔽该人物。此标志不承诺会删除其他记录或用户提供文本中的所有相关提及。分享结果之前，请检查你的数据和客户端的隐私设置。

安装

安装为 .NET 工具

需要 .NET 10 SDK：

dotnet tool install --global GedFire
gedfire --version

更新：dotnet tool update --global GedFire。

下载发行版

从 GitHub Releases 下载适用于你平台的归档文件并解压。这些独立二进制文件无需单独安装 .NET。

在 Windows 上运行 .\GedFire.exe help。在 Linux 或 macOS 上运行 ./GedFire help。

命令行

CLI 使用与 MCP 服务相同的引擎。

命令	用途
create	创建带有种子数据的 GEDCOM 7 文档。
upgrade / downgrade	在 GEDCOM 5.5 和 7 之间转换。
validate	检查是否符合 GEDCOM 7。
apply	预览或应用选定的变更集项目；使用 --dry-run 进行预览。
generate	生成静态家族页面，可选暂存媒体文件。
export-index	导出 JSON 人名索引。
select-targets	检测、评分并为研究姓氏绘制研究缺口。
date-calc	规范化双日期，或计算日期和年龄。
find-person / get-record / get-document-stats	执行一次查询并打印 JSON，无需启动服务。
pack / unpack	创建或提取 GEDZIP 归档文件。
mcp	启动仅限本地的 stdio MCP 服务；不使用 HTTP 或远程传输。
tools list / tools describe / tools call	使用相同的 JSON 架构和处理程序，直接发现或调用任意 MCP 工具。

运行 gedfire help 查看命令语法。有关变更集语义和日期运算示例，请参阅 MCP 参考。

在脚本中使用工具

每个 MCP 工具也都可作为一次性命令使用，无需服务或 AI 客户端：

gedfire tools list
gedfire tools describe find_person
gedfire tools call find_person --input family.ged --args request.json --out result.json --enforce-privacy

参数文件只包含 MCP 工具的参数对象，例如：

{"query":"Mara Example","maxResults":8}

使用 --args - 从 stdin 读取 JSON，或省略 --args，此时使用 {}。除非通过 --out 指定新文件，否则结果将以 JSON 格式输出到 stdout；如果输出文件已存在，则会拒绝覆盖。诊断信息会输出到 stderr。成功时退出代码为 0，发生错误或验证／合理性检查失败时为 1。

--policy、--read-only 和 --enforce-privacy 的含义与 mcp 中相同。只读模式会阻止修改 GEDCOM，但不会阻止生成单独的草稿或报告文件。发现工具无需 GEDCOM；调用 date_calc 和 describe_changeset_ops 无需 --input。现有便捷命令保持不变。有关输出详情，请参阅脚本接口。

从源代码构建

需要 .NET 10 SDK：

git clone https://github.com/morrillonline/GedFire.git
cd GedFire
dotnet build --nologo
dotnet test --nologo
.\GedFire\bin\Debug\net10.0\GedFire.exe help

该解决方案包含 GedCore（引擎）、GedFire（CLI、MCP 服务和站点生成器）以及 GedCore.Tests。

版本遵循 VersionMajor.VersionMinor.BuildNumber 格式。 Directory.Build.props 定义主版本号和次版本号（当前为 4.1）。本地构建默认使用构建号 1；CI 使用工作流运行编号，发布构建使用 v<major>.<minor>.<build> 标签的末尾部分。通过 dotnet build、test 或 publish 设置 -p:BuildNumber=<build>，即可在本地复现指定的构建号。

标准与贡献

GedFire 独立实现了 FamilySearch GEDCOM 7。它与 FamilySearch 或耶稣基督后期圣徒教会没有关联，也未获得其认可。有关标准和扩展，请参阅官方规范仓库 和注册表。

欢迎提交错误报告、拉取请求和合成边缘案例样例。 请勿在问题、样例或拉取请求中包含私人家族数据。 提交 PR 前请运行 dotnet test --nologo。

许可证

MIT。