Hpo Link

Python 3.12+ CI Conformance License: MIT

An MCP server (Streamable HTTP or stdio) that grounds phenotype work in the Human Phenotype Ontology (HPO): term lookup, the is_a hierarchy, cross-ontology mapping, and gene↔phenotype↔disease associations, served read-only from a local index of the HPO release and its HPOA annotations.

[!IMPORTANT] Research use only. Not clinical decision support. Do not use for diagnosis, treatment, triage, or patient management.

Why

HPO ships as bulk artifacts — an OBO/JSON ontology graph (hp.json) and a flat annotation table (phenotype.hpoa). Neither answers a question. "Which genes are annotated to seizure, including its subtypes?" needs the transitive is_a closure over a multi-parent DAG, a synonym/xref index to get from free text to HP:0001250, and a join against HPOA — plumbing every consumer otherwise rebuilds, badly.

hpo-link builds that once into a read-only SQLite index (closure table, FTS over names/synonyms/definitions, xrefs ranked by mapping predicate) and serves it as MCP tools. No upstream call sits in the request path, so lookups are offline and deterministic, and every response cites the HPO id and the HPO release it came from.

Quick start

Hosted — no install:

claude mcp add --transport http hpo-link https://hpo-link.genefoundry.org/mcp

Local (Python 3.12+, uv):

uv sync --group dev   # install
make data             # REQUIRED: download HPO + HPOA and build the local database
make data-status      # loaded HPO release + counts
make dev              # unified REST + MCP on http://127.0.0.1:8000 (/mcp, /health)

There is no data until make data (uv run hpo-link-data build) has run once.

claude mcp add --transport http hpo-link --scope user http://127.0.0.1:8000/mcp
make mcp-serve        # stdio instead, for Claude Desktop (stdout is the protocol)

Three console scripts: hpo-link (unified server), hpo-link-mcp (stdio), hpo-link-data (build / refresh / status).

Tools

Every response carries _meta.next_commands (ready-to-call follow-ups). Ids are normalised to HP:NNNNNNN. response_mode ∈ minimal | compact | standard | full (default compact) trades detail for tokens. Worked examples: docs/usage.md.

Leaf names are unprefixed per Tool-Naming Standard v1 (serverInfo.name = hpo-link); behind genefoundry-router the gateway applies the canonical namespace token hpo, so they surface as hpo_<tool> — e.g. hpo_resolve_term.

Data & provenance

Built from two upstream artifacts: the HPO ontology (hp.json, via the OBO PURL http://purl.obolibrary.org/obo/hp.json) and the HPOA annotations (phenotype.hpoa), which link HPO terms to OMIM / Orphanet / DECIPHER diseases and, derived from those, to genes.

Refresh is a conditional GET (ETag / Last-Modified); a 304 reuses the local file, so make data-refresh is cheap and rebuilds only on a new release. Builds are atomic and lock-serialised, and the loaded release is reported by get_diagnostics. A prebuilt database can be pulled instead of built (HPO_LINK_DATA__PREBUILT_DB_URL). Details: docs/data.md.

Data licence: HPO is distributed under a custom licence for research and educational use (https://hpo.jax.org/app/license) — attribution required.

Cite: Köhler S, Gargano M, Matentzoglu N, et al. The Human Phenotype Ontology in 2021. Nucleic Acids Research 2021;49(D1):D1207–D1217. doi:10.1093/nar/gkaa1043. For the most recent release cite instead: Gargano MA, Matentzoglu N, Coleman B, et al. The Human Phenotype Ontology in 2024: phenotypes around the world. Nucleic Acids Research 2024;52(D1):D1333–D1346. doi:10.1093/nar/gkad1005.

Documentation

• Usage — per-tool examples, the citation contract, typical workflows.
• Architecture — the two planes, ingest pipeline, SQLite schema, request lifecycle.
• Data & provenance — sources, freshness, build integrity, prebuilt artifacts, licence.
• Configuration — every HPO_LINK_* variable and the Host/Origin/CORS allowlists.
• Deployment — Docker, refresh scheduling, health and deploy verification.
• AGENTS.md — engineering conventions, invariants, definition of done.

Contributing

See AGENTS.md for the invariants and conventions. make ci-local is the definition-of-done gate: format, lint, line budget, README standard, mypy, and tests. Write the failing test first.

License

MIT © Bernt Popp — code only. The HPO data is licensed separately for research and educational use with required attribution (https://hpo.jax.org/app/license); see Data & provenance.