gramps-effect-mcp

An Effect TypeScript MCP server for safe access to Gramps Web. It exposes Gramps records, relationships, timelines, media, and verified mutations to Claude Desktop, OpenCode, and other Model Context Protocol clients over stdio.

Overview

This project is a replacement for the legacy Gramps MCP surface. It keeps the familiar read, analysis, create, update, delete, media, and convenience tools while putting every mutation through one serialized write pipeline. References are resolved at every registered depth, writes are read back from Gramps, and integrity scans report repair suggestions without changing records.

The tested target is Gramps Web API 3.19.0 with Gramps 6.0.8. Other Gramps Web 3.x releases are unverified compatibility targets. The MCP integration uses the experimental @effect/ai@0.37.0 package and has been tested with MCP protocol version 2025-06-18. See the dependency matrix for every exact Effect package pin.

Related MCP server: obsidian-modified-mcp-server

Install

Requirements:

• Node.js 22 or newer

• A reachable Gramps Web instance with an API user

git clone https://example.com/your/gramps-effect-mcp.git
cd gramps-effect-mcp
npm ci
npm run build

The compiled stdio server starts with:

npm start

It communicates on stdin and stdout. It doesn't open an HTTP port.

Config

Set the required connection variables in the MCP client's environment. Keep credentials in the client configuration or its secret store, not in this repository.

Client Wiring

Build the project first, then point the MCP client at the absolute path to dist/main.js. The same mcpServers entry works in Claude Desktop and MCP clients that use the standard JSON shape:

{
  "mcpServers": {
    "gramps": {
      "command": "node",
      "args": ["/absolute/path/to/gramps-effect-mcp/dist/main.js"],
      "env": {
        "GRAMPS_API_URL": "https://gramps.example.com",
        "GRAMPS_USERNAME": "your-api-user",
        "GRAMPS_PASSWORD": "set-this-in-your-client-secret-store"
      }
    }
  }
}

For Claude Desktop, add the entry to the application's MCP configuration and restart Claude Desktop. For OpenCode, add the same server command, arguments, and environment to its MCP configuration. Other stdio MCP clients need the equivalent command and environment fields. Don't run the server through a shell wrapper that writes status messages to stdout, since stdout is reserved for MCP JSON-RPC messages.

Operational Docs

Safety and capability model

• Deep resolution: Gramps IDs and opaque handles are resolved at every registered reference path before a write is sent. Free text isn't scanned for ID-like strings.

• Serialized writes: one semaphore covers reference resolution, mutation, read-back verification, and resolver cache invalidation for a complete logical write.

• Verified results: each returned handle is fetched again. Supplied semantic fields are compared with the canonical server form rather than raw request bytes.

• Integrity scans: scan_integrity reports stale references, reciprocal-link problems, and suggested repair tools. It doesn't mutate the tree.

• Capability states: metadata, JWT permissions, server media support, and local policy determine media exposure, upload, semantic-search, task-queue, and transaction availability. Transaction eligibility requires AddObject, EditObject, and DeleteObject permissions.

Gramps fills defaults, recalculates date sort values, normalizes handles, expands type values, and updates server-owned fields. The verifier accounts for these transforms. See server canonicalizations for the exact 3.19.0 behavior.

Write outcomes

The write pipeline has four outcomes. A client must not treat all four as interchangeable:

Mutation retries are disabled because a dropped response can't prove that Gramps received no request bytes. Reads retry only transport failures, rate limits, HTTP 429, and HTTP 5xx responses, using jittered exponential backoff with bounded attempts and elapsed time. See the retry policy for the exact schedule.

Media flags

Media exposure and upload are separate controls:

• GRAMPS_MEDIA_RESOURCES_ENABLED gates downloads and thumbnails returned to the MCP client. It defaults to false to prevent accidental file disclosure.

• GRAMPS_MEDIA_UPLOAD_ENABLED gates binary uploads. It defaults to true, but uploads still require server support, permissions, MIME approval, size approval, and read-back verification.

• GRAMPS_MEDIA_MAX_BYTES, GRAMPS_MEDIA_ALLOWED_MIME_TYPES, and GRAMPS_MEDIA_ALLOW_PRIVATE apply to both boundaries.

Disabling exposure doesn't disable upload. Disabling upload doesn't expose existing files.

ETags and concurrent writes

GRAMPS_IF_MATCH_ENABLED defaults to false for Gramps Web API 3.19.0. In the tested server, GET ETags hash response JSON while PUT compares an internal object digest that the item endpoint doesn't expose. A GET token therefore fails an immediate PUT precondition. Enable conditional writes only after proving that the target server returns a usable token. The full probe and decision are recorded in ETag findings.

The server still serializes and verifies writes when ETags are disabled. If a target has working conditional writes, overlapping field changes are rejected, while disjoint changes can be merged and retried once.

Secret Scanning

Install the tracked pre-commit hook once per clone:

npm run hooks:install

The hook requires gitleaks on PATH and scans staged changes before every commit. Scan the complete working tree manually with:

npm run secrets:scan

Test Commands

npm test
npm run test:live
npm run test:final
npm run typecheck
npm run build

• npm test runs the unit project without starting Gramps.

• npm run test:live boots a disposable loopback instance pinned to gramps-webapi==3.19.0 and Gramps 6.0.8. It requires uv and never uses GRAMPS_API_URL.

• npm run test:final runs final compliance and scope checks.

• npm run typecheck checks the strict TypeScript project without emitting files.

• npm run build compiles the stdio server into dist/.

The captured legacy tool schemas and parity baseline are in docs/legacy-tools.json. Final compliance tests check the production registry against that contract.