Gramps MCP MCP Server

Gramps MCP Server

プロジェクト

opencode、Claude、Cursor などの AI エージェントや、その他あらゆる MCP クライアントから Gramps Web API のすべての機能を利用できる Model Context Protocol（MCP）サーバーです。PyPI では gramps-mcp-full として公開されています。

Gramps は無料のオープンソース系譜プログラムです。Gramps Web には REST API（gramps-web-api）が付属しており、家系図（人物、家族、イベント、場所、資料、引用、メモ、メディア、リポジトリ、タグ）の読み取りや操作に加え、系譜データの処理（統合、タイムライン、続柄、生存状況、DNA）、インポート／エクスポート、レポート、トランザクション、サーバー管理ができます。

このサーバーを使うと、エージェントから Gramps の家系図に直接問い合わせたり、操作したりできます。すべてのオブジェクトタイプの完全な CRUD、全文／セマンティック検索、オブジェクトの統合（フェニックス／タイタニック生存者）、タイムライン、関係、生存者の推定、DNA マッチ分析、メディアパイプライン（バイナリのアップロード、ファイルのダウンロード、サムネイル、OCR、顔検出）、プライバシーフィルター付きの GEDCOM／Gramps XML インポートおよびエクスポート、レポート生成、生のトランザクション、ユーザー、家系図、ブックマーク、タイプ用語集の管理を利用できます。複数のインスタンス（トークン／JWT 認証を使用する 1 つ以上の Gramps Web ベース URL）にも対応しています。

⚠️ 公式 API、変更可能なデータです。 非公開のエンドポイントをリバースエンジニアリングする EduPage サーバーとは異なり、このサーバーは公式に文書化された Gramps Web REST API（gramps-web-api）を使用します。この API は gramps-project 組織が保守しており、OpenAPI 仕様が https://gramps-project.github.io/gramps-web-api/ で公開されています。読み取り専用機能は自由にお使いください。書き込み機能（manage_*、merge_objects、manage_import、manage_transaction、…）は、実際の家系図データを変更するため、慎重に使用してください。

---

目次

• 別の Gramps MCP サーバーが必要な理由
• 提供機能
• はじめに
  • 前提条件
  • 1. インストール
  • 2. 認証情報の設定
  • 3. MCP クライアントへの登録
• プロンプトの例
• 複数インスタンス（ベース URL）
• ツールのリファレンス
• データと安全性に関する注意
• 貢献
• 制限事項
• サポート
• ライセンス

---

もう1つのGramps MCPサーバーを作る理由

すでにGramps MCPサーバーはいくつかあります。

• Knuckles-Team/gramps-mcp — 35個のアクション振り分け型ツール、A2Aエージェント、OTELテレメトリー、単一のGRAMPS_URL
• cabout-me/gramps-mcp — 16個のツール、AGPL-3.0、Docker Composeベース、HTTP優先
• Scormave/gramps-web-mcp — 57個のツール＋6個のリソース、.NET、複数のトランスポート、読み取り専用モード
• Genealogy-MCP/gramps-mcp — AGPLv3、GitLabミラー、32回のリリース

どれも優れたプロジェクトで、私はそれらと一切関係ありません。誠実な比較のために、ここで紹介しているだけです。これらのプロジェクトは、機能をほぼ同じ多数のツールに分割しているか、APIのうち読み取り中心の一部しかカバーしていません。

このプロジェクトでは、意図的にさらに踏み込んでいます。

機能	Knuckles-Team/gramps-mcp	cabout-me/gramps-mcp	Scormave/gramps-web-mcp	このプロジェクト
完全なCRUD — 人物、家族、イベント、場所、出典、引用、メモ、メディア、リポジトリ、タグ	一部（アクション）	一部	✅	✅
オブジェクトの種類ごとに1つのmanage_*ツール（action=でget/list/create/update/delete）	❌	❌	❌	✅
系譜計算 — merge_objects（フェニックス／タイタニック）、get_timeline、get_relation、get_living	❌	❌	一部	✅
DNA分析 — analyze_dna（一致、Y-DNA、セグメントパーサー）	❌	❌	❌	✅
メディアパイプライン — バイナリーアップロード、ファイルダウンロード、サムネイル、OCR、顔検出	❌	一部	一部	✅
インポート／エクスポート — GEDCOM／Gramps XML、ドライラン、復元、プライバシーフィルター対応	インポートのみ	インポートのみ	エクスポートのみ	✅
レポート — 一覧表示、生成、ダウンロード	❌	❌	❌	✅
トランザクション — raw apply/undo、履歴、一括作成／削除	❌	❌	❌	✅
管理 — ユーザー、ツリー（修復／移行／検証／設定）、ブックマーク、タイプ	一部	❌	一部	✅
サーバーメタデータ — データベース、バージョン、ロケール、件数、機能	❌	❌	❌	✅
複数インスタンス — 1つ以上のGramps WebベースURL	❌	❌	✅	✅
認証 — 遅延トークンログイン/api/token/＋事前発行JWT＋更新	JWT	ユーザー名／パスワード	トークン	✅
読み取り専用モード	❌	❌	✅	✅
デフォルトで有効な品質ゲート — py_compile、Docker MCPハンドシェイク、HTTP認証スモークテスト、Trivy、Glama TDQSウォッチドッグ	❌	❌	❌	✅
公開 — PyPI、GHCR、MCP Registry、Glama	PyPI	Docker Hub/GitHub	GHCR	✅

主な差別化要因：

• 適切なパラメーターを備えた、厳選されたツールセット。 27個のツール（分割された57個やアクション振り分け型の35個に対し）：オブジェクトの種類ごとに1つのmanage_*ツールを用意し、action=パラメーターで操作します。これは、標準的なget_timetable／loginファミリーの設計を踏襲しています。
• 系譜に特化した計算機能。 フェニックス／タイタニック方式の生存者判定を伴うマージ、時系列タイムライン、親族関係の距離／経路、推定日付に基づく生存状況、そして実際に機能するDNAセグメントパーサーを備えています。単なるオブジェクトストレージではありません。
• 書き込み機能を完全に網羅。 プライバシーフィルターとドライランに対応したインポート／エクスポート、レポート生成、rawトランザクション、ユーザー／ツリー／ブックマーク／タイプの管理を備えています。他のサーバーでは、これらはカバーされていません。
• 本番環境に対応。 複数インスタンスに対応し、トークン／JWT認証と更新機能を備えています。すべてのPRに品質ゲート（lint → Dockerハンドシェイク → HTTP認証スモークテスト → Trivy → Glama TDQSウォッチドッグ）を適用し、OIDCを使ってPyPI、GHCR、MCP Registryに公開します。

提供する機能

27 個のツールを公開する単一の MCP サーバーです（PyPI では gramps-mcp-full として公開されています）。

• コア — ping（ヘルスチェック）、get_instances（設定済みの Gramps Web ベース URL）
• オブジェクト（完全な CRUD） — manage_person、manage_family、manage_event、manage_place、manage_source、manage_citation、manage_note、manage_media、manage_repository、manage_tag。いずれも action=（get、list、create、update、delete）を指定します。manage_media はバイナリのアップロード、ファイルのダウンロード、サムネイル、OCR、顔検出にも対応しています
• 検索と計算 — search（全文／セマンティック検索。オブジェクトの種類でフィルタリング可能）、merge_objects（デフォルトでは phoenix が残り、titanic はオプション）、get_timeline（人物／家族／ツリー）、get_relation（続柄の度合いと経路）、get_living（ステータスまたは推定日付）、analyze_dna（マッチ、Y-DNA、セグメントパーサー）
• データ管理 — manage_import（インポーターの一覧表示、ドライランでのファイルのインポート、バックアップの復元）、manage_export（エクスポーターの一覧表示、プライバシーフィルターを適用した GEDCOM／Gramps XML／CSV のエクスポート）、manage_report（レポートの一覧表示／生成／ダウンロード）、manage_transaction（未加工のペイロードの適用／取り消し、履歴、一括作成／削除）
• 管理 — manage_user、manage_tree（作成／更新／無効化／有効化／修復／移行／検証／設定）、manage_bookmark（名前空間ごと）、manage_type（デフォルトおよびカスタムの語彙）、get_server_info（データベース、バージョン、ロケール、オブジェクト数、機能）

---

はじめに

MCP 対応クライアント（opencode、Claude Desktop、Cursor など）と、アクセス可能な Gramps Web インスタンス（ベース URL と必要な権限を持つユーザーアカウント）が必要です。

1. インストール

AI コーディングクライアントを使用している場合は、たとえば「この GitHub リポジトリ oliverhruby/gramps-mcp の説明に従って Gramps MCP をインストールしてください」のような簡単なプロンプトだけで始められることがよくあります。ほとんどの MCP 対応クライアントでは、利用可能なセットアップオプションを確認しながら進められます。

オプション A — MCP Registry から（推奨、VS Code／GitHub Copilot でワンクリック）

このサーバーは MCP Registry に掲載されています。VS Code または GitHub Copilot で「Gramps MCP」を検索し、ワンクリックでインストールしてください。または、次の直接リンクを使用してください：mcp://install/io.github.oliverhruby/gramps-mcp

オプション B — PyPI から

リリース済みバージョンを通常どおり使用する場合はこちらを使用してください。

要件：uvx を使用する場合は uv、pip を使用する場合は Python 3.10+。

uvx gramps-mcp-full
# or, if you prefer pip (into whatever environment your MCP client uses):
pip install gramps-mcp-full

uvx を使うと、パッケージを永続的にインストールせずに実行できます。uvx が使えない場合は、先に uv をインストールしてください（pip install uv または winget install astral-sh.uv）。

オプション C — GitHub から（最新のソース）

PyPI リリース前の最新の変更を利用する場合はこちらを使用してください。

要件：uvx を使用する場合は uv、pip を使用する場合は Python 3.10+。

uvx --from "git+https://github.com/oliverhruby/gramps-mcp.git" gramps-mcp-full
# or
pip install "git+https://github.com/oliverhruby/gramps-mcp.git"

オプション D — Docker

分離されたコンテナーランタイムを使用する場合はこちらを使用してください。

要件：Docker。

ビルド済みイメージをプルします（推奨）：

docker pull ghcr.io/oliverhruby/gramps-mcp:latest

docker run --rm -i \
  -e GRAMPS_MCP_INSTANCES=https://gw.example.com \
  -e GRAMPS_MCP_USERNAME=your_username \
  -e GRAMPS_MCP_PASSWORD=your_password \
  ghcr.io/oliverhruby/gramps-mcp:latest

固定したイメージを使用したい場合は、バージョンタグ（例：v0.1.0）も利用できます。

ソースからローカルでビルドします（代替手段）：

docker build -t gramps-mcp-full .

docker run --rm -i \
  -e GRAMPS_MCP_INSTANCES=https://gw.example.com \
  -e GRAMPS_MCP_USERNAME=your_username \
  -e GRAMPS_MCP_PASSWORD=your_password \
  gramps-mcp-full

このコンテナーでは、認証情報の設定で説明されているものと同じ環境変数を使用します。また、HEALTHCHECK も含まれています（デフォルトでは stdio プロセスの稼働状況を確認し、HTTP トランスポートモードではローカル TCP を確認します）。

HTTP トランスポートでは、次の任意のランタイム変数を設定してください：

• MCP_TRANSPORT：stdio（デフォルト）、sse、または streamable-http
• MCP_HOST：バインドするホスト（デフォルトは 127.0.0.1）
• MCP_PORT：バインドするポート（デフォルトは 8000）
• MCP_API_KEY：HTTP 認証用の任意のベアラートークン

MCP_API_KEY が設定されている場合、HTTP リクエストには Authorization: Bearer <key> を含める必要があります。MCP_API_KEY が設定されていない場合、HTTP エンドポイントは認証なしで利用できます。本番環境では、リバースプロキシまたは API ゲートウェイを介して適切な認証と TLS を適用することを推奨します。

pyproject.toml では mcp<2（安定版の FastMCP v1 API）を固定しています。mcp 2.x では FastMCP が MCPServer に改称され、API の仕様も変更されました。このサーバーでは、シンプルさと安定性を重視して FastMCP v1 API を対象としています。 オプション E -- APM で一度にインストール（サーバー と 同梱スキル）

APM（Agent Package Manager）は、エージェントのコンテキスト（エージェントスキル、MCP サーバー、設定のための npm のようなもの）を配布する新しいオープン標準です。任意のため、使わなくても上記のどのオプションもこれまでどおり動作します。すでに APM を使っている場合（または試してみたい場合）は、コマンド 1 つで、このプロジェクトが提供する 2 つの要素を両方インストールできます。

1. CLI を一度インストールします。必要なもの：git と、サーバーランタイム用の uv。

   • Windows：winget install --id Microsoft.APM -e（または scoop bucket add apm https://github.com/microsoft/scoop-apm; scoop install apm）
   • macOS / Linux：brew install apm
   • Python 3.10+ が使えるすべてのプラットフォーム：pip install apm-cli
   • その他の方法：インストール手順

2. このパッケージをインストールします。

   apm install oliverhruby/gramps-mcp
   

   この 1 つのコマンドで、次の処理が行われます。

   • APM が検出したすべてのハーネスの MCP 設定に、uvx gramps-mcp-full の stdio サーバーエントリを書き込みます（Claude Code .mcp.json、VS Code / GitHub Copilot、Cursor、OpenCode、Codex、Gemini、Windsurf、Kiro、...）。特定のハーネスを指定するには --target claude（または codex、cursor、...）を追加します。
   • 同梱の person-research-brief スキルを、そのハーネスのスキルディレクトリ（.claude/skills/、.agents/skills/、...）に配置します。

3. 確認します。

   apm mcp list        # server registered?
   

   apm uninstall oliverhruby/gramps-mcp を実行すると、パッケージと配置されたスキルファイルが削除されますが、.mcp.json（およびほかのハーネス設定）に書き込まれた MCP サーバーエントリは残ります。削除したい場合は、そのエントリを自分で削除してください。

認証情報がパッケージに埋め込まれることはありません。apm install を実行する前に、環境で GRAMPS_MCP_USERNAME / GRAMPS_MCP_PASSWORD（および任意で GRAMPS_MCP_INSTANCES）を設定してください。2. 認証情報を設定するを参照してください。APM はこれらを生成されるサーバー設定に引き継ぎます。

バージョンの固定。 正確なリビジョンに固定して APM の「dependency unpinned」警告を抑制するには、apm.yml を含むリリース以降で #<tag>、または #<sha> を末尾に追加します。固定しない場合、APM は解決されたコミットを apm.lock.yaml に記録します。v0.2.1 までのリリースにはマニフェストが含まれていないため、次のリリースまではコミット sha を使用してください。

ソースからの開発

コントリビュートする場合や、ローカルでデバッグする場合に使用してください。

必要なもの：Python 3.10+。

git clone https://github.com/oliverhruby/gramps-mcp.git
cd gramps-mcp
pip install -e . pytest

2. 認証情報を設定する

環境変数を設定するか、実行時に渡してください。サーバーの接続先となる Gramps Web インスタンスとアカウントを指定します。

# Windows (persistent, per-user)
setx GRAMPS_MCP_INSTANCES "https://gw.example.com,https://gw2.example.com"   # one or more base URLs
setx GRAMPS_MCP_USERNAME "your_username"
setx GRAMPS_MCP_PASSWORD "your_password"

# macOS / Linux
export GRAMPS_MCP_INSTANCES="https://gw.example.com,https://gw2.example.com"
export GRAMPS_MCP_USERNAME="your_username"
export GRAMPS_MCP_PASSWORD="your_password"

インスタンスが 1 つの場合：ベース URL と GRAMPS_MCP_USERNAME / GRAMPS_MCP_PASSWORD を設定するだけです。ログインは遅延実行されます。サーバーは認証情報なしで起動し、初回使用時に POST /api/token/ 経由でログインします。

複数のインスタンスがある場合：カンマ区切りの GRAMPS_MCP_INSTANCES リストを追加します。ログインはインスタンスごとに api/token/ で行われます（デフォルトでは初回使用時）。または、GRAMPS_MCP_TOKENS（GRAMPS_MCP_INSTANCES と同じ順序で並べたカンマ区切りの値）を設定すると、各インスタンス用に発行済みの JWT を指定できます。

その他の設定項目：GRAMPS_MCP_TIMEOUT（読み取りタイムアウト秒数、デフォルトは 60）、GRAMPS_MCP_INSECURE=1（自己署名サーバーの TLS 検証を省略）、GRAMPS_MCP_READONLY=1（すべてのツールを読み取り専用モードで実行。書き込み操作 manage_*、merge_objects、manage_import、manage_export などは拒否されます）。

3. MCP クライアントに登録する

opencode — ~/.config/opencode/opencode.json（または opencode.jsonc）に追加します。

{
  "mcp": {
    "gramps": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "gramps-mcp-full"],
      "env": {
        "GRAMPS_MCP_INSTANCES": "{env:GRAMPS_MCP_INSTANCES}",
        "GRAMPS_MCP_USERNAME": "{env:GRAMPS_MCP_USERNAME}",
        "GRAMPS_MCP_PASSWORD": "{env:GRAMPS_MCP_PASSWORD}"
      }
    }
  }
}

認証情報はシェル／環境（または .env）に設定し、{env:VAR} で参照するか、env: に直接記述してください。uvx は初回にパッケージを自動でセットアップします。PATH に含まれている必要があります。

Claude Desktop / Cursor — 標準形式の mcpServers エントリを含む claude_desktop_config.json / .mcp.json を使用し、command/args で venv の python と gramps_mcp.py のパスを指定し、さらに認証情報を含む env ブロックを追加してください。

クライアント設定を編集した後は、MCP サーバーを読み込むためにクライアントを再起動してください。

---

プロンプトの例

ユーザープロンプト	想定されるツール呼び出し	期待される応答
"接続されていて、ログインしていますか？"	ping → get_instances	サーバーの状態と設定済みの Gramps Web インスタンス。
"1900年以降に生まれた人物をすべて一覧表示して"	manage_person action="list"	条件に一致する人物の簡潔な一覧。
"人物 I001 の家系図を表示して"	manage_family action="list" → get_timeline handle="I001"	その人物の家族と時系列のタイムライン。
"人物 I002 を I001 に統合し、I001 のデータを残して"	merge_objects obj_type="person" handle1="I001" handle2="I002"	統合の確認（phoenix の存続）。
"人物 I003 と I020 の関係は？"	get_relation handle1="I003" handle2="I020"	続柄と、それらの間の経路。
"人物 I005 は生存している可能性がありますか？"	get_living handle="I005"	生存している可能性の判定、または推定される生没年月日。
"人物 I010 の DNA 一致を分析して"	analyze_dna action="matches" handle="I010"	DNA 一致、Y-DNA クレード、解析されたセグメント。
"人物 I012 のメディアファイルをアップロードして"	manage_media action="upload" handle="I012" …	メディアオブジェクトを作成し、サムネイルと OCR を利用可能にします。
"プライバシーフィルターを適用して家系図を GEDCOM としてエクスポートして"	manage_export extension="gedcom" options={"privacy": …}	エクスポートファイルが作成され、ダウンロード可能になります。
"GEDCOM ファイルをインポートして（最初にドライラン）"	manage_import action="import" extension="gedcom" file_path="…"	ドライランのレポートと、その後のインポート結果。
"人物 I018 の調査レポートを生成して"	manage_report action="generate" report_id="…"	レポートが生成され、ダウンロード可能になります。
"ソースを更新するため、生のトランザクションを適用して"	manage_transaction action="apply" payload="…"	トランザクションが適用されます（後で取り消すこともできます）。
"すべてのユーザーを一覧表示してから、ciowner を無効にして"	manage_user action="list" → manage_user action="update" data={…}	ユーザー一覧と、無効化されたアカウント。
"新しい家系図を作成して、ベース URL を設定して"	manage_tree action="create" data={…} → … action="config_set"	新しい家系図が作成され、設定されます。
"既定のイベント／場所タイプとカスタムのイベント／場所タイプをすべて一覧表示して"	manage_type action="all"	オブジェクトタイプごとのタイプ語彙。
"サーバーのメタデータを取得して"	get_server_info	データベース、バージョン、ロケール、オブジェクト数、機能。

---

複数のインスタンス（ベース URL）

各 Gramps Web インスタンスは、独自のセッションを保持します。設定方法は 2 つあります。

A）環境変数（推奨）。 GRAMPS_MCP_INSTANCES（カンマ区切りのベース URL）と、共有の GRAMPS_MCP_USERNAME／GRAMPS_MCP_PASSWORD を設定します。サーバーは各インスタンスの初回使用時に遅延ログインします。

setx GRAMPS_MCP_INSTANCES "https://gw.example.com,https://gw2.example.com"   # Windows
export GRAMPS_MCP_INSTANCES="https://gw.example.com,https://gw2.example.com" # macOS / Linux

get_instances     # lists both base URLs + login status per instance

各データツールはアクティブなインスタンスを対象とします。各インスタンスは、初回使用時に api/token/ を介して遅延ログインします。

B）発行済み JWT。 GRAMPS_MCP_INSTANCES と順序をそろえて GRAMPS_MCP_TOKENS（カンマ区切り）を設定すると、セッションが直接設定され、オンデマンドの api/token/ ログインは行われません。

インスタンスが 1 つの場合は？ GRAMPS_MCP_INSTANCES ＋ USERNAME ＋ PASSWORD を設定するだけです。複数の場合は、カンマ区切りのリストに追加する（自動ログイン）か、GRAMPS_MCP_TOKENS を設定します。

---

ツールリファレンス

ツール	説明	書き込み
ping	ヘルスチェックです。	💡 読み取り
get_instances	設定済みの Gramps Web インスタンスを一覧表示します。	💡 読み取り
manage_person	Person レコードの CRUD（action = get/list/create/update/delete）です。	✅ 作成／更新／削除
manage_family	Family レコードの CRUD です（父／母／子の参照は上流で維持されます）。	✅ 作成／更新／削除
manage_event	Event レコードの CRUD です（種類は manage_type から取得します）。	✅ 作成／更新／削除
manage_place	Place レコードの CRUD です。	✅ 作成／更新／削除
manage_source	Source レコードの CRUD です。	✅ 作成／更新／削除
manage_citation	Citation レコードの CRUD です（source_handle にリンクします）。	✅ 作成／更新／削除
manage_note	Note レコードの CRUD です（DNA セグメント文字列、文章などを保持します）。	✅ 作成／更新／削除
manage_media	Media の CRUD と、バイナリのアップロード、ファイルのダウンロード、サムネイル、OCR、顔検出を行います。	✅ 作成／更新／削除／アップロード
manage_repository	Repository レコードの CRUD です。	✅ 作成／更新／削除
manage_tag	Tag レコードの CRUD です。	✅ 作成／更新／削除
search	オブジェクトの種類で絞り込み可能な、全文検索またはセマンティック検索です。	💡 読み取り
merge_objects	同じ種類の 2 つのオブジェクトを 1 つに統合します。	✅ 統合
get_timeline	人物、家族、またはツリー全体のイベントを時系列で表示します。	💡 読み取り
get_relation	2 人の間の系譜上の関係を計算します。	💡 読み取り
get_living	人物が存命かどうか（またはいつまで存命だったか）を推定します。	💡 読み取り
analyze_dna	DNA マッチの分析と、生のマッチ文字列の解析を行います。	✅ 解析のみ
manage_import	インポーターの一覧表示、またはファイルのインポート（Gramps XML、GEDCOM…）を行います。ドライランと復元に対応します。	✅ ファイル／復元
manage_export	エクスポーターの一覧表示、またはエクスポートの生成（GEDCOM、Gramps XML…）を行います。プライバシーフィルターに対応します。	✅ 実行
manage_report	レポート（PDF、テキスト、Web…）の一覧表示、設定、生成を行います。	✅ 実行
manage_transaction	生の DB トランザクション、元に戻す履歴、一括作成／削除を適用します。	✅ すべての操作
manage_user	Gramps Web ユーザーを管理します（作成／更新／削除／パスワード変更）。	✅ すべての操作
manage_tree	ツリーの作成／更新、無効化／有効化、修復、移行、検証、設定を行います。	✅ すべての操作
manage_bookmark	オブジェクト名前空間ごとのブックマークを読み取る、または編集します。	✅ 追加／削除
manage_type	すべてのオブジェクト種類について、Gramps の種類語彙（カスタムおよびデフォルト）を一覧表示します。	💡 読み取り
get_server_info	サーバー、データベース、ロケール、オブジェクト数のメタデータを読み取ります。	💡 読み取り

✅ 書き込み／💡 読み取りのラベルは、各ツールの docstring（AGENTS.md ルール 4）に基づいています。

---

データと安全性に関する注意事項

• ほとんどのツールには、action= を介して読み取りと書き込みの両方の操作があります。書き込み操作（上記で ✅ と表示）は実際の Gramps ツリーデータを変更します。慎重に使用し、破壊的な操作の前には、利用可能な場合はドライラン（manage_import のドライラン、エクスポートのプレビュー）を優先してください。
• merge_objects は、デフォルトでフェニックス方式で存続します（存続するオブジェクトがハンドルを保持します）。タイタニック方式で存続させるには、適切なオプションを渡してください。元に戻すことはできません。事前に manage_transaction でスナップショットを作成するか、エクスポートのバックアップを検討してください。
• manage_transaction は生の DB ペイロードを適用します。誤りがあった場合は、返されたトランザクション ID を使って action="undo" で元に戻せますが、それ以外ではツリーはその場で変更されます。
• ライブ E2E スイートは実際のアカウントと実際のデータにアクセスします。公開 CI では実行されません。また、個人を特定できる情報をコミット、ログ記録、アップロードすることはありません。CI では一方向の SHA-256 フィンガープリントのみを比較し、ローカル実行では正確な値を gitignore 対象のファイルに保持します。
• 品質ゲートはすべての PR で実行されます。内容は py_compile、Docker MCP ハンドシェイク、HTTP 認証のスモークテスト、Trivy スキャン、Glama TDQS ウォッチドッグ（ツールの評価、インベントリ、全体の qualityScore）です。

貢献

貢献者およびメンテナー向けのガイダンスは、CONTRIBUTING.md をご覧ください。

• 貢献のワークフローとローカル環境のセットアップ
• アーキテクチャと実装の詳細
• リリースプロセス（PyPI、GitHub Releases、GHCR、MCP Registry）
• CI の品質ゲートと Glama TDQS ウォッチドッグ
• 規約：ツールを追加・削除する際は、4 つの同期ポイントを常に一致させてください（品質ゲートのツール数下限、GLAMA_EXPECTED_TOOLS、README のツール一覧と件数、tests/e2e/test_manifest.py）

---

制限事項

• 公式 Gramps Web API に依存しています。 対応フィールドは上流の gramps-project/gramps-web-api REST スキーマに準拠しており、オブジェクトのペイロードでは Gramps のハンドル／gramps_id の規約を使用します。
• 書き込みツールは確認なしに実データを変更します。 内容を理解していない破壊的なツール呼び出しは、決して実行しないでください。サーバーは API に加えて確認プロンプトを追加しません。
• 認証はプロセスの存続期間中有効です。 セッションはインスタンスごとに api/token/ 経由で遅延作成され、必要に応じて更新されます。ブラウザー形式の永続的なログインではありません。
• メディアの OCR／顔検出は、Gramps Web のオプションサービスに依存します。 インスタンスでこれらのサービスが有効になっていない場合、manage_media の該当機能はアップロード／ダウンロードのみになります。
• ライセンスによるツリー数の制限があります。 Gramps Web の無料プランでは、従来、複数ユーザー／ツリー機能が制限されていました。管理ツール（manage_user、一部の manage_tree アクション）の使用には、該当機能を利用できるライセンスプランが必要です。
• MCP_API_KEY が保護するのは HTTP トランスポートのみです。 本番環境では、ストリーミング可能な HTTP エンドポイントの前段にリバースプロキシを設置し、TLS を終端して認証してください。

---

サポート

このプロジェクトを気に入っていただき、応援や機能のリクエストをしたい場合は、ビールをおごってください。気分が落ち着いて、アイデアが浮かびやすくなります :-)

---

ライセンス

MIT © Oliver Hrubý

このプロジェクトは、Gramps プロジェクトまたは gramps-web-api の作者とは提携しておらず、承認も受けていません。Gramps はそれぞれの所有者の商標です。