family-tree-mcp
# Family Tree
Self-hosted, private family trees with graph/list views, photos, search, relationship comparison, sharing and GEDCOM import/export. Public code; private family data.
## Host your own
One application, two deployments. Follow [setup & recovery](docs/operations.md).
| | [Docker](docs/operations.md#docker) | [Cloudflare](docs/operations.md#cloudflare) |
|---|---|---|
| Runtime | Node.js + SQLite + private files | Workers + D1 + private R2 |
| Configuration | `.env.example` → `.env` | `web/installation.example.json` → `web/installation.json` |
| Cost | Your hardware/hosting | Free within Cloudflare usage limits |
Visitors enter a shared family password. Approved editors and the configured owner sign in with Google. Access covers every tree in the installation; share links never bypass it.
| Role | Permissions |
|---|---|
| Viewer | Browse, suggest changes, add/replace photos |
| Editor | Also edit people/relationships, review suggestions, clear photos |
| Owner | Also manage trees/access/settings, import, delete people, export backups |
## Optional MCP
Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/). Create a token under **Agent access**, then configure your MCP client to run `uv run family-tree-mcp` with:
| Environment | Value |
|---|---|
| `FAMILY_TREE_URL` | App URL including base path, e.g. `https://family.example.com/family-tree` |
| `FAMILY_TREE_TOKEN` | Owner-issued token, stored in client secrets |
Works with either host; edits save directly. Search before adding people and reuse their IDs across trees.
## Develop
Node.js 26.12.1+, pnpm 12.15.0; Docker for production-image tests.
```sh
pnpm --dir web install --frozen-lockfile
pnpm --dir web build
pnpm --dir web dev
```
Open **http://localhost:8000/family-tree/**; password: `local-preview-only`. The preview starts empty and stores data separately; screenshot demo data is not included.
Editing requires [Google sign-in setup](docs/operations.md#google-and-first-sign-in): `GOOGLE_CLIENT_ID`, `OWNER_EMAIL` and an authorized localhost origin.
[Checks & code map](AGENTS.md) · [Operations](docs/operations.md) · [Architecture](docs/private-hosting/adr-002-two-deployments-one-application.md) · [MIT](LICENSE) · [ELK.js](web/ui/vendor/README.md) · [Geist (OFL)](https://github.com/vercel/geist-font/blob/main/OFL.txt)
TDQS
Scored across 22 tools
Most tools target clearly distinct resources and actions, with explicit guidance separating overlapping areas such as remove_person vs. set_tree_members(remove=True), add_people vs. update_people, and publish_site vs. export_website. There are still several adjacent people/tree/website operations that an agent must parse carefully, but the descriptions generally resolve the boundaries.
Tool names follow a consistent verb_noun convention throughout: configure_website, create_tree, rename_tree, add_people, update_people, merge_people, find_people, get_relationship, export_website, and so on. The only minor deviation is the bare 'undo', but it is still a clear action name within an otherwise predictable pattern.
At 22 tools, the surface is heavy for a family-tree server, even though the tools cover several coherent subdomains: trees, people, relationships, website publishing, and review checks. Most tools earn their place, but the overall count sits in the borderline-heavy range and could likely be consolidated.
The core lifecycle is well covered: tree CRUD, people add/update/remove/merge/find/get, relationship queries, global undo, website configure/publish/export, and review checks. Minor gaps remain around backup/restore management, editing tree descriptions, and unpublishing an already published website, but these are not fatal to the main workflows.