convez.ai
MCP Server
berntpopp

hgnc-link

berntpopp/hgnc-link

Ver no GitHub
InicialPluginScore · de 0 a 100

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-link

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 dias
Versão
v2.2.2
Issues abertas
2
Contribuidores
2

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

ToolPurpose
get_server_capabilitiesDiscovery surface (tools, signatures, workflows, vocab).
get_hgnc_diagnosticsLoaded release, counts, freshness, data-source status.
resolve_symbolAny symbol/ID → {hgnc_id, approved_symbol, match_type} + candidates.
resolve_symbols_batchResolve many symbols/IDs at once (never fails on a miss).
get_geneFull HGNC record (alias/previous aware).
search_genesFTS over symbol/name/alias/previous symbols.
get_gene_cross_referencesGene → NCBI/Ensembl/UniProt/RefSeq/MANE/OMIM/…
resolve_gene_by_xrefExternal ID → HGNC gene (reverse mapping).
get_gene_groupBrowse 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.

Ver o original no GitHub

Bom para

Relacionados