GedFire

# GedFire

<!-- mcp-name: io.github.morrillonline/gedfire -->

[![CI](https://github.com/morrillonline/GedFire/actions/workflows/ci.yml/badge.svg)](https://github.com/morrillonline/GedFire/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-2e7d32.svg)](LICENSE)
[![.NET 10](https://img.shields.io/badge/.NET-10-512bd4.svg)](https://dotnet.microsoft.com/)

GedFire is a command-line tool that lets an AI agent help with your family
history research without giving it write access to your GEDCOM file. The agent
writes its findings as a JSON proposal; you review it, approve the items you
want, and GedFire applies them, keeping each citation attached to the claim it
supports. It can then generate a static family-page site from the result.

```text
agent research -> JSON proposal -> your review -> verified GEDCOM -> static HTML
```

GedFire works only with local files and makes no network requests. Your chosen
AI client controls where tool results are processed.

Why not just let the agent edit the file? GEDCOM looks like plain text, but
the level hierarchy, cross-record pointers, and continuation rules are easy to
get wrong — agents asked to rewrite raw GEDCOM tend to produce broken levels,
dangling references, or files that no longer validate. GedFire instead applies
typed operations to a parsed document and refuses to write anything invalid,
so a valid input file stays valid. As a bonus, the agent doesn't have to read
and reproduce whole GEDCOM records, which saves a lot of tokens.

**[Browse a live generated family-page site →](https://morrillonline.github.io/GedFire/)**
*Generated from the synthetic family in [`docs/demo`](docs/demo), rebuilt by
CI on every push. Facts retain their source citations, available as
hover-popover footnotes in the HTML.*

## MCP server

GedFire also runs as a Model Context Protocol server, so clients including
Claude Desktop, Claude Code, Cursor, Windsurf, Gemini CLI, and Codex can query
your GEDCOM directly, in conversation, instead of shelling out to the CLI:

```powershell
gedfire mcp --input family.ged
```

Install the [global .NET tool](#install-as-a-net-tool) before configuring a
client. The command above starts a long-running stdio server, so waiting
silently for a client connection is normal.

Most MCP clients accept the same local stdio server entry. Add this block to
the client's MCP configuration, replacing the GEDCOM path with an absolute
path:

```json
{
  "mcpServers": {
    "gedfire": {
      "command": "gedfire",
      "args": [
        "mcp",
        "--input",
        "/absolute/path/to/family.ged"
      ]
    }
  }
}
```

Use that `mcpServers` entry in the location your client supports:

| Client | Configuration |
|---|---|
| Claude Desktop | Open **Settings → Developer → Edit Config** and add it to `claude_desktop_config.json`. |
| Claude Code | Add it to `.mcp.json` in the project root, or run `claude mcp add --scope project --transport stdio gedfire -- gedfire mcp --input <absolute-path>`. |
| Cursor | Add it to `.cursor/mcp.json` for the project or the client's global `mcp.json`. |
| Windsurf | Add it to `~/.codeium/windsurf/mcp_config.json`. |
| Gemini CLI | Add it to `.gemini/settings.json` for the project or `~/.gemini/settings.json`. |

Codex uses TOML instead of the JSON wrapper above. Add this to
`.codex/config.toml` in the project or `~/.codex/config.toml`:

```toml
[mcp_servers.gedfire]
command = "gedfire"
args = ["mcp", "--input", "/absolute/path/to/family.ged"]
```

Two optional flags follow `--input` in `args` (or after `--input <path>` on
the `claude mcp add` / TOML command lines above):

| Flag | Effect |
|---|---|
| `--read-only` | Disable `apply_changeset`: every call to it is refused with an error, and the bound file is never written. `validate_changeset` and every other (already read-only) tool stay available — an agent can still preview changesets, it just can't apply them. Use this for a client you trust to look and propose, but not to write, even after review. |
| `--enforce-privacy` | Run every tool's view of the document through the same privacy filter `generate` applies before publishing a site: individuals with an RESN of CONFIDENTIAL or PRIVACY, and individuals plausibly still living (no death-class fact, born within the last 100 years), are reduced to a "Living \<Surname\>" placeholder — no dates, places, notes, or media. Use this when the MCP client is one you don't want seeing the living branches of the file. |

On Windows, JSON paths use escaped backslashes such as
`C:\\Users\\me\\family.ged`; forward slashes also work. The `gedfire`
command must be available on the environment `PATH` inherited by the client,
or `command` must contain the absolute path of the executable. GedFire needs
no environment variables, API keys, or other credentials.

Restart or reload the client after changing its configuration, approve the
local server if prompted, and confirm that it discovers `find_person`,
`date_calc`, `get_document_stats`, `get_record`, `describe_changeset_ops`,
`validate_changeset`, `validate_document`, and `apply_changeset`.

As a smoke test, ask "How many people and families are in this file?" The
client should call `get_document_stats` and report both counts.

The server binds to one document over stdio and exposes eight tools. Seven
are read-only; `apply_changeset` is the only one that writes to the file,
and only after validation and in-memory verification both pass (or not at
all, if the server was started with `--read-only`). The server also watches
the bound file and reloads automatically if it changes on disk — including
a change `apply_changeset` itself just wrote — no restart needed:

| Tool | What it does |
|---|---|
| `date_calc` | Normalize a dual-dated year, add or subtract a genealogical age, or calculate elapsed years/months/days. Uses exact Gregorian dates supplied in the call and never reads or changes the bound document. |
| `find_person` | Resolve a name the agent heard in conversation — "my great-grandfather Fred Morrill" — to scored candidates, a confident match when one exists, and family handoff identifiers. Optional structured hints distinguish birth from death, father from mother, and one marriage from another. Set `maxResults` to an integer from `1` through `20` (default `8`) without changing the matcher's confidence decision. |
| `get_document_stats` | Report person/family counts, the declared GEDCOM version, and the running gedfire version, for a quick orientation before other work. |
| `get_record` | Fetch the full detail of a specific person, family, or source by xref. |
| `describe_changeset_ops` | Return the changeset envelope shape and the full v2 op dialect (every `createOrUpdate`/`delete`/`merge` op, its required and optional fields, and one worked example) — so an agent can compose a valid changeset without external documentation or trial-and-error against `validate_changeset`'s error text. Takes no arguments. |
| `validate_changeset` | Dry-run a proposal changeset (`changesetPath`, `items`) against the bound document: every op is validated exactly as `apply_changeset` would validate it, but nothing is written. Always available, even under `--read-only`. |
| `validate_document` | Run the same GEDCOM 7 conformance checks as `gedfire validate` against the whole bound document — independent of any changeset — and return the findings structured instead of as plain-text lines. Optional `warningsAsErrors` mirrors the CLI flag. Always available, even under `--read-only`. |
| `apply_changeset` | Validate, apply, and verify a proposal changeset, then write the file — the same safety model as `gedfire apply` (dry-run-equivalent validation, byte-stable round-trip check, pointer resolution, record-count deltas) reached over MCP instead of the CLI. Refuses to run under `--read-only`. |

`date_calc`, `find_person`, `get_document_stats`, and `get_record` also have
a one-shot CLI mirror — `find-person`, `get-record`, `get-document-stats`,
and `date-calc` — that runs the same engine and prints the same JSON without
starting a server. `validate_changeset` and `apply_changeset` mirror the
CLI's own `apply --dry-run` and `apply`, and `validate_document` mirrors
`validate`, described under "Command reference" below, rather than having
a same-named CLI counterpart of their own.

For example, an MCP client can call `find_person` with:

```json
{
  "query": "Frederick Morrill",
  "hints": {
    "birth": { "year": 1841, "place": "New Hampshire" },
    "parents": { "father": "Wyman Morrill" },
    "spouse": {
      "name": "Sarah Blake",
      "marriage": { "year": 1865, "place": "Maine" }
    }
  },
  "maxResults": 20
}
```

Every hint leaf is optional, but each supplied object must contain at least
one fact. Birth and death places are event-specific; census or otherwise
unclassified places are not hints. Parent names require a known `father` or
`mother` role. All fields under `spouse` describe one marriage and are never
combined across different marriages. Hints rank only people already recalled
by the name query, and missing candidate data is not penalized.

Every result has the same top-level fields: `matchType`,
`confidentMatchXref`, `confidentMatchScore`, `person`, `candidates`,
`suggestions`, `totalMatches`, and `truncated`. Candidates and suggestions
always include `matchScore`. Scores rank evidence within this matcher; they
are not statistical probabilities. Use `matchType` and
`confidentMatchXref` to decide whether the lookup resolved one person.
`maxResults` changes only the returned comparison-list length, never recall,
ranking, or confidence classification.

`apply_changeset` is the only tool that writes to the file, and it applies
the same numbered JSON changeset you'd review by hand — an agent proposing a
change still writes a changeset for you to see, not a second, unreviewed
path to your data; `apply_changeset` is how that reviewed changeset gets
applied without leaving the c