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.

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.

Variable	Default	Description
GRAMPS_API_URL	Required	Gramps Web base URL, for example https://gramps.example.com. Trailing slashes are removed.
GRAMPS_USERNAME	Required	Gramps Web API username.
GRAMPS_PASSWORD	Required	Gramps Web API password. It is held as a redacted value by the application.
GRAMPS_TEST_API_URL	Unset	Optional API URL for test configuration. Production clients normally leave this unset.
GRAMPS_IF_MATCH_ENABLED	false	Enables conditional writes only when the server supplies an ETag accepted by PUT preconditions. Leave disabled for 3.19.0.
GRAMPS_READ_RATE_LIMIT	10	Maximum number of GET attempts started per second, including retries.
GRAMPS_HTTP_TIMEOUT_MS	30000	HTTP request timeout in milliseconds.
GRAMPS_RETRY_MAX_ATTEMPTS	5	Maximum read attempts, including the first request. Mutations are never retried automatically.
GRAMPS_MEDIA_RESOURCES_ENABLED	false	Allows MCP clients to read media file and thumbnail bytes.
GRAMPS_MEDIA_UPLOAD_ENABLED	true	Allows media uploads through the verified write pipeline. Independent of media exposure.
GRAMPS_MEDIA_MAX_BYTES	10485760	Maximum exposed or uploaded media size in bytes, 10 MiB by default.
GRAMPS_MEDIA_ALLOWED_MIME_TYPES	image/jpeg,image/png,application/pdf	Comma-separated allowlist used by media exposure and upload policy.
GRAMPS_MEDIA_ALLOW_PRIVATE	false	Allows media marked private to cross the media boundary.

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:

Outcome	Meaning	Operator action
VerifiedCommitted	Gramps committed the write and a fresh read matched the requested semantic fields.	Continue normally.
CommittedVerificationFailed	Gramps committed the write, but read-back verification found missing or different fields.	Inspect the returned reference and problems before another write. Don't retry blindly.
RejectedBeforeMutation	Validation, resolution, permissions, conflict checks, or another pre-mutation step rejected the operation. Compound operations can still report refs committed by earlier sequential steps.	Correct the reported error. Review any returned refs before retrying a compound operation.
CommitIndeterminate	A transport failure happened after mutation bytes may have been sent, so commit status can't be proven. Compound operations can report earlier committed refs.	Read the target state before deciding whether to retry.

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.