mcp-neo4j-biomechanisms

A schema-bounded MCP server for empirical neuroscience knowledge graphs in Neo4j.

The graph maps what peer-reviewed empirical neuroscience has measured about the biological substrate of consciousness — neural structures, circuits, manifold dimensions, lesion patients, falsification conditions, theoretical principles, evidence, studies. Every mutation goes through a tool that validates type, properties, and direction against a registry; there is no raw write-Cypher path. GDS analytics (PageRank, Betweenness, Louvain, WCC) are first-class, because the structure of the connected evidence reveals patterns no individual paper does.

Install

uv sync --dev

Requires Python ≥3.10, Neo4j ≥5.26 with the APOC and GDS plugins enabled, and a fulltext-capable database.

Run

# stdio (default; for Claude Desktop and similar)
uv run mcp-neo4j-biomechanisms --db-url bolt://localhost:7687

# streamable HTTP
uv run mcp-neo4j-biomechanisms \
  --transport http --server-host 0.0.0.0 --server-port 8000 --server-path /mcp/

All flags have environment-variable equivalents. CLI > env > default.

Transports: stdio, http (alias: streamable-http), sse.

Docker

docker compose up

The provided compose.yml runs the server in http mode on :8002 and connects to a Neo4j on the host (bolt://host.docker.internal:7687). Set NEO4J_BIOMECHANISMS_PASSWORD in the environment.

Tools

A --namespace foo flag prefixes every tool with foo-, useful when running multiple servers in one MCP client.

Ontology

8 node types. NeuralStructure, EdgeConfiguration, ManifoldDimension, Patient, FalsificationCondition, TheoreticalPrinciple, EmpiricalEvidence, Study.

12 relationship types, in four categories with enforced direction:

• Structural — CONNECTS_TO, PARTICIPATES_IN (NeuralStructure→EdgeConfiguration), GENERATES (EdgeConfiguration→ManifoldDimension), DECOMPOSES_INTO, COMPOSES_INTO
• Evidential — DEMONSTRATES (Patient→{ManifoldDimension,EdgeConfiguration} with effect enum), SUPPORTS, CHALLENGES
• Theoretical — EXPLAINS (TheoreticalPrinciple→…), WOULD_FALSIFY (with severity enum)
• Provenance — STUDIED_IN (Patient→Study), REPORTED_IN (EmpiricalEvidence→Study)

Property enums are enforced server-side: effect ∈ {collapse, preservation, severing, rerouting, gain_change}, severity ∈ {falsify, invalidate, constrain, weaken}, layer ∈ {data, envisioning, affective}. Every node carries an auto-set t_created; empirical claims carry t_valid for when the finding was true in the world (independent of when the graph learned it).

Use list_node_types and list_relation_types for the live, complete schema — those tools introspect the registry, so there is no separate documentation to drift.

GDS workflow

gds_create_projection {"name": "bio_full"}
gds_pagerank          {"projection": "bio_full"}
gds_betweenness       {"projection": "bio_full"}
gds_louvain           {"projection": "bio_full"}
gds_drop_projection   {"name": "bio_full"}

Projections survive across tool calls within a session; always drop them when done. Use node_types / rel_types filters on gds_create_projection for focused analyses (e.g. only NeuralStructure + EdgeConfiguration for circuit-level topology).

Development

uv run pytest                # 55 unit tests, no Neo4j required
uv run pyright src           # type check

Validation logic lives in biomechanisms.py and is fully tested without a database. The async driver only enters at the Neo4jBiomechanisms class boundary.

Operating the graph

HOWTO.xml is an LLM-facing operations manual for the entity using these tools — what node-type goes where, when to draw which edge, when to add a TheoreticalPrinciple versus extend an EmpiricalEvidence, why GDS is constitutive rather than decorative. Read it before populating the graph.

License

MIT — see LICENSE.