关于 Gramps MCP MCP Server
Gramps MCP Server 通过官方文档化的 REST API,将 AI Agent 连接到 Gramps Web 家谱。它结合对象管理、谱系分析、数据导入导出和管理功能,并支持多个实例。
主要功能
- 01谱系对象的增删改查
- 02全文和语义搜索
- 03时间线、关系及 DNA 分析
- 04GEDCOM 和 Gramps XML 导入导出
- 05媒体处理和报告生成
- 06多实例访问与管理
适用场景
- 01搜索和更新家谱
- 02探索亲属关系和时间线
- 03分析 DNA 匹配及片段
- 04通过隐私筛选导入或导出谱系数据
MCP 相关
该 MCP 服务将 Gramps Web API 能力作为工具提供给 MCP 客户端,包括家谱操作和谱系分析。支持 Token 或 JWT 身份验证以及多个 Gramps Web 实例。
配置
远程服务无需本地安装。选择你使用的客户端,复制配置或使用一键安装。
https://ghcr.io/oliverhruby/gramps-mcp:latestclaude mcp add --transport http oliverhruby-gramps https://ghcr.io/oliverhruby/gramps-mcp:latest{"mcpServers":{"oliverhruby-gramps":{"type":"http","url":"https://ghcr.io/oliverhruby/gramps-mcp:latest"}}}在 Cursor 中打开{"servers":{"oliverhruby-gramps":{"type":"http","url":"https://ghcr.io/oliverhruby/gramps-mcp:latest"}}}在 VS Code 中打开{"mcpServers":{"oliverhruby-gramps":{"type":"http","url":"https://ghcr.io/oliverhruby/gramps-mcp:latest"}}}{"mcpServers":{"oliverhruby-gramps":{"serverUrl":"https://ghcr.io/oliverhruby/gramps-mcp:latest"}}}命令在终端中运行;JSON 粘贴到对应客户端的 MCP 配置后重启。需要授权的服务会在首次连接时提示登录。
工具
详细介绍
Gramps MCP 服务
项目
一个 Model Context Protocol(MCP)服务,可将 Gramps Web API 的全部功能提供给 opencode、Claude、Cursor 等 AI Agent 以及其他任何 MCP 客户端。该项目已发布到 PyPI,名称为 gramps-mcp-full。
Gramps 是一款免费开源的家谱程序,而 Gramps Web 提供了一个 REST API(gramps-web-api),让你能够读取和操作家谱树——包括人物、家庭、事件、地点、来源、引文、笔记、媒体、存储库和标签,以及家谱计算功能(合并、时间线、关系、在世状态、DNA)、导入/导出、报告、事务和服务器管理。
此服务让你的 Agent 能够直接查询和操作 Gramps 家谱树:对所有对象类型执行完整的 CRUD 操作、全文/语义搜索、合并对象(凤凰/泰坦尼克号幸存者)、时间线、关系、在世状态估算、DNA 匹配分析、媒体处理流程(二进制上传、文件下载、缩略图、OCR、人脸检测)、带隐私过滤器的 GEDCOM / Gramps XML 导入和导出、报告生成、原始事务,以及对用户、家谱树、书签和类型词汇表的管理——并支持多个实例(一个或多个 Gramps Web 基础 URL,每个实例均使用令牌/JWT 进行身份验证)。
⚠️ 官方 API,可修改数据。 与 EduPage 服务(通过逆向工程使用未公开的端点)不同,本服务使用的是 官方且有文档说明的 Gramps Web REST API——
gramps-web-api,由gramps-project组织维护,并在 https://gramps-project.github.io/gramps-web-api/ 发布了 OpenAPI 规范。你可以放心使用只读功能;使用写入功能(manage_*、merge_objects、manage_import、manage_transaction、……)时请务必谨慎——这些功能会修改真实的家谱树数据。
目录
为什么还要开发另一个 Gramps MCP 服务?
目前已经有其他 Gramps MCP 服务:
Knuckles-Team/gramps-mcp— 35 个按操作路由的工具、A2A Agent、OTEL 遥测、单个GRAMPS_URLcabout-me/gramps-mcp— 16 个工具、AGPL-3.0、基于 Docker Compose、优先使用 HTTPScormave/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 — 人物、家庭、事件、地点、来源、引用、笔记、媒体、存储库、标签 | 部分(按操作) | 部分 | ✅ | ✅ |
每种对象类型一个 manage_* 工具(action= get/list/create/update/delete) | ❌ | ❌ | ❌ | ✅ |
谱系计算 — merge_objects(凤凰/泰坦尼克模式)、get_timeline、get_relation、get_living | ❌ | ❌ | 部分 | ✅ |
DNA 分析 — analyze_dna(匹配、Y-DNA、片段解析器) | ❌ | ❌ | ❌ | ✅ |
| 媒体处理流程 — 二进制上传、文件下载、缩略图、OCR、人脸检测 | ❌ | 部分 | 部分 | ✅ |
| 导入 / 导出 — 支持试运行、恢复和隐私筛选的 GEDCOM / Gramps XML | 仅导入 | 仅导入 | 仅导出 | ✅ |
| 报告 — 列出、生成、下载 | ❌ | ❌ | ❌ | ✅ |
| 事务 — 原始应用/撤销、历史记录、批量创建/删除 | ❌ | ❌ | ❌ | ✅ |
| 管理 — 用户、树(修复/迁移/验证/配置)、书签、类型 | 部分 | ❌ | 部分 | ✅ |
| 服务元数据 — 数据库、版本、区域设置、计数、功能 | ❌ | ❌ | ❌ | ✅ |
| 多个实例 — 一个或多个 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 个按操作路由的工具):每种对象类型都由一个带有
action=参数的manage_*工具处理,沿用标准的get_timetable/login系列设计。 - 谱系专用计算。 支持凤凰/泰坦尼克式生存判定的合并、按时间顺序排列的时间线、亲属关系级别/路径、根据推测日期判断在世状态,以及真正的 DNA 片段解析器——不只是对象存储。
- 完整的写入功能。 支持带隐私筛选和试运行的导入/导出、报告生成、原始事务、用户/树/书签/类型管理——其他服务都未覆盖这些功能。
- 适用于生产环境。 支持多实例 + 可刷新的令牌/JWT 身份验证,每个 PR 都经过质量门禁(lint → Docker 握手 → HTTP 身份验证冒烟测试 → Trivy → Glama TDQS 看门狗),并通过 OIDC 发布到 PyPI、GHCR 和 MCP Registry。
提供的功能
一个 MCP 服务,提供 27 个工具(在 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”,然后一键安装。也可以使用直接 deeplink: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-httpMCP_HOST:绑定主机(默认值为127.0.0.1)MCP_PORT:绑定端口(默认值为8000)MCP_API_KEY:用于 HTTP 身份验证的可选 bearer token
设置 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 一键安装(MCP 服务和捆绑技能)
APM(Agent Package Manager)是一项新兴的开源标准,用于分发 Agent 上下文——可以把它理解为面向 Agent 技能、MCP 服务和配置的 npm。它是可选的:不使用它,上述任何选项都可以照常运行。如果你已经在使用 APM(或想试试),只需运行一条命令,即可安装本项目提供的两个部分。
-
安装一次 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 - 其他选项:安装文档
- Windows:
-
安装此软件包:
apm install oliverhruby/gramps-mcp此命令会一次性完成以下操作:
- 将
uvx gramps-mcp-fullstdio 服务条目写入 APM 检测到的每个运行环境的 MCP 配置中(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/等)。
- 将
-
验证:
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 会将这些凭据传递到生成的服务配置中。
固定版本。 添加 #<sha>(或在某个版本包含 apm.yml 后添加 #<tag>),即可固定到确切的修订版本并消除 APM 的“依赖项未固定”警告;如果不固定版本,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"
单个实例? 只需设置基础 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}"
}
}
}
}
将凭据放入 shell/环境变量(或
.env文件),并通过{env:VAR}引用;也可以直接在env:下硬编码。首次运行时,uvx会自动配置软件包;它必须位于你的PATH中。
Claude Desktop / Cursor —— 使用 claude_desktop_config.json / .mcp.json,添加符合标准格式的 mcpServers 条目,将 command/args 指向虚拟环境中的 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 实例都有独立的会话。可通过以下两种方式配置:
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_TOKENS(以逗号分隔,并与 GRAMPS_MCP_INSTANCES 对应)——会话将直接初始化,无需按需登录 api/token/。
单个实例? 只需设置
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 | 将两个相同类型的对象合并为一个。 | ✅ 合并 |
get_timeline | 某个人、家庭或整棵家谱树的事件时间线。 | 💡 读取 |
get_relation | 计算两个人之间的家谱关系。 | 💡 读取 |
get_living | 估算某人是否在世(或在世至何时)。 | 💡 读取 |
analyze_dna | DNA 匹配分析及原始匹配字符串解析。 | ✅ 仅解析 |
manage_import | 列出导入器或导入文件(Gramps XML、GEDCOM…);支持试运行和还原。 | ✅ 文件/还原 |
manage_export | 列出导出器或生成导出文件(GEDCOM、Gramps XML…);支持隐私筛选。 | ✅ 执行 |
manage_report | 列出、配置或生成报告(PDF、文本、网页…)。 | ✅ 执行 |
manage_transaction | 应用原始数据库事务、撤销历史记录或批量创建/删除。 | ✅ 所有操作 |
manage_user | 管理 Gramps Web 用户(创建/更新/删除/更改密码)。 | ✅ 所有操作 |
manage_tree | 家谱树:创建/更新、禁用/启用、修复、迁移、验证、配置。 | ✅ 所有操作 |
manage_bookmark | 读取或编辑各对象命名空间下的书签。 | ✅ 添加/移除 |
manage_type | 列出所有对象类型的 Gramps 类型词汇表(自定义 + 默认)。 | 💡 读取 |
get_server_info | 读取服务器、数据库、区域设置和对象计数元数据。 | 💡 读取 |
✅ 写入 / 💡 读取标签来自各工具的文档字符串(AGENTS.md 规则 4)。
数据与安全注意事项
- 大多数工具都通过
action=提供读取和写入路径。写入操作(上方标记为 ✅)会修改真实的 Gramps 家谱树数据——请谨慎使用,并在执行破坏性操作前优先使用可用的试运行(manage_import试运行、导出预览)。 merge_objects默认采用 phoenix 存续方式(存续对象保留其句柄);如需采用 titanic 存续方式,请传入相应选项。此操作无法撤销——请考虑事先使用manage_transaction创建快照或导出备份。manage_transaction会应用原始数据库负载;出错时可使用返回的事务 ID,通过action="undo"撤销,但除此之外,家谱树会直接原地修改。- 实时 e2e 测试套件会触及真实账户和真实数据。它绝不会在公共 CI 中运行;也绝不会提交、记录日志或上传身份信息——CI 仅比较单向 SHA-256 指纹,本地运行则将准确值保存在 Git 忽略文件中。
- 每个 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-apiREST 架构;对象载荷使用 Gramps 句柄 /gramps_id约定。 - 写入工具会直接修改真实数据,且没有确认环节。 切勿运行你不了解的破坏性工具调用;服务不会在 API 之外额外添加确认提示。
- 身份验证在进程的整个生命周期内有效。 每个实例会通过
api/token/按需创建会话,并在需要时刷新;这不是类似浏览器的持久登录。 - 媒体 OCR / 人脸检测依赖可选的 Gramps Web 服务。 如果实例未启用这些服务,
manage_media的相关功能将降级为仅上传 / 下载。 - 单树许可证限制。 Gramps Web 的免费版历来限制多用户 / 多树功能;管理工具(
manage_user、部分manage_tree操作)需要具备相应功能的许可证级别。 MCP_API_KEY仅保护 HTTP 传输。 用于生产环境时,应终止 TLS,并通过可流式传输的 HTTP 端点前置的反向代理进行身份验证。
支持
如果你喜欢这个项目并想支持它或请求新功能,请请我喝杯啤酒,让我放松思绪、迸发灵感 :-)
许可证
MIT © Oliver Hrubý
本项目与 Gramps 项目或 gramps-web-api 的作者无关,也未获得其认可。Gramps 是其各自所有者的商标。
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。
