[adamjohnwright]

Puts the Cypher capability that #39 (22aec8b) removed back, switched off by default, so a publicly hosted instance can never run Cypher. Internal instances can point it at a dedicated Reactome graph database container.

The gate

Graph access exists only when both NEO4J_URI is set (non-blank) and MCP_ALLOW_CYPHER=1. There is one predicate, isGraphAccessEnabled() in src/graph/gate.ts, and it reads the environment at call time.

#39 removed the tools because the old gate was checked in four places and the HTTP entrypoint checked the wrong thing. This time the driver checks as well, so a surface that forgets the check still cannot connect:

Where	What happens with the gate closed
getDriver() (src/clients/neo4j.ts, the only file allowed to import neo4j-driver)	throws; no driver is constructed
registerCypherTools()	registers nothing
registerGraphResources()	registers nothing
permittedGroups(), applied by registerAllTools, registerAllResources and buildServerInstructions to any group list they are given	drops cypher
resolveToolGroups()	when unset, leaves out cypher; MCP_TOOL_GROUPS=…,cypher refuses to start
warmGraphSchema(), called by both entrypoints instead of each deciding for itself	does nothing (warns if NEO4J_URI is set without the opt-in)
/health, startup log	graphAccess: false

The tools join the #40 tool groups as a new group, cypher.

Tests, written first

tests/graph-access-gate.test.ts replaces no-graph-access.test.ts. It runs 6 env cases (neither variable, URI alone, opt-in alone, MCP_ALLOW_CYPHER=true, a blank URI, both) against 8 surfaces: the predicate, createServer, the registrars given every group explicitly, MCP_TOOL_GROUPS, the driver factory, the stdio entrypoint, the HTTP entrypoint, and startHttpServer over real HTTP. Each test counts driver constructions on a fake neo4j-driver. No test connects to Neo4j.

• Against main: 34 tests failed before the code was written.
• Against a plain git revert 22aec8b: NEO4J_URI alone > the HTTP entrypoint never constructs a driver failed. That is the door the old gate missed, and the new test catches it.
• Sabotage after the fix:
  • weakening getDriver's check fails 2 tests
  • also adding the old URI-only prefetch fails 4
  • skipping the filter in the instructions fails 5
  • dropping the registrar's own check fails 2

No APOC

The Reactome graph image runs Neo4j 4.4 Community without APOC, and the old schema code read apoc.meta.*. The schema now comes from built-in procedures only:

• dbms.components
• db.labels / db.relationshipTypes, with per-token counts from the count store
• db.schema.nodeTypeProperties, relTypeProperties and visualization
• SHOW INDEXES / SHOW CONSTRAINTS, falling back to db.indexes() / db.constraints()

Each section fails on its own and is reported as unavailable instead of being shown empty. If no section answers, the fetch throws and nothing is cached. tests/graph-schema.test.ts covers this with a fake driver that answers like 4.4 Community.

Read-only safety

• Every query runs in a READ-mode session with a server-side timeout.
• Row count, row width and total size are capped, and the global response cap still applies.
• The guard now also refuses LOAD CSV. It is a read clause, so READ mode allows it, and it fetches URLs.
• The guard can no longer be bypassed by // inside a string literal, by a comment that splits a procedure name, or by backtick-quoted names.

Checked against a real Release 97 container (read-only)

• Neo4j 4.4.48 Community. The schema fetch read every section in about 65 s (2.96M nodes, 108 labels, 88 relationship types).
• A CREATE was refused by the READ session, and the timeout fired.
• Over HTTP with only NEO4J_URI set: no Cypher tools were listed and no driver was opened.
• Over HTTP with both variables set: all three tools were listed and a query was answered.
• Rendered naively, the schema digest came to 87,000 characters, over the 40,000 cap. It now renders at 34,341.

Lockfile

Additions only. neo4j-driver, neo4j-driver-core and neo4j-driver-bolt-connection 6.2.0 are added, along with their own dependencies: rxjs 7.8.2, tslib 2.8.1, buffer 6.0.3, base64-js 1.5.1, ieee754 1.2.1, safe-buffer 5.2.1 and string_decoder 1.3.0. Each entry is byte-identical to the lockfile before the removal, and no existing entry changed.

Worth a look

• Constitution Principle IV is redefined (v2.0.0). It changes from "no Neo4j in any deployment" to "none on a public instance; internal instances opt in behind one gate that the driver enforces".
• Default changes:
  • NEO4J_DATABASE now defaults to the server's default database (previously graph.db).
  • NEO4J_PASSWORD now defaults to none, i.e. no credentials (previously neo4j).
• The timeout bounds time, not memory, and it is checked periodically. A 300 ms timeout ended a query after about 4 s. This is documented as another reason never to enable graph access publicly.
• The reactome://graph/schema resource is about 600 KB of JSON. Resources are not capped; this was also true before Remove graph database access rather than gating it #39.

🤖 Generated with Claude Code