orphanet-link

A read-only Model Context Protocol (MCP) server that grounds rare-disease queries in Orphanet's scientific knowledge files (Orphadata).

It is backed by a locally-built, read-only SQLite + FTS5 database parsed from the eight English Orphadata XML products (nomenclature, cross-references, classifications, gene associations, HPO phenotypes, epidemiology, and natural history). The database is built in CI and published to GitHub Releases as a versioned artifact; the server downloads the prebuilt database at runtime and falls back to building locally when the artifact is unavailable.

orphanet-link is a sibling in the GeneFoundry "-link" fleet. It follows the same two-plane architecture and conventions as mondo-link and slots into genefoundry-router under the orphanet namespace.

Research use only. This server is not clinical decision support. It is not suitable for diagnosis, treatment, triage, or patient management. Every payload carries an unsafe_for_clinical_use signal. See the license section below.

Data source

Orphadata — the free-access scientific-knowledge file distribution of Orphanet (INSERM, Paris).

Eight English XML products are ingested; all are directly downloadable with no authentication:

License & attribution

Data are distributed under Creative Commons Attribution 4.0 International (CC BY 4.0). Redistributing a derived SQLite database is explicitly permitted under CC BY 4.0 provided attribution is given and changes are indicated.

Required citation (also available via orphanet://citation):

"Orphadata Science: Free access data from Orphanet. © INSERM 1999. Available on http://sciences.orphadata.com/. Data version [date/version]." Changes: "Converted Orphadata XML to a normalized SQLite database."

Related MCP server: medterms-mcp

Install

Python 3.12+ and uv are required.

git clone https://github.com/berntpopp/orphanet-link.git
cd orphanet-link
uv sync --group dev   # installs all runtime + dev dependencies

Build the database

Option A — prebuilt artifact (default, fastest)

The server auto-fetches the latest prebuilt orphanet.sqlite.gz from the GitHub Release on first startup when ORPHANET_LINK_DATA__PREFER_PREBUILT=true (the default). No manual step is required.

To force a fetch manually:

make data-fetch
# equivalent to:
uv run orphanet-link-data fetch

Option B — build locally from Orphadata XML

Downloads all eight XML products directly from Orphadata (~150 MB) and builds the normalized SQLite database locally:

make data
# equivalent to:
uv run orphanet-link-data build

Check what is currently built:

make data-status
# equivalent to:
uv run orphanet-link-data status

Conditionally refresh (rebuild only if any upstream file changed):

make data-refresh
# equivalent to:
uv run orphanet-link-data refresh

Example build stats

A typical build from a recent Orphanet release produces:

Run the server

Development (unified REST + MCP, auto-reload)

make dev
# equivalent to:
uv run python server.py --transport unified --host 127.0.0.1 --port 8000

The MCP endpoint is at http://127.0.0.1:8000/mcp.

stdio (for direct MCP client use)

make mcp-serve
# equivalent to:
uv run python mcp_server.py

Docker

make docker-build
make docker-up     # binds a free host port; prints the MCP URL
make docker-logs   # follow container logs
make docker-down

MCP client setup

Claude Code (HTTP transport)

claude mcp add --transport http orphanet-link http://localhost:8000/mcp

MCP config block (HTTP)

{
  "mcpServers": {
    "orphanet-link": {
      "transport": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Claude Code (stdio)

{
  "mcpServers": {
    "orphanet-link": {
      "command": "uv",
      "args": ["run", "python", "mcp_server.py"],
      "cwd": "/path/to/orphanet-link"
    }
  }
}

Tools (19 total)

All tools are READ_ONLY_OPEN_WORLD, accept response_mode (minimal / compact / standard / full, default compact), and follow the fleet's Response-Envelope-Standard-v1 (success / _meta / payload or error). _meta.next_commands carries ready-to-call follow-up suggestions in compact and richer modes.

Typical workflow

resolve_disease(query="Aicardi syndrome")
  -> get_disease(term="ORPHA:676")
      -> get_disease_genes / get_disease_phenotypes / get_disease_prevalence
      -> get_disease_classification / get_disease_ancestors
      -> map_cross_ontology

Follow _meta.next_commands rather than guessing the next tool.

Resources

The server exposes MCP resources under the orphanet:// scheme:

• orphanet://capabilities — full discovery contract (JSON)

• orphanet://tools — live tool overview

• orphanet://citation — required INSERM attribution string

• orphanet://license — CC BY 4.0 text + required attribution + changes note

• orphanet://research-use — research-use-only statement

• orphanet://usage — usage guide

• orphanet://reference — reference links

Development commands

make install        # uv sync --group dev
make format         # ruff format
make lint           # ruff check
make typecheck      # mypy --strict
make test           # pytest (unit only)
make test-cov       # pytest with coverage report
make ci-local       # format-check + lint-ci + lint-loc + typecheck + test-fast (the full gate)
make verify-deploy URL=<server>/health   # confirm deployed SHA matches local HEAD

Disclaimer

This server is for research use only. It is not clinical decision support and is not suitable for diagnosis, treatment, triage, or patient management. Orphanet data are provided under CC BY 4.0 by INSERM; this derived database is not an official Orphanet product and has not been validated by Orphanet or INSERM.