MCP interface
Team: @UNC-RENCI-KGAI/mcp-interface
A read-only MCP server over a Neo4j copy of the final graph. Any MCP client, Pi included, can use it to search nodes, explore neighbors and paths, and explain any edge down to the source file, columns and record it came from ("why does A connect to B?").
The implementation spec is AGENTS.md in this directory.
How it fits together
final graph (nodes.jsonl, edges.jsonl) + transform_report.json files
-> orion-neo4j-dump + deploy/prepare_dump.sh -> kgb dump + artifacts tarball
-> Helm chart (deploy/helm/kgb-mcp): Neo4j 5 Community, read-only
<- kgbcia-mcp (this server), run locally over stdio by each MCP client
The server ships as its own package, kgbcia-mcp, so it can be installed from PyPI without the
rest of the pipeline. Lineage beyond Biolink fields comes from each edge's
kgbcia_source_records, resolved against the TransformReports (see agents/AGENTS.md).
Run it alone
Pipeline stage: an offline check that the final graph is ready to be dumped into Neo4j.
uv run kgb-mcp check --input <dir with nodes.jsonl and edges.jsonl>
# For a local development graph whose reports are outside data/transformation/:
uv run kgb-mcp check --input <graph-dir> --report <transform_report.json>
Prepare or refresh release artifacts:
# Full graph-to-dump release: runs ORION, then computes MCP statistics on a temporary Neo4j.
bash agents/mcp_interface/deploy/prepare_dump.sh \
--graph-dir <dir with nodes.jsonl and edges.jsonl> \
--reports-dir <dir containing transform_report.json files> \
--graph-metadata <merge-metadata.json or graph metadata JSON> \
--description data/describe/description.json \
--output-dir <prepared-output-dir> \
--graph-version <version>
# Artifacts-only refresh for an already deployed kgb.dump: skips ORION and copies the dump unchanged.
bash agents/mcp_interface/deploy/prepare_dump.sh \
--artifacts-only \
--existing-dump <existing kgb.dump> \
--reports-dir <dir containing transform_report.json files> \
--graph-metadata <merge-metadata.json or graph metadata JSON> \
--description data/describe/description.json \
--output-dir <prepared-output-dir> \
--graph-version <version>
MCP server, against a running Neo4j:
# Authenticated Neo4j (the local-k8s default): set both variables.
export NEO4J_URI=bolt://<host>:7687 NEO4J_USER=<user> NEO4J_PASSWORD=<password>
export KGB_MCP_ARTIFACTS=<dir or URL of the artifacts tarball>
export KGB_MCP_ARTIFACTS_SHA256=<required when artifacts is a URL>
uv run kgbcia-mcp serve --enable-cypher # stdio
uvx kgbcia-mcp serve --enable-cypher # once published to PyPI
An artifacts URL is downloaded and unpacked once, by checksum, into $KGB_CACHE_DIR/mcp-artifacts/
when KGB_CACHE_DIR is set (the pipeline's cache root, shared/paths.py), else
~/.cache/kgbcia-mcp/artifacts/.
For the local authenticated cluster, port-forward Bolt and source the local ignored deployment environment before starting Pi or the server:
kubectl -n <namespace> port-forward svc/kgb-mcp-neo4j 7687:7687
set -a; . agents/mcp_interface/deploy/.env; set +a
uv run kgbcia-mcp serve --enable-cypher
For the prepared AWS final host, use deploy/aws/README.md. It deploys
only Neo4j from the same chart with the LitCoin test overlay and keeps mcp.enabled=false; run
kgbcia-mcp locally over stdio against the host's Bolt Service.
Input / output
Input: nodes.jsonl and edges.jsonl in ORION KGX format (shared.schema.Node / Edge),
from the cleaning stage or, until that exists, data/transformation/merged/. Every edge must
have an id and a kgbcia_source_records list, except an edge the augmentation stage proposed
from the literature (primary_knowledge_source: infores:kgbcia-augmentor): it has no
transformation record, so it is accepted without one when it cites publications and names the
edges it refines in original_edge_ids, and check counts it on a line of its own. Plus the
per-source transform_report.json files under data/transformation/.
Output: check writes no graph files. kgbcia-mcp hubs writes hubs.json; the server
returns JSON-serializable, read-only query results. deploy/prepare_dump.sh produces the
Neo4j dump and artifact tarball (manifest.json, graph metadata, hubs and reports). The graph
metadata now includes precomputed counts for get_graph_info, get_schema, and argument
validation, so the running server does not scan the whole deployed graph for aggregate answers.
In --artifacts-only mode the script recomputes the artifact tarball from an existing dump and
copies that dump to the output unchanged.
Neo4j notes
Confirmed on the local-k8s Neo4j 5.26.31 load in November 2026:
- Every graph node has the
biolink:NamedThinganchor label. Categories are labels, not acategoryproperty; node CURIEs are inid. - Relationship IDs are stored in
r.id; provenance lists, includingkgbcia_source_records, return as native Neo4j string arrays. kgbcia_node_fulltextis online overname,synonym, and the StringArrayequivalent_identifiersproperty. The generatedkgbcia_relationship_id_*range indexes are online for relationshipidproperties.- The chart's
server.databases.default_to_read_only=truerejects a graphCREATEthrough a raw driver session as well as throughquery_cypher. - Neo4j Community permits the separate
kgbciaaccount to create and drop users insystemdespite the graph database being read-only. AWS setsNEO4J_AUTH=none, so there is no application account or reusable password, but an unauthenticated raw client can still create system users. Network exposure remains the maintainer's responsibility; graph writes remain blocked by the database-level read-only setting and resource limits.
Status
The MCP interface is deployed against the real cleaned graph on the prepared AWS k3s host. The
loaded graph has 943,412 nodes and 11,701,010 edges. Neo4j runs read-only with
NEO4J_AUTH=none; the MCP HTTP deployment is disabled (mcp.enabled=false), so teammates run
kgbcia-mcp locally over stdio and connect to the shared Bolt endpoint. Network exposure is
controlled by the maintainer outside this repository.
Build-order steps 1–4 are complete: the standalone uv workspace package, offline graph check,
artifact loading, TransformReport lineage, bounded Neo4j service, FastMCP tools, optional
Cypher tool, dump preparation, precomputed statistics, indexes, Docker image, Helm chart,
local-k8s sample deployment, AWS sample deployment, and AWS real-graph deployment. Step 5,
publication to PyPI, remains open; until then teammates run from a checkout with
uv run kgbcia-mcp serve --enable-cypher.
A teammate can connect from a checkout by adding an MCP entry like this, with placeholders filled
from the current release handoff. Update KGB_MCP_ARTIFACTS_SHA256 every time a new
artifacts.tar.gz is published.
{
"mcpServers": {
"kgbcia-mcp": {
"command": "uv",
"args": ["run", "kgbcia-mcp", "serve", "--enable-cypher"],
"env": {
"NEO4J_URI": "bolt://<aws-bolt-host>:7687",
"NEO4J_DATABASE": "neo4j",
"KGB_MCP_ARTIFACTS": "https://<public-artifact-host>/artifacts.tar.gz",
"KGB_MCP_ARTIFACTS_SHA256": "<64-hex-artifact-checksum>"
}
}
}
}
Current verification:
get_graph_info()returns 943,412 nodes and 11,701,010 edges and includes thebuildsection fromdescription.json.get_schema()returns a 116-row one-category meta-graph, avoiding the former whole-graph aggregate timeout.- Precomputed flag counts are present for
unresolved_node(1,914,123),type_violation(178,255),self_loop(2,435), andrare_category_combination(1,325). - Flag formatting and
exclude_flagswere verified onWIKIPATHWAYS:WP4580->CHEBI:10034(biolink:has_participant, edge62c07ced-910e-5540-b2b6-3c4cdd94491f):get_edges_between(include_lineage=true)returnsunresolved_nodeandrare_category_combinationas{flag, reason}pairs, andget_node_edges(..., exclude_flags=["unresolved_node"])filters those edges out. - The issue #63 olodaterol (
CHEBI:82700) -> ADRB2 (UniProtKB:P07550)wrong_mechanismexample is pending a future graph cleaned with #62 and #49. In the current non-final graph, that DrugCentral edge cites PMID:20371707 but carries nokgbcia_flags/kgbcia_flag_reasonsproperties in the cleaned input, so the server correctly has no flag to report.
Known limits:
- The package is not yet on PyPI; use
uv runfrom a checkout. explain_edge(edge_id)still unions over relationship types and can time out on the full graph for some edge IDs. Preferget_edges_between(include_lineage=true)when endpoint IDs are known; it returns the same lineage for direct edges with an anchored query.- AWS uses unauthenticated Bolt. Read-only graph settings block graph writes, but Neo4j
Community does not provide a strong authorization boundary for the
systemdatabase. Keep Bolt exposure restricted. query_cypheris read-only, row-capped and useful for ad hoc aggregates, but expensive raw queries can still hit the configured 30-second transaction timeout or 2 GiB transaction memory cap.
Design decisions
- Separate package:
kgbcia-mcpis a uv workspace member with no imports fromsharedoragents, so it can be published independently from the pipeline code. - Local stdio server, shared Neo4j: each client runs the MCP server locally over stdio while all clients share one read-only Neo4j service. This avoids deploying and authenticating a public MCP HTTP endpoint for the demo.
- Precomputed artifacts for aggregate answers:
prepare_dump.shcomputes graph summary, schema, property examples and flag counts on a temporary build-time Neo4j and writes them tograph_metadata.json. Runtime tools and validation use those artifacts and never scan the full graph forget_graph_info()orget_schema(). - One category per node in the meta-graph: nodes carry ancestor labels, so the meta-graph uses the rarest graph-wide category label per node to avoid cross-products over all ancestors.
- Indexes baked into the dump: the deployed database starts read-only, so the full-text node
index and relationship-id indexes are created before the final
kgb.dumpis produced. - Checksum-keyed loads: Helm init containers key their PVC marker on the dump checksum, not the URL, so changing presigned URLs does not reload an unchanged dump.
- AWS auth disabled: Neo4j Community allowed the authenticated sample user to administer
system; the AWS deployment therefore usesNEO4J_AUTH=noneplus maintainer-controlled network exposure, graph read-only mode and resource limits rather than a reusable plaintext Bolt password. - Build description is an artifact:
description.jsonis generated on the VM that has the Nov 9 transformation output and cleaning report, then sanitized and packed into the artifact tarball so user-facing tools can mention failed or missing sources.
Metadata
Release files for kgbcia-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kgbcia_mcp-0.1.0.tar.gz | 29.2 kB | Without provenance | Details for kgbcia_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kgbcia_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for kgbcia_mcp-0.1.0-py3-none-any.whl |
Total release size: 60.4 kB
Release files / kgbcia_mcp-0.1.0.tar.gz
| Download URL | kgbcia_mcp-0.1.0.tar.gz |
|---|---|
| Size | 29.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2e3af540589652fe05a6b81ea0bcc8e061ead2d00f75f55bbf565cd69a36fa6a
|
|
BLAKE2b-256 checksum How to use checksums |
1982ea5d564406c66a9a5b5ee8990b41df5567d8a43f41092af6c80e0d00ea4e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.5
|
Release files / kgbcia_mcp-0.1.0-py3-none-any.whl
| Download URL | kgbcia_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 31.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7a4494460159a4fef3ef1a791cb00c11dbaf89848b6c4198e97a2c8fcd662c32
|
|
BLAKE2b-256 checksum How to use checksums |
4307ae4085cf21f0a6d7191c3543b3c7cc2e16eb0e2ad6b73b7bd7acbb19418d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.5
|
Security for kgbcia-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.