protein-mcp-server

Публичный сервер: https://protein.caseyjhand.com/mcp

Инструменты

Семь инструментов, охватывающих весь цикл исследования структуры — поиск, получение, поиск гомологов, отслеживание лигандов, сравнение, профилирование корпуса и аннотирование — для экспериментальных (PDB) и предсказанных (AlphaFold) структур из одного интерфейса:

protein_search_structures

Федеративный поиск по экспериментальным (PDB) и предсказанным (вычислительным моделям) структурам через RCSB Search v2.

• Фильтры по свободному тексту, последовательности белка (запускает поиск подобия mmseqs2), а также по организму / методу / разрешению

• content_type ограничивает поиск значениями experimental, predicted или all — по умолчанию all является настоящим объединением обеих вселенных, поэтому вычислительные модели появляются рядом с записями PDB

• Каждый результат указывает свой source; экспериментальные результаты обогащены заголовком, методом, разрешением и организмом, а вычислительные модели несут UniProt-аксессор, извлечённый из их ID

• Опциональные facets возвращают разбивку по методу / организму / году выпуска вместе с результатами без дополнительного вызова, каждый из которых сообщает, сколько совпадений не имеют значения для этого измерения; каждое измерение может быть указано один раз

• Передавайте ID результатов напрямую в protein_get_structure

protein_get_structure

Получение структур с метаданными и URL файлов координат, разрешение по провайдерам через source.

• source: experimental принимает ID записей PDB, пакетно в одном вызове RCSB GraphQL; он также разрешает ID вычислительных моделей, возвращаемые поиском (AF_* / MA_*), которые возвращаются как source: predicted с указанием провайдера моделирования

• source: predicted принимает UniProt-аксессоры и возвращает модель AlphaFold с уверенностью pLDDT/PAE

• source: best_available принимает UniProt-аксессоры и возвращает лучшую федеративную модель (экспериментальную, если она существует, иначе лучшее предсказание)

• Частичный успех по каждому ID — неразрешённые ID перечисляются в failed[], а не как ошибка уровня пакета

• include_coords встраивает содержимое координат; когда пакет превышает бюджет ответа, возвращается сводка размеров по каждой структуре, так что вы можете повторить вызов с sections: [ids] для конкретных структур

• Каждый ответ содержит блок attribution с указанием лицензий и цитат исходных данных (см. Лицензирование исходных данных)

protein_find_similar

Поиск структурно или эволюционно родственных белков по последовательности или по структуре.

• by: sequence выполняет синхронный поиск RCSB mmseqs2; by: structure выполняет асинхронный поиск Foldseek по экспериментальным и предсказанным базам данных

• Запрос по сырой однобуквенной последовательности, PDB ID или UniProt-аксессору

• Цели Foldseek по умолчанию: pdb100 + afdb50; переопределите через databases (например, afdb-swissprot, BFVD)

• Асинхронные задания, превышающие бюджет опроса, возвращают status: computing с ticketId — повторите вызов с ticket_id, установленным в это значение, чтобы опросить то же задание вместо повторной отправки

• Каждый результат указывает движок и исходную базу данных, из которой он получен

protein_track_ligands

Обнаружение лигандов и анализ сайтов связывания по всему PDB.

• mode: find_ligand преобразует название или формулу в ID химических компонентов с формулой, весом, SMILES и InChIKey

• mode: structures_with_ligand возвращает записи PDB, содержащие лиганд, по точному ID компонента

• mode: binding_site возвращает остатки белка, выстилающие карман лиганда в структуре, с расстояниями контактов

• Сайты связывания доступны только для экспериментальных структур — вычисляются из депонированных координат (предсказанные модели не содержат связанных лигандов)

protein_compare_structures

Структурное выравнивание нескольких структур (до настроенного предела PROTEIN_MAX_COMPARE_STRUCTURES) через сервис структурного сравнения RCSB.

• Методы: tm-align, fatcat-rigid, fatcat-flexible

• reference: first выравнивает каждую структуру относительно первой; reference: all_pairs вычисляет полную попарную матрицу

• Опциональный chain для каждой структуры ограничивает выравнивание одной цепью

• Структура, повторяющаяся в structures[], сравнивается один раз — повтор добавил бы только самовыравнивание и зеркальную пару, которые механизм возобновления не может отличить от оригинала

• Каждая пара — это независимое асинхронное задание, распределяемое с ограничением параллелизма и частичным успехом по каждой паре — пара, всё ещё вычисляющаяся по истечении бюджета, возвращает status: computing с uuid задания, а неудачная пара ухудшает свою строку, не затрагивая остальные

• Повторите вызов с соответствующим элементом { a, b, uuid } в resume[] (скопированным из pairs[] предыдущего ответа), чтобы опросить задание вычисляющейся пары вместо повторной отправки

• Возвращает TM-score, RMSD и количество выровненных остатков для каждой пары, а также modeledResidues и coverage — каждый в виде кортежа [a, b], где coverage — процент 0–100 от количества смоделированных остатков этой структуры

protein_analyze_collection

Профилирование PDB на распределения и тренды по опциональному ограничивающему запросу — на основе серверного фасетного движка RCSB (один вызов, компактные корзины, без выгрузки строк).

• Группировка по method, organism, polymer_type, resolution, release_year или molecular_weight

• Одно измерение group_by для разбивки или два различных измерения для перекрёстной таблицы (первое вкладывает второе); повторяющееся измерение отклоняется

• interval задаёт ширину корзины для гистограмм значений или период для гистограмм дат (year / month / quarter)

• Ограничьте область с помощью свободного текста query, organism, method или max_resolution; content_type выбирает вселенную структур

• bucket_limit ограничивает количество корзин на уровень измерения, а не на ответ — перекрёстная таблица применяет его отдельно к родительскому измерению и к вложенному дочернему внутри каждой родительской корзины, поэтому возвращается до bucket_limit × (1 + bucket_limit) корзин. Каждый уровень отмечает собственное усечение, а bucketsReturned даёт фактическое общее количество

• Каждое измерение сообщает missingValueCount — совпадения в области, не имеющие значения для этого атрибута, которые поэтому не попадают ни в одну корзину (разбивка по resolution не охватывает записи ЯМР, и ни method, ни resolution не охватывают вычислительные модели)

protein_get_annotations

Последовательность и функциональная аннотация белка.

• Функции UniProt (домены, сайты связывания, посттрансляционные модификации) и природные варианты последовательности

• Членство в доменах/семействах InterPro (Pfam, PROSITE, …) с соответствующими GO-терминами

• Укажите UniProt-аксессор напрямую или PDB ID — разрешается в UniProt-аксессор через перекрёстную ссылку на последовательность структуры

• Мультицепная запись PDB может соответствовать нескольким аксессорам; по умолчанию выбирается детерминированная цепь с наименьшим авторским индексом, альтернативы перечислены в ambiguity. Передайте chain (ID авторской цепи, например A), чтобы выбрать конкретную

• include ограничивает, какие классы аннотаций извлекаются: features, domains, variants или all

• Каждый ответ содержит блок attribution с указанием лицензий и цитат исходных данных (см. Лицензирование исходных данных)

Related MCP server: UniProt MCP Server

Ресурсы

Все данные ресурсов также доступны через инструменты — pdb://{entry_id} соответствует protein_get_structure для source: experimental, а af://{uniprot} — для source: predicted. Многие MCP-клиенты поддерживают только инструменты и не отображают ресурсы; сводки остаются доступными через инструменты.

Возможности

Построено на @cyanheads/mcp-ts-core:

• Декларативные определения инструментов и ресурсов — один файл на примитив, фреймворк обрабатывает регистрацию и валидацию

• Единая обработка ошибок — обработчики выбрасывают исключения, фреймворк перехватывает, классифицирует и форматирует

• Подключаемая аутентификация: none, jwt, oauth

• Сменяемые бэкенды хранилища: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Структурированное логирование с опциональной трассировкой OpenTelemetry

• Транспорты STDIO и Streamable HTTP

Специфика белков:

• Единая федеративная поверхность для экспериментальных (PDB) и предсказанных (AlphaFold / 3D-Beacons) структур — поиск, получение и сравнение обрабатывают обе вселенные одинаково

• Без ключей для всех вышестоящих источников — RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro и Foldseek, не требуется настраивать API-ключи

• Аналитика корпуса выполняется на стороне сервера на движке фасетов RCSB — распределения, гистограммы и перекрёстные таблицы одним вызовом, без выгрузки строк и без SQL-рабочего пространства

• Асинхронные задания выравнивания и Foldseek опрашиваются в рамках ограниченного бюджета и возвращают билет задания (ticketId / uuid для каждой пары) вместо блокировки — повторный вызов с ticket_id или записью resume[] позволяет опросить то же задание, а не отправлять его заново

Вывод, удобный для агентов:

• Происхождение данных в каждом ответе — каждый результат несёт source (experimental / predicted), движок и базу данных, которые его создали, а также эхо эффективного запроса и общего количества, чтобы агенты могли оценивать покрытие

• Корректное частичное сбои — пакетные выборки и попарные сравнения возвращают строки по каждому элементу (failed[], status для каждой пары) вместо отказа всего запроса, каждая с практическими рекомендациями по восстановлению

• Различаемые выходные контракты — типизированные объединения source и status, результаты computing с билетами возобновления и описания переполнения бюджета позволяют вызывающим ветвиться на основе данных, а не разбора строк

Начало работы

Публичный размещённый экземпляр

Публичный экземпляр доступен по адресу https://protein.caseyjhand.com/mcp — установка не требуется. Направьте любой MCP-клиент на него через Streamable HTTP:

{
  "mcpServers": {
    "protein": {
      "type": "streamable-http",
      "url": "https://protein.caseyjhand.com/mcp"
    }
  }
}

Самостоятельное размещение

Добавьте следующее в файл конфигурации вашего MCP-клиента. API-ключ не требуется — все вышестоящие провайдеры работают без ключей.

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/protein-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Или с помощью npx (Bun не требуется):

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/protein-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Или с помощью Docker:

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/protein-mcp-server:latest"]
    }
  }
}

Для Streamable HTTP установите транспорт и запустите сервер:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Предварительные требования

• Bun v1.3.2 или выше (или Node.js v24+).

• Никаких учётных записей или API-ключей — RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro и Foldseek — все публичные и не требуют ключей.

Установка

1. Клонируйте репозиторий:

git clone https://github.com/cyanheads/protein-mcp-server.git

2. Перейдите в каталог:

cd protein-mcp-server

3. Установите зависимости:

bun install

Конфигурация

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

См. .env.example для полного списка переопределений базовых URL провайдеров и пределов настройки.

Запуск сервера

Локальная разработка

• Сборка и запуск:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Запуск проверок и тестов:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t protein-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 protein-mcp-server

Dockerfile по умолчанию использует HTTP-транспорт, режим без сохранения состояния сессий и записывает логи в /var/log/protein-mcp-server. Зависимости OpenTelemetry peer устанавливаются по умолчанию — соберите с --build-arg OTEL_ENABLED=false, чтобы исключить их.

Структура проекта

Руководство по разработке

См. CLAUDE.md/AGENTS.md для руководства по разработке и архитектурных правил. Краткая версия:

• Обработчики выбрасывают исключения, фреймворк перехватывает — никаких try/catch в логике инструментов

• Используйте ctx.log для логирования в рамках запроса, ctx.state для хранилища в рамках тенанта

• Регистрируйте новые инструменты и ресурсы через баррели в src/mcp-server/*/definitions/index.ts

• Оборачивайте внешние API-вызовы: валидируйте сырые данные → нормализуйте в доменный тип → возвращайте схему вывода; никогда не выдумывайте отсутствующие поля

Вклад

Приветствуются issues и pull request'ы. Запустите проверки и тесты перед отправкой:

bun run devcheck
bun run test

Лицензирование данных вышестоящих источников

Структурные и аннотационные данные поступают из публичных вышестоящих баз данных, каждая под своей лицензией. protein_get_structure и protein_get_annotations содержат блок attribution в каждом ответе — лицензию, цитирование и домашнюю страницу для каждого источника, внёсшего вклад в этот конкретный ответ, — так что обязательство по атрибуции передаётся вместе с данными конечным потребителям, а не остаётся только здесь. Источники CC BY / CC BY-SA требуют указания авторства при распространении; источники CC0 требуют только цитирования (указание авторства рекомендуется, но не обязательно).

best_available объединяет предсказанные модели через 3D-Beacons, поэтому блок attribution указывает фактического поставщика (AlphaFold DB, SWISS-MODEL, BFVD, …); поставщик без курируемой записи лицензии получает запасной вариант See provider terms, указывающий обратно на 3D-Beacons, а не выдуманную лицензию. Собственные классификации доменов/семейств InterPro имеют лицензию CC0; термины GO, передаваемые вместе с ними, отдельно лицензированы CC BY 4.0, поэтому каждый из них указывается независимо только тогда, когда он действительно вносит вклад. Полные цитаты для каждого источника передаются в блоке attribution соответствующих ответов инструментов. Это касается лицензирования данных вышестоящих источников — собственный код сервера лицензирован отдельно (см. Лицензия).

Лицензия

Apache-2.0 — см. LICENSE для подробностей.