Save the graph schema, and serve it only against its own database

[adamjohnwright]

What

• reactome-mcp extract-schema — runs the server's own fetchGraphSchema() once against a database named with --uri (--database, --user, --password-env VAR, --out file; stdout without --out) and writes the schema JSON. One extractor; no second implementation.
• schemaFormat + source fingerprint on every schema: Neo4j version/edition, Reactome release from DBInfo (omitted when there is no DBInfo node), total node and relationship counts (count store), generatedAt.
• NEO4J_SCHEMA_FILE — with graph access on, the first schema request reads the file, takes the live fingerprint (4 cheap queries, not the extraction), and serves the file only if it matches. Different release / counts / Neo4j version, another schemaFormat, an incomplete snapshot, a missing or non-JSON/malformed file → a warning naming the reason and live extraction. A database that cannot be fingerprinted is not a match. With graph access off, the file is never read.
• README: saving the schema, the fingerprint guard, producing reactome-<release>-schema.json from the release pipeline, and Pointing at your own database for curators. CHANGELOG. Digest header now names the release.

Decisions worth a look

1. How the CLI gets past MCP_ALLOW_CYPHER. It sets NEO4J_URI + MCP_ALLOW_CYPHER=1 for its own process only, after its arguments validate, and then uses the same gated getDriver() — rather than adding a second, ungated way to build a driver. So it reads in the same READ sessions under the same timeouts. The gate test asserts the CLI imports no server/tool/resource/transport module, and that reactome-mcp extract-schema dispatches to it without building a server. Recorded as constitution 2.0.1 (PATCH) under Principle IV.
2. --uri is required; user/database/password fall back to NEO4J_USER/NEO4J_DATABASE/NEO4J_PASSWORD like the server. --password, --password=… and -p are refused (exit 2) without echoing the value; --password-env naming an unset variable is refused rather than silently connecting without credentials.
3. Incomplete schemas are never snapshotted: the CLI refuses to write one (exit 1), and the server rejects a file with unavailable sections — a snapshot is served for as long as the DB matches, so a gap would never be retried.
4. The CLI ignores an inherited NEO4J_SCHEMA_FILE so it always extracts rather than copying a matching snapshot.
5. Fingerprint compares version, edition, release, node and relationship counts; generatedAt is recorded but not compared. Release compares as a string (97 ≡ "97"). Snapshot JSON is validated field by field with zod, not cast (Principle I).
6. fetchGraphSchema() now asks the gate itself before touching the file or the DB (mutation-checked: removing it fails 5 gate tests).
7. Writes go to <out>.<pid>.partial then rename, so a failed run never leaves a truncated file.

Also fixed

build() in src/clients/neo4j.ts hooked SIGINT/SIGTERM/beforeExit on every driver build and never unhooked; a process that reconnected exceeded Node's listener warning. Now hooked once per process (test: 12 CLI runs add at most one listener).

Tests (fake driver; no real DB)

Written first and shown failing before the code: tests/extract-schema-cli.test.ts (structure equals the server's extraction + fingerprint, stdout/--out, no MCP_ALLOW_CYPHER needed, READ + timeouts, password refusal / env / --password-env, usage errors, incomplete schema, DB down, listener leak), tests/graph-schema-file.test.ts (matching file skips every expensive schema query; 11 mismatch cases + missing file fall back with a warning; no-DBInfo file vs no-DBInfo DB matches; unfingerprintable DB never served), additions to tests/graph-schema.test.ts (fingerprint, no-DBInfo), and the gate matrix (snapshot read 0 times closed / once open, per entrypoint and for fetchGraphSchema directly). The scripted 4.4 responder moved to tests/helpers/community44.ts, shared by three files.

npm run check green: lint, format, both typechecks, build, 268 tests.

Not done: no live smoke run against a real graph database — credentials for the local one were not available to this change, so the CLI and NEO4J_SCHEMA_FILE are verified against the fake driver only. Worth one manual run of extract-schema against the Release 97 container, then the server with NEO4J_SCHEMA_FILE, before merging.

🤖 Generated with Claude Code