Gramps Evidence

gramps-evidence-mcp

AI アシスタントにGramps の家系図への読み書きアクセスを提供し、レガシー GEDCOM エクスポートに対する**読み取り専用の「参照レイヤー」**も備えた MCP サーバーです。

証拠を重視して設計された 97 個のツール。 家系図の操作を任されたアシスタントは、もっともらしい先祖を喜んで作り出してしまう、というのがこのプロジェクトの前提です。そのため、ここではすべての主張に出典が付くよう、書き込み処理を設計しています。事実は引用を添えて作成され、uncite は引用がなくなったデータを削除します。また、親子関係のリンクは引用を個別に付けます。1 つの引用オブジェクトでは 2 つの確信度を保持できないためです。さらに、list_unsourced_facts、get_backlinks、find_duplicates と、query_objects および query_records によるサーバー側クエリからなる監査ツール群を用意し、この規律が守られていない箇所を見つけられるようにしています。

レガシーの家系図（Ancestry / FamilySearch のエクスポート）は、真実の根拠ではなく、信頼できないヒントとして読み取り専用の参照レイヤーを通じて参照します。

このサーバーは **Gramps Web の REST クライアント（gramps-webapi）**です。Gramps のデータベースファイルに直接触れることはありません。詳しくは接続方法をご覧ください。

存命人物のプライバシーフィルタリングはデフォルトで有効です。詳しくはプライバシーをご覧ください。

これは独立したプロジェクトです。Gramps プロジェクトによって作成、承認、サポートされたものではありません。

---

目次

• 接続方法
• セットアップ
• 設定
• クライアントの設定
• リモートアクセス（Claude Web / モバイル）
• 証拠モデルとトランザクション
• プライバシー
• ツールリファレンス
• ドキュメントの読み取り：ocr_media
• 参照レイヤー（レガシー GEDCOM）
• 実例
• 開発
• 制限事項
• リポジトリの構成

---

接続方法

このサーバーは HTTP で gramps-webapi と通信し、Gramps のデータベースファイルを開くことはありません。API サーバーがデータベースを単独で管理するため、このサーバーと Gramps Web のフロントエンドは、デスクトップアプリの排他的ロックを取り合うことなく、どちらも書き込みを行えます。このパッケージは gramps.gen.* モジュールをインポートせず、sys.path の調整も必要ありません。

注意点が 1 つあります。並行して使うとは、Gramps Web のフロントエンドとこのサーバーの両方が同じ gramps-webapi と通信することを意味します。Gramps のデスクトップアプリから、gramps-webapi が提供しているものと同じデータベースファイルを指すことではありません。それをすると、再び 2 つの書き込み元が競合する問題が発生します。Gramps Web の家系図を信頼できる情報源として扱い、デスクトップアプリとの間ではエクスポート／インポートでデータをやり取りしてください。

各レイヤーの詳細については、docs/ARCHITECTURE.mdをご覧ください。

---

セットアップ

稼働中の Gramps Web インスタンスと、サーバーの実行に必要な uv が必要です。

オプション A — すでに Gramps Web を実行している場合

アクセス可能な場所ですでに Gramps Web が稼働している場合、同梱の docker-compose は必要ありません。MCP の接続先を指定するだけです。

1. API のベース URL を確認します。例：http://gramps.example.org:5000。REST API は …/api 以下にあります。
2. エディターロール以上の権限を持つ専用 MCP ユーザーを作成します（書き込みにはエディター権限が必要です。オーナー権限でも構いません）。Gramps Web ホスト／コンテナー上のシェルから実行します。

   gramps-web user add mcp 'A_STRONG_PASSWORD' --fullname 'MCP client' --role 3
   

   （公式イメージではラッパーは gramps-web です。基盤となるコマンドは python3 -m gramps_webapi user add … です。）
3. URL と認証情報を環境変数に設定します（設定をご覧ください）。

オプション B — 同梱の compose を使って Gramps Web をローカルで実行する

すぐに使えるスタックが docker/docker-compose.yml にあります： SQLite バックエンド、バインドマウントされたデータディレクトリとメディアディレクトリ（ほかのディレクトリと同様にコピーやバックアップができる通常のディレクトリツリー）、ホストポート 5555 → コンテナ 5000 です。macOS では AirPlay Receiver が 5000 を使用するため、ポート 5555 を使います。

docker compose -f docker/docker-compose.yml up -d

次に、最初の所有者（http://localhost:5555 のブラウザーウィザード、または CLI）と、専用のMCP エディターユーザーを作成します：

docker compose -f docker/docker-compose.yml exec grampsweb \
    gramps-web user add owner 'OWNER_PW' --fullname 'Owner' --role 4
docker compose -f docker/docker-compose.yml exec grampsweb \
    gramps-web user add mcp 'MCP_PW' --fullname 'MCP client' --role 3

GRAMPSWEB_TREE で指定されたツリー（デフォルトは MyTree）は、初回起動時に作成されます。

MCP サーバーをインストールする

uvx gramps-evidence-mcp

これにより、MCP クライアントがサーバーを起動する方法である stdio 経由でサーバーが実行されます。通常は自分で実行するのではなく、クライアントの設定（以下を参照）に記述します。

---

設定

シークレットは環境変数に、それ以外はすべて TOML ファイルに保存します。 そのため、TOML ファイルに認証情報が含まれることはありません。

環境変数

クライアントの設定、またはサーバーの起動ディレクトリにある .env ファイル（.env.example を参照）に設定します。環境変数はファイルの設定より優先されます。

変数	意味
GRAMPS_MCP_API_URL	gramps-webapi のベース URL。例：http://gramps.example.org:5000
GRAMPS_MCP_USERNAME	専用の MCP ユーザー
GRAMPS_MCP_PASSWORD	そのユーザーのパスワード
GRAMPS_MCP_CONFIG	TOML 設定ファイルのパス（デフォルトは ./gramps_mcp.toml。作業ディレクトリを基準とします）
GRAMPS_MCP_EXPOSE_PRIVATE	TOML の expose_private フラグを上書きします
GRAMPS_MCP_TRANSPORT	stdio（デフォルト）または http — リモートアクセスを参照してください
GRAMPS_MCP_HOST、GRAMPS_MCP_PORT	http の待ち受け先（デフォルトは 127.0.0.1:8090）
GRAMPS_MCP_TRANSKRIBUS_USERNAME、GRAMPS_MCP_TRANSKRIBUS_PASSWORD	任意。ocr_media の手書き文字認識ルートで使用する Transkribus アカウント（Scholar プラン以上）。両方を設定するか、どちらも設定しないでください。ドキュメントの読み取りを参照してください
GRAMPS_MCP_TRANSKRIBUS_PAGE_BUDGET	呼び出し元が spend_credits を指定しなくても、ocr_media が Transkribus に送信できる暦月あたりのページ数。デフォルトは 0 で、すべてのページで確認を求めます
GRAMPS_MCP_TRANSKRIBUS_API_URL	Transkribus の処理 API（デフォルトは https://transkribus.eu/processing/v1、Metagrapho v1）

TOML ファイル（gramps_mcp.example.toml を参照）

[server]
expose_private = false          # see Privacy below

[[reference]]
path  = "~/gedcoms/export_one.ged"
label = "Ancestry (one branch)"
trust = "User-built; many hints unsourced. Verify everything."

デスクトップクライアントは独自に選んだディレクトリでサーバーを起動するため、GRAMPS_MCP_CONFIG には絶対パスを指定してください。

---

クライアントの設定

Claude Desktop — claude_desktop_config.json（macOS の場合は ~/Library/Application Support/Claude/）に追加します：

{
  "mcpServers": {
    "gramps": {
      "command": "uvx",
      "args": ["gramps-evidence-mcp"],
      "env": {
        "GRAMPS_MCP_API_URL": "http://gramps.example.org:5000",
        "GRAMPS_MCP_USERNAME": "mcp",
        "GRAMPS_MCP_PASSWORD": "MCP_PW",
        "GRAMPS_MCP_CONFIG": "/path/to/gramps_mcp.toml"
      }
    }
  }
}

Claude Code：

claude mcp add gramps \
    -e GRAMPS_MCP_API_URL=http://gramps.example.org:5000 \
    -e GRAMPS_MCP_USERNAME=mcp -e GRAMPS_MCP_PASSWORD=MCP_PW \
    -e GRAMPS_MCP_CONFIG=/path/to/gramps_mcp.toml \
    -- uvx gramps-evidence-mcp

stdio サーバーを起動するほかの MCP クライアントも同様に動作します。コマンドは uvx gramps-evidence-mcp で、上記の変数を環境に設定します。設定を編集した後は、クライアントを再起動してください。

クローンから実行する場合は、uvx gramps-evidence-mcp を uv --directory /path/to/gramps-evidence-mcp run gramps-evidence-mcp に置き換えてください。

---

リモートアクセス（Claude Web／モバイル）

上記の設定ではstdioトランスポートを使用します。クライアントがサーバーをローカルのサブプロセスとして起動します。Claude Web（claude.ai）とモバイルアプリではこれができません。Streamable HTTPトランスポートを使ってHTTPS 経由でリモートサーバーに接続し、カスタムコネクタとして追加します。計画時に考慮すべき違いは 3 つあります。

1. トランスポートは stdio ではなく HTTP である必要があります。
2. 到達可能性 — Anthropic のサーバーからお使いのサーバーにアウトバウンド接続するため、パブリックな HTTPS URLが必要です。http://192.168.1.50:5000のような LAN アドレスは使えません。
3. 認証 — 生存する親族のデータベースへの書き込みアクセスとなるため、認証で保護する必要があります。サーバー自体には認証機能がありません。認証なしで公開しないでください。

ブラウザーやスマートフォンからのアクセスが特に必要でない場合、デスクトップクライアントなら、このサーバーをローカルで動作させたまま同じモデルを利用できます（stdio、パブリックに公開する必要はありません）。以下の手順は、実際にリモートアクセスが必要な場合に限ります。

1. HTTP 経由で提供する

GRAMPS_MCP_TRANSPORT=http uvx gramps-evidence-mcp

これにより、MCP エンドポイントがhttp://127.0.0.1:8090/mcpで提供されます。GRAMPS_MCP_HOSTとGRAMPS_MCP_PORTで接続先を変更できます。その他のGRAMPS_MCP_*変数はこれまでどおり適用されます。

ループバックアドレスにバインドすると、サーバーが受け付けるのはHostがlocalhostまたは127.0.0.1のリクエストに限られます。これは、DNS リバインディングを防ぐ MCP SDK の保護機能によるものです。そのため、同じマシン上のトンネルまたはプロキシはHost: localhostを送信する必要があります（cloudflared ではhttpHostHeader設定によりこれが実現されます）。コンテナー内では、以下のように0.0.0.0にバインドし、コンテナーネットワークで分離してください。

2. Gramps Web の隣にデプロイする

Gramps Web と同じホスト上のコンテナーで実行し、内部ネットワーク経由で API と通信させます。最小限のDockerfileは次のとおりです。

FROM python:3.13-slim
RUN pip install uv
ENV GRAMPS_MCP_TRANSPORT=http GRAMPS_MCP_HOST=0.0.0.0 GRAMPS_MCP_PORT=8090
EXPOSE 8090
CMD ["uvx", "gramps-evidence-mcp"]

Gramps Web の compose に追加し（同じネットワークを使用）、サービス名で API を指定して、環境変数からシークレットを読み込みます。

  gramps_evidence_mcp:
    build: /path/to/dockerfile-dir
    restart: unless-stopped
    environment:
      GRAMPS_MCP_API_URL: "http://grampsweb:5000"   # internal service name
      GRAMPS_MCP_USERNAME: "mcp"
      GRAMPS_MCP_PASSWORD: "${MCP_PW}"
    # no host port needed if the tunnel (below) runs in the same compose network

3. TLS を使ってパブリックに公開する

リバーストンネルを使えば、ポートフォワーディングを避けながら、TLS と安定したホスト名を利用できます。以下はいずれも使用できます。

• Cloudflare Tunnel — cloudflaredをサーバーと並行して実行し、https://gramps-mcp.example.orgのようなホスト名をhttp://gramps_evidence_mcp:8090にルーティングします。
• Tailscale Funnel — 独自の tailnet を経由するパブリックな HTTPS です。
• 手早く使い捨てのテストをする場合はngrok http 8090を実行します。

または、ポート 8090 の前段に任意のリバースプロキシを置いて、ご自身で TLS を終端してください。

4. 認証を設定する

claude.ai のカスタムコネクタは、MCP のOAuth 2.0フローを使用します。トンネルのホスト名の前段にアイデンティティプロキシを配置してください。Cloudflare Access、Authelia、oauth2-proxy などは、いずれもコネクタが必要とする OAuth フローに連携できます。サーバー自体は呼び出し元を認証しません。詳しくはdocs/ROADMAP.mdを参照してください。

5. claude.ai でコネクタを追加する

設定 → コネクタ → カスタムコネクタを追加 →https://gramps-mcp.example.org/mcpを貼り付け、認証プロンプトを完了すると、チャットに 97 個のツールが表示されます。（カスタムコネクタには有料の Claude プランが必要です。Team／Enterprise では、管理者による有効化が必要な場合があります。）

セキュリティに関する注意: このエンドポイントでは、生存する人物を含む家系図のレコードを作成、編集、削除できます。認証で保護し、公開ポートよりプライベートトンネルを優先してください。リモートでの参照だけが必要な場合は、Gramps Web の読み取り専用ロールを持つユーザーの使用を検討してください。その場合、サーバーの書き込みツールは書き込みを行わず、権限エラーになります。

---

エビデンスモデルとトランザクション

サーバーは Gramps のエビデンスモデルを適用します。

Repository  →  Source  →  Citation  →  fact (Event / Attribute)

**事実を記録する書き込みには、すべて引用が必要です。**既存の引用／出典を参照するか、その場で作成します。引用なしで事実を記録するには、require_citation=False を明示的に渡す必要があります。この場合、イベントに UNSOURCED=true 属性が付与され、後から list_unsourced_facts で見つけられます。信頼度レベルは Gramps の 0～4 の尺度（very_low, low, normal, high, very_high）に対応します。

**タイプ名には Gramps 独自の名前を使います。**Gramps は、正確には認識できないタイプ名（"birth"、"Web Home Page" など）を、意図されていた標準タイプの隣に新しいカスタムタイプとして保存し、ツリーの語彙に永久に保持します。そのため、書き込みのたびに、まずタイプ名を照合します。大文字と小文字、句読点を無視して、Gramps の標準名とツリーのカスタム名を照合し、次に曖昧さのないいくつかの同義語（「Born」は Birth、「microfilm」は Film）を照合します。それでも一致する名前がない場合は、最も近い名前を提示して拒否します。新しいカスタムタイプを作成する場合（「Territory」の場所に対する「Land Grant」など）は、allow_new_type を指定します。詳しくは docs/PITFALLS.md のセクション 26 を参照してください。

書き込みと DbTxn トランザクションの対応

gramps-webapi は、オブジェクトの作成／更新をそれぞれ独自のサーバー側 DbTxn（New Person、Edit Event などのラベル付き）でラップします。そのため、すべての書き込みが適切なトランザクションを経由し、Gramps の取り消し履歴に保持されます。複合操作（引用付きの出生を伴う add_person など）は、オブジェクト書き込みを順序どおりに実行することで行われます。具体的には、出典 → 引用 → イベント → 人物の順に処理しながら、参照を関連付けます。

設計上の注記（文書化された逸脱）：gramps-webapi には、複数のオブジェクトをまとめて、カスタムの説明を付けた単一の DbTxn にできる、生の POST /api/transactions/ エンドポイントもあります。このエンドポイントは、（a）handle と gramps_id を自動割り当てし、（b）英語のタイプ文字列（"Birth"）を Gramps 内部のタイプ辞書に変換するサーバー側ヘルパーを迂回するため、意図的に使用しません。これを使うと、このクライアントで Gramps の ID 割り当てとタイプの内部処理を再実装し、さらに gramps_id を独自に生成する必要が生じ、ID カウンターの同期がずれるおそれがあります。オブジェクトごとのトランザクション方式のほうが安全で、取り消し履歴の一貫性も保たれます。一方で、論理上は 1 回の追加操作が、取り消し履歴では 1 件ではなく複数件として表示されます。

---

プライバシー

ツリーには存命の人物が含まれています。expose_private = false（デフォルト）の場合、一括出力では非公開または存命の可能性が高い人物が除外されます。

• 存命の可能性が高いとは、記録された死亡がなく、出生から 110 年未満であることを意味します。出生も死亡も記録されていない場合も、プライバシーを優先して該当します。日付がなくても、死亡イベントがあれば死亡は記録済みとして扱われます。110 年は系譜学で慣例的に使われる「死亡と推定される」境界であり、明らかに歴史上の人物を永久に非表示にするものではありません。
• 非公開とは、種類を問わず、レコードに Gramps の非公開フラグが設定されていることを意味します。

各ツールでの具体的な扱いは次のとおりです。

出力	非公開または存命の可能性がある人物…
search_people、get_ancestors、get_descendants、query_objects、query_records	…は伏せ字のスタブとして表示されます。ID のみで、名前や事実は含まれないため、意図的に取得することはできます。query_records の家族行は、両親に基づいて判定されます。
ツリー全体を対象とする list_unsourced_facts	…の事実は省かれて件数に含まれ、スタブとして一度だけ表示されます。
find_duplicates	…は省かれます。同姓同名のグループは、存命ではない人物が 2 人残っている場合にのみ報告されます。
get_timeline、consolidated_timeline	…は親族として含められる場合、そのイベントが省かれて件数に含まれます。指定した人物は表示されます。家族のメンバー自身も親族と同様に判定されるため、存命の夫婦の家族タイムラインは空になります。
get_facts	…は、サーバーが処理を計算する前に除外されます。
run_report	…は、該当するオプションを持つレポートから省かれます。Gramps の 25 件のレポートのうち 21 件には living_people があり、24 件には incl_private があります。どちらかを渡さない限り、これらには false が渡されます。Gramps 自体のデフォルトでは両方が有効です。結果の privacy_options に適用された設定が表示されます。
consult_reference	…は一致結果から省かれ、件数に含まれます。Ancestry などのサイトからのエクスポートでは、誰も非公開になりません。
check_family_links	…で見つかったリンクの問題は省かれ、件数に含まれます。

ID による検索はフィルタリングされません。 get_person、get_object、その他の型指定されたゲッター、および特定の人物を指定した list_unsourced_facts は、すべての情報を返します。これは、ツリーの所有者が自分のデータを対象に実行する個人用ツールです。目的は、検索結果の一括取得、ツリーの走査、レポートの共有による意図しない大規模な情報漏えいを防ぐことであり、所有者が自分のデータにアクセスできないようにすることではありません。ID を指定して 1 件のレコードを要求するのは、意図的な操作です。

書き込みはフィルタリングされません。 存命の人物や非公開の人物に対する追加、引用、編集、統合、削除も、他の人物と同様に実行できます。

依頼すれば、1 回の呼び出しで全員が表示されます。 表内の各ツールは include_private を受け取ります。true を渡すと、その呼び出しでは存命の人物、非公開レコード、Gramps 独自のレポートのデフォルト設定を含むすべての情報が返され、次の呼び出しでは再びフィルタリングされます。これは、「1950 年以降に生まれた自分のいとこを一覧表示して」のように、存命の親族を名前で尋ねる場合を想定したものです。ツールの説明でも、そのようにアシスタントに伝えています。各使用は、レコードではなくツール名とともに記録されます。

設計上または制限上、フィルタリングされないもの：

• export_backup はデータを損失なくバックアップするためのものです。存命の人物を除外するバックアップでは、ツリーを復元できません。
• verify_tree は、Gramps 独自の調査結果をそのまま返します。
• get_dna_matches は指定した人物について回答しますが、それぞれの一致相手も別の人物であり、通常は存命の人物です。相手はハンドルで特定され、セグメントデータも返されます。
• イベント、引用、メモ、メディアは、それぞれ自身の非公開フラグのみで判定されます。イベント行には人物へのリンクが含まれないため、イベント自体が非公開でない限り、存命の人物の出生イベントもイベント検索で表示されます。
• list_research_tasks はタスク自体の非公開フラグで判定し、その説明はメモのフラグで判定します。タスクのタイトルに存命の人物の名前が含まれる場合があります。そのようなタスクは非公開にしてください。
• タイムラインのエントリは人物に基づいて判定されます。イベント自体の非公開フラグはタイムラインのエンドポイントから報告されません。
• ocr_media は、ID による検索と同様に、指定したメディアオブジェクトを読み取ります。非公開かどうかは問いません。非公開のメディアが Transkribus などの第三者に送信されることはありません。ただし、存命の人物の記録が公開画像であれば送信されるため、そのような記録は非公開にしてください。
• スタブでも、レコードが一致したことはわかります。名前と生年を指定した検索でスタブが返された場合、その ID の人物が両方の条件に合致することが確認できます。このフィルターは意図しない情報開示を防ぐものであり、執拗な検索を防ぐものではありません。

すべての呼び出しでフィルターを無効にするには、TOML ファイルで expose_private = true を設定するか、クライアントの設定で GRAMPS_MCP_EXPOSE_PRIVATE=true を設定します。すべてを監査する場合や、存命の人物がいないツリーの場合に使用します。これにより、アシスタントが読み取るすべての情報に対するプライバシー保護が弱まります。 ログに記録内容が含まれることはありません。記録されるのはハンドル、ID、操作名のみです。 リクエスト URL もログには残りません。クエリフィルターが URL に含まれるためです。

---

ツールリファレンス

97 個のツール。 ツリーを変更するすべてのツールは、PUT でオブジェクト全体を書き戻す前に再取得します。編集には service._mutate() を使用します。keys= の落とし穴を参照してください。

すべてのツールは MCP アノテーションを宣言しており、読み取りのみ、追加、変更と削除のいずれを行うかが示されています。そのため、クライアントは読み取りを自動的に承認し、それ以外の操作の前に確認を求めることができます。 45 個のツールは読み取りのみを行います。ocr_media は読み取りを行いますが、読み取り専用でもクローズドワールドでもないものとしてアノテーションされています。米国議会図書館と Internet Archive から取得を行い、Transkribus のクレジットを消費し、書き起こしのノートを保存する場合があります。

不明なパラメーターは拒否されます。 スペルを間違えた引数や、存在しない引数を指定すると、そのツールが受け付けるパラメーターの一覧を示すエラーになります。以前は query_objects(query=...)（正しいパラメーター名は gql）がフィルターなしで最初の 200 個のオブジェクトを一覧表示していましたが、そのように黙って無視されることはありません。

作成

ツール	目的
add_person	人物を作成します。出典付きの出生・死亡イベントを任意で追加でき、各イベントの種類は省略できます。
add_family	親と子を関連付け、任意で出典付きの結婚イベントを追加します。子の各親との関係を指定できるため、同じ呼び出しで継子として登録できます。
add_event_to_person	出典付きのイベント（居住、国勢調査、職業など）を人物に追加します。
add_event_to_family	日付や場所のあるイベント（結婚、離婚など）を家族に追加します。
add_child_to_family	既存の人物を既存の家族の子として追加します。
add_event_ref	既存のイベントを役割（証人、情報提供者、代父母など）とともに別の人物と共有します。国勢調査の記録または埋葬記録を 1 件、出典情報を 1 セットとして共有します。その人物固有の情報（記録用紙上の記載、年齢など）は、参照に属性（As enumerated、Age）として追加します。
add_alternate_name	出典付きの別名（別名、結婚後の姓、愛称）を人物に追加します。
add_source	出典（記録群、書籍、証明書）を作成します。任意でリポジトリに登録できます。
add_citation	出典に関連付けた単独の引用を作成または再利用します。
add_repository	リポジトリ（公文書館、図書館、墓地、ウェブサイト）を作成します。
add_place	イベントで名前を指定した副作用として場所を作成するのではなく、種類と親を明示して場所を作成します。
add_note	ノートを作成し、任意でオブジェクトに添付します。対象を再読み込みし、添付を確認できない場合は、添付したと主張せず verified: false を返します。1 回の呼び出しで長さに制限なく指定できます。サーバーエラーには何かが書き込まれたかどうかが示され、添付に失敗した場合は新しいノートを取り消します。
add_media	画像、PDF、音声、動画ファイルを、単独の Media オブジェクトとしてアップロードします。md5 が一致するファイルは再利用します。
attach_media	ファイル（アップロードを含む）または既存の Media オブジェクトを、オブジェクトにリンクします。
add_attribute	型付きのキーと値の属性を追加します（オブジェクトには Attribute、出典・引用には SrcAttribute）。
add_url	人物、場所、リポジトリにウェブ URL を追加します。
add_dna_match	DNA マッチを証拠として記録します。Gramps Web の保存形式に従って保存し、マッチを検出した検査に引用を付けます。解析できないセグメントデータと、同じペアの 2 件目の記録は拒否します。

引用 — 主張に証拠を添付する

ツール	目的
cite_event	既存のイベントに引用を付けます。
cite_object	引用を持つあらゆるオブジェクトに引用を付けます。特に家族や、人物の名前（object_type="name"。主名または別名）が対象です。
cite_child_link	親子関係そのものに引用を付けます。1つの引用オブジェクトには異なる2つの信頼度を設定できないため、必ずリンク専用の引用を作成します。
uncite	引用を切り離し、孤立した場合は削除します。切り離しても削除しない方法では、孤立した残骸が2回発生しているため、必ず削除してください。メモまたは画像を保持する唯一の引用はそのまま残します。ただし、移動先の引用をcarry_toで指定した場合は除きます。

編集 — すでにある内容を修正する

ツール	目的
update_citation	ロケーター、信頼度、日付を更新するか、引用の参照先を別のソースに変更します。
update_citations	1 回の呼び出しで多数の引用を同様に更新します。一括処理です。expect_page_prefix は、一括処理の計画後にページが変更された行を上書きせずに報告します。
update_event	タイプ（ツリーの語彙と照合）、日付、場所、説明を、イベントの ID と紐づくすべての情報を維持したまま更新します。ソースに記載のない場所や日付はクリアします。
update_source	タイトル、著者、出版情報、略称を更新します。
update_media	説明、日付、パスを更新します。
update_person	性別、主名（データ入力ミスでない限り、以前の名前は別名として保持します。データ入力ミスの場合はその場で訂正し、理由をメモに記録します）、プライバシーフラグを更新します。
update_alternate_name	引用を維持したまま、別名をその場で訂正、再分類、または削除します。引用付きの名前は削除されません。
update_child_ref	父親または母親に対する子どもの続柄（実子、継子、養子など）を、リンクの引用と出生順を維持したままその場で更新します。
move_child	リンクの引用、メモ、プライバシーを維持し、出生順に配置したまま、子どもを別の家族に移します。古い家族へのリンクはすべて削除され、重複するリンクも削除されます。
set_family_parent	既存の家族の父親または母親を設定、（依頼された場合に）置換、または削除し、各人のリンクの両側を維持します。
update_event_ref	共有イベントに対する人物の参照をその場で更新します。役割、または名前で指定した属性セットを追加・削除し、引用を維持します。
update_attribute	人物、家族、イベント、メディアオブジェクト、ソース、引用の属性を 1 つだけ、その場で設定または削除し、引用を維持します。属性名で選択し、同じ名前が複数ある場合は値の一部も指定します。削除した属性の引用は明示されます。
update_object_fields	それ以外のオブジェクト（場所、メモ、リポジトリなど）のスカラー項目を更新します。構造を持つリストは拒否されます。
update_place	場所のタイプ、親の包含地名、名前、タイトル、座標を更新します。親はすでに存在している必要があります（名前から新規作成されることはありません）。循環参照は拒否され、複数の期間付きの包含地名は統合せずに拒否されます。
update_url	人物、場所、リポジトリにある既存の URL 項目を 1 つだけ編集または削除します。部分文字列で照合し、完全に 1 件に一致する必要があります。誤ったタイプに登録されたリンクを修正できます。
link_repository	既存のソースを既存のリポジトリに、請求記号と媒体を指定してリンクします。
link_repositories	1 回の呼び出しで多数のソースを同様にリンクし、各行の結果を報告します。
tag_object	名前付きタグをオブジェクトに付与します。タグが存在しない場合は作成します。
set_private	オブジェクトの Gramps プライベートフラグを設定または解除します。
merge_objects	サーバー独自のマージ処理を 1 つのトランザクション内で実行し、重複オブジェクトを統合します。デフォルトではドライランです。ドライランでは、Gramps がほかに統合するもの（人物の統合で 2 つの家族が、家族の統合で 2 人の父親が統合される場合など）と、拒否する処理が示されます。場所の場合は、両方の場所の親を残すのではなく、統合後に残す場所の包含地名を確定します。
detach_object	イベント、メディア、メモ、タグ、子ども、リポジトリの参照、または場所の追加の親を削除します。孤立した場合にオブジェクトを削除するよう指定することもできます。タグは名前で指定でき、リポジトリへのリンクは請求記号 1 件に絞り込めます。
delete_object	ハンドルまたは Gramps ID を指定してオブジェクトを完全に削除します。そのオブジェクトだけが保持しているメモや画像が孤立する場合、および引用が残っているソースの場合は拒否されます。

読み取り

ツール	用途
get_person	詳細情報：名前、すべての別名（引用数付き）、性別、イベント、属性（引用数付き）、家族、メディア。
get_family	関係、親、子、イベント数。
get_event	種類、日付（「1882」ではなく、「1882年から1883年の間」のような修飾語付き）、場所、説明、引用数。
get_source	タイトル、著者、出版情報、略称、および実際の引用数。
get_repository	名前、種類、URL、および所蔵する資料。
get_object	任意の種類の未加工レコード。保存されているレコードを返すため、編集時に必要な情報を取得できます。
get_place	名前、タイトル、種類、包含関係の連鎖、座標、URL。
get_citation	ページ、確度、日付、資料、および cited_by_count。ゼロの場合は参照されていない残骸を意味します。
get_note	種類と全文。メモには推論が記録されるため、省略されることはありません。
get_media	パス、MIME タイプ、チェックサム、および参照しているオブジェクトの数。
consolidated_timeline	複数の人物または家族のイベントをまとめたタイムライン。世帯が一緒に国勢調査の記録を移動していく様子を確認できます。
get_timeline	人物または家族のイベントを時系列で表示します。各イベントの年齢、引用数、最も高い確度に加え、uncited_count も含まれます。
get_relationship	2 人の関係を文章と世代数で示します。答えが一意でない家系図では all_paths を使用します。
assess_living	サーバー独自の存命・故人判定と親族の確認を行います。推定日付や推論を任意で含めることもできます。
event_span	2 つのイベント間の経過時間。あらゆるイベント時年齢の確認に使われる計算の根拠です。
get_facts	家系図全体、または人物 1 人の祖先・子孫を対象に、死亡時の最高齢、最年少の親、子どもの最多人数などの記録保持者を調べます。あり得ない記録保持者は、通常、データエラーです。
get_dna_matches	DNA マッチの合計および最大の共有センチモルガン数と、特定されている共通祖先を表示します。unattributed_count は未解決の調査事項です。
get_ydna	Y-DNA ハプログループを、最も広いクレードから末端クレードまで表示します。直接の父系のみを示します。
parse_dna_segments	貼り付けた共有セグメントデータをセグメントと合計値に解析します。共有 DNA がない場合と区別し、解析の失敗はそのように報告します。
get_researcher	研究者の詳細情報。すべてのエクスポートに含まれます。
list_reports	Gramps が生成できる 25 種類のレポート：アーヘンタフェル、子孫、家族グループ、親族関係、ファンチャートや関係図、統計、系統の終端。
get_report_options	1 つのレポートの既定オプション。レポートにはオプション全体の辞書を渡すため、上書き設定を統合する際の基準になります。
run_report	レポートを生成します。指定しない限り、存命の人物と非公開の記録は除外されます。
search_people	名前の部分一致と、任意の出生年範囲（プライバシーフィルター適用済み）。
get_ancestors / get_descendants	家系図を N 世代たどります（プライバシーフィルター適用済み）。
list_tags	すべてのタグと、ハンドル、名前、色。
list_object_types	書き込みツールで受け付ける種類名：Gramps の標準の種類と、家系図のカスタム種類。

監査

ツール	用途
query_objects	GrampsQL を使って、任意のコレクションをサーバー側でフィルタリングします。 監査の主力ツールです。構文上の注意点は以下をお読みください。
get_backlinks	このオブジェクトを参照しているものを確認します。「このソースは引用されているか」と尋ねる正しい方法はこれだけです。
find_duplicates	戦略に基づいて重複候補を見つけます：media_checksum、source_title、citation_page、vital_events、person_name。
list_unsourced_facts	引用のないイベント、または UNSOURCED とタグ付けされたイベントを表示します。
check_family_links	人物↔家族のリンクを双方向で確認します。同じ家族が二度記載されている、片側にリンクがない、存在しない対象へのリンクなどが対象です。各検出結果には修正方法が記載されます。
db_stats	人物／家族／イベント／引用などの件数を表示します。
query_records	構造化クエリエンジンです。 インデックス付きカラム、保存オブジェクト内の json_path、関係のたどり、正規表現／like／in、並べ替え、キーセットページングに対応します。イベントをタイプでフィルタリングする唯一の方法です。サーバーが誤って回答する形式（カラムとしての type、日付の year、in 以外とのリスト比較など）は拒否し、利用可能な方法を示します。
list_event_types	ツリーのイベントタイプの語彙と、保存されている整数値を表示します。ここに予期しない名前があれば、通常は Gramps がカスタムタイプとして受け入れた誤字です。
list_filter_rules	Gramps のフィルタールールの語彙（「子孫である」「共通の祖先がいる」など）を表示します。これらは GrampsQL でも query_records でも表現できません。
list_custom_filters	このインスタンスに保存されているフィルターを、名前で再利用できる形で表示します。
create_filter	これらのルールで作成した再利用可能な選択条件を保存します。
delete_filter	保存済みのフィルターを削除します。定義だけに作用します。
verify_tree	Gramps 独自の系譜上の妥当性チェックです。9歳の母親、120年続いた結婚、解析できない日付などを検出します。引用の一括調査とは別の監査です。
ocr_media	ドキュメント画像を、その内容に適したエンジンで読み取ります。印刷物には既存の OCR テキストまたは Tesseract、英語の手書き文字には画像そのもの、ドイツ語とノルウェー語の手書き文字には Transkribus、国勢調査表には FamilySearch の索引を使用します。これは調査の手がかりであり、証拠ではありません。引用する前に画像を読んでください。ドキュメントの読み取りを参照してください。

調査タスク — Gramps Web 独自のタスクリスト

ツール	用途
add_research_task	Gramps Web の「タスク」ビューにタスクを追加します。「新しいタスク」フォームと同じ形式で作成します。ToDo タグを付けたソースとし、Status および Priority のソース属性を設定して、説明を To Do ノートにします。
list_research_tasks	「タスク」ビューの順序でタスクを表示し、ステータス、優先度、タグ、属性、説明を含めます。ステータス、タグ、属性値で絞り込めます。非公開タスクは内容を伏せたスタブとして表示されます。
update_research_task	タスクのステータス、優先度、公開設定、属性を設定します。これらは以前の値に追加されるのではなく、常に置き換えられます。以前の値が残ると Gramps Web には表示されません。また、説明に段落を追加できます。非公開タスクの説明ノートも非公開です。タスクを公開にしても、private_note=false を指定しない限り、非公開ノートは非公開のままです。

ここで作成したタスクも Gramps Web で作成したタスクも同じものです。どちらも「タスク」ビューに表示され、デスクトップ版 Gramps ではノートを通じて To Do グランプレットに表示されます。タスクは To Do であり、証拠ではないため、引用されることはありません。これらは list_jobs が報告するバックグラウンドジョブとは異なります。

運用

ツール	目的
export_backup	新しいファイルに Gramps XML のツリー全体をエクスポートします。既存のファイルを置き換えることはありません。一括書き込みの前に必ず実行してください。
list_transactions	最近の書き込みの内容、日時、実行ユーザーを確認します。別のセッションが書き込み中かどうかを確認する方法でもあります。
undo_transaction	競合を確認してから、トランザクションを取り消します。デフォルトではドライランです。task_id を返します。
list_jobs	このツリーの最近のバックグラウンドジョブを、新しい順に表示します。
get_transaction	変更したオブジェクトを含め、1件のトランザクションの全内容を取得します。取り消す前に読み取ってください。
get_record_history	1件のレコードを誰がいつ追加、編集、削除したかを、それぞれの変更に紐づくトランザクションとともに確認します。削除済みのレコードはハンドルで指定します。field を指定すると、1つのフィールドの値が変更された書き込みに絞り、変更前後の値を表示します。gramps-webapi 3.21 では代わりにトランザクションログ全体を読み取るため、処理に時間がかかることも明記されます。
get_job	バックグラウンドジョブが完了したか、正常に動作したかを確認します。取り消し、検証、再インデックスはすべてワーカーに送られます。
reindex_search	Gramps Web の検索ボックスで使用される全文検索インデックスを再構築します。サーバーは書き込みのたびにインデックスを更新しますが、大規模なインポート後や、ツリーにある情報が検索で見つからない場合は再構築してください。

参照レイヤー（読み取り専用。ツリーには一切触れません）

ツール	目的
consult_reference	信頼できないヒントとして、レガシー GEDCOM エクスポートから人物を検索します。参照レイヤーを参照してください。

GrampsQL でのクエリ

query_objects は、コレクションを取得して Python で絞り込むのではなく、データベース内でフィルタリングします。この構文には注意が必要です。CI の各実行で gramps-webapi 3.21.1、3.22.3、3.23.1 を対象に検証されています。

• 等価演算子は単一の = です。page == "" は解析エラーになります。
• ~ は部分文字列を検索します。例：description ~ "1871"。
• .length は任意のリストで使用できます。例：media_list.length = 0。
• オブジェクトに存在しないフィールドは、エラーにならず何にも一致しません。 件数が 0 の場合、フィールド名のスペルミスが原因かもしれません。
• イベントでは type がこのようなフィールドにあたります。 type = "Birth" は、数百件の出生イベントがあるツリーでも、何にも一致せずに終了します。代わりに event_type を指定して query_records を使用してください。
• ソースには citation_list がありません。引用はソースを参照するものです。引用されていないソースを探すには get_backlinks を使用してください。ソースに対して citation_list をクエリしても、引用済みかどうかにかかわらず、何にも一致しません。
• ブール値は整数として比較されます。private = true ではなく、private = 1 を使用してください。
• リストはその項目を通じて検索します。 リスト自体に対する ~ は、値が項目そのものであるかを調べるため、urls ~ "http" は何にも一致しません。query_objects はこの形式を拒否し、使用できる形式を示します。.any.（または .all.）で項目にアクセスし、get_<type> でハンドルをたどります。
• 条件ごとにコレクション全体をオブジェクト単位で読み取るため、GrampsQL の読み取りには 120 秒が許可されています。6,000 件を超える引用を対象にしたリスト条件の OR クエリには 29 秒かかりました。

便利なクエリ：

citations   confidence >= 3 AND page = ""                high-confidence claims with no locator
sources     media_list.length = 0                        documents with no image attached
media       desc = ""                                    media nothing identifies
person      urls.any.path ~ "findagrave"                 a URL anywhere among a person's links
citation    note_list.any.get_note.text.string ~ "x"     a citation whose note mentions x

各ツールには、使用するタイミング、パラメーターの意味、適切な引用方法を説明する、LLM 向けの docstring があります。

---

ドキュメントの読み取り：ocr_media

Gramps Web 独自の OCR は、印刷物を読み取る Tesseract です。家族史を左右する文書は、遺言書、権利証書、手紙、クレント文字で書かれたドイツの教会記録、ノルウェーの教区記録などの手書き文書です。どの読み取りツールが適切かは、筆跡と言語によって異なります。ocr_media は、呼び出し元が指定した文書の種類（doc_type）と言語（lang）に応じて処理を振り分けます。

文書	読み取り方法	理由
print	メディアにすでに含まれているテキスト（Transcript メモ、PDF のテキストレイヤーなど）、またはソース内で URL が指定されているページについては、米国議会図書館または Internet Archive の OCR。それ以外の場合は、Gramps Web 経由で Tesseract	既存のテキストなら費用はかかりません。Tesseract は印刷文字の読み取りに優れています
hand、英語	呼び出し元のモデルに対し、「外交的翻刻」を指示したうえで、MCP の画像コンテンツとして返される画像。綴りは原文どおりにし、改行と略語を保持し、不確かな箇所には [?] を付けます。second_witness を指定すると Transkribus も追加され、2つの読み取り結果が異なる名前と数字をすべて示すよう求めます	視覚モデルは18世紀および19世紀の英語の筆記体を、文字誤り率5.7～7％で読み取ります。これは専用エンジンより優れています（Humphries et al.）
hand、ドイツ語	Transkribus のみ（ドイツ語 Kurrent モデルを使用）。Transkribus がない場合は拒否します。依頼された場合でも視覚モデルによる読み取りは行わず、ドイツ語の表や巻物も対象外です	視覚モデルの歴史的なドイツ語の文字誤り率は 48.8％ です（METATR、2026年5月、READ-2016）
hand、ノルウェー語	Transkribus（NorHand 1820–1940）と照合用の画像。Transkribus がない場合は、画像と誤り率に関する警告を返します	視覚モデルのノルウェー語の文字誤り率は約10％です（METATR、NorHand）
hand、その他の言語	Transkribus の汎用モデル（Text Titan II）と画像。利用できない場合は、画像と警告を返します	視覚モデルによる読み取りについて、既知のベンチマークはありません
table	読み取りません。FamilySearch のインデックス（familysearch-mcp の get_records_on_image）を使用します	エンジンは行を横断して読み取り、どのセルがどの人物に対応するかを見失います
volume	まず FamilySearch Full-Text Search を使い、その後 Transkribus でページごとに読み取ります	巻物は読み取るより検索するほうが効果的です

engine は、単一の読み取り方法として existing、tesseract、vision（ドイツ語の筆記体では拒否）または transkribus を明示的に指定します。返される画像は、現在の Claude モデルが再拡大せずに読み取れるサイズに調整されます（長辺2576ピクセル、3.75メガピクセル）。パーセント指定の region=[x1, y1, x2, y2] を使うと、ページの一部を最大限の詳細度で返します。PDF はページごとに（page）読み取ります。テキストレイヤーと、ページに埋め込まれたスキャン画像を使います。スキャン画像のないページは Gramps Web でレンダリングしますが、レンダリングされるのは最初のページだけです。

すべての結果には出典情報 — {engine, model, date} — と、同じ注意書きが含まれます。文字起こしは証拠そのものではありません。引用元は画像のままです。 store=true を指定すると、機械読み取り結果をメディアオブジェクトの Transcript メモとして保存します。メモにはエンジン、モデル、日付を記載し、ジョブの1日後に Transkribus が削除するため、Transkribus の PAGE XML は2つ目の整形済みメモとして保存します。視覚モデルによる読み取り結果は、呼び出し元のモデルが add_note で保存します。後から print を指定して呼び出すと、保存済みの読み取り結果が見つかった場合は再読み取りせずに返します。

Transkribus は任意で、利用には料金がかかります。 API ジョブの料金はアプリ料金の半額で、1ページあたり約0.5クレジット、約€0.12です。そのため、spend_credits=true を指定するか、今月の GRAMPS_MCP_TRANSKRIBUS_PAGE_BUDGET に余裕がある場合に限り、ページを送信します。各結果には、使用したクレジット数と今月の利用ページ数が記載されます。利用数はキャッシュディレクトリの transkribus-usage.json に保存されます。ページは送信前にカウントされ、カウントできない場合は送信されません。同じファイル、ページ、モデルに対する1日以内のジョブは再取得され、再課金されません。失敗したジョブは破棄されるため、次の呼び出しで新たに試行できます。非公開のメディアオブジェクトや、ここで対応しているモデルがない言語のページは送信されません。画像はオーストリアの READ-COOP に送信されます。同社のドキュメントによると、画像はジョブのためだけに使用され、保存されません。また、利用規約では、送信された素材を製品の改善に使用できるとされています。 Transkribus の経路は公開済み API に合わせて構築されており、実環境ではまだ動作確認されていません。 Metagrapho v1 の OpenAPI ドキュメントと、READ-COOP が文書化しているログイン手順に従っており、これらの形式に沿ったフィクスチャを使ってテストしています。構築にアカウントは使用していません。Library of Congress と Internet Archive の経路、画像と PDF の処理、タスクキュー経由の Tesseract は、2026-10-06 に実際のツリーとアーカイブで確認しました。

---

参照レイヤー（レガシー GEDCOM）

consult_reference は TOML 設定に記載された GEDCOM ファイルを検索し、ファイルごとに、一致する個人と、その個人について主張されている事実を返します。重要なのは、各事実にレガシーツリーが出典を付けているかどうかがフラグで示され、出典テキストがあればそれも返される点です。これにより、アシスタントは「Ancestry は実際の死亡証明書を出典としている」と「出典のない推測」を区別できます。

• GEDCOM 5.5.1 を解析します。Ancestry の方言（_APID、_TREE、…）にも対応しています。カスタムのアンダースコア付きタグも保持され、解析時にエラーになりません。
• ファイルは遅延読み込みされ、解析済みの形式はディスクにキャッシュされます（パス／サイズ／mtime をキーとして使用するため、大きなエクスポートも一度だけ解析されます）。
• 各ファイルには、結果に表示される信頼性に関する注記があります。

これらは信頼できないヒントです。想定される手順は、ヒントを参照する → 探すべき実際の記録を判断する → その記録を出典としてツリーに事実を作成する、というものです。ヒントを出典付きの情報であるかのように転記してはいけません。

実際の GEDCOM はコミットされません（.gitignore により、合成テスト用フィクスチャを除く *.ged は除外されます）。

---

使用例：出典を付けた出生記録のある人物

あなた： マーサ・エラリーを追加してください。女性で、1890年1月12日にオハイオ州コロンバスで生まれました。出生証明書（オハイオ州の証明書番号 #12345）を持っています。確信度は非常に高いとして出典を付けてください。

アシスタントは1つのツールを呼び出します。

add_person({
  "given": "Martha", "surname": "Ellery", "gender": "female",
  "birth": {
    "type": "Birth",
    "date": "12 Jan 1890",
    "place": "Columbus, Ohio, USA",
    "citation": {
      "source_title": "Ohio Birth Certificate #12345",
      "page": "certificate no. 12345",
      "confidence": "very_high"
    }
  }
})

サーバーは内部で、Source「Ohio Birth Certificate #12345」を作成 → それに Citation（ページ番号と非常に高い確信度を含む）を作成 → Place「Columbus, Ohio, USA」を検索または作成 → Birth Event（日付と場所を設定し、引用を付与）を作成 → そのイベントを主な出生として参照する Person を作成、という処理を行います。新しい gramps_id（例：I0001）を返します。

いつでも list_unsourced_facts を呼び出すと、出典が必要な項目を確認できます。まだ出典を付けられない事実を追加する場合は、require_citation=false を渡すと、その事実に UNSOURCED のタグが付き、監査リストに表示されます。

---

開発

git clone https://github.com/ianderso/gramps-evidence-mcp
cd gramps-evidence-mcp
uv sync --extra dev
uv run pytest

テストスイートは、respx 経由で提供する gramps-webapi のインメモリの偽物に対して実行されるため、Gramps Web のインスタンスは不要です。また、実際の接続を開こうとするテストがあれば失敗します。クライアントからの呼び出しと同じ方法でツールのインターフェースを検証します。各ツールのスキーマ、不明な引数の拒否、すべての編集ツールにおけるオブジェクト全体の書き込みルール、各一括出力に対するプライバシーフィルター、例外を発生させずに各ツールが返すエラーエンベロープをテストします。

2つ目のテストスイート tests/live は、使い捨ての実際の gramps-webapi に対して実行されます。CI では 3.21.1、3.22.3、3.23.1 を使用し、Docker を使わずに PyPI からインストールします。docs/PITFALLS.md に記載されているサーバーの動作をすべて確認し、ツールをエンドツーエンドで実行します。また、偽物とサーバーに対して同じシナリオを実行し、同じ回答が返ることを求めるため、偽物が再現対象から乖離することはありません。実行方法は CONTRIBUTING.md に記載されています。

変更に必要なものは CONTRIBUTING.md に記載されています。

---

制限事項

• gramps-webapi 3.21 以降（Gramps 6.0）が必要です。CI の各実行で 3.21.1、3.22.3、3.23.1 に対してテスト済みです。古いサーバーでは、すべてのツールがバージョンを示す unsupported_server エラーを返します。3.20 には、検索とプライバシーフィルターが使用するクエリエンドポイントがありません。インスタンスの /api/openapi.json が正確な情報源です。呼び出しが予期せぬ動作をする場合は確認し、API の動作でこれまでに予想外の結果が生じた箇所については docs/PITFALLS.md を参照してください。
• ツリーセレクターはありません。 gramps-webapi では、ツリーは認証に使用するアカウントに紐付けられており、データエンドポイントはツリーパラメーターを受け取りません。別のツリーを操作するには、そのツリーに属する認証情報を使用してください。
• 型名（"Birth"、"Married"）は、Gramps の英語標準名およびツリーのカスタム名と、大文字小文字や句読点を区別せずに照合されます。また、いくつかの明確な同義語（「Born」は Birth）にも対応しています。それ以外は、新しいカスタム型を作成するよう allow_new_type で指定しない限り、最も近い名前を提示して拒否されます。そのため、他の言語の型名は保存されずに拒否されます。英語名を指定してください。詳しくは docs/PITFALLS.md のセクション 26 を参照してください。
• search_people、list_unsourced_facts、find_duplicates はコレクション全体を読み込みます。数千人規模の個人用ツリーには適していますが、非常に大規模なデータベース向けには作られていません。
• get_facts は呼び出しのたびにサーバーで計算され、1,000 人未満のツリーでも数十秒かかります。この呼び出しのタイムアウトは 3 分です。
• ocr_media の Transkribus 経路は、稼働中のサービスに対してまだ実行されていません。Gramps Web が表示する PDF のページは最初のページのみのため、スキャン画像が埋め込まれていない後続ページは画像として読み取れません。

---

リポジトリの構成

src/gramps_evidence_mcp/    the MCP server
  server.py                 tool definitions (the 97 tools) and the entry point
  service.py                genealogy operations; edits go through _mutate()
  client.py                 gramps-webapi REST client
  mapping.py                Gramps object <-> JSON shapes
  models.py                 Pydantic input models shared by the tools
  privacy.py                living-person assessment and redaction
  gedcom_ref.py             read-only reference layer over legacy GEDCOMs
  ocr.py                    ocr_media's routing, images, archives and Transkribus
  config.py                 env vars + TOML
tests/                      against an in-memory fake; no live server needed
  live/                     against a throwaway gramps-webapi (CI: 3.21.1, 3.22.3, 3.23.1)
docker/                     docker-compose for a local Gramps Web
docs/
  ARCHITECTURE.md           how the server is put together
  PITFALLS.md               gramps-webapi behaviours that have cost real data
  ROADMAP.md                what is planned (nothing), and what is not

gramps-webapi を直接操作するスクリプトを書く前に、docs/PITFALLS.md を必ず読んでください。 そこに記載されている項目は、いずれも何かを失った経験から得られたものです。keys= を指定した PUT で 65 家族の親リンクが消えたこと、2 つの主張で同じ引用ハンドルが再利用されて 107 件の親子リンクの評価を誤ったこと、そして 2 つの同時セッションによって書き込み処理が約 18 時間停止したことなどです。