{"id":50807009,"url":"https://github.com/berntpopp/spliceailookup-link","last_synced_at":"2026-06-13T02:06:36.965Z","repository":{"id":364359150,"uuid":"1266580831","full_name":"berntpopp/spliceailookup-link","owner":"berntpopp","description":"MCP + REST server for SpliceAI / Pangolin splice-impact prediction (Broad SpliceAI Lookup backends). Part of the -link family.","archived":false,"fork":false,"pushed_at":"2026-06-12T18:56:43.000Z","size":1157,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T19:14:56.105Z","etag":null,"topics":["bioinformatics","genomics","mcp","model-context-protocol","pangolin","spliceai","splicing","variant-interpretation"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/berntpopp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-11T18:52:56.000Z","updated_at":"2026-06-12T18:56:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/berntpopp/spliceailookup-link","commit_stats":null,"previous_names":["berntpopp/spliceailookup-link"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/berntpopp/spliceailookup-link","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berntpopp%2Fspliceailookup-link","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berntpopp%2Fspliceailookup-link/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berntpopp%2Fspliceailookup-link/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berntpopp%2Fspliceailookup-link/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/berntpopp","download_url":"https://codeload.github.com/berntpopp/spliceailookup-link/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berntpopp%2Fspliceailookup-link/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34269369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","genomics","mcp","model-context-protocol","pangolin","spliceai","splicing","variant-interpretation"],"created_at":"2026-06-13T02:06:36.260Z","updated_at":"2026-06-13T02:06:36.957Z","avatar_url":"https://github.com/berntpopp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# spliceailookup-link\n\nAn MCP (Model Context Protocol) + REST server that grounds **splicing-impact\nprediction** for genetic variants in the Broad Institute's\n[SpliceAI Lookup](https://spliceailookup.broadinstitute.org) backends — the same\n**SpliceAI**, **Pangolin**, and **SpliceAI-10k** consequence predictions the\nwebsite surfaces — exposed as LLM-ergonomic tools.\n\nPart of the `-link` family (gnomad-link, gtex-link, pubtator-link,\ngenereviews-link) and built to the same conventions: FastMCP, a thin FastAPI\nhost, structured error envelopes, `_meta.next_commands` chaining, capabilities\ndiscovery, and a research-use disclaimer.\n\n\u003e Research use only; not for clinical decision support.\n\n## Features\n\n- **predict_splicing** — one call resolves the variant, runs SpliceAI **and**\n  Pangolin, includes the SpliceAI-10k consequence prediction (exon skipping,\n  intron retention, frameshift), and reports whether the two models agree.\n- **predict_spliceai** / **predict_pangolin** — single-model delta scores.\n- **predict_splicing_batch** — score a whole gene panel in one call (server-side\n  fan-out under the concurrency cap; per-variant errors don't fail the batch).\n- **resolve_variant** — HGVS / rsID / loose coordinates → canonical\n  `CHROM-POS-REF-ALT` via Ensembl VEP (also returns gene + consequence;\n  multi-allelic rsIDs return a structured `variant_ids` list, never a stringified one).\n- **get_server_capabilities** — tools, parameters, score glossary, limits, plus a\n  `capabilities_version` content hash so warm clients can skip re-fetching it.\n- **warmup** — pre-warm the cold upstream before a burst.\n- GRCh37 + GRCh38; `raw`/`masked`; `basic`/`comprehensive` gene sets;\n  MANE-only or all transcripts; `compact`/`full`/`minimal` responses.\n- Build-mismatch pre-flight **and** an opportunistic cross-build probe on\n  `not_found`, aggressive caching, conservative rate limiting (the upstream is\n  interactive-use-only), and cross-server `see_also` hints to gnomad-link /\n  genereviews-link / gtex-link.\n- **Long-running calls are first-class**: every prediction tool emits MCP\n  progress notifications and opts into the 2025-11-25 background-task protocol\n  (`task=True`), so an agent can fire-and-continue instead of blocking on a 30 s+\n  cold call.\n- **Runtime observability**: every `_meta` carries `request_id` and\n  `timing.elapsed_ms`; prediction payloads add `cache` (`hit`/`miss`/`partial`)\n  and `upstream_elapsed_ms`.\n\n## Quick start\n\n```bash\nuv sync --group dev          # install\ncp .env.example .env         # optional: override hosts / limits\nmake dev                     # FastAPI /health + MCP HTTP at http://127.0.0.1:8603/mcp\nmake mcp-serve               # stdio MCP server (for Claude Desktop)\n```\n\n## MCP integration\n\nThe recommended transport is **streamable HTTP over HTTPS**, matching the sibling\n`-link` servers (gnomad-link, gtex-link, pubtator-link, genereviews-link). Put the\nserver behind a TLS-terminating reverse proxy and connect to its `https://` URL.\n\nHosted (HTTPS — Claude Code):\n\n```bash\nclaude mcp add --transport http spliceailookup-link https://spliceailookup-link.example.org/mcp\n```\n\nHosted (HTTPS — Claude Desktop / claude.ai connectors, `claude_desktop_config.json`):\n\n```json\n{ \"mcpServers\": { \"spliceailookup-link\": { \"type\": \"http\", \"url\": \"https://spliceailookup-link.example.org/mcp\" } } }\n```\n\nLocal development (HTTP on loopback only):\n\n```bash\nmake dev   # serves http://127.0.0.1:8603/mcp\nclaude mcp add --transport http spliceailookup-link http://127.0.0.1:8603/mcp\n```\n\nstdio (Claude Desktop, no network):\n\n```json\n{\n  \"mcpServers\": {\n    \"spliceailookup-link\": {\n      \"command\": \"spliceailookup-link-mcp\",\n      \"env\": { \"PYTHONUNBUFFERED\": \"1\", \"SPLICEAILOOKUP_LINK_LOG_LEVEL\": \"WARNING\" }\n    }\n  }\n}\n```\n\n\u003e TLS is terminated at your proxy (nginx / Caddy / npm); the app itself serves plain\n\u003e HTTP on its port, exactly like the sibling `-link` deployments.\n\n## Example\n\n```text\npredict_splicing(variant=\"NM_001089.3(ABCA3):c.875A\u003eT\", genome_build=\"GRCh38\")\n# -\u003e headline: \"ABCA3 (GRCh38): SpliceAI Δ=0.02; Pangolin Δ=0.05; models agree.\"\npredict_splicing(variant=\"chr8-140300616-T-G\")\n# -\u003e headline: \"TRAPPC9 (GRCh38): SpliceAI Δ=0.83; Pangolin Δ=0.85; models agree; predicted exon skipping.\"\n```\n\n## Tools\n\n| Tool | Purpose |\n|---|---|\n| `get_server_capabilities` | Discovery: tools, parameters, glossary, limits, citations |\n| `resolve_variant` | HGVS / rsID / loose input → `CHROM-POS-REF-ALT` + gene + consequence |\n| `predict_spliceai` | SpliceAI delta scores (+ optional SAI-10k consequence) |\n| `predict_pangolin` | Pangolin splice gain/loss scores |\n| `predict_splicing` | Combined SpliceAI + Pangolin + consequence (headline tool) |\n| `predict_splicing_batch` | Score many variants (gene panel) in one envelope, fanned out server-side |\n| `warmup` | Pre-warm the upstream Cloud Run containers before a burst |\n\n## Configuration\n\nAll environment variables are prefixed `SPLICEAILOOKUP_LINK_` (see `.env.example`).\nKey knobs: the scoring/Ensembl host templates, `REQUEST_TIMEOUT` (default 90s),\n`MAX_CONCURRENCY` (default 2 — the upstream is rate-limited), `CACHE_TTL_MINUTES`\n(default 1440), `RATE_BUDGET_MIN_INTERVAL_MS` (default 12000 — the soft client-pacing\ninterval surfaced as `_meta.rate_budget`), and `MCP_TRANSPORT`/`MCP_HOST`/`MCP_PORT`/`MCP_PATH`.\n\nBackground tasks use FastMCP's Docket backend. `DOCKET_URL` defaults to\n`memory://` (in-process, correct for the single-process unified host); set\n`SPLICEAILOOKUP_LINK_DOCKET_URL=redis://…` (or the FastMCP-native\n`FASTMCP_DOCKET_URL`) for a multi-worker deployment.\n\n## Development\n\n```bash\nmake ci-local        # format-check + lint + line-budget + typecheck + tests\nmake test            # deterministic unit tests\nmake test-integration   # live SpliceAI/Pangolin/VEP tests (marked, may be slow)\nmake docker-build \u0026\u0026 make docker-up\n```\n\n## Scope \u0026 boundaries\n\nIn scope: SpliceAI / Pangolin / SAI-10k splice prediction + variant resolution.\nOut of scope (delegated): allele frequency \u0026 ClinVar (gnomad-link), gene–disease\ncontext (genereviews-link), expression (gtex-link), liftover (gnomad-link), and\nthe AlphaMissense / PrimateAI / PromoterAI / CADD annotations shown on the website.\n\n## Citations\n\n- **SpliceAI** — Jaganathan K, et al. *Cell* 2019;176(3):535-548. PMID:30661751.\n- **Pangolin** — Zeng T, Li YI. *Genome Biology* 2022;23:103. PMID:35449021.\n- **SpliceAI-10k** — Canson DM, et al. *Bioinformatics* 2023.\n- **SpliceAI Lookup** — Broad Institute, https://spliceailookup.broadinstitute.org.\n- **Ensembl VEP** — https://rest.ensembl.org.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberntpopp%2Fspliceailookup-link","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fberntpopp%2Fspliceailookup-link","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberntpopp%2Fspliceailookup-link/lists"}