Skip to content

Architecture

Architecture

This document describes the system design of AlphaFold Sovereign MCP as shipped in the current release. Where a capability is planned but not yet implemented, it is listed under Roadmap rather than described as if it exists. For the threat model, see docs/threat-model.md.

Design principles

  1. Sovereign and offline-capable. The package installs and runs without network access. With ALPHAFOLD_OFFLINE=1, the base HTTP client refuses all egress before a socket is opened (raising AirGapError). The knowledge-graph query and export tools answer from the local SQLite store; the upstream-querying tools do not read the knowledge graph, so they fail closed in offline mode -- any upstream call raises AirGapError. The deterministic --self-test makes no network calls.
  2. Provenance by capability. Every tool result can be persisted to a local SQLite store through the knowledge-graph API. The tool_invocations and provenance tables are designed to hold the tool name, parameters, input and output SHA-256 hashes, the upstream data-source versions, and a UTC timestamp; the writer (KnowledgeGraph.log_tool_invocation) exists but is not yet hooked into the tool-dispatch path, so in normal operation these tables stay empty unless a caller persists explicitly. Cryptographic signing of these records is a roadmap item; it is not yet implemented.
  3. Single licence. The codebase is Apache 2.0 — one licence, with no dual-licence funnel and no feature gated behind a paid edition.
  4. Protocol-native, tools first. The server implements the MCP tools surface over the stdio transport: 29 tools registered on a single FastMCP application. MCP resources, MCP prompts, and the Streamable HTTP transport are on the roadmap and are not part of the shipped surface.
  5. Disease-integrated. Structural data is joined with disease context. The variant- and target-level tools traverse MONDO, HPO, Open Targets, ClinVar, gnomAD, and DisGeNET to answer why a given structure matters clinically.

Module map (shipped)

src/alphafold_sovereign/
│
├── __init__.py          Package metadata (__version__, author, licence)
├── __main__.py          CLI entry point: --version, --self-test, stdio server
│
├── server/              MCP transport layer
│   ├── app.py           The single FastMCP application instance
│   └── stdio.py         stdio transport; imports the tool modules and runs it
│
├── tools/               MCP tool implementations (29 tools; thin orchestration)
│   ├── precision_medicine.py     variant clinical report, ACMG draft,
│   │                             druggability tier, protein dossier,
│   │                             disease–drug map, drug repurposing  (6)
│   ├── structure_intelligence.py pLDDT confidence, topology fingerprint,
│   │                             topological comparison, evolutionary
│   │                             shifts, core-residue clusters, disorder,
│   │                             structure retrieval                    (7)
│   ├── disease.py                MONDO/HPO lookups, target–disease evidence,
│   │                             3-D variant triage, ICD-10 resolution  (11)
│   └── knowledge_graph_tools.py  query and export the local graph        (5)
│
├── clients/             Async HTTP clients — 11 specialized clients + shared base
│   ├── _base.py         BaseAsyncClient: httpx HTTP/2, tenacity retry with
│   │                    jitter, aiolimiter per-host rate limiting, a circuit
│   │                    breaker, and the offline allowlist (raises AirGapError);
│   │                    a _sha256 helper is available to callers, not auto-applied
│   ├── alphafold.py     AlphaFold DB (prediction metadata, PDB, PAE, AlphaMissense)
│   ├── _isoform.py      UniProtKB curated displayed-isoform verification
│   ├── pdbe_literature.py  Optional PDBe/IUCr source-reported residue mentions
│   ├── opentargets.py   Open Targets Platform GraphQL
│   ├── chembl.py        ChEMBL REST
│   ├── ensembl.py       Ensembl REST (VEP, gene and variant lookup, orthologs)
│   ├── clinvar.py       ClinVar via NCBI E-utilities
│   ├── gnomad.py        gnomAD GraphQL
│   ├── mondo.py         MONDO via OLS4
│   ├── hpo.py           HPO via the HPO API (ontology.jax.org)
│   └── disgenet.py      DisGeNET REST
│
├── domain/              Pure-Python types; no I/O, no network, no MCP SDK
│   ├── disease.py       PathogenicityClass, EvidenceType, OntologyTerm,
│   │                    DiseaseRecord, PhenotypeAssociation,
│   │                    TargetEvidenceScore, PopulationFrequency, VariantReport
│   ├── druggability.py  Deterministic HOT/WARM/COLD/NOT_DRUGGABLE tier heuristic
│   └── uniprot.py       UniProtKB accession / isoform syntax patterns
│
└── storage/             Persistence and provenance
    ├── knowledge_graph.py   SQLite knowledge graph (WAL mode); six entity,
    │                        four relationship, and two provenance tables;
    │                        per-row SHA-256 fingerprint columns (not keys)
    └── seed.py              No-op compatibility entrypoint; no automatic data seed

The package also contains six reserved namespace packages — compliance/, compute/, observability/, prompts/, resources/, and security/. Each is currently an empty __init__.py: they reserve import paths for the roadmap items below and contain no shipped code.


Data flow

3-D variant triage (a multi-source tool)

This is the data flow as currently implemented. Some upstreams named in the tool's design are not yet wired (see the Wave-3 notes inline and in the Roadmap).

Claude (MCP client): triage_variant_3d(hgvs="BRCA1:c.181T>G")
  │
  ▼
tools/disease.py::triage_variant_3d
  │
  ├─ _parse_hgvs_gene        extract gene symbol from the HGVS string
  │                          (local parse; no Ensembl/UniProt resolution yet)
  ├─ clients/clinvar.py      gene-relative HGVS: unverified candidates only;
  │                          versioned-transcript match: source interpretation
  │                          and review status, not independent allele proof
  ├─ clients/gnomad.py       gnomAD gene-constraint scores; AlphaMissense
  │                          score is read from this payload when present
  ├─ disease context         placeholder note today; full Open Targets /
  │                          MONDO traversal is a Wave-3 item
  ├─ structure context       a text note pointing at analyze_structural_confidence(); the
  │                          AlphaFold pLDDT/PAE join is a Wave-3 item
  │
  └─ result                  assembled as a plain dict with a provenance
                             footer and returned as JSON (no automatic
                             knowledge-graph persist)

Optional literature-residue evidence

generate_variant_clinical_report can call clients/pdbe_literature.py only when explicitly opted in and given a canonical UniProt accession plus residue. It parses the documented PDBe/IUCr nested annotation response into source-attributed publication mentions. Mapping between the caller's HGVS variant and that UniProt coordinate, and PDBe's source-reported SIFTS correspondence, are not independently verified. These mentions remain distinct from clinical assertions, AlphaMissense, and ACMG criterion scoring. No additional public MCP tool or background query is introduced.

Every upstream call passes through clients/_base.py, which applies a per-host rate limit (aiolimiter), retry with exponential back-off and jitter (tenacity), and a per-host circuit breaker. With ALPHAFOLD_OFFLINE=1, egress is refused at this layer before a socket is opened (AirGapError); the client layer does not transparently fall back to the knowledge graph, so a tool that needs fresh upstream data fails closed in offline mode.


Persistence: the knowledge graph

The only persistence layer is a local SQLite database (storage/knowledge_graph.py), opened in WAL mode. Its location defaults to the platform user-data directory and can be overridden with ALPHAFOLD_KG_PATH. The schema comprises:

  • Entity tables (6): proteins, variants, diseases, drugs, phenotypes, genes.
  • Relationship tables (4): protein_disease, protein_drug, variant_disease, gene_phenotype.
  • Provenance tables (2): tool_invocations (a tool call with its parameters, input and output hashes, and timing) and provenance (the data-source version snapshot per invocation). The writer for tool_invocations, KnowledgeGraph.log_tool_invocation, is implemented but is not yet called from the tool-dispatch path, so the table is populated only when a caller invokes it explicitly.

Result blobs are stored as JSON in the tool_invocations table; each row also carries SHA-256 fingerprint columns (params/result hashes) recorded for integrity inspection, not used as keys -- so there is no content-addressing and identical results are not deduplicated. Data already written to the store can be queried and exported offline through the knowledge-graph tools. A columnar analytical layer (DuckDB) for aggregation and export is planned but not yet wired: there is no DuckDB runtime dependency and the code does not import it. See the Roadmap.


Disease-ontology integration

The disease-layer tools query six upstreams directly:

Source What is used API
MONDO Unified disease IDs and cross-references (ICD-10, OMIM, Orphanet, DOID) OLS4 REST + Monarch
HPO Phenotype terms and gene–phenotype links HPO API + OLS4
Open Targets Disease–target evidence and association scores GraphQL
ClinVar Variant clinical significance and review status NCBI E-utilities
gnomAD Population allele frequencies and constraint GraphQL
DisGeNET Gene–disease association scores REST

ICD-10 codes are resolved through resolve_icd10_to_mondo, using MONDO cross-references. The MONDO client also supports exact Orphanet cross-reference lookup for source integration, without offering a curated clinical narrative or orphan-disease atlas. The get_common_disease_targets tool retrieves live source evidence from a small, ontology-checked set of example disease identifiers.


Security and sovereignty

Shipped controls:

  • Egress control. With ALPHAFOLD_OFFLINE=1, all outbound requests are refused in clients/_base.py before a socket is opened. ALPHAFOLD_ALLOW_HOSTS provides a comma-separated allowlist for partial-air-gap deployments.
  • Provenance trail (capability). The SQLite tool_invocations table can hold each tool call with input and output SHA-256 hashes and UTC timestamps, written insert-only via KnowledgeGraph.log_tool_invocation. This writer is not yet hooked into tool dispatch, so the trail is populated only when a caller logs explicitly; automatic per-invocation logging is a roadmap item.
  • Parameterised SQL. All knowledge-graph queries use bound parameters; table names are drawn from a fixed internal allowlist, never from user input.

For the full STRIDE analysis, see docs/threat-model.md.


Roadmap (not yet shipped)

These capabilities are intentionally absent from the current release and are listed so the shipped boundary is unambiguous:

  • Streamable HTTP transport with OAuth 2.1 / PKCE. Only the stdio transport ships today; stdio clients (such as Claude Desktop) own their own process capabilities and use no separate auth.
  • MCP resources and prompts. Only the tools surface is implemented.
  • Automatic provenance logging. KnowledgeGraph.log_tool_invocation exists but is not yet invoked by the tool-dispatch path; wiring it in so every MCP tool call lands in tool_invocations is a roadmap item. Until then the audit trail is a capability, not an always-on behaviour.
  • A DuckDB analytical layer. A columnar path over the SQLite store for fast aggregation and export is planned. It is not wired today: there is no DuckDB dependency and the code does not import it.
  • Cryptographic signing of provenance records (for example, ed25519 signatures and an external transparency log). Records are currently stored unsigned in SQLite.
  • A FIPS 140-3 build that switches cryptography to the OpenSSL FIPS provider.

The reserved namespace packages (compliance/, compute/, observability/, prompts/, resources/, security/) hold the import paths for this work.