# AlphaFold Sovereign MCP Answering a structural-biology or variant question usually means querying many public databases by hand — AlphaFold DB, Open Targets, ClinVar, gnomAD, and more — and reconciling their formats. This server wraps those sources behind one set of MCP tool calls that run as a local process on your own machine, with no hosted service of ours in the path, no telemetry, and a local SQLite knowledge graph that never leaves your disk. In the default online mode the tools query those public upstreams directly, so the identifiers you look up are sent to them (and one, DisGeNET, needs its own free API key); set `ALPHAFOLD_OFFLINE=1` to refuse outbound requests before any socket opens, so no identifier leaves the machine (the knowledge-graph tools still answer from local data; the upstream tools report their source as unavailable). "Sovereign" here means local-first — your compute and stored results stay on your machine — not that the server runs without a network. A Model Context Protocol server — an AlphaFold MCP server — that wraps AlphaFold DB and 8 other public biomedical data sources behind a set of MCP tool calls, with a conditional UniProtKB request to verify explicitly requested displayed isoforms. It is backed by a local SQLite knowledge graph with query and export tools (results can be persisted through its API; automatic per-invocation persistence is not yet wired). This is an unfunded, independent open-source project. It is not a service, not certified for any regulated use, and its outputs are research aids that should be reviewed by qualified humans before any clinical or regulatory use. **Research authorship:** Santiago Maniches (ORCID [0009-0005-6480-1987](https://orcid.org/0009-0005-6480-1987)) independently directs and maintains this server and is the sole scientific author of its original research contributions. AI-assisted tools have supported coding, testing, and internal review. They are not scientific coauthors, clinical validators, or a substitute for independent evaluation. The public databases, prediction models, and existing algorithms remain credited to their sources. This project is not affiliated with, endorsed by, or sponsored by Google DeepMind or EMBL-EBI. "AlphaFold" is a trademark of its respective owner and is used here only to describe the public data (the AlphaFold DB API) that this software consumes. [![CI](https://github.com/smaniches/alphafold-sovereign-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/smaniches/alphafold-sovereign-mcp/actions/workflows/ci.yml) [![Docs](https://github.com/smaniches/alphafold-sovereign-mcp/actions/workflows/docs.yml/badge.svg)](https://smaniches.github.io/alphafold-sovereign-mcp/) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/smaniches/alphafold-sovereign-mcp/badge)](https://api.securityscorecards.dev/projects/github.com/smaniches/alphafold-sovereign-mcp) [![Release](https://img.shields.io/github/v/release/smaniches/alphafold-sovereign-mcp?sort=semver)](https://github.com/smaniches/alphafold-sovereign-mcp/releases) [![PyPI](https://img.shields.io/pypi/v/alphafold-sovereign-mcp?label=PyPI)](https://pypi.org/project/alphafold-sovereign-mcp/) [![PyPI downloads/30d](https://img.shields.io/pypi/dm/alphafold-sovereign-mcp?label=downloads%2F30d)](https://pypistats.org/packages/alphafold-sovereign-mcp) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml) [![MCP Spec 2025-06-18](https://img.shields.io/badge/MCP-2025--06--18-purple)](https://modelcontextprotocol.io) [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/smaniches/alphafold-sovereign-mcp/actions/workflows/ci.yml) [![ORCID](https://img.shields.io/badge/ORCID-0009--0005--6480--1987-A6CE39?logo=orcid&logoColor=white)](https://orcid.org/0009-0005-6480-1987) [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20134773-3C5A99?logo=zenodo&logoColor=white)](https://doi.org/10.5281/zenodo.20134773) [![Glama score](https://glama.ai/mcp/servers/smaniches/alphafold-sovereign-mcp/badges/score.svg)](https://glama.ai/mcp/servers/smaniches/alphafold-sovereign-mcp) [![Awesome MCP Servers](https://img.shields.io/badge/Awesome_MCP-Listed-blue?logo=github)](https://github.com/punkpeye/awesome-mcp-servers#bio) **Status:** Beta. Engineering-validated (100% line and branch coverage). Not yet scientifically validated by independent domain experts; not yet deployed in production. See [`STATUS.md`](STATUS.md) and [`LIMITATIONS.md`](LIMITATIONS.md). --- ## What this is A Python MCP server that: - Wraps AlphaFold DB, MONDO, HPO, Open Targets, ClinVar, gnomAD, DisGeNET, ChEMBL, and Ensembl behind MCP tool calls. Explicit numbered isoforms may also trigger a UniProtKB sequence-and-identity check. Each call preserves upstream records and their provenance. Retrieval is not a new biological observation; derived workflows are explicitly identified as Topologica calculations rather than source-reported findings. - Composes upstreams into multi-source workflows: variant cross-reference reports, disease–target landscape summaries, heuristic target-druggability scoring, drug-repurposing candidate ranking, and cross-species structural-distance computation. - Ships a local SQLite knowledge graph (`storage/knowledge_graph.py`) with query, export, and traversal tools. Fresh installations begin without automatically inserted biomedical records; data is stored by explicit writes through the knowledge-graph API. Existing SQLite files are preserved, including illustrative rows from earlier releases; historical numerical values are not independently validated source records. Analysis tools do not automatically persist their results. - Includes an exploratory Cα-derived feature-vector module. With the optional `[tda]` extra (`gudhi`), it reports H₀/H₁ terminal-filtration Betti numbers; H₂ is not computed. The fallback reports a 4-Å contact graph component count and geometric features, not persistent homology. L2 distance between those feature vectors is not a calibrated measure of protein homology or biological function. It targets `mcp-spec 2025-06-18` and is CI-tested on Python 3.11–3.13. Python 3.10 reached upstream end of life on 1 October 2026 and is no longer supported. New installs require Python 3.11+. The runtime requires patched `dnspython>=2.9.0` (CVE-2026-114605); optional documentation builds require `pillow>=13.0.0` to avoid the affected Pillow 12 line. Existing Python 3.10 users should upgrade their interpreter before upgrading this package. **AlphaFold DB compatibility:** the prediction API announced modern model and sequence field names and a legacy-field sunset in June 2026. The sampled live API still exposes old aliases as of 9 October 2026. The client uses the current fields, retains legacy-response compatibility, and selects the exact requested UniProt accession when the API returns multiple isoforms. See the [API compatibility notes](docs/afdb-compatibility.md) for the migration contract, remaining fragment limitations, and the optional October 2026 PDBe/IUCr literature-annotation evidence client. Those annotations are upstream PDBe research, not an independent AlphaFold Sovereign scientific discovery. ## Evidence responsibility AlphaFold Sovereign MCP does not develop or validate AlphaFold's underlying structure predictions, MONDO ontology assertions, UniProt annotations, or ClinVar submissions. Those belong to the cited source and retain their source-reported confidence and limitations. Topologica **is responsible** for reliable retrieval, accession identity, cross-source joins, reproducible local calculations, provenance attribution, and honest failure/uncertainty reporting. An inference made from a predicted structure remains conditional on that prediction; it does not become an experimental observation because it is joined to another database. Derived heuristics are research aids, not source-validated clinical conclusions. **ClinVar identity boundary:** A gene-relative expression such as `BRCA1:c.181T>G` discovers possible records but does not identify a unique reference allele; results are labelled *unverified candidates* and their classifications cannot be assigned to that query. A matching versioned transcript expression such as `NM_007294.4:c.181T>G` permits only a literal transcript-title match. ClinVar Variation IDs can represent sets of alleles; neither match level establishes independent clinical equivalence or a patient-specific classification. Source failures are reported separately from absent matches. No cross-transcript equivalence is assumed. ## What this is **not** - It is **not** a hosted service or a SaaS. - It is **not** certified for any regulated use (HIPAA, GxP, 21 CFR Part 11, FedRAMP, FIPS, SOC 2). The code structures audit logging in a way that could later support such a certification, but no such audit has been performed. - It does **not** train, fine-tune, or publish AlphaFold models — it consumes AlphaFold DB's public REST API. - Variant-report evidence is a **provisional computational signal** for expert review, not established ACMG/AMP criteria. The `classify_variant_acmg` tool does not assign a clinical class when gene–disease mechanism and criterion-specific evidence are unverified. - The "druggability tier" that `assess_target_druggability` returns is a **heuristic** built from drug-precedent counts, Open Targets tractability labels, pLDDT, and gnomAD constraint. It is not a validated prediction. - "Structural distance" is an L2 distance on derived Cα feature vectors. It is not sequence identity, RMSD, persistence-diagram Wasserstein distance, validated homology, or functional equivalence. Methods are reported separately rather than sorted on incompatible scales. - The AlphaFold structures consumed here are *predicted* models with per-residue pLDDT confidence, not experimental structures. Low-pLDDT regions are unreliable; some proteins (BRCA1 among them) are largely low-confidence, and structural inference over those regions should be treated with caution. For a complete, itemised list of known limitations (with module references, impact, and planned resolution), see [`LIMITATIONS.md`](LIMITATIONS.md). For the high-level posture — what is engineering-validated vs. what is not yet scientifically validated — see [`STATUS.md`](STATUS.md). --- ## Install ### From PyPI (recommended) ```bash pip install alphafold-sovereign-mcp ``` Or run it without installing using `uvx`: ```bash uvx alphafold-sovereign-mcp ``` Every release on PyPI is built by the `release.yml` workflow under OIDC Trusted Publishing and attached to a signed GitHub Release with Sigstore (`cosign`) signature bundles, a CycloneDX SBOM, and a Zenodo DOI mirror. SLSA L3 build provenance is generated in CI by `slsa-github-generator`; attaching the attestation to each release is a roadmap item. `scripts/replicate.sh` downloads the exact published wheel and sdist, recomputes their PyPI SHA-256 digests, verifies the GitHub Release Sigstore bundles against those bytes and this repository's release workflow identity, and independently verifies that the released CycloneDX SBOM is bound to the downloaded wheel. If SLSA provenance is attached to a future release, the same script verifies it against the wheel when `slsa-verifier` is installed. ### From source ```bash git clone https://github.com/smaniches/alphafold-sovereign-mcp cd alphafold-sovereign-mcp uv pip install -e . # With persistent-homology TDA (requires gudhi): # uv pip install -e ".[tda]" ``` ### Verify the install ```console $ alphafold-sovereign --version 1.5.9 $ alphafold-sovereign --self-test SELF-TEST PASS - ACMG helpers behave as expected on the BRCA1 c.5266dupC fixture. ``` If you ran it via `uvx` without installing, use `uvx alphafold-sovereign-mcp --self-test` instead (the bare `alphafold-sovereign` script is only on PATH after a pip/uv install). `--self-test` runs fully offline: it checks the deterministic ACMG-evidence helpers (VEP, gnomAD, and AlphaMissense mapped to ACMG criteria) against a built-in `BRCA1:c.5266dupC` fixture. Returns exit code 0 on PASS, non-zero on FAIL. No network calls, no credentials required. ### Configure Claude Desktop Add to `claude_desktop_config.json`: ```json { "mcpServers": { "alphafold-sovereign": { "command": "alphafold-sovereign-mcp", "args": [] } } } ``` Restart Claude Desktop and the tools become available in conversations. Try asking, for example: *"Triage BRCA1 c.5266dupC"* or *"Assess EGFR as a drug target"*. See [`examples/`](examples/) for source-retrieval workflow guidance. The previous illustrative clinical-session transcripts were retired. ### Offline mode ```bash ALPHAFOLD_OFFLINE=1 alphafold-sovereign-mcp ``` Refuses outbound HTTP before a socket is opened (raising `AirGapError`), except to hosts you explicitly allowlist via `ALPHAFOLD_ALLOW_HOSTS`. The knowledge-graph query and export tools still answer from the local SQLite store. The upstream-querying tools have no local cache and report their source as unavailable; note that the structure tools currently surface this as a "no AlphaFold model" result rather than an explicit offline error. --- ## Tool inventory The server exposes 29 MCP tools across four modules. Each tool's input schema is a Pydantic model; results are JSON. ### Disease & ontology (`tools/disease.py`) | Tool | What it does | |---|---| | `lookup_disease` | MONDO record + hierarchy + ICD cross-references | | `search_diseases` | Full-text MONDO ontology search | | `lookup_phenotype` | HPO term + associated diseases | | `get_gene_phenotype_profile` | HPO phenotypes + gnomAD constraint for a gene | | `get_disease_targets` | Top drug targets for a MONDO disease (Open Targets) | | `get_target_diseases` | Top diseases for a UniProt target (Open Targets) | | `get_common_disease_targets` | Parallel profiling across curated MONDO diseases | | `triage_variant_3d` | HGVS → ClinVar + gnomAD constraint (disease/structure context: pointer notes) | | `phenotype_to_structures` | HPO → diseases → OT targets → UniProt IDs | | `compare_disease_target_overlap` | Jaccard similarity of target sets for two diseases | | `resolve_icd10_to_mondo` | ICD-10 code → MONDO disease record | ### Precision medicine (`tools/precision_medicine.py`) | Tool | What it does | |---|---| | `generate_variant_clinical_report` | HGVS → sourced multi-database report + unreviewed computational signals | | `assess_target_druggability` | UniProt → uncalibrated HOT/WARM/COLD/NOT_DRUGGABLE heuristic when an observed drug count is available; otherwise explicit tool error | | `synthesize_protein_dossier` | UniProt → source-attributed research briefing; errors rather than inventing a druggability tier if source counts are unavailable | | `map_disease_drug_landscape` | MONDO → approved drugs + pipeline + ChEMBL phase counts | | `classify_variant_acmg` | HGVS → source evidence + unassessed candidate signals; no automatic clinical class | | `find_drug_repurposing_candidates` | MONDO → candidates ranked by OT evidence × ChEMBL phase | Computational candidate signals are not assessed clinical ACMG/AMP criteria. Source classifications (for example, ClinVar) retain their original attribution; clinical interpretation requires independent review. ### Structure intelligence (`tools/structure_intelligence.py`) | Tool | What it does | |---|---| | `analyze_structural_confidence` | mean pLDDT + confidence tier + PAE-derived domain boundaries | | `compute_topology_fingerprint` | 64-component exploratory vector; GUDHI computes H₀/H₁ at filtration endpoint; H₂ unavailable | | `compare_proteins_topologically` | Pairwise L2 fingerprint-distance matrix for 2–10 proteins | | `find_evolutionary_structural_shifts` | Ensembl sequence identity + method-labeled structural feature distances; no mixed-scale risk ranking | | `score_binding_pocket_geometry` | Geometric pocket detection + heuristic druggability index | | `detect_intrinsically_disordered` | Low-pLDDT modeled intervals; no validated disorder, linker, or clinical classification | | `get_protein_structure` | Retrieve an AlphaFold model: metadata, download URLs, optional coordinates | ### Knowledge graph (`tools/knowledge_graph_tools.py`) | Tool | What it does | |---|---| | `query_variant_database` | Search locally stored variant triage results | | `query_protein_database` | Search locally stored protein assessments | | `get_knowledge_graph_stats` | Database size, entity counts, last activity | | `export_research_dataset` | Export tables to JSON for pandas/ML pipelines | | `find_drug_gene_network` | Traverse the local drug–gene–disease graph | --- ## Example usage See [`examples/`](examples/) for research workflow guidance. The previous named clinical session transcripts were retired because they described an obsolete output contract. Current synthetic regression tests exercise retrieval and evidence attribution without asserting independently validated clinical conclusions. ### Clinical variant report ``` generate_variant_clinical_report(hgvs="BRCA1:c.181T>G") ``` The server searches ClinVar, gnomAD, AlphaMissense (via AlphaFold DB), Open Targets disease evidence, ChEMBL and Ensembl VEP, and returns a source-attributed research report with unreviewed computational signals. The gene-relative example above is a candidate search: it cannot borrow a ClinVar record's classification as though it proved allele identity. Use a versioned transcript expression for strict transcript-title matching; even then, additional validation is required for clinical allele identity. The client does not automatically perform a variant-specific experimental- structure or SIFTS mapping. ### Optional PDBe/IUCr literature evidence The clinical-report tool also supports an **opt-in, source-attributed** residue-annotation lookup, available only when both a canonical UniProt accession and its **one-based UniProt residue position** are provided: ```python generate_variant_clinical_report( hgvs="RBM39:p.Trp495Ala", include_literature_evidence=True, literature_uniprot_id="Q8VH51", literature_uniprot_residue=495, ) ``` The example demonstrates the request shape, not proof that this HGVS expression has been transcript-mapped or clinically interpreted. Returned `literature_residue_evidence` preserves PDBe/IUCr annotation provenance: publication identifiers, text-mined sentence and exact span, extraction confidence, experimental PDB chain/residue information, and source-reported UniProt correspondence. Source errors and ambiguous or missing residue mappings are explicitly distinguished. This evidence does **not** change ACMG criteria or pathogenicity tiers. Verify the exact HGVS-to-UniProt coordinate independently; the client does not independently validate SIFTS or experimental quality. See the [compatibility and mapping limitations](docs/afdb-compatibility.md). ### Drug repurposing ``` find_drug_repurposing_candidates(disease_mondo_id="MONDO:0007739") ``` Returns drugs whose Open Targets evidence connects them to the disease, ranked by a composite of OT evidence score × the maximum ChEMBL clinical phase reached against the target. ### Cross-species structural divergence ``` find_evolutionary_structural_shifts( gene_symbol="ACE2", target_species=["mus_musculus", "rhinolophus_ferrumequinum"] ) ``` For each species: fetches the ortholog (Ensembl), the AlphaFold structure, computes the TDA fingerprint, and returns the L2 fingerprint distance from the human structure along with sequence identity. --- ## Data sources | Source | What we use | License | |---|---|---| | AlphaFold DB v6 (EBI/DeepMind) | Structures, pLDDT, PAE, AlphaMissense | CC BY 4.0 | | UniProtKB REST (EMBL-EBI/SIB/PIR) | Conditional displayed-isoform identity verification, not general annotation retrieval | CC BY 4.0 | | MONDO (OLS4) | Disease ontology, ICD cross-refs | CC BY 4.0 | | HPO (JAX) | Phenotype terms, gene-disease links | HPO license (free for all use) | | Open Targets | Disease–target evidence | CC0 1.0 (data) | | ClinVar (NCBI) | Variant pathogenicity | Public domain | | gnomAD v4 | Population allele frequencies | CC0 1.0 | | DisGeNET | Gene–disease association scores | Free academic tier / commercial (MedBioinformatics) | | ChEMBL v37 (EMBL-EBI) | Drug bioactivity, MoA, ADMET | CC BY-SA 3.0 | | Ensembl (EMBL-EBI) | VEP, orthologs, gene lookup | No restrictions (data); Apache 2.0 (code) | UniProt accessions are used throughout as protein **identifiers**. The UniProtKB REST API is queried **only** for an explicit isoform not separately labeled in AlphaFold DB: its curated Displayed designation and full canonical sequence must agree with the model before reuse. This extra upstream request has its own rate limit and is blocked in offline mode. Failed verification raises an error rather than proving no model exists. Domain (InterPro), Gene Ontology, experimental-structure (RCSB PDB), and tissue-expression (Human Protein Atlas) lookups are **not** integrated in this release. The optional PDBe/IUCr literature client is not a tenth default core source: it is called only when `include_literature_evidence=True` and an explicit UniProt coordinate is supplied. The data originates in PDBe's IUCr text-mining pipeline and requires its own upstream attribution. No experimental RCSB PDB structure retrieval is implied. See [`NOTICE`](NOTICE) for full attributions. --- ## Architecture ``` clients/_base.py ├── Air-gap enforcement (refuses sockets when ALPHAFOLD_OFFLINE=1) ├── Token-bucket rate limiting (aiolimiter) ├── Exponential backoff with jitter (tenacity) ├── Circuit breaker (CLOSED / OPEN / HALF_OPEN) └── HTTP/2 transport with connection pooling and keep-alive (httpx) storage/knowledge_graph.py ├── SQLite WAL mode (embedded, ACID) ├── 6 entity tables: proteins, variants, diseases, drugs, genes, phenotypes ├── 4 relationship tables: protein_disease, protein_drug, variant_disease, gene_phenotype ├── tool_invocations audit table (SHA-256 of input + output, timestamps) └── Analytical views: variant_summary, drug_landscape domain/disease.py └── Pure Python frozen dataclasses (PathogenicityClass, VariantReport, ...) domain/druggability.py └── Pure, I/O-free target-druggability heuristic (named/cited weights and cut-offs, plus confidence / data-completeness / borderline reporting) ``` See [`ARCHITECTURE.md`](ARCHITECTURE.md) for the full module map. --- ## Testing & quality - A comprehensive offline unit-test suite (respx-mocked upstreams, including parametrised expansions); the full suite runs hermetically in under a minute on a laptop. - Coverage on the shipped surface (`src/alphafold_sovereign/clients`, `domain`, `storage`, `server`, `tools`): **100% line + branch**, every shipped module at 100%. - Lint: `ruff` (19 rule families, see `[tool.ruff.lint]` in `pyproject.toml`). Type checking: `mypy --strict` on the full source tree. - Security: `bandit` plus CodeQL `security-extended`. - Supply chain: release CI builds and attests the distributions, generates a wheel-bound CycloneDX SBOM from the installed runtime dependency closure, and signs release artifacts with Sigstore. `scripts/replicate.sh` independently downloads the published wheel and sdist, verifies their PyPI hashes and Sigstore bundles, and checks the released CycloneDX binding. SLSA provenance is generated in CI; attaching it to each GitHub Release remains a roadmap item. The full CI matrix (Python 3.11, 3.12, 3.13 × Ubuntu, macOS) runs on every push. The coverage percentage above is the number a `git clone && uv run nox -s cov` produces on the current HEAD; if you find a divergence, please open an issue. --- ## Contributing DCO sign-off required (`git commit -s`). No copyright assignment. Coverage gate: CI enforces 100% line and branch coverage on the shipped surface (`nox -s cov`). Full guide: [`CONTRIBUTING.md`](CONTRIBUTING.md). --- ## Related MCP servers by the same author - [`uniprot-mcp`](https://github.com/smaniches/uniprot-mcp) — Model Context Protocol server for UniProt Swiss-Prot and TrEMBL (`pip install uniprot-mcp-server`). - [`semantic-scholar-mcp`](https://github.com/smaniches/semantic-scholar-mcp) — Semantic Scholar MCP server, 200M+ academic papers (`pip install s2-mcp-server`). --- ## Citation Machine-readable metadata: [`CITATION.cff`](CITATION.cff) (GitHub renders a "Cite this repository" button in the sidebar that consumes this file). ```bibtex @software{maniches_alphafold_sovereign_mcp, author = {Maniches, Santiago}, title = {AlphaFold Sovereign MCP}, year = {2026}, version = {1.5.9}, url = {https://github.com/smaniches/alphafold-sovereign-mcp}, license = {Apache-2.0}, orcid = {0009-0005-6480-1987}, doi = {10.5281/zenodo.20134773} } ``` When citing results derived from this software, please also cite the upstream data sources (AlphaFold DB, UniProtKB when verifying explicit isoforms, Open Targets, ChEMBL, Ensembl, ClinVar, gnomAD, MONDO, HPO, DisGeNET) according to their own citation requirements. ## License Copyright 2024–2026 Santiago Maniches. Licensed under the Apache License, Version 2.0. See [`LICENSE`](LICENSE). Patent reservation: see [`PATENTS.md`](PATENTS.md). Trademark policy: see [`TRADEMARKS.md`](TRADEMARKS.md).