gramps-remote-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code (and other agents) working in this repository.

What this is

An MCP server (stdio transport) that exposes a live Gramps Web genealogy instance to an MCP client over its REST API. See README.md for the user-facing description and the full tool list.

Commands

pip install -r requirements-dev.txt   # runtime + dev deps

pytest -q                             # full suite (fast, no network — the API is mocked)
pytest tests/test_gramps_client.py -q # one file
pytest -q -k import_file              # one topic

ruff check .                          # lint
ruff format .                         # format
ruff format --check .                 # verify only, as CI does

pre-commit install                    # once per clone: auto-fix on commit, verify on push

python server.py                      # run the server (needs the env vars below)

CI (.github/workflows/lint.yml) runs ruff check, ruff format --check and pytest.

Environment

Variable	Purpose
GRAMPS_BASE_URL	Gramps Web instance to talk to
GRAMPS_USERNAME / GRAMPS_PASSWORD	credentials; the client re-logs in on 401 and retries once
GRAMPS_ENABLE_DESTRUCTIVE	1 registers the gramps_delete_* tools. Absent = they do not exist
GRAMPS_BACKUP_DIR	directory gramps_export_tree / gramps_import_file may touch
GRAMPS_BLOG_BODY_FORMAT	blog post body format

Never commit real credentials — .env* is ignored except .env.example.

Layout

Four flat modules at the root, no package:

• server.py — MCP tool registration only. create_server(client, ...) is a factory with a closure register() decorator; main() wires it to stdio.
• gramps_client.py — all Gramps Web REST calls, guards, retry/relogin, polling.
• gramps_blog.py — blog-post CRUD.
• backup_store.py — filesystem access for export/import, with the path-traversal guard.

Tests mirror the modules one-to-one under tests/.