hpo-link

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.

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.

Related MCP server: Unofficial HPO MCP Server

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 for data authoring, and materialize-data for the hardened deployment init sidecar).

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.

Local data authoring can refresh from upstream with conditional GET (ETag / Last-Modified), but deployed servers do not. Production uses the immutable, digest-pinned release declared in container-release.json: hpo-data-init materializes it before the application starts, then the application reads the selected snapshot only. 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 init sidecar, 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.