knowledge-graph-mcp¶
Source
Server lives at mcp/knowledge-graph-mcp/.
The content below is included verbatim from its README.md.
title: knowledge-graph-mcp¶
knowledge-graph-mcp — Model Context Protocol server for the EpiHack DuckLake knowledge graph¶
A Model Context Protocol server that
gives an LLM (Claude Desktop, Claude Code, the
agentic architecture for
EpiHack Arizona 2026, or any other MCP client) read-only access to
the project's DuckLake knowledge graph (kg.node / kg.edge /
kg.property as seeded under schema/).
Built for EpiHack Arizona 2026 — supports both the Wildlife & Vector-Borne Diseases and Heat focus groups.
Read-only. Mutations to the knowledge graph belong to the Validation Agent and dedicated write tooling, not the LLM. The single SQL escape hatch (
kg_sql) rejects anything that isn't aSELECT/WITH ... SELECTstatement and caps results at 5000 rows.
What it does¶
Core graph tools¶
| MCP tool | Backed by |
|---|---|
kg_node_lookup |
SELECT … FROM kg.node JOIN kg.property |
kg_neighborhood |
iterative kg.edge expansion (max depth 3) |
kg_path |
BFS over the undirected kg.edge projection (max depth 8) |
kg_search |
substring match against label / description / node_id |
kg_nodes_by_type |
SELECT … FROM kg.node WHERE node_type = ? |
kg_edges_by_predicate |
SELECT … FROM kg.edge WHERE predicate = ? |
kg_regions_at_point |
bounding-box lookup against lat/lon properties on county / tribe / region nodes |
kg_pathogens_by_vector |
kg.edge WHERE predicate = 'transmittedBy' AND object_id = ? |
kg_pathogens_by_focus |
kg.edge WHERE predicate = 'targetsFocusArea' AND object_id = ? |
kg_outbreak_check |
causedBy + optional occurredIn filter |
kg_resource_lookup |
kg.edge WHERE predicate = 'informs' AND object_id = ? |
kg_sql |
escape hatch: SELECT-only, 5000-row cap |
Aggregation tools (agency-dashboard wishlist)¶
These four tools cover the heavier rollups the agency-dashboard
sub-agent flagged. Each one would otherwise force a custom kg_sql
GROUP BY (or worse, a client-side scan) per page render; the
dedicated tools cap the surface area so dashboards can't silently
start scanning unbounded data.
| MCP tool | Use it for |
|---|---|
kg_observations_by_window |
Server-side rollup of kg.node(node_type='observation') bucketed by (iso_week, county_id, pathogen_id). Returns {observation_count, severity_max, triage_class_breakdown} per cell. |
kg_cluster_scan |
Wraps onehealth_agents.cluster.ClusterDetectionAgent (Tier-1 deterministic Poisson scan + Tier-2 Gamma-Poisson posterior). Returns the live calibrated ClusterAlert rows for a vertical. |
kg_milestone_intervals |
Joins kg.v_observation_timeliness against kg.node/kg.property and folds in per-observation cost totals from kg.agent_run. Returns one row per observation with the Figure-3 milestones + interval-in-minutes columns + cost summary. |
kg_normalize_diagnosis |
Maps free-text diagnosis (e.g. "plague", "Y. pestis", "Yersinia pestis", "A20.0", "58750007") to a canonical pathogen.* slug. Resolution order: exact ICD-10 → exact SNOMED CT → curated alias → substring → fuzzy SequenceMatcher. |
When to use which¶
| If you want to… | Use | Why not kg_sql? |
|---|---|---|
| Render a weekly heat-map or per-county chart of observations | kg_observations_by_window |
The tool de-dupes observations that have multiple county/pathogen edges; a naive GROUP BY over kg.property will double-count. |
| Show live cluster alerts on a dashboard | kg_cluster_scan |
The detector implements a calibrated two-tier rule (deterministic + Bayesian) that cannot be expressed in pure SQL. |
| Plot the Figure-3 timeliness clock or the cost panel | kg_milestone_intervals |
Hides the join shape of kg.v_observation_timeliness ⨝ kg.v_agent_run_cost and applies the vertical/agency filters once on the server. |
| Canonicalise an inbound SMS/voice/agency free-text diagnosis | kg_normalize_diagnosis |
Combines ICD-10 + SNOMED lookups, a curated alias table, and difflib fuzzy match — orders of magnitude more compact than re-implementing all five tiers per consumer. |
| Run a one-off ad-hoc query that doesn't fit any of the above | kg_sql |
Aggregation tools are intentionally narrow; the escape hatch covers the long tail. |
Resources¶
| Resource URI | Returns |
|---|---|
kg://node-types |
distinct node_type values currently loaded |
kg://predicates |
distinct edge predicate values currently loaded |
kg://schema |
text rendering of the kg.node / kg.edge / kg.property column shapes |
kg://aggregation-tools |
guidance describing each of the four aggregation tools and when to reach for them vs kg_sql |
Why this matters for EpiHack¶
The DuckLake knowledge graph is the project's shared memory: it
encodes which parameters belong to which categories, which milestones
precede which outbreaks, which pathogens are transmitted by which
vectors, which counties have which vector-control resources, and which
datasets / APIs inform which world-cafe questions. Exposing it as an
MCP server lets the agents in
plan/03-agentic-architecture.md
answer questions like:
- "For a
vector.ixodes_scapularissighting incounty.coconino, which pathogens should we worry about and is there an active outbreak record?" - "What resources
informsHeat-Q4 (vulnerable populations)?" - "What's the shortest path between
param.symptomsandpathogen.wnvin the graph?"
without writing SQL or shipping bespoke glue per consumer.
Data sources¶
Two operating modes:
- In-memory (default). Replays every
.sqlfile under$KG_SCHEMA_PATH(defaults to../../schemarelative to this package) into a fresh DuckDB. Load order: schema/knowledge_graph.sqlschema/system_designs.sqlschema/world_cafe.sqlschema/wildlife_vectors.sqlschema/heat.sql- every
schema/deep/*.sqlin alphabetical order
Files that fail to apply are logged and skipped — one broken seed won't take the server down.
- Attached DuckLake. Set
KG_DUCKLAKE_URI(e.g.ducklake:postgres:dbname=epihack host=localhost user=epihack) and the server installs/loads theducklake+postgresextensions, attaches the catalog, andUSEs it.KG_DUCKLAKE_DATA_PATHis forwarded as theDATA_PATHattach option.
Install & run¶
As a Claude Desktop MCP server¶
- Install
uvif you don't have it. - Drop the snippet in
examples/claude_desktop_config.jsoninto your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS,%APPDATA%\Claude\claude_desktop_config.jsonon Windows). - Replace the path with the absolute path to this directory.
- Optionally set
KG_SCHEMA_PATHorKG_DUCKLAKE_URI. - Restart Claude Desktop.
Standalone¶
bash
cd mcp/knowledge-graph-mcp
uv sync
uv run knowledge-graph-mcp # stdio (default)
MCP_TRANSPORT=streamable-http uv run knowledge-graph-mcp # HTTP
Tests¶
bash
cd mcp/knowledge-graph-mcp
uv run pytest
Tests cover three files:
tests/test_kg_tools.py— 22 cases against a six-node synthetic graph exercisingkg_node_lookup,kg_neighborhood,kg_path, the domain conveniences, and the SQL escape-hatch's SELECT-only enforcement.tests/test_aggregation.py— 7 cases per-tool against synthetic observation + audit-run seeds forkg_observations_by_window,kg_cluster_scan, andkg_milestone_intervals.tests/test_normalize_diagnosis.py— 11 cases asserting that the four canonical surface forms ("plague"/"Y. pestis"/"Yersinia pestis"/"A20.0") and the SNOMED 58750007 code all normalise topathogen.yersinia_pestis.
No live data is required.
Environment variables¶
| Variable | Default | Effect |
|---|---|---|
MCP_TRANSPORT |
stdio |
stdio or streamable-http |
KG_SCHEMA_PATH |
<repo>/schema |
Directory of .sql files to seed in-memory mode |
KG_DUCKLAKE_URI |
unset | Attach a real DuckLake catalog instead of in-memory mode |
KG_DUCKLAKE_DATA_PATH |
unset | DATA_PATH attach option for the DuckLake catalog |
Notes & limitations¶
kg_regions_at_pointis a coarse bounding-box lookup against thelat/lon(orlatitude/longitude, orcentroid_lat/centroid_lon) numeric properties on county / tribe / region nodes. The defaultschema/deep/counties.sqlandschema/deep/tribes.sqlseeds do not carry centroid properties today, so the tool returns an empty list against the stock graph. Loading a centroids seed (or attaching a DuckLake catalog that carries them) makes the tool light up automatically.- The SQL escape hatch is a single statement, SELECT-only, and capped
at 5000 rows; mutations, DDL,
ATTACH,COPY,PRAGMA, and multi-statement queries are all rejected.
License¶
MIT, alongside the rest of epihack-2026.