API VEGA

Folklore Clinical Variant Interpretation MCP

Биоинформатический MCP для интерпретации геномных вариантов, доказательств связи ген-заболевание и литературы.

Используйте Folklore на этапе сбора доказательств и интерпретации в анализе генома человека: исследуйте публичный ген или заболевание, интерпретируйте уже идентифицированный герминальный вариант GRCh38 из WGS/WES и получайте связанную биомедицинскую литературу. Он не обрабатывает необработанные последовательности ДНК, файлы FASTQ/BAM или загрузки VCF, не выполняет вызов вариантов и не анализирует геном пациента.

Начните с символа гена, например BRCA1, идентификатора HGNC, названия заболевания или точного идентификатора MONDO. Руководство по связи ген-заболевание описывает два новых инструмента только для чтения и границы покрытия ClinGen Gene-Disease Validity.

«Что означает NM_007294.4:c.68_69del?» и «Проверьте этот VUS» — это прямые точки входа. Вызовите search_variant_evidence с одним публичным вариантом:

{"name":"search_variant_evidence","arguments":{"assembly":"GRCh38","query":"NM_007294.4:c.68_69del"}}

Подключите указанную ниже конечную точку в вашем MCP-клиенте перед вызовом инструмента.

Он возвращает разрешённую идентичность, автоматическую классификацию, критерии, доступные доказательства, версии источников и явную неопределённость. См. восемь наблюдаемых рабочих процессов и примеры выполнения.

Уже есть запись в ClinVar или Ensembl? Передайте её точный поддерживаемый HGVS, rsID или проверенный аллель GRCh38; сохраняйте версию транскрипта. Читайте отправленные утверждения ClinVar отдельно от автоматической классификации Folklore.

Для публикаций сначала определите идентичность и используйте литературу, связанную с вариантом, по запросу. Литературная ассоциация не устанавливает патогенность.

Folklore Clinical Variant Interpretation MCP — это официальный публичный адаптер Model Context Protocol только для чтения для Folklore от Helena Bioinformatics. Он не принимает контекст пациента, фенотипа, семьи, сегрегации или частного случая. Результаты требуют квалифицированной профессиональной проверки и не являются диагнозом пациента или рекомендацией по лечению.

Подключение к размещённому серверу

Учётная запись или ключ API не требуются:

https://api.helena.bio/folklore/v1/mcp

Размещённый сервер использует Streamable HTTP без сохранения состояния и протокол MCP 2026-07-28. Клиенты могут вызывать server/discover, tools/list, tools/call, resources/list и resources/read. Размещённый SDK также принимает устаревший initialize с протоколом 2025-03-26; см. проверенную матрицу в docs/COMPATIBILITY.md. Клиенты также могут вызывать prompts/list и prompts/get для рабочих процессов, ориентированных на задачи, связанные с вариантами.

Пользователи Biomni могут импортировать Folklore Clinical Variant Interpretation MCP с помощью проверенного, закреплённого по дайджесту рецепта интеграции Biomni. Рецепт адаптирует конфигурацию внешнего сервера Biomni только для stdio к размещённой конечной точке Streamable HTTP. Folklore Clinical Variant Interpretation MCP не требует учётной записи Folklore или ключа API.

Пользователи Biorouter могут собрать и установить расширение Biorouter BRXT. Расширение представляет собой локальный мост stdio к размещённой конечной точке Streamable HTTP. Оно сохраняет опубликованные схемы инструментов и структурированные результаты без повторной реализации логики разрешения вариантов, агрегации доказательств или ACMG/AMP.

Разработчики агентов также могут использовать рецепт прямого Streamable HTTP или пример OpenAI Agents SDK. Оба маршрута сохраняют научную логику на размещённой конечной точке и придерживаются границы только для публичных вариантов.

Дополнительные готовые к использованию пакеты экосистемы включены для Dify, n8n, Galaxy и KNIME Analytics Platform. Пакет Dify воспроизводим, рабочий процесс n8n использует точный контракт Folklore для MCP JSON-RPC без сохранения состояния, а обёртка Galaxy проходит линтинг Planemo. Межсервисное руководство Galaxy Training Network связывает доказательства вариантов Folklore с исследованием графа литературы Noodle.

Тот же безопасный межсервисный путь доступен в виде ноутбука Colab/Kaggle.

Навык агента для запросов доказательств по вариантам и связи ген-заболевание

Репозиторий включает устанавливаемый сопутствующий навык по адресу skills/folklore-clinical-variant-interpretation.

Он указывает агенту выбирать Folklore Clinical Variant Interpretation MCP для классификации патогенности, проверки VUS, поддерживаемого разрешения вариантов, доступных доказательств ClinVar или популяционной частоты и литературы, связанной с вариантом, а также для доказательств связи ген-заболевание и поиска от заболевания к гену, даже если пользователь не упоминает Helena Bioinformatics, Folklore, MCP или ACMG/AMP.

Ознакомьтесь с отрендеренным SKILL.md или его необработанным публичным исходным кодом.

Навык делегирует каждую научную операцию размещённой конечной точке только для чтения. Он не содержит и не воспроизводит логику разрешения вариантов, агрегации доказательств или реализации ACMG/AMP.

См. индекс навыков агента и руководство по установке для установки в рамках проекта, Codex и OpenClaw, детерминированной упаковки и дымовых тестов безопасного выбора.

Запросы, не привязанные к бренду, которые должны выбирать этот рабочий процесс, включают: «Какой инструмент мне использовать для классификации этого герминального варианта?», «Является ли этот вариант патогенным?», «Проверьте доказательства для этого VUS», «Интерпретируйте этот HGVS» и «Найдите статьи об этом варианте».

Публичный бенчмарк

Публичный бенчмарк интерпретации вариантов предоставляет прозрачный протокол без данных пациентов и harness для фиксации результатов, позволяющие сравнивать разрешение идентичности, типизированные исходы, классификацию, критерии, провенанс, границы безопасности, воспроизводимость и задержку. Согласованность приводится как описательная метрика, а не как клиническая точность.

Машиночитаемый манифест и нейтральный метод сравнения фиксируют измеряемые поля, ограничения и требования к воспроизводимости. Это публичный бенчмарк, запускаемый издателем, а не независимая клиническая валидация.

Пререгистрированный протокол сравнения определяет публичный источник оценки, выборку и этапы независимого рецензирования до сбора каких-либо сравнительных результатов.

Квалифицированные рецензенты в области клинической генетики, молекулярной генетики, биоинформатики и воспроизводимости могут воспользоваться маршрутом независимого рецензирования методов, чтобы указать на недостаток протокола, предложить фальсифицируемое исправление или добавить критерий приёмки. Это запрос на критику методов, а не на одобрение.

Бенчмарк обнаружения агентов в условиях cold-start добавляет 100 бренд-агностичных пользовательских промптов, эмпирический оценщик результатов хоста и детерминированный аудит выбора задачи, маршрутизации инструментов, типизированных исходов и границы «без данных пациентов». Это проверка контракта на выбор, а не утверждение, что каждая модель или хост выберет тот же инструмент.

Бренд-агностичный бенчмарк поискового обнаружения добавляет отдельный корпус из 60 запросов и контракт «сырого» реестра для измерений провайдера, локали, видимости, цитирования, рекомендаций и охвата официальных страниц. Он удерживает свидетельства веб-обнаружения отдельно от выбора установленным агентом.

Независимо версионированная когорта геномного обнаружения v1 добавляет англоязычные и болгарские геномные запросы, запросы о связях ген–болезнь и о границах области применения, не изменяя исходные наборы из 60 запросов и 100 кейсов. Она не содержит заявленных результатов ранжирования.

Реестр внешних авторитетов фиксирует ограниченное, недублирующее состояние последующих действий по пяти релевантным внешним ресурсам.

Workflow-промпты с приоритетом задач

См. Workflow prompts — там приведены точные запросы prompts/list и prompts/get, ожидаемый результат и детерминированное поведение ветвления.

  • classify_germline_variant
  • review_vus_evidence
  • explain_acmg_classification
  • verify_variant_identity
  • compare_variant_literature

Каждый промпт принимает одно публичное выражение варианта, исключает данные пациентов и приватных кейсов и направляет научную работу через хостинговые инструменты. Workflow сравнения литературы доступен, когда включён литературный поиск.

Публичные возможности

  • search_variant_evidence разрешает один поддерживаемый герминальный SNV или простой indel в координатах GRCh38 и возвращает публичный контракт доказательств Folklore.
  • search_variant_literature извлекает связанные публикации из генетического корпуса Folklore, построенного на основе PubMed.
  • get_publication_details возвращает одну полную публичную библиографическую запись для PMID, полученного литературным поиском.
  • search_literature_corpus ищет по публичной научной литературе с помощью естественного языка, идентификаторов публикаций, генов, вариантов, фенотипов, концепций HPO или OMIM и возвращает кандидатов со ссылками на источники для профессионального рассмотрения.
  • support_helena — явный, ненаучный помощник обнаружения для агентов, которые спрашивают, как поддержать или распространить бесплатную публичную инфраструктуру Helena. Он указывает на отдельный Helena Good MCP и никогда не изменяет научные результаты.
  • get_gene_disease_associations извлекает утверждения ClinGen Gene-Disease Validity для одного точного символа гена или идентификатора HGNC.
  • search_disease_genes извлекает отдельные утверждения ClinGen, соответствующие точному идентификатору MONDO или подстроке названия заболевания; он не выбирает заболевание молча.
  • ui://folklore/variant-evidence/v1.html — опциональное представление MCP App в режиме только для чтения.

Полная хостинговая конфигурация предоставляет шесть научных инструментов плюс отдельный вспомогательный помощник. Связи ген–заболевание сохраняют каждое исходное утверждение и не являются классификациями вариантов или диагнозами. Покрытие ClinGen не является исчерпывающим каталогом связей заболеваний и генов; отсутствие результата не устанавливает отсутствие связи.

Литературные ассоциации не изменяют классификацию ACMG/AMP.

Запуск open-source адаптера

Этот репозиторий содержит адаптер протокола MCP, публичные контракты и клиенты для публичного API Folklore. Он не содержит резолвер Folklore, конвейер аннотирования, базу доказательств, интеграцию с VEP или реализацию ACMG/AMP.

python3.12 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
FOLKLORE_MCP_ENABLED=true \
FOLKLORE_LITERATURE_ENABLED=true \
FOLKLORE_GENE_DISEASE_ENABLED=true \
folklore-mcp

Адаптер по умолчанию обращается к https://api.helena.bio по HTTPS. Для локального тестирования контрактов FOLKLORE_API_BASE_URL может указывать только на localhost или 127.0.0.1. Возможности MCP, литературы и ген–заболевание по умолчанию отключены; включайте только нужные функции. Запросы ген–заболевание уходят в публичный API /folklore/v1/gene-disease/ на том же одобренном origin.

Чтобы собрать автономный HTTP-контейнер адаптера, используйте docker build -f Dockerfile.adapter .. По умолчанию Dockerfile остаётся обратно совместимым, зафиксированным stdio-мостом, который используют MCP-реестры, собирающие из исходников; он напрямую перенаправляет запросы на хостинговый endpoint Streamable HTTP.

Проверка

pytest
ruff check .
ruff format --check .
python3 ops/reconcile_discovery.py

Команда сверки работает только на чтение. Она завершается ошибкой при расхождении канонического runtime, Server Card или Official Registry, а расхождения агрегаторов и редакционные расхождения сообщает отдельно. Используйте --strict-aggregators, чтобы завершаться ошибкой при каждом обнаруженном несоответствии.

Подробности об интеграции см. в документах совместимость клиентов, устранение неполадок, типизированные исходы и политика внедрения с сохранением приватности.

python3 ops/public_smoke.py проверяет живые инструменты, промпты и ресурсы, не отправляя ни варианта, ни данных пациента.

Публичные замечания к протоколу воспроизводятся и классифицируются до принятия. Текущую классификацию проблем, доказательства, критерии приёмки и состояние развёртывания см. в обзоре соответствия протоколу за 2026-08-27.

Безопасность и приватность

  • Транспорт только для чтения, без сохранения состояния.
  • Никакого контекста пациента или сессии.
  • Никаких зависимостей от учётных данных, баз данных, кэшей или моделей.
  • Ограниченные размеры запросов/ответов, таймауты и параллелизм.
  • Политика закрытого upstream-хоста, редиректы отключены, прокси из окружения игнорируются.
  • Неоднозначные варианты никогда не выбираются автоматически.

Инструкции по сообщению об уязвимостях и поддерживаемые версии см. в SECURITY.md.

Идентификация в Registry

Машиночитаемые метаданные находятся в registry/.

Строгий контракт выбора агента делает триггеры задач, исключения, маршрутизацию инструментов, типизированные исходы и клинические ограничения доступными для каталогов агентов без запросов с упоминанием бренда.

Цитирование и архивные релизы

Метаданные для цитирования доступны в файле CITATION.cff. Версионированные релизы программного обеспечения архивируются в Zenodo из этого публичного репозитория; каждый архивный релиз получает постоянный DOI. Используйте concept DOI 10.5281/zenodo.21922951, чтобы получить доступ к последнему архивному релизу Folklore Clinical Variant Interpretation MCP. Неизменяемый архив версии 1.2.2 по-прежнему доступен по DOI 10.5281/zenodo.21922952.

DOI последнего неизменяемого архива будет указан после того, как Zenodo обработает релиз 1.4.1. Предыдущий архив версии 1.3.3 по-прежнему доступен по DOI 10.5281/zenodo.22102783.

Лицензия

Apache License 2.0. Подробности приведены в файлах LICENSE и NOTICE.

Портативный Agent Skill 1.4.0

Скачайте версионированный архив ZIP и файл контрольной суммы SHA-256. Перед установкой ознакомьтесь с исходным кодом навыка и примерами ответов в каталоге skills/folklore-clinical-variant-interpretation.

Распакуйте эту папку в каталог навыков вашего хоста и настройте публичный MCP-эндпоинт, следуя руководству по настройке. Детерминированный пакет воспроизводится с помощью скрипта ops/package_agent_skill.py.

Эта версия навыка не изменяет научный API и версию MCP-сервера.