Autopvs1 Link

Python 3.12+ CI Conformance License: MIT

An MCP (Model Context Protocol) server — and a REST API on the same process — serving PVS1 loss-of-function evidence for variants and CNVs from AutoPVS1, the automated ACMG PVS1 interpreter.

[!IMPORTANT] Research use only. Not clinical decision support. Do not use for diagnosis, treatment, triage, or patient management.

Why

AutoPVS1 has no API. It is a web form that renders results as HTML, so every programmatic consumer has to scrape and parse the page. This server does that once, defensively, and hands back typed JSON: the PVS1 strength, the flowchart decision path, and the disease-mechanism rows.

Doing it properly is the whole point. Parsers are pinned to committed HTML fixtures so an upstream DOM change fails CI instead of silently returning wrong evidence; a 1.0s courtesy delay and a 24h cache keep a chatty agent from hammering a service that never asked for the traffic; and every scraped payload carries a provenance note saying the fields came from unversioned HTML and may drift. Bulk and CNV entry points, which the web form has no equivalent for, come for free.

Quick start

Use the hosted deployment — no install, no upstream scraping of your own:

claude mcp add --transport http autopvs1 https://autopvs1-link.genefoundry.org/mcp

To run it locally (Python 3.12+, uv):

uv sync --group dev
cp .env.example .env
make dev            # REST + MCP on http://127.0.0.1:8000 (MCP at /mcp)

There is no data build — the server holds no local corpus and fetches from AutoPVS1 live. But outbound network access is denied by default, so a fresh checkout answers nothing until you opt in explicitly:

AUTOPVS1_LINK_API_EGRESS_MODE=allowlist
AUTOPVS1_LINK_API_ALLOWED_UPSTREAM_ORIGINS=https://autopvs1.bgi.com,https://rest.ensembl.org,https://grch37.rest.ensembl.org

Those public services receive the variant identifiers you submit. Do not point this profile at patient-derived data — see Configuration for the controlled-deployment alternative, and Deployment for stdio (Claude Desktop) and Docker.

Tools

Leaf names are unprefixed per Tool-Naming Standard v1 — namespacing is the gateway's job. Behind genefoundry-router this server mounts under the canonical namespace token autopvs1, so the tools above surface as autopvs1_<tool> (e.g. autopvs1_get_variant_pvs1_data, the pinned entry point).

A destructive clear_cache tool exists but is off the default surface; it registers only when AUTOPVS1_LINK_ENABLE_DESTRUCTIVE_TOOLS=true. Two MCP resources and two classification prompts ship alongside the tools. Response envelopes, response_mode / meta_mode token controls, pagination, and error codes are documented in the API reference; full schemas are in the generated tool catalog.

Data & provenance

• Upstream: AutoPVS1 (BGI). Genome builds hg19 and hg38; omitting the build defaults to hg38 and returns a warning.
• Refresh model: none — this server mirrors nothing. Every answer is scraped live from AutoPVS1's HTML and cached in memory (default 256 entries, 24h TTL). Upstream requests are spaced by a 1.0s rate-limit delay by contract; do not shorten it.
• Fragility: AutoPVS1's HTML is not a versioned contract. Scrape-tier responses carry an upstream_provenance note saying so, and _meta.unsafe_for_clinical_use is always true.
• Citation — cite AutoPVS1, not this wrapper:

  Xiang J, Peng J, Baxter S, Peng Z. AutoPVS1: An automatic classification tool for PVS1 interpretation of null variants. Human Mutation. 2020;41(9):1488-1498. DOI 10.1002/humu.24051, PMID 32442321.

Documentation

• Architecture — layered design, the technology stack, and the fleet federation contract.
• Configuration — every AUTOPVS1_LINK_* variable, the egress policy, and the legacy-prefix migration.
• Deployment — transports, Claude Desktop stdio, Docker, and the reverse-proxy boundary.
• API reference — REST endpoints, the response envelope, resources, and prompts.
• Tool catalog — generated input/output schemas for every tool.
• MCP evaluation checklist — the MCP contract checks.
• SECURITY.md · CHANGELOG.md · AGENTS.md

Contributing

Read AGENTS.md for engineering conventions — it is the contributor guide. make ci-local is the definition-of-done gate: format, lint, line budget, README standard, mypy, and tests. New parser behaviour needs an HTML fixture under tests/fixtures/.

License

Code: MIT © Bernt Popp. Data: PVS1 classifications are produced by the upstream AutoPVS1 service and remain subject to its terms; this repository redistributes none of them and asserts no licence over them. Research use only — mirror AutoPVS1's disclaimers and the citation above.