{
  "markdown": "# AlphaFold Sovereign MCP\n\n<!-- mcp-name: io.github.smaniches/alphafold-sovereign-mcp -->\n\nAnswering a structural-biology or variant question usually means querying\nmany public databases by hand — AlphaFold DB, Open Targets, ClinVar,\ngnomAD, and more — and reconciling their formats. This server wraps those\nsources behind one set of MCP tool calls that run as a local process on\nyour own machine, with no hosted service of ours in the path, no\ntelemetry, and a local SQLite knowledge graph that never leaves your disk.\nIn the default online mode the tools query those public upstreams\ndirectly, so the identifiers you look up are sent to them (and one,\nDisGeNET, needs its own free API key); set `ALPHAFOLD_OFFLINE=1` to refuse\noutbound requests before any socket opens, so no identifier leaves the\nmachine (the knowledge-graph tools still answer from local data; the\nupstream tools report their source as unavailable). \"Sovereign\" here means\nlocal-first — your compute and stored results stay on your machine — not\nthat the server runs without a network.\n\nA Model Context Protocol server — an AlphaFold MCP server — that\nwraps AlphaFold DB and 8 other public biomedical data sources behind\na set of MCP tool calls, backed by a local SQLite knowledge graph with\nquery and export tools (results can be persisted through its API;\nautomatic per-invocation persistence is not yet wired).\n\nThis is an unfunded, independent open-source project. It is not a\nservice, not certified for any regulated use, and its outputs are\nresearch aids that should be reviewed by qualified humans before any\nclinical or regulatory use.\n\nThis project is not affiliated with, endorsed by, or sponsored by\nGoogle DeepMind or EMBL-EBI. \"AlphaFold\" is a trademark of its\nrespective owner and is used here only to describe the public data\n(the AlphaFold DB API) that this software consumes.\n\n[![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)\n[![Docs](https://github.com/smaniches/alphafold-sovereign-mcp/actions/workflows/docs.yml/badge.svg)](https://smaniches.github.io/alphafold-sovereign-mcp/)\n[![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)\n[![Release](https://img.shields.io/github/v/release/smaniches/alphafold-sovereign-mcp?sort=semver)](https://github.com/smaniches/alphafold-sovereign-mcp/releases)\n[![PyPI](https://img.shields.io/pypi/v/alphafold-sovereign-mcp?label=PyPI)](https://pypi.org/project/alphafold-sovereign-mcp/)\n[![PyPI downloads/30d](https://img.shields.io/pypi/dm/alphafold-sovereign-mcp?label=downloads%2F30d)](https://pypistats.org/packages/alphafold-sovereign-mcp)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)\n[![MCP Spec 2025-06-18](https://img.shields.io/badge/MCP-2025--06--18-purple)](https://modelcontextprotocol.io)\n[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/smaniches/alphafold-sovereign-mcp/actions/workflows/ci.yml)\n[![ORCID](https://img.shields.io/badge/ORCID-0009--0005--6480--1987-A6CE39?logo=orcid&logoColor=white)](https://orcid.org/0009-0005-6480-1987)\n[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20134773-3C5A99?logo=zenodo&logoColor=white)](https://doi.org/10.5281/zenodo.20134773)\n[![Glama score](https://glama.ai/mcp/servers/smaniches/alphafold-sovereign-mcp/badges/score.svg)](https://glama.ai/mcp/servers/smaniches/alphafold-sovereign-mcp)\n[![Awesome MCP Servers](https://img.shields.io/badge/Awesome_MCP-Listed-blue?logo=github)](https://github.com/punkpeye/awesome-mcp-servers#bio)\n\n**Status:** Beta. Engineering-validated (100% line and branch\ncoverage). Not yet scientifically validated by\nindependent domain experts; not yet deployed in production. See\n[`STATUS.md`](STATUS.md) and [`LIMITATIONS.md`](LIMITATIONS.md).\n\n---\n\n## What this is\n\nA Python MCP server that:\n\n- Wraps AlphaFold DB, MONDO, HPO, Open Targets, ClinVar, gnomAD,\n  DisGeNET, ChEMBL, and Ensembl behind MCP tool calls. Each call\n  is a thin orchestration over those upstreams; the server does not\n  add scientific judgement.\n- Composes upstreams into multi-source workflows: variant\n  cross-reference reports, disease–target landscape summaries,\n  heuristic target-druggability scoring, drug-repurposing candidate\n  ranking, and cross-species structural-distance computation.\n- Ships a local SQLite knowledge graph (`storage/knowledge_graph.py`)\n  with query, export, and traversal tools. It loads a curated boot\n  seed automatically when empty (`storage/seed.py`, 16 entities and 15\n  relationships; disable with `AFSMCP_DISABLE_KG_SEED=1`) and can be\n  extended by writing through the knowledge-graph API. There is no\n  automatic per-invocation persistence: the analysis tools do not write\n  to the store on their own.\n- Includes a topological-data-analysis (TDA) module that computes\n  persistent-homology fingerprints (Betti numbers β₀, β₁, β₂) over\n  Vietoris-Rips filtrations of Cα coordinates, and an\n  L2-distance comparator between those fingerprint vectors. The full\n  persistent-homology features require the optional `[tda]` extra\n  (`gudhi`).\n\nIt targets `mcp-spec 2025-06-18` and runs on Python 3.10–3.13.\n\n## What this is **not**\n\n- It is **not** a hosted service or a SaaS.\n- It is **not** certified for any regulated use (HIPAA, GxP, 21 CFR\n  Part 11, FedRAMP, FIPS, SOC 2). The code structures audit logging\n  in a way that could later support such a certification, but no\n  such audit has been performed.\n- It does **not** train, fine-tune, or publish AlphaFold models — it\n  consumes AlphaFold DB's public REST API.\n- The \"ACMG/AMP criteria\" that `generate_variant_clinical_report`\n  produces are a **draft surface** of the upstream evidence the\n  server can fetch automatically. They are not a substitute for\n  clinical-laboratory variant review.\n- The \"druggability tier\" that `assess_target_druggability` returns is\n  a **heuristic** built from drug-precedent counts, Open Targets\n  tractability labels, pLDDT, and gnomAD constraint. It is not a\n  validated prediction.\n- \"Structural distance\" between proteins is an L2 distance on\n  length-normalised TDA fingerprint vectors. It measures *topological*\n  similarity of the Cα point cloud. It is not a sequence similarity,\n  RMSD, optimal-transport Wasserstein distance, or\n  functional-equivalence measure.\n- The AlphaFold structures consumed here are *predicted* models with\n  per-residue pLDDT confidence, not experimental structures. Low-pLDDT\n  regions are unreliable; some proteins (BRCA1 among them) are largely\n  low-confidence, and structural inference over those regions should\n  be treated with caution.\n\nFor a complete, itemised list of known limitations (with module\nreferences, impact, and planned resolution), see [`LIMITATIONS.md`](LIMITATIONS.md).\nFor the high-level posture — what is engineering-validated vs. what is\nnot yet scientifically validated — see [`STATUS.md`](STATUS.md).\n\n---\n\n## Install\n\n### From PyPI (recommended)\n\n```bash\npip install alphafold-sovereign-mcp\n```\n\nOr run it without installing using `uvx`:\n\n```bash\nuvx alphafold-sovereign-mcp\n```\n\nEvery release on PyPI is built by the `release.yml` workflow under\nOIDC Trusted Publishing and attached to a signed GitHub Release with\nSigstore (`cosign`) signature bundles, a CycloneDX SBOM, and a Zenodo\nDOI mirror. SLSA L3 build provenance is generated in CI by\n`slsa-github-generator`; attaching the attestation to each release is a\nroadmap item. `scripts/replicate.sh` downloads the exact published wheel\nand sdist, recomputes their PyPI SHA-256 digests, verifies the GitHub\nRelease Sigstore bundles against those bytes and this repository's release\nworkflow identity, and independently verifies that the released CycloneDX\nSBOM is bound to the downloaded wheel. If SLSA provenance is attached to a\nfuture release, the same script verifies it against the wheel when\n`slsa-verifier` is installed.\n\n### From source\n\n```bash\ngit clone https://github.com/smaniches/alphafold-sovereign-mcp\ncd alphafold-sovereign-mcp\nuv pip install -e .\n# With persistent-homology TDA (requires gudhi):\n# uv pip install -e \".[tda]\"\n```\n\n### Verify the install\n\n<!-- x-release-please-start-version -->\n```console\n$ alphafold-sovereign --version\n1.4.9\n$ alphafold-sovereign --self-test\nSELF-TEST PASS - ACMG helpers behave as expected on the BRCA1 c.5266dupC fixture.\n```\n<!-- x-release-please-end-version -->\n\nIf you ran it via `uvx` without installing, use\n`uvx alphafold-sovereign-mcp --self-test` instead (the bare\n`alphafold-sovereign` script is only on PATH after a pip/uv install).\n\n`--self-test` runs fully offline: it checks the deterministic ACMG-evidence\nhelpers (VEP, gnomAD, and AlphaMissense mapped to ACMG criteria) against a\nbuilt-in `BRCA1:c.5266dupC` fixture. Returns exit code 0 on PASS, non-zero on\nFAIL. No network calls, no credentials required.\n\n### Configure Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"alphafold-sovereign\": {\n      \"command\": \"alphafold-sovereign-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\nRestart Claude Desktop and the tools become available in conversations.\nTry asking, for example: *\"Triage BRCA1 c.5266dupC\"* or *\"Assess EGFR\nas a drug target\"*. See the [`examples/`](examples/) directory for three end-to-end\nillustrations of what a session looks like.\n\n### Offline mode\n\n```bash\nALPHAFOLD_OFFLINE=1 alphafold-sovereign-mcp\n```\n\nRefuses 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.\n\n---\n\n## Tool inventory\n\nThe server exposes 30 MCP tools across four modules. Each tool's\ninput schema is a Pydantic model; results are JSON.\n\n### Disease & ontology (`tools/disease.py`)\n\n| Tool | What it does |\n|---|---|\n| `lookup_disease` | MONDO record + hierarchy + ICD cross-references |\n| `search_diseases` | Full-text MONDO ontology search |\n| `lookup_phenotype` | HPO term + associated diseases |\n| `get_gene_phenotype_profile` | HPO phenotypes + gnomAD constraint for a gene |\n| `get_disease_targets` | Top drug targets for a MONDO disease (Open Targets) |\n| `get_target_diseases` | Top diseases for a UniProt target (Open Targets) |\n| `get_common_disease_targets` | Parallel profiling across curated MONDO diseases |\n| `triage_variant_3d` | HGVS → ClinVar + gnomAD constraint (disease/structure context: pointer notes) |\n| `phenotype_to_structures` | HPO → diseases → OT targets → UniProt IDs |\n| `get_orphan_disease_atlas` | Orphanet → MONDO → HPO + OT targets |\n| `compare_disease_target_overlap` | Jaccard similarity of target sets for two diseases |\n| `resolve_icd10_to_mondo` | ICD-10 code → MONDO disease record |\n\n### Precision medicine (`tools/precision_medicine.py`)\n\n| Tool | What it does |\n|---|---|\n| `generate_variant_clinical_report` | HGVS → multi-source report + draft ACMG/AMP criteria |\n| `assess_target_druggability` | UniProt → HOT/WARM/COLD/NOT_DRUGGABLE tier |\n| `synthesize_protein_dossier` | UniProt → multi-source briefing |\n| `map_disease_drug_landscape` | MONDO → approved drugs + pipeline + ChEMBL phase counts |\n| `classify_variant_acmg` | HGVS → ACMG/AMP criteria checklist (PVS1, PM2, PP3, BP4, BP7, BS1, PP5) |\n| `find_drug_repurposing_candidates` | MONDO → candidates ranked by OT evidence × ChEMBL phase |\n\nThe ACMG/AMP criteria produced are a **draft**: they reflect the\nupstream evidence the server can fetch automatically, and they\nare not a substitute for clinical-laboratory review.\n\n### Structure intelligence (`tools/structure_intelligence.py`)\n\n| Tool | What it does |\n|---|---|\n| `analyze_structural_confidence` | mean pLDDT + confidence tier + PAE-derived domain boundaries |\n| `compute_topology_fingerprint` | 64-dim TDA fingerprint (Betti numbers β₀ β₁ β₂) |\n| `compare_proteins_topologically` | Pairwise L2 fingerprint-distance matrix for 2–10 proteins |\n| `find_evolutionary_structural_shifts` | Cross-species structural divergence (TDA + Ensembl orthologs) |\n| `score_binding_pocket_geometry` | Geometric pocket detection + heuristic druggability index |\n| `detect_intrinsically_disordered` | IDR map (linkers, tails, long IDRs) |\n| `get_protein_structure` | Retrieve an AlphaFold model: metadata, download URLs, optional coordinates |\n\n### Knowledge graph (`tools/knowledge_graph_tools.py`)\n\n| Tool | What it does |\n|---|---|\n| `query_variant_database` | Search locally stored variant triage results |\n| `query_protein_database` | Search locally stored protein assessments |\n| `get_knowledge_graph_stats` | Database size, entity counts, last activity |\n| `export_research_dataset` | Export tables to JSON for pandas/ML pipelines |\n| `find_drug_gene_network` | Traverse the local drug–gene–disease graph |\n\n---\n\n## Example usage\n\nFor three documented end-to-end illustrations of a Claude Desktop\nsession against this server — variant triage on BRCA1 c.5266dupC,\ntarget characterisation on EGFR, and a drug-discovery walk-through\non Imatinib → BCR-ABL → CML — see the [`examples/`](examples/)\ndirectory. Each example includes the user prompt, the tool calls\nthe model issues, the server's response shape, and the model's\nparaphrased reply.\n\n### Clinical variant report\n\n```\ngenerate_variant_clinical_report(hgvs=\"BRCA1:c.181T>G\")\n```\n\nThe server resolves the HGVS, fetches ClinVar, gnomAD, AlphaMissense\n(via AlphaFold DB), Open Targets disease evidence, ChEMBL drug data,\nand Ensembl VEP consequence annotations, and returns a single JSON\nrecord with the cross-referenced fields plus the ACMG/AMP criteria\nthat the available evidence supports.\n\n### Drug repurposing\n\n```\nfind_drug_repurposing_candidates(disease_mondo_id=\"MONDO:0007739\")\n```\n\nReturns drugs whose Open Targets evidence connects them to the\ndisease, ranked by a composite of OT evidence score × the maximum\nChEMBL clinical phase reached against the target.\n\n### Cross-species structural divergence\n\n```\nfind_evolutionary_structural_shifts(\n    gene_symbol=\"ACE2\",\n    target_species=[\"mus_musculus\", \"rhinolophus_ferrumequinum\"]\n)\n```\n\nFor each species: fetches the ortholog (Ensembl), the AlphaFold\nstructure, computes the TDA fingerprint, and returns the L2 fingerprint\ndistance from the human structure along with sequence identity.\n\n---\n\n## Data sources\n\n| Source | What we use | License |\n|---|---|---|\n| AlphaFold DB v6 (EBI/DeepMind) | Structures, pLDDT, PAE, AlphaMissense | CC BY 4.0 |\n| MONDO (OLS4) | Disease ontology, ICD cross-refs | CC BY 4.0 |\n| HPO (JAX) | Phenotype terms, gene-disease links | HPO license (free for all use) |\n| Open Targets | Disease–target evidence | CC0 1.0 (data) |\n| ClinVar (NCBI) | Variant pathogenicity | Public domain |\n| gnomAD v4 | Population allele frequencies | CC0 1.0 |\n| DisGeNET | Gene–disease association scores | Free academic tier / commercial (MedBioinformatics) |\n| ChEMBL v37 (EMBL-EBI) | Drug bioactivity, MoA, ADMET | CC BY-SA 3.0 |\n| Ensembl (EMBL-EBI) | VEP, orthologs, gene lookup | No restrictions (data); Apache 2.0 (code) |\n\nUniProt accessions are used throughout as protein **identifiers** — they\nkey AlphaFold structures and Open Targets cross-references — but the\nUniProt API itself is not queried as a data source. Domain (InterPro),\nGene Ontology, experimental-structure (RCSB PDB), and tissue-expression\n(Human Protein Atlas) lookups are **not** integrated in this release.\n\nSee [`NOTICE`](NOTICE) for full attributions.\n\n---\n\n## Architecture\n\n```\nclients/_base.py\n  ├── Air-gap enforcement (refuses sockets when ALPHAFOLD_OFFLINE=1)\n  ├── Token-bucket rate limiting (aiolimiter)\n  ├── Exponential backoff with jitter (tenacity)\n  ├── Circuit breaker (CLOSED / OPEN / HALF_OPEN)\n  └── HTTP/2 transport with connection pooling and keep-alive (httpx)\n\nstorage/knowledge_graph.py\n  ├── SQLite WAL mode (embedded, ACID)\n  ├── 6 entity tables: proteins, variants, diseases, drugs, genes, phenotypes\n  ├── 4 relationship tables: protein_disease, protein_drug, variant_disease, gene_phenotype\n  ├── tool_invocations audit table (SHA-256 of input + output, timestamps)\n  └── Analytical views: variant_summary, drug_landscape\n\ndomain/disease.py\n  └── Pure Python frozen dataclasses (PathogenicityClass, VariantReport, ...)\n\ndomain/druggability.py\n  └── Pure, I/O-free target-druggability heuristic (named/cited weights and\n      cut-offs, plus confidence / data-completeness / borderline reporting)\n```\n\nSee [`ARCHITECTURE.md`](ARCHITECTURE.md) for the full module map.\n\n---\n\n## Testing & quality\n\n- A comprehensive offline unit-test suite (respx-mocked upstreams,\n  including parametrised expansions); the full suite runs hermetically\n  in under a minute on a laptop.\n- Coverage on the shipped surface (`src/alphafold_sovereign/clients`,\n  `domain`, `storage`, `server`, `tools`): **100% line + branch**,\n  every shipped module at 100%.\n- Lint: `ruff` (full ruleset). Type checking: `mypy --strict` on the\n  full source tree.\n- Security: `bandit` plus CodeQL `security-extended`.\n- Supply chain: release CI builds and attests the distributions, generates a\n  wheel-bound CycloneDX SBOM from the installed runtime dependency closure,\n  and signs release artifacts with Sigstore. `scripts/replicate.sh`\n  independently downloads the published wheel and sdist, verifies their PyPI\n  hashes and Sigstore bundles, and checks the released CycloneDX binding.\n  SLSA provenance is generated in CI; attaching it to each GitHub Release\n  remains a roadmap item.\n\nThe full CI matrix (Python 3.10, 3.11, 3.12, 3.13 × Ubuntu, macOS)\nruns on every push. The coverage percentage above is the number a\n`git clone && uv run nox -s cov` produces on the current HEAD; if you\nfind a divergence, please open an issue.\n\n---\n\n## Contributing\n\nDCO sign-off required (`git commit -s`). No copyright assignment.\nCoverage gate: CI enforces 100% line and branch coverage on the shipped surface (`nox -s cov`).\nFull guide: [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n---\n\n## Related MCP servers by the same author\n\n- [`uniprot-mcp`](https://github.com/smaniches/uniprot-mcp) — Model Context Protocol server for UniProt Swiss-Prot and TrEMBL (`pip install uniprot-mcp-server`).\n- [`semantic-scholar-mcp`](https://github.com/smaniches/semantic-scholar-mcp) — Semantic Scholar MCP server, 200M+ academic papers (`pip install s2-mcp-server`).\n\n---\n\n## Citation\n\nMachine-readable metadata: [`CITATION.cff`](CITATION.cff) (GitHub\nrenders a \"Cite this repository\" button in the sidebar that consumes\nthis file).\n\n<!-- x-release-please-start-version -->\n```bibtex\n@software{maniches_alphafold_sovereign_mcp,\n  author    = {Maniches, Santiago},\n  title     = {AlphaFold Sovereign MCP},\n  year      = {2026},\n  version   = {1.4.9},\n  url       = {https://github.com/smaniches/alphafold-sovereign-mcp},\n  license   = {Apache-2.0},\n  orcid     = {0009-0005-6480-1987},\n  doi       = {10.5281/zenodo.20134773}\n}\n```\n<!-- x-release-please-end-version -->\n\nWhen citing results derived from this software, please also cite the\nupstream data sources (AlphaFold DB, Open Targets, ChEMBL, Ensembl,\nClinVar, gnomAD, MONDO, HPO, DisGeNET) according to their own citation\nrequirements.\n\n## License\n\nCopyright 2024–2026 Santiago Maniches.\n\nLicensed under the Apache License, Version 2.0. See [`LICENSE`](LICENSE).\n\nPatent reservation: see [`PATENTS.md`](PATENTS.md).\nTrademark policy: see [`TRADEMARKS.md`](TRADEMARKS.md).\n",
  "bytes": 19922,
  "sha": "e0d2896e64425de3bee61c507982cbd4cf6ae8025218c3c7f1ea8480ba242b46",
  "repo_slug": "smaniches/alphafold-sovereign-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_smaniches_alphafold_sovereign__ed5a4387/readme"
}