AlphaFold Sovereign MCP
Чтобы ответить на вопрос из области структурной биологии или о варианте, обычно приходится вручную опрашивать множество публичных баз данных — AlphaFold DB, Open Targets, ClinVar, gnomAD и другие — и сводить воедино их форматы. Этот сервер оборачивает эти источники в единый набор вызовов инструментов MCP, которые выполняются как локальный процесс на вашей собственной машине: в цепочке нет ни одного нашего хостингового сервиса, нет телеметрии, а локальный граф знаний на SQLite никогда не покидает ваш диск.
В режиме онлайн по умолчанию инструменты обращаются к этим публичным вышестоящим источникам напрямую, поэтому идентификаторы, которые вы ищете, отправляются им (а один из них, DisGeNET, требует собственного бесплатного API-ключа); установите ALPHAFOLD_OFFLINE=1, чтобы отклонять исходящие запросы до открытия любого сокета, — тогда ни один идентификатор не покидает машину (инструменты графа знаний по-прежнему отвечают по локальным данным; инструменты, работающие с вышестоящими источниками, сообщают, что их источник недоступен). «Sovereign» здесь означает local-first — ваши вычисления и сохранённые результаты остаются на вашей машине, — а не то, что сервер работает без сети.
Сервер Model Context Protocol — MCP-сервер AlphaFold, — который оборачивает AlphaFold DB и ещё 8 публичных источников биомедицинских данных в набор вызовов инструментов MCP, опираясь на локальный граф знаний на SQLite с инструментами запросов и экспорта (результаты можно сохранять через его API; автоматическое сохранение при каждом вызове пока не реализовано).
Это независимый проект с открытым исходным кодом, не имеющий финансирования. Это не сервис, он не сертифицирован для какого-либо регулируемого применения, а его результаты — вспомогательные материалы для исследований, которые должны быть проверены квалифицированными специалистами перед любым клиническим или регуляторным использованием.
Этот проект не связан с Google DeepMind или EMBL-EBI, не одобрен и не спонсируется ими. «AlphaFold» — товарный знак соответствующего правообладателя; здесь он используется исключительно для описания публичных данных (API AlphaFold DB), которые потребляет это программное обеспечение.
Статус: Beta. Проверено с инженерной точки зрения (100% покрытие строк и ветвей). Ещё не прошло научную валидацию независимыми экспертами в предметной области; ещё не развёрнуто в продакшене. См. STATUS.md и LIMITATIONS.md.
Что это такое
MCP-сервер на Python, который:
-
Оборачивает AlphaFold DB, MONDO, HPO, Open Targets, ClinVar, gnomAD, DisGeNET, ChEMBL и Ensembl в вызовы инструментов MCP. Каждый вызов — это лёгкая оркестрация поверх этих вышестоящих источников; сервер не добавляет собственных научных суждений.
-
Объединяет вышестоящие источники в многоисточниковые рабочие процессы: отчёты перекрёстных ссылок по вариантам, сводки по ландшафту «заболевание — мишень», эвристическую оценку перспективности мишени для разработки лекарств, ранжирование кандидатов для перепрофилирования препаратов и вычисление структурных расстояний между видами.
-
Поставляется с локальным графом знаний на SQLite (
storage/knowledge_graph.py) и инструментами запросов, экспорта и обхода. При пустом хранилище автоматически загружается подготовленный стартовый набор (storage/seed.py, 16 сущностей и 15 связей; отключается черезAFSMCP_DISABLE_KG_SEED=1), а расширять граф можно через запись в API графа знаний. Автоматического сохранения при каждом вызове нет: аналитические инструменты сами в хранилище не пишут. -
Включает модуль топологического анализа данных (TDA), который вычисляет отпечатки персистентной гомологии (числа Бетти β₀, β₁, β₂) по фильтрациям Вьеториса — Рипса координат Cα, и компаратор L2-расстояния между векторами этих отпечатков. Полный набор функций персистентной гомологии требует опционального дополнения
[tda](gudhi).
Сервер ориентирован на mcp-spec 2025-06-18 и работает на Python 3.10–3.13.
Чем это не является
-
Это не хостинговый сервис и не SaaS.
-
Он не сертифицирован для какого-либо регулируемого применения (HIPAA, GxP, 21 CFR Part 11, FedRAMP, FIPS, SOC 2). В коде журналирование аудита организовано так, что в будущем могло бы поддержать подобную сертификацию, однако такой аудит не проводился.
-
Он не обучает, не дообучает и не публикует модели AlphaFold — он потребляет публичный REST API AlphaFold DB.
-
«Критерии ACMG/AMP», которые выдаёт
generate_variant_clinical_report, — это черновой срез доказательной базы вышестоящих источников, который сервер может получать автоматически. Они не заменяют лабораторный клинический разбор вариантов. -
«Категория перспективности для разработки лекарств», которую возвращает
assess_target_druggability, — это эвристика, построенная на подсчёте прецедентов лекарств, метках трактабельности Open Targets, pLDDT и ограничениях gnomAD. Это не валидированный прогноз. -
«Структурное расстояние» между белками — это L2-расстояние между векторами отпечатков TDA, нормализованными по длине. Оно измеряет топологическое сходство облака точек Cα. Это не сходство последовательностей, не RMSD, не расстояние Вассерштейна в задаче оптимального переноса и не мера функциональной эквивалентности.
-
Структуры AlphaFold, которые здесь используются, — это предсказанные модели с оценкой уверенности pLDDT по каждому остатку, а не экспериментальные структуры. Области с низким pLDDT ненадёжны; некоторые белки (в том числе BRCA1) в значительной степени имеют низкую уверенность, и к структурным выводам по таким областям следует относиться с осторожностью.
Полный постатейный список известных ограничений (со ссылками на модули, оценкой влияния и планами по устранению) см. в LIMITATIONS.md.
Общая картина — что проверено с инженерной точки зрения, а что ещё не прошло научную валидацию — приведена в STATUS.md.
Установка
Из PyPI (рекомендуется)
pip install alphafold-sovereign-mcp
Или запустите без установки с помощью uvx:
uvx alphafold-sovereign-mcp
Каждый релиз на PyPI собирается рабочим процессом release.yml в рамках OIDC Trusted Publishing и прикрепляется к подписанному релизу GitHub вместе с пакетами подписей Sigstore (cosign), SBOM в формате CycloneDX и зеркалом Zenodo DOI. Происхождение сборки SLSA L3 генерируется в CI с помощью slsa-github-generator; прикрепление аттестации к каждому релизу — пункт дорожной карты. Скрипт scripts/replicate.sh скачивает именно опубликованные wheel и sdist, заново вычисляет их SHA-256-дайджесты с PyPI, проверяет пакеты Sigstore из релиза GitHub по этим байтам и идентичности рабочего процесса релиза данного репозитория, а также независимо проверяет, что выпущенный SBOM CycloneDX привязан к скачанному wheel. Если к будущему релизу будет прикреплено происхождение SLSA, тот же скрипт проверит его по wheel при установленном slsa-verifier.
Из исходного кода
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]"
Проверка установки
$ alphafold-sovereign --version
1.4.9
$ alphafold-sovereign --self-test
SELF-TEST PASS - ACMG helpers behave as expected on the BRCA1 c.5266dupC fixture.
Если вы запускали через uvx без установки, используйте uvx alphafold-sovereign-mcp --self-test (короткий скрипт alphafold-sovereign появляется в PATH только после установки через pip/uv). --self-test работает полностью офлайн: он проверяет детерминированные помощники для сбора доказательств ACMG (VEP, gnomAD и AlphaMissense, сопоставленные с критериями ACMG) на встроенном образце BRCA1:c.5266dupC. Возвращает код выхода 0 при PASS и ненулевой при FAIL. Никаких сетевых вызовов и учётных данных не требуется.
Настройка Claude Desktop
Добавьте в claude_desktop_config.json:
{
"mcpServers": {
"alphafold-sovereign": {
"command": "alphafold-sovereign-mcp",
"args": []
}
}
}
Перезапустите Claude Desktop — и инструменты станут доступны в диалогах. Попробуйте, например, спросить: «Проведи триаж BRCA1 c.5266dupC» или «Оцени EGFR как мишень для лекарства». В каталоге examples/ приведены три сквозных примера того, как выглядит сессия.
Офлайн-режим
ALPHAFOLD_OFFLINE=1 alphafold-sovereign-mcp
Отклоняет исходящие HTTP-запросы до открытия сокета (выбрасывая AirGapError), кроме хостов, явно разрешённых через ALPHAFOLD_ALLOW_HOSTS. Инструменты запроса и экспорта графа знаний по-прежнему отвечают из локального хранилища SQLite. У инструментов, обращающихся к вышестоящим источникам, нет локального кэша, и они сообщают, что их источник недоступен; учтите, что инструменты работы со структурами сейчас представляют это как результат «нет модели AlphaFold», а не как явную ошибку офлайн-режима.
Перечень инструментов
Сервер предоставляет 30 инструментов MCP в четырёх модулях. Входная схема каждого инструмента — это модель Pydantic; результаты — в формате JSON.
Болезни и онтология (tools/disease.py)
| Инструмент | Назначение |
|---|---|
lookup_disease | Запись MONDO + иерархия + перекрёстные ссылки на ICD |
search_diseases | Полнотекстовый поиск по онтологии MONDO |
lookup_phenotype | Термин HPO + связанные заболевания |
get_gene_phenotype_profile | Фенотипы HPO + ограничения gnomAD для гена |
get_disease_targets | Ведущие лекарственные мишени для заболевания MONDO (Open Targets) |
get_target_diseases | Ведущие заболевания для мишени UniProt (Open Targets) |
get_common_disease_targets | Параллельный анализ по курируемым заболеваниям MONDO |
triage_variant_3d | HGVS → ClinVar + ограничения gnomAD (контекст заболевания/структуры: пояснительные заметки) |
phenotype_to_structures | HPO → заболевания → мишени OT → идентификаторы UniProt |
get_orphan_disease_atlas | Orphanet → MONDO → HPO + мишени OT |
compare_disease_target_overlap | Сходство Жаккара для наборов мишеней двух заболеваний |
resolve_icd10_to_mondo | Код ICD-10 → запись заболевания MONDO |
Персонализированная медицина (tools/precision_medicine.py)
| Инструмент | Назначение |
|---|---|
generate_variant_clinical_report | HGVS → отчёт из нескольких источников + черновик критериев ACMG/AMP |
assess_target_druggability | UniProt → уровень HOT/WARM/COLD/NOT_DRUGGABLE |
synthesize_protein_dossier | UniProt → сводка из нескольких источников |
map_disease_drug_landscape | MONDO → одобренные препараты + пайплайн + счётчики фаз ChEMBL |
classify_variant_acmg | HGVS → чек-лист критериев ACMG/AMP (PVS1, PM2, PP3, BP4, BP7, BS1, PP5) |
find_drug_repurposing_candidates | MONDO → кандидаты, ранжированные по доказательности OT × фаза ChEMBL |
Критерии ACMG/AMP, которые формируются таким образом, — это черновик: они отражают
исходные доказательства, которые сервер способен получить автоматически, и
не заменяют собой клинико-лабораторную экспертизу.
Анализ структур (tools/structure_intelligence.py)
| Инструмент | Назначение |
|---|---|
analyze_structural_confidence | средний pLDDT + уровень уверенности + границы доменов, выведенные из PAE |
compute_topology_fingerprint | 64-мерный TDA-отпечаток (числа Бетти β₀ β₁ β₂) |
compare_proteins_topologically | Матрица попарных L2-расстояний между отпечатками для 2–10 белков |
find_evolutionary_structural_shifts | Межвидовая структурная дивергенция (TDA + ортологи Ensembl) |
score_binding_pocket_geometry | Геометрическое обнаружение карманов + эвристический индекс druggability |
detect_intrinsically_disordered | Карта IDR (линкеры, хвосты, длинные IDR) |
get_protein_structure | Получение модели AlphaFold: метаданные, ссылки для скачивания, опционально координаты |
Граф знаний (tools/knowledge_graph_tools.py)
| Инструмент | Назначение |
|---|---|
query_variant_database | Поиск по локально сохранённым результатам триажа вариантов |
query_protein_database | Поиск по локально сохранённым оценкам белков |
get_knowledge_graph_stats | Размер базы данных, количество сущностей, последняя активность |
export_research_dataset | Экспорт таблиц в JSON для пайплайнов pandas/ML |
find_drug_gene_network | Обход локального графа лекарство–ген–заболевание |
Примеры использования
Три документированных сквозных примера работы сессии Claude Desktop
с этим сервером — триаж варианта BRCA1 c.5266dupC,
характеристика мишени EGFR и пошаговый разбор поиска лекарств
для Imatinib → BCR-ABL → CML — доступны в каталоге
Каждый пример включает пользовательский запрос, вызовы инструментов,
которые делает модель, формат ответа сервера и пересказанный ответ модели.
Клинический отчёт по варианту
G")">
generate_variant_clinical_report(hgvs="BRCA1:c.181T>G")
Сервер разрешает HGVS, получает данные из ClinVar, gnomAD, AlphaMissense
(через AlphaFold DB), доказательства связи с заболеванием из Open Targets,
данные о препаратах из ChEMBL и аннотации последствий Ensembl VEP,
а затем возвращает единую JSON-запись с перекрёстно связанными полями
и критериями ACMG/AMP, которые подтверждаются доступными доказательствами.
Перепрофилирование препаратов
find_drug_repurposing_candidates(disease_mondo_id="MONDO:0007739")
Возвращает препараты, чьи доказательства в Open Targets связывают их с
заболеванием, ранжированные по композитному показателю: оценка
доказательности OT × максимальная клиническая фаза ChEMBL, достигнутая
по данной мишени.
Межвидовая структурная дивергенция
find_evolutionary_structural_shifts(
gene_symbol="ACE2",
target_species=["mus_musculus", "rhinolophus_ferrumequinum"]
)
Для каждого вида: получает ортолог (Ensembl), структуру AlphaFold,
вычисляет TDA-отпечаток и возвращает L2-расстояние отпечатка
от структуры человека вместе с идентичностью последовательности.
Источники данных
| Источник | Что используется | Лицензия |
|---|---|---|
| AlphaFold DB v6 (EBI/DeepMind) | Структуры, pLDDT, PAE, AlphaMissense | CC BY 4.0 |
| MONDO (OLS4) | Онтология заболеваний, перекрёстные ссылки на ICD | CC BY 4.0 |
| HPO (JAX) | Термины фенотипов, связи ген–заболевание | Лицензия HPO (бесплатно для любого использования) |
| Open Targets | Доказательства связи заболевание–мишень | CC0 1.0 (данные) |
| ClinVar (NCBI) | Патогенность вариантов | Общественное достояние |
| gnomAD v4 | Популяционные частоты аллелей | CC0 1.0 |
| DisGeNET | Оценки ассоциаций ген–заболевание | Бесплатный академический тариф / коммерческая лицензия (MedBioinformatics) |
| ChEMBL v37 (EMBL-EBI) | Биоактивность препаратов, MoA, ADMET | CC BY-SA 3.0 |
| Ensembl (EMBL-EBI) | VEP, ортологи, поиск генов | Без ограничений (данные); Apache 2.0 (код) |
Идентификаторы UniProt повсеместно используются как идентификаторы
белков — они служат ключами для структур AlphaFold и перекрёстных
ссылок Open Targets — однако сам API UniProt в качестве источника данных
не опрашивается. Поиск по доменам (InterPro), Gene Ontology, по
экспериментальным структурам (RCSB PDB) и по тканевой экспрессии
(Human Protein Atlas) в этом релизе не интегрирован.
Полные сведения об атрибуции см. в NOTICE.
Архитектура
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)
Полную карту модулей см. в ARCHITECTURE.md.
Тестирование и качество
- Обширный набор офлайн-юнит-тестов (с моками восходящих сервисов через respx,
включая параметризованные расширения); полный набор прогоняется герметично
менее чем за минуту на ноутбуке.
- Покрытие на поставляемой поверхности (
src/alphafold_sovereign/clients,
domain, storage, server, tools): 100% строк + ветвей,
каждый поставляемый модуль — на 100%.
- Линтинг:
ruff(полный набор правил). Проверка типов:mypy --strictпо
всему дереву исходников.
-
Безопасность:
banditплюс CodeQLsecurity-extended. -
Цепочка поставок: релизный CI собирает и аттестует дистрибутивы, генерирует
привязанный к колесу CycloneDX SBOM из установленного замыкания
runtime-зависимостей и подписывает релизные артефакты через Sigstore.
scripts/replicate.sh независимо скачивает опубликованные wheel и sdist,
проверяет их хеши PyPI и бандлы Sigstore, а также проверяет привязку
CycloneDX в релизе. SLSA provenance генерируется в CI; его прикрепление
к каждому релизу GitHub остаётся пунктом дорожной карты.
Полная матрица CI (Python 3.10, 3.11, 3.12, 3.13 × Ubuntu, macOS)
запускается на каждый push. Указанный выше процент покрытия — это число,
которое выдаёт git clone && uv run nox -s cov на текущем HEAD; если вы
обнаружите расхождение, пожалуйста, откройте issue.
Участие в разработке
Требуется подпись DCO (git commit -s). Передача авторских прав не требуется.
Порог покрытия: CI требует 100% покрытия строк и ветвей на поставляемой поверхности (nox -s cov).
Полное руководство: CONTRIBUTING.md.
Другие MCP-серверы того же автора
-
uniprot-mcp — сервер Model Context Protocol для UniProt Swiss-Prot и TrEMBL (
pip install uniprot-mcp-server). -
semantic-scholar-mcp — MCP-сервер Semantic Scholar, более 200 млн научных статей (
pip install s2-mcp-server).
Цитирование
Машиночитаемые метаданные: CITATION.cff. На основе этого файла GitHub отображает в боковой панели кнопку «Cite this repository».
@software{maniches_alphafold_sovereign_mcp,
author = {Maniches, Santiago},
title = {AlphaFold Sovereign MCP},
year = {2026},
version = {1.4.9},
url = {https://github.com/smaniches/alphafold-sovereign-mcp},
license = {Apache-2.0},
orcid = {0009-0005-6480-1987},
doi = {10.5281/zenodo.20134773}
}
При цитировании результатов, полученных с помощью данного ПО, пожалуйста, указывайте также первичные источники данных (AlphaFold DB, Open Targets, ChEMBL, Ensembl, ClinVar, gnomAD, MONDO, HPO, DisGeNET) в соответствии с их собственными требованиями к цитированию.
Лицензия
Copyright 2024–2026 Santiago Maniches.
Проект распространяется по лицензии Apache License, Version 2.0. Подробности см. в файле LICENSE.
Положение о патентах: см. PATENTS.md.
Политика в отношении товарных знаков: см. TRADEMARKS.md.