hgnc-link
berntpopp/hgnc-link
MCP server grounding gene-nomenclature work in the HGNC dataset (genenames.org): symbol/ID resolution, cross-references, search, gene groups — backed by a cron-refreshed local index.
Instalação
npx convez-ai berntpopp/hgnc-link1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
hgnc-link
An MCP (Model Context Protocol) + HTTP server that grounds gene-nomenclature work in the HUGO Gene Nomenclature Committee (HGNC) dataset from genenames.org.
It is a sibling of uniprot-link, gnomad-link, gencc-link, clingen-link,
etc., and shares their architecture: a FastAPI + FastMCP unified server, a typed
error envelope, {tool, arguments} chaining via _meta.next_commands, and
capabilities-as-resource discovery.
Why
Every downstream genetics tool needs the same thing from HGNC: turn any gene
symbol — current, outdated (previous), or alias — and any HGNC ID form into the
canonical {hgnc_id, approved_symbol}, then pull cross-references. hgnc-link
makes that a single fast call, with the match provenance and any ambiguity made
explicit instead of silently collapsed.
Speed: local index, refreshed by cron
For speed and reliability the server is backed by a local SQLite index built
from HGNC's bulk downloads (hgnc_complete_set.json + withdrawn.txt) and
refreshed by a cron-invoked CLI — no per-request REST round-trips. The live
rest.genenames.org API is used only as an optional fallback before the first
build completes.
# Build the index once (downloads ~33 MB, builds in seconds):
uv run hgnc-link-data build
# Cron entry point — conditional refresh (304-cheap; rebuilds only on change):
uv run hgnc-link-data refresh
# Inspect the loaded release:
uv run hgnc-link-data status
See docs/deployment.md for a crontab line and a systemd
timer.
Tools
| Tool | Purpose |
|---|---|
get_server_capabilities | Discovery surface (tools, signatures, workflows, vocab). |
get_hgnc_diagnostics | Loaded release, counts, freshness, data-source status. |
resolve_symbol | Any symbol/ID → {hgnc_id, approved_symbol, match_type} + candidates. |
resolve_symbols_batch | Resolve many symbols/IDs at once (never fails on a miss). |
get_gene | Full HGNC record (alias/previous aware). |
search_genes | FTS over symbol/name/alias/previous symbols. |
get_gene_cross_references | Gene → NCBI/Ensembl/UniProt/RefSeq/MANE/OMIM/… |
resolve_gene_by_xref | External ID → HGNC gene (reverse mapping). |
get_gene_group | Browse a gene family by group ID or name. |
Every response carries _meta.next_commands (a ready-to-call {tool, arguments}
list) on success and error. Response verbosity is controlled by
response_mode ∈ {minimal, compact, standard, full} (default compact).
Federation: the serverInfo.name is hgnc-link, and leaf tool names are
intentionally unprefixed per the GeneFoundry Tool-Naming Standard v1. The
canonical gateway namespace token is hgnc; when federated behind
genefoundry-router, tools surface as hgnc_<tool> (e.g. hgnc_resolve_symbol,
hgnc_resolve_gene_by_xref).
Quick start
make install # uv sync --group dev
make data # build the local HGNC index
make dev # unified REST + MCP server on http://127.0.0.1:8000/mcp
make mcp-serve # stdio MCP server (Claude Desktop)
make test # unit tests
Register with Claude Code (HTTP):
claude mcp add --transport http hgnc-link --scope user http://127.0.0.1:8000/mcp
Or stdio (Claude Desktop) — see claude-desktop-config.json.
Data & license
HGNC data is released with no usage restrictions (effectively CC0). Attribution is requested: Seal RL, et al. Genenames.org: the HGNC resources in 2023. Nucleic Acids Res. RRID:SCR_002827.
Research use only; not for clinical decision support.
Development
make check # format + lint
make typecheck # mypy --strict
make ci-local # format-check + lint + lint-loc + typecheck + tests
make test-integration # live HGNC download + REST asserts (opt-in)
Architecture details: docs/architecture.md.
Design spec: docs/superpowers/specs/2026-06-12-hgnc-link-design.md.