Metadata-Version: 2.5
Name: kgbcia-mcp
Version: 0.1.1
Summary: Read-only MCP server for the KGB-CIA biomedical knowledge graph
Project-URL: Repository, https://github.com/UNC-RENCI-KGAI/KGB-CIA
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: biolink-model==4.4.6
Requires-Dist: bmt<2,>=1.5.0
Requires-Dist: fastmcp==3.4.11
Requires-Dist: neo4j<6,>=5
Requires-Dist: pydantic<3,>=2
Description-Content-Type: text/markdown

# 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`](https://github.com/UNC-RENCI-KGAI/KGB-CIA/blob/main/agents/mcp_interface/AGENTS.md) in the
[KGB-CIA repository](https://github.com/UNC-RENCI-KGAI/KGB-CIA).

## Quick start

Requires [uv](https://docs.astral.sh/uv/) and Python 3.12 or newer. Add this to your MCP client's
configuration (for Pi, `.pi/mcp.json`). The Bolt host, artifacts URL and checksum change with
each release; get the current ones from the KGB-CIA team by opening an issue in the
[repository](https://github.com/UNC-RENCI-KGAI/KGB-CIA/issues).

```json
{
  "mcpServers": {
    "kgbcia-mcp": {
      "command": "uvx",
      "args": ["kgbcia-mcp", "serve", "--enable-cypher"],
      "env": {
        "NEO4J_URI": "bolt://<bolt-host>:7687",
        "NEO4J_DATABASE": "neo4j",
        "KGB_MCP_ARTIFACTS": "https://<public-artifact-host>/artifacts.tar.gz",
        "KGB_MCP_ARTIFACTS_SHA256": "<64-hex-artifact-checksum>"
      }
    }
  }
}
```

The shared Neo4j runs without authentication, so no user or password is needed. The server
downloads and verifies the artifacts tarball on first start.

## Tools

- `get_graph_info`, `get_schema`: counts, sources, build status, quality-flag counts and the
  category–predicate–category meta-graph, all precomputed.
- `search_nodes`, `get_node`: find nodes by CURIE, equivalent identifier, name or synonym.
- `summarize_node_edges`, `get_node_edges`: what a node connects to, with optional predicate,
  category, property and `exclude_flags` filters.
- `get_edges_between(include_lineage=true)`: every direct edge between two nodes with full
  lineage: the one-call answer to "why does A connect to B?".
- `find_paths`, `find_connected_nodes`: bounded multi-hop connections, skipping hub nodes.
- `explain_edge`: Biolink provenance, quality flags with reasons, and each source record
  resolved to its file, record set and columns.
- `query_cypher` (with `--enable-cypher`): read-only, row-capped Cypher for counts and patterns
  the fixed tools can't express. Column aliases are optional.

Every edge in a response carries its ID, predicate, primary knowledge source, publication count
and quality flags. To work on part of the graph (a gene family, a disease, a drug class), just
ask: the server's instructions tell the agent to resolve and confirm the seed nodes, then scope
its answers to them.

## 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` on PyPI](https://pypi.org/project/kgbcia-mcp/),
so it runs without the rest of the pipeline. Lineage beyond Biolink fields comes from each edge's
`kgbcia_source_records`, resolved against the `TransformReport`s (see
[`agents/AGENTS.md`](https://github.com/UNC-RENCI-KGAI/KGB-CIA/blob/main/agents/AGENTS.md)).

## Run it alone

Pipeline stage: an offline check that the final graph is ready to be dumped into Neo4j.

```bash
uv run kgb-mcp check --input <dir with nodes.jsonl and edges.jsonl>
# For a graph whose reports live outside data/transformation/:
uv run kgb-mcp check --input <graph-dir> --report <transform_report.json>
```

Prepare or refresh release artifacts:

```bash
# 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:

```bash
export NEO4J_URI=bolt://<host>:7687
# Only for an authenticated Neo4j (the local-k8s default); the AWS deployment has no auth:
export 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>
uvx kgbcia-mcp serve --enable-cypher               # stdio, the published package from PyPI
uv run kgbcia-mcp serve --enable-cypher            # stdio, this checkout's code (for development)
```

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), 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:

```bash
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 AWS host, use [`deploy/aws/README.md`](https://github.com/UNC-RENCI-KGAI/KGB-CIA/blob/main/agents/mcp_interface/deploy/aws/README.md).
It deploys only Neo4j from the same chart with `values-aws.yaml` 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 (`data/cleaning/`, the default) or `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:NamedThing`` anchor label. Categories are labels, not a
  `category` property; node CURIEs are in `id`.
- Relationship IDs are stored in `r.id`; provenance lists, including
  `kgbcia_source_records`, return as native Neo4j string arrays.
- `kgbcia_node_fulltext` is online over `name`, `synonym`, and the StringArray
  `equivalent_identifiers` property. The generated `kgbcia_relationship_id_*` range indexes are
  online for relationship `id` properties.
- The chart's `server.databases.default_to_read_only=true` rejects a graph `CREATE` through a
  raw driver session as well as through `query_cypher`.
- Neo4j Community permits the separate `kgbcia` account to create and drop users in `system`
  despite the graph database being read-only. AWS sets `NEO4J_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 deployment, and AWS deployment of the cleaned graph. Step 5, publication to PyPI, is
complete: [`kgbcia-mcp`](https://pypi.org/project/kgbcia-mcp/) is
published, so anyone can run `uvx kgbcia-mcp serve --enable-cypher` without a checkout.

Anyone can connect with the entry under "Quick start". Update `KGB_MCP_ARTIFACTS_SHA256` every
time a new `artifacts.tar.gz` is published.

Current verification:

- `get_graph_info()` returns 943,412 nodes and 11,701,010 edges and includes the `build` section
  from `description.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), and `rare_category_combination` (1,325).
- Flag formatting and `exclude_flags` were verified on `WIKIPATHWAYS:WP4580` -> `CHEBI:10034`
  (`biolink:has_participant`, edge `62c07ced-910e-5540-b2b6-3c4cdd94491f`):
  `get_edges_between(include_lineage=true)` returns `unresolved_node` and
  `rare_category_combination` as `{flag, reason}` pairs, and
  `get_node_edges(..., exclude_flags=["unresolved_node"])` filters those edges out.
- The issue #63 olodaterol (`CHEBI:82700`) -> ADRB2 (`UniProtKB:P07550`) `wrong_mechanism`
  example is **pending a future graph cleaned with #62 and #49**. In the current non-final graph,
  that DrugCentral edge cites PMID:20371707 but carries no `kgbcia_flags` /
  `kgbcia_flag_reasons` properties in the cleaned input, so the server correctly has no flag to
  report.

Known limits:

- `uvx kgbcia-mcp` runs the published release, not your checkout. To test local changes to the
  server, use `"command": "uv", "args": ["run", "kgbcia-mcp", ...]` from the repository root.
- `explain_edge(edge_id)` still unions over relationship types and can time out on the full
  graph for some edge IDs. Prefer `get_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 and resource limits
  bound expensive queries, but Neo4j Community does not provide a strong authorization boundary
  for the `system` database. Who can reach Bolt is set by the maintainer's AWS security group;
  open it widely only for as long as needed.
- `query_cypher` is 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. Add `LIMIT` to large queries: rows beyond the cap are discarded.

## Design decisions

- **Separate package:** `kgbcia-mcp` is a uv workspace member with no imports from `shared` or
  `agents`, 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.sh` computes graph summary,
  schema, property examples and flag counts on a temporary build-time Neo4j and writes them to
  `graph_metadata.json`. Runtime tools and validation use those artifacts and never scan the
  full graph for `get_graph_info()` or `get_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.dump` is 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 read-only user (`kgbcia`) to
  administer `system`; the AWS deployment therefore uses `NEO4J_AUTH=none` plus
  maintainer-controlled network exposure, graph read-only mode and resource limits rather than a
  reusable plaintext Bolt password.
- **Build description is an artifact:** `description.json` is 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.
