gramps-web-mcp

Компаньон MCP-сервер для платформы с открытым исходным кодом Gramps Web, предназначенной для генеалогии. Он предоставляет ИИ-агентам структурированный, инструментальный доступ к генеалогическим древам через протокол Model Context Protocol.

Этот проект не является самостоятельным генеалогическим интерфейсом или заменой Gramps Web. Запускайте его вместе с существующим экземпляром Gramps Web; ваши пользователи, деревья, медиафайлы, разрешения и интерфейс редактирования генеалогии остаются в Gramps Web.

Возможности

• 57 MCP-инструментов — чтение, создание, обновление и удаление людей, семей, событий, мест, источников, цитат, заметок, медиафайлов, репозиториев и тегов

• Поиск и просмотр — полнотекстовый поиск и постраничный просмотр объектов

• Инструменты родства — предки, потомки, родственные связи и временные шкалы

• Составные рабочие процессы — быстрое добавление человека, добавление события к человеку, поиск по Gramps ID

• 6 MCP-ресурсов — словари типов, руководство по вводу, метаданные дерева, настройки имен и опциональные миниатюры/файлы медиа для агентов с поддержкой зрения

• Защита медиафайлов — ограничения размера, белые списки MIME-типов и настройки приватных записей по умолчанию

• MCP-подсказки — направляемые рабочие процессы для исследования, добавления людей/семей и импорта

• Несколько транспортов — stdio (локальные клиенты), Streamable HTTP, устаревший SSE

• Режим только для чтения — оставляет все инструменты видимыми, блокируя вызовы создания, обновления и удаления

Полный список см. в каталоге инструментов.

Related MCP server: ASPNET Core Debugging MCP Server

Предварительные требования

• .NET 8 SDK (для локальной разработки)

• Работающий экземпляр Gramps Web с доступом к API

• Docker (опционально, для развертывания в контейнере)

Быстрый старт

Локальная разработка (демо-сервер)

run-local-server.sh подключается к публичному экземпляру demo.grampsweb.org, используя общеизвестные демо-учетные данные (owner / owner):

./run-local-server.sh

Сервер запускается с HTTP-транспортом по адресу http://127.0.0.1:8080/mcp. Ключ API не требуется при привязке только к loopback.

Docker

Предварительно собранные мультиархитектурные образы (linux/amd64, linux/arm64) публикуются в GitHub Container Registry. Docker автоматически выбирает подходящую архитектуру; amd64 подходит для большинства хостов Unraid и x86, arm64 — для Apple Silicon и ARM SBC:

docker pull ghcr.io/scormave/gramps-web-mcp:latest

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  ghcr.io/scormave/gramps-web-mcp:latest

Образ предоставляет конечную точку GET /health для Docker HEALTHCHECK, проверки работоспособности контейнера Unraid и других мониторов времени безотказной работы. Она возвращает HTTP 200, когда MCP-сервер может аутентифицироваться в Gramps Web, или HTTP 503 в противном случае. Публичный ответ по умолчанию минимален: { "status": "healthy" } или { "status": "unhealthy" }. Журналы запуска содержат строку вида Connected to Gramps Web at …, как только API становится доступен.

Образ по умолчанию использует Streamable HTTP (MCP_TRANSPORT=http) на порту 8080, что и делают команды выше. Клиенты, которые сами запускают контейнер (например, установки MCP Registry), вместо этого запускают его через stdio с -e MCP_TRANSPORT=stdio и оставленным открытым stdin (docker run -i); этот режим объявлен в server.json.

Для режима только для чтения добавьте -e GRAMPS_READ_ONLY=true:

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  -e GRAMPS_READ_ONLY=true \
  ghcr.io/scormave/gramps-web-mcp:latest

Установка на Unraid

Пользователи Unraid могут установить gramps-web-mcp из Community Applications. Исходный код шаблона поддерживается по адресу Scormave/gramps-web-mcp-unraid. Для получения справки, специфичной для Unraid, см. ветку поддержки на форумах Unraid.

Базовая настройка:

1. В Unraid откройте Apps / Community Applications.

2. Найдите gramps-web-mcp и установите шаблон.

3. Укажите GRAMPS_API_URL, GRAMPS_USERNAME, GRAMPS_PASSWORD и GRAMPS_TREE_ID для вашего экземпляра Gramps Web. Установите MCP_API_KEY, если порт MCP доступен с других машин в вашей сети.

4. Оставьте порт контейнера по умолчанию 8080 или сопоставьте его с другим портом хоста.

5. Запустите контейнер и проверьте /health; он возвращает HTTP 200, как только сервис может аутентифицироваться в Gramps Web, с минимальным JSON-ответом по умолчанию.

Для наиболее простого сопряжения запустите Gramps Web и gramps-web-mcp в одной сети Docker Unraid и укажите GRAMPS_API_URL как URL контейнера Gramps Web. Конечная точка MCP для клиентов — http://<unraid-host>:<mapped-port>/mcp.

Gramps Web + MCP (Docker Compose)

Чтобы запустить Gramps Web и MCP-сервер на одном хосте и в одной сети Docker, используйте docker-compose.example.yml в качестве отправной точки:

cp docker-compose.example.yml docker-compose.yml
cp .env.example .env
# Complete the Gramps Web setup wizard, then set credentials in .env
docker compose up -d

Gramps Web публикуется на порту 5055; MCP — на 8080 (/mcp и /health). Внутри сети compose контейнер MCP обращается к Gramps Web по адресу http://grampsweb:5000.

Claude Desktop (расширение MCPB)

Установка в один клик для Claude Desktop доступна в виде MCP Bundle (.mcpb) из GitHub Releases. Загрузите пакет для вашей платформы:

1. Загрузите файл .mcpb для вашей ОС из последнего релиза.

2. Дважды щелкните по нему или перетащите в окно Claude Desktop.

3. Введите URL Gramps Web, имя пользователя, пароль/токен и UUID дерева.

4. Оставьте Режим только для чтения включенным для первого сеанса; отключайте его только когда хотите, чтобы Claude создавал или редактировал записи.

5. Завершите установку и начните новый чат.

Расширение работает локально через stdio и не требует .NET SDK на вашем компьютере. См. mcpb/README.md для получения подробной информации об упаковке и PRIVACY.md для политики конфиденциальности.

Чтобы собрать пакет локально:

./scripts/pack-mcpb.sh osx-arm64   # or osx-x64, win-x64, linux-x64, linux-arm64

Настройка MCP-клиента (вручную)

stdio (например, Claude Desktop, Cursor):

{
  "mcpServers": {
    "gramps-web": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/gramps-web-mcp/GrampsWeb.Mcp/GrampsWeb.Mcp.csproj"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "GRAMPS_API_URL": "https://your-gramps.example.com",
        "GRAMPS_USERNAME": "your-user",
        "GRAMPS_PASSWORD": "your-password",
        "GRAMPS_TREE_ID": "your-tree-uuid"
      }
    }
  }
}

Чтобы запустить stdio-сервер в режиме только для чтения, добавьте "GRAMPS_READ_ONLY": "true" в env.

HTTP (удаленный / Docker):

Укажите вашему MCP-клиенту на http://host:8080/mcp с транспортом Streamable HTTP. Когда установлен MCP_API_KEY, отправляйте его как Authorization: Bearer <key> или X-Api-Key: <key> в каждом MCP-запросе.

curl -X POST http://host:8080/mcp \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}},"id":1}'

Агенты с поддержкой зрения могут читать опциональные медиафайлы через инструменты (GetMediaThumbnail, GetMediaFile) или через бинарные MCP-ресурсы, такие как gramps://media/{handle}/thumbnail/{size} и gramps://media/{handle}/file. GetMediaFile возвращает содержимое ресурса изображения, аудио или встроенного BLOB-объекта в зависимости от MIME-типа. Сквозной анализ зависит от того, пересылает ли MCP-клиент типизированное содержимое инструмента или бинарное содержимое ресурса способной модели.

Конфигурация

Обязательные (подключение к Gramps)

Режим выполнения

• GRAMPS_READ_ONLY: установите true, чтобы заблокировать вызовы создания, обновления и удаления, оставив инструменты видимыми.

• GRAMPS_MUTATION_SERIALIZE: выполняет HTTP-вызовы создания/обновления/удаления по одному в этом процессе.

• GRAMPS_MUTATION_MIN_INTERVAL_MS: минимальная пауза между мутационными HTTP-вызовами, включая шаги внутри составных инструментов.

Примечания по выполнению:

• GRAMPS_READ_ONLY=false означает, что сервер запускается в режиме чтения/записи.

• Расширение Claude Desktop MCPB является исключением: его форма настройки по умолчанию использует режим только для чтения для более безопасного первого использования.

• Сериализация записи и опциональный интервал защищают типичные деревья SQLite Gramps Web от всплесков записи со стороны агента.

• Шлюз записи действует только в рамках процесса. Он не координируется между несколькими репликами MCP, интерфейсом Gramps Web или другими API-клиентами.

• Развертывания SQLite, которые по-прежнему видят database is locked при последовательных правках, должны установить GRAMPS_MUTATION_MIN_INTERVAL_MS=250 или 500.

• При ошибках блокировки SQLite или HTTP 429 от вышестоящего сервера инструменты мутации возвращают повторяемую ошибку MCP с краткой подсказкой о задержке вместо общего 500.

• Установите GRAMPS_MUTATION_SERIALIZE=false, когда Gramps Web использует PostgreSQL и вам нужна параллельная запись.

Доступ к медиафайлам

Инструменты/ресурсы для работы с байтами медиа отключены по умолчанию. get_media остается доступным для метаданных без включения загрузки файлов.

Отдавайте предпочтение GetMediaThumbnail или gramps://media/{handle}/thumbnail/{size} для анализа ИИ. Полные файлы могут быть большими и конфиденциальными и по-прежнему подлежат тем же проверкам размера, MIME и приватных записей.

Поддерживаются точные типы и подстановочные знаки type/*. Белый список медиа по умолчанию: image/jpeg,image/png,image/webp,image/avif,application/pdf.

Транспорты

Установите GRAMPS_API_URL, GRAMPS_USERNAME, GRAMPS_PASSWORD и GRAMPS_TREE_ID как обычно.

Для HTTP-транспорта ответы передаются через SSE. См. спецификацию Streamable HTTP для получения подробной информации о протоколе. Установите ASPNETCORE_URLS, чтобы выбрать адрес прослушивания, например http://127.0.0.1:8080.

HTTP-аутентификация

Если задан MCP_API_KEY, все MCP HTTP/SSE-эндпоинты требуют ключ в каждом запросе. GET /health остается анонимным для проверок Docker и балансировщиков нагрузки.

Сгенерируйте ключ:

openssl rand -base64 32

Без ключа сервер все равно запускается (обратная совместимость). Если адрес прослушивания не является только loopback, в журнал записывается предупреждение с рекомендацией установить MCP_API_KEY, использовать обратный прокси с собственной аутентификацией или привязаться к 127.0.0.1 для локального использования.

Внутри Docker ASPNETCORE_URLS обычно равен http://0.0.0.0:8080, поэтому предупреждение появляется, даже если хост публикует порт только на 127.0.0.1. Это ожидаемо, когда внешний доступ уже ограничен.

Разработка

dotnet test

См. CONTRIBUTING.md и руководство разработчика.

Документация

Участие в разработке

Вклад приветствуется. См. CONTRIBUTING.md.

Безопасность

Чтобы сообщить об уязвимости, см. SECURITY.md.

Политика конфиденциальности

Расширение для Claude Desktop — это локальный MCP-сервер. Он отправляет данные только в экземпляр Gramps Web, который вы настраиваете, и не собирает аналитику или данные разговоров. Полные сведения см. в PRIVACY.md.

Лицензия

Copyright (c) Scormave

Этот проект лицензирован в соответствии с GNU Affero General Public License v3.0 (AGPL-3.0-or-later). Поскольку это сетевое серверное программное обеспечение, размещение модифицированной версии требует предоставления соответствующего исходного кода пользователям, взаимодействующим с ней через сеть.