alphafold-sovereign-mcp

# AlphaFold Sovereign MCP

<!-- mcp-name: io.github.smaniches/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.

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.10+](https://img.shields.io/badge/python-3.10%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
  is a thin orchestration over those upstreams; the server does not
  add scientific judgement.
- 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. It loads a curated boot
  seed automatically when empty (`storage/seed.py`, 16 entities and 15
  relationships; disable with `AFSMCP_DISABLE_KG_SEED=1`) and can be
  extended by writing through the knowledge-graph API. There is no
  automatic per-invocation persistence: the analysis tools do not write
  to the store on their own.
- Includes a topological-data-analysis (TDA) module that computes
  persistent-homology fingerprints (Betti numbers β₀, β₁, β₂) over
  Vietoris-Rips filtrations of Cα coordinates, and an
  L2-distance comparator between those fingerprint vectors. The full
  persistent-homology features require the optional `[tda]` extra
  (`gudhi`).

It targets `mcp-spec 2025-06-18` and runs on Python 3.10–3.13.

**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.

## 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.
- The "ACMG/AMP criteria" that `generate_variant_clinical_report`
  produces are a **draft surface** of the upstream evidence the
  server can fetch automatically. They are not a substitute for
  clinical-laboratory variant review.
- 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" between proteins is an L2 distance on
  length-normalised TDA fingerprint vectors. It measures *topological*
  similarity of the Cα point cloud. It is not a sequence similarity,
  RMSD, optimal-transport Wasserstein distance, or
  functional-equivalence measure.
- 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

<!-- x-release-please-start-version -->
```console
$ alphafold-sovereign --version
1.5.0
$ alphafold-sovereign --self-test
SELF-TEST PASS - ACMG helpers behave as expected on the BRCA1 c.5266dupC fixture.
```
<!-- x-release-please-end-version -->

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