snowstorm-mcp-server

MCP-сервер для запросов клинической терминологии SNOMED CT через бэкенды Snowstorm и Snowstorm Lite.

SNOMED CT — самая полная в мире клиническая терминология, используемая в электронных медицинских картах более чем в 80 странах. Этот сервер предоставляет поиск, проверку, навигацию по иерархии и расширение наборов значений SNOMED CT через Model Context Protocol (MCP), позволяя AI-ассистентам работать с клинической терминологией напрямую.

Поддерживаются все редакции SNOMED CT, доступные на подключённом бэкенде (International, US, UK, AU и т. д.). При подключении к публичному экземпляру Snowstorm учётная запись не требуется.

Этот репозиторий поддерживает два связанных, но различных режима использования:

1. Размещённый удалённый коннектор: запустите публичную HTTPS MCP-конечную точку и подключите Claude к ней через пользовательский коннектор / поток Connector Directory.

2. Самостоятельное размещение и локальное использование: запустите сервер самостоятельно против собственного развёртывания Snowstorm или Snowstorm Lite, включая сценарии упаковки для Claude Desktop и будущего MCPB.

Если вы готовите размещённый коннектор для Claude web/desktop/mobile, начните с раздела «Размещённый удалённый коннектор». Если вы хотите запустить сервер самостоятельно против собственного терминологического бэкенда, начните с раздела «Самостоятельное размещение и локальное использование».

Размещённый удалённый коннектор

Используйте этот режим, когда вы управляете публичной MCP-конечной точкой, например https://your-domain.example/mcp, и хотите, чтобы Claude подключался к ней из инфраструктуры Anthropic.

Размещённое развёртывание (Docker)

Соберите и запустите контейнер:

docker build -t snowstorm-mcp-server .
docker run -p 8000:8000 --memory=512m --restart=unless-stopped snowstorm-mcp-server

Установите --memory. Без ограничения cgroup контейнер может расти, пока не сработает глобальный OOM-killer ядра, а он выбирает самый крупный процесс на хосте — поэтому сбой в этом сервере обрушит всю машину, а не только контейнер. С ограничением контейнер будет убит в одиночку, а --restart сразу вернёт его к жизни.

Сервер запускается в режиме Streamable HTTP на порту 8000, используя встроенный config.docker-snowstorm.yaml (ожидает локальный Snowstorm по адресу http://localhost:8080). Смонтируйте собственную конфигурацию во время выполнения:

docker run -p 8000:8000 \
  -v /path/to/your/config.yaml:/app/config.yaml \
  snowstorm-mcp-server

Для продакшена разворачивайте за HTTPS-обратным прокси или на платформе с автоматическим TLS (Cloud Run, Fly.io, Railway и т. д.). Для публичных развёртываний настройте поклиентское ограничение скорости на обратном прокси (на основе IP). MCP 2026-07-28 удалил сессии на уровне протокола, поэтому ограничение на сессию на уровне приложения больше не применяется к HTTP-клиентам; глобальное ограничение по-прежнему ограничивает суммарную нагрузку на бэкенд — см. Защитные механизмы производительности ниже.

Для удалённых развёртываний MCP-коннектора, предназначенных для Claude web/desktop, сервер по умолчанию включает CORS для https://claude.ai и https://claude.com на конечной точке Streamable HTTP. При необходимости переопределите список разрешённых источников с помощью переменной окружения SNOWSTORM_MCP_CORS_ALLOW_ORIGINS, используя список, разделённый запятыми.

Проверка источника (Origin) включена по умолчанию. Запрос к MCP-конечной точке, у которого заголовок Origin присутствует, но не входит в список разрешённых, отклоняется с HTTP 403. Именно это предотвращает DNS rebinding: POST с подменённой страницы по-прежнему несёт свой настоящий источник, потому что браузеры добавляют Origin к каждому POST — включая same-origin — согласно Fetch Standard. Запросы без Origin вообще, то есть все не-браузерные MCP-клиенты, не затрагиваются.

Это справедливо для всех современных браузерных движков. Firefox до 103 (июль 2022) мог полностью опускать Origin вместо отправки null, особенно когда был отключён параметр network.http.sendOriginHeader; установите также SNOWSTORM_MCP_ALLOWED_HOSTS, если такие клиенты входят в область охвата.

Список разрешённых по умолчанию совпадает с указанными выше источниками CORS. Переопределите его независимо с помощью SNOWSTORM_MCP_ALLOWED_ORIGINS (через запятую) для same-origin развёртываний за обратным прокси, где CORS выключен, но браузерные POST по-прежнему содержат Origin. Он заменяет список, а не дополняет его, поэтому включите каждый браузерный источник, который вы обслуживаете, — если указать только свой домен, https://claude.ai будет заблокирован. Установка * отключает проверку на уровне приложения; учтите, что если также задан SNOWSTORM_MCP_ALLOWED_HOSTS, уровень SDK всё равно проверяет Origin по списку CORS.

Обновление: браузерные клиенты, чей источник страницы не входит в список разрешённых, теперь получают 403 там, где раньше запрос проходил, — независимо от настроек CORS. CORS никогда не отклонял эти запросы; он лишь не отдавал заголовки ответа, а same-origin чтения вообще никогда не ограничивались CORS. Самостоятельно размещённое развёртывание, обслуживающее собственный веб-интерфейс, должно установить SNOWSTORM_MCP_ALLOWED_ORIGINS в этот источник или в *, чтобы восстановить прежнее поведение. Не-браузерные клиенты не отправляют Origin и не затрагиваются.

Установите SNOWSTORM_MCP_ALLOWED_HOSTS в имена хостов, по которым доступен сервер (через запятую, например mcp.example.org,mcp.example.org:443), чтобы дополнительно отклонять нераспознанный Host с HTTP 421. По умолчанию эта проверка выключена, потому что неполный список хостов отклоняет весь трафик; она включается автоматически при привязке к localhost. Это защита в глубину — проверка Origin выше уже закрывает вектор rebinding на этой POST-only конечной точке.

Версии протокола MCP

Сервер поддерживает две эпохи: он обслуживает stateless-редакцию MCP 2026-07-28 и более старые редакции на основе рукопожатия (2025-11-25 и более ранние) с одной и той же конечной точки, поэтому существующие клиенты продолжают работать. В обоих случаях он работает без состояния и никогда не создаёт Mcp-Session-Id, а значит, его можно масштабировать горизонтально без привязки к сессии.

Примечания к удалённому коннектору

• Anthropic подключается к вашей размещённой MCP-конечной точке из своей облачной инфраструктуры.

• Anthropic не настраивает ваши внутренние параметры бэкенда Snowstorm, такие как base_url, user_agent или целевую аутентификацию. Они остаются в конфигурации вашего сервера.

• manifest.json в этом репозитории предназначен для локальных сценариев упаковки, а не для потока размещённого удалённого коннектора.

Related MCP server: Smart EHR MCP Server

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

Используйте этот режим, когда вы хотите запустить MCP-сервер самостоятельно против собственного бэкенда Snowstorm или Snowstorm Lite — локально, в частной инфраструктуре или для упаковки в стиле Claude Desktop / MCPB.

Быстрый старт для разработки

uv venv
uv pip install -e ".[dev]"
uv run pytest -q
./scripts/check.sh

О рабочих процессах модульных и интеграционных тестов (включая настройку Docker-стека и импорт RF2) см. docs/testing.md.

Интеграционный Docker-стек (Snowstorm + Lite)

Запустите локальные контейнеры для интеграционного тестирования:

docker compose -f docker-compose.integration.yml up -d

Импортируйте локальный архив RF2 в Snowstorm и Snowstorm Lite:

dev/integration/import_snomed.sh \
  --rf2-zip ../SnomedCT_InternationalRF2_PRODUCTION_20251101T120000Z.zip

Запустите интеграционные тесты для каждого бэкенда. Установите SNOWSTORM_MCP_TEST_CONFIG в вашем .env, чтобы указать на соответствующую конфигурацию, затем:

uv run pytest -q tests/integration

Локальный запуск сервера

Сервер читает конфигурацию из YAML-файла (см. example-configs/config.local.yaml). Создайте файл .env в корне проекта, чтобы задать путь к конфигурации и любые секреты (см. .env.example):

cp .env.example .env
# edit .env to point at your config file

Сервер автоматически загружает .env из текущего рабочего каталога при запуске. Существующие переменные окружения оболочки имеют приоритет над значениями из .env.

stdio (для Claude Desktop и большинства MCP-клиентов):

uv run snowstorm-mcp-server --transport stdio

Используйте --log-level DEBUG|INFO|WARNING|ERROR для управления подробностью вывода (по умолчанию: INFO). Логи пишутся в stderr и перехватываются Claude Desktop в mcp-server-snowstorm.log. При запуске сервер выводит активную конфигурацию защитных механизмов, чтобы вы могли убедиться, что настройки загружаются из правильного конфигурационного файла.

Логирование

По умолчанию сервер пишет по одному JSON-объекту в строке с меткой времени UTC, которую агрегаторы логов могут разобрать напрямую:

{"timestamp": "2026-07-13T10:29:04.929Z", "level": "ERROR", "logger": "snowstorm_mcp_server.mcp_app", "message": "Tool call failed [E_BACKEND_HTTP]: HTTP 502 ...", "error_code": "E_BACKEND_HTTP", "error_type": "HttpRequestError", "status_code": 502}

Сбои инструментов содержат структурированные поля (error_code, error_type, status_code), чтобы вы могли разбить частоту ошибок по причинам. Срабатывания защитных механизмов (ограничения скорости, заблокированный ECL, обнаружение обхода) логируются как предупреждения. Используйте --log-format text для традиционного человекочитаемого вывода во время локальной разработки.

Streamable HTTP (для MCP-клиентов на основе HTTP):

uv run snowstorm-mcp-server --transport streamable-http

Отдельный транспорт sse удалён в пользу Streamable HTTP. Транспорт HTTP+SSE устарел начиная с MCP 2025-03-26 и официально помечен как Deprecated в соответствии с политикой жизненного цикла функций начиная с 2026-07-28.

Пример конфигурации Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "snowstorm": {
      "command": "uv",
      "args": [
        "run",
        "--project", "/path/to/snowstorm-mcp-server",
        "snowstorm-mcp-server",
        "--transport", "stdio"
      ]
    }
  }
}

Примечание: Claude Desktop запускает uv из каталога проекта, поэтому автоматически подхватывает файл .env. Если вы предпочитаете явные переменные окружения, передайте их через ключ "env" в конфигурации Claude Desktop.

Локальная упаковка / установка MCPB

Если вы устанавливаете сервер из записи Connector Directory, манифест запрашивает путь к конфигурационному файлу и передаёт его как --config при запуске. Выберите один из YAML-файлов в example-configs/ для локальной разработки или укажите путь к конфигурации вашего собственного развёртывания Snowstorm/Snowstorm Lite.

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

См. example-configs/config.local.yaml (Snowstorm по адресу http://localhost:8080).

Ограничение типа бэкенда

Одна конфигурация должна использовать либо цели Snowstorm, либо Snowstorm Lite — смешивать оба типа в одной конфигурации не поддерживается. Поле server_mode должно соответствовать типу цели ("snowstorm" для целей Snowstorm, "lite" для целей Lite).

Поддерживается несколько экземпляров Snowstorm Lite (по одному на редакцию SNOMED).

Пример конфигурации Lite с несколькими редакциями

server_mode: "lite"
default_terminology: snomedct
response_limits:
  max_expand_contains: 100
  max_search_hits: 50
  max_synonyms: 25

# Guards — all values shown are defaults. Omit the block to use defaults.
# For public-facing HTTP deployments, do per-client limiting at the reverse
# proxy: MCP 2026-07-28 removed sessions, so per_session_rate_limit_calls
# only has an effect on stdio.
# guards:
#   rate_limit_calls: 10
#   rate_limit_window_seconds: 60
#   max_concurrent_requests: 3
#   max_count_per_call: 500
#   large_result_threshold: 1000
#   max_children_calls_per_minute: 5
#   per_session_rate_limit_calls: null   # stdio only; no effect over HTTP
#   block_zero_cardinality_on_large_sets: false  # set true to block [0..0] on top-level roots
#   enable_expansion_size_guard: false   # preflight summary check for any non-summary expansion
#   expansion_count_threshold: 20000     # block if total concepts exceeds this value
#   size_cache_ttl_seconds: 86400

targets:
  lite-int:
    base_url: "http://localhost:8081"
    mode: "lite"
    terminology_name: "snomedct"
    fhir_path: "/fhir"
    auth:
      mode: "none"

  lite-us:
    base_url: "http://localhost:8082"
    mode: "lite"
    terminology_name: "snomedct-us"
    fhir_path: "/fhir"
    auth:
      mode: "bearer"
      token: "${SNOWSTORM_LITE_TOKEN}"

Маршрутизация на основе терминологии

Этот сервер маршрутизирует запросы по терминологии (редакции SNOMED), а не по цели бэкенда.

• Snowstorm: Терминологии автоматически обнаруживаются через GET /codesystems. shortName каждой системы кодов (в нижнем регистре) становится именем терминологии (например, snomedct, snomedct-us). Путь ветки используется автоматически для нативных операций Snowstorm.

• Snowstorm Lite: Каждый экземпляр обслуживает одну терминологию. Укажите terminology_name в конфигурации цели.

Терминология по умолчанию

Установите default_terminology в конфигурации, чтобы вызывающие стороны могли опускать параметр terminology. Если доступна только одна терминология, она становится терминологией по умолчанию автоматически.

Доступные MCP-инструменты

Все инструменты принимают необязательный параметр terminology (например, "snomedct-us"). Большинство инструментов также принимают необязательный параметр target для ограничения маршрутизации / устранения неоднозначности выбора цели. Если параметр не указан, используется терминология по умолчанию.

Переопределение секретов через переменные окружения

Секреты можно передавать во время выполнения через переменные окружения вместо сохранения значений в коде:

• Подстановка плейсхолдеров в конфигурации: ${ENV_VAR} или ${ENV_VAR:-default}

• Переменные переопределения секретов аутентификации цели:

  • SNOWSTORM_MCP_TARGETS__<TARGET_NAME_UPPER>__AUTH__PASSWORD

  • SNOWSTORM_MCP_TARGETS__<TARGET_NAME_UPPER>__AUTH__TOKEN

Примеры вызовов инструментов MCP

list_terminologies:

{}

Ожидаемая форма ответа:

{
  "terminologies": [
    {"name": "snomedct", "backend_type": "snowstorm", "branch_path": "MAIN"},
    {"name": "snomedct-us", "backend_type": "lite", "branch_path": null}
  ],
  "default_terminology": "snomedct"
}

server_capabilities (терминология по умолчанию):

{}

Ожидаемая форма ответа:

{
  "terminology": "snomedct",
  "backend_type": "snowstorm",
  "reachable": true,
  "fhir_base_url": "http://localhost:8080/fhir",
  "capabilities": {"has_fhir": true, "has_native_api": true, "has_lite_load_package": false},
  "fhir_metadata_summary": {"resourceType": "CapabilityStatement", "fhirVersion": "4.0.1"}
}

fhir_metadata в режиме только сводки (без необработанного тела CapabilityStatement):

{"terminology": "snomedct", "include_raw": false}

Ожидаемая форма ответа:

{
  "terminology": "snomedct",
  "fhir_base_url": "http://localhost:8080/fhir",
  "summary": {"resourceType": "CapabilityStatement", "fhirVersion": "4.0.1"}
}

snomed_lookup:

{"code": "404684003", "terminology": "snomedct"}

Ожидаемая форма ответа:

{
  "terminology": "snomedct",
  "code": "404684003",
  "found": true,
  "display": "Clinical finding",
  "system": "http://snomed.info/sct"
}

Если код не существует в данном издании, инструмент возвращает структурированный отрицательный результат, а не ошибку:

{
  "terminology": "snomedct",
  "code": "99999999999",
  "found": false,
  "message": "Code '99999999999' was not found in this SNOMED CT edition/version. Verify the concept ID or search for the concept by term."
}

snowstorm_search_concepts (только Snowstorm):

{"terminology": "snomedct", "term": "myocardial infarction", "limit": 5}

Ожидаемая форма ответа:

{
  "terminology": "snomedct",
  "term": "myocardial infarction",
  "branch": "MAIN",
  "returned": 5,
  "hits": [{"concept_id": "22298006", "pt": "Myocardial infarction"}]
}

Примеры использования

Эти примеры показывают, как ИИ-ассистент использует инструменты сервера в ответ на вопросы на естественном языке.

Пример 1 — Поиск клинического концепта

Пользователь: «Что такое концепт SNOMED CT 22298006?»

Ассистент вызывает snomed_lookup с {"code": "22298006"} и получает предпочтительный термин концепта («Инфаркт миокарда»), URI системы SNOMED CT и любые связанные свойства. Затем ассистент может объяснить концепт пользователю простым языком, включая его клиническое значение.

Пример 2 — Проверка иерархической связи

Пользователь: «Является ли сахарный диабет 2 типа разновидностью эндокринного расстройства в SNOMED CT?»

Ассистент вызывает snomed_subsumes с {"code_a": "362969004", "code_b": "44054006"} (эндокринное расстройство и сахарный диабет 2 типа соответственно). Ответ показывает, охватывает ли code_a код code_b, подтверждая или опровергая отношение IS-A.

Пример 3 — Поиск концептов по клиническому термину

Пользователь: «Найди концепты SNOMED CT, связанные с „фибрилляцией предсердий“.»

Ассистент вызывает snomed_expand с {"filter": "atrial fibrillation", "count": 10}, чтобы выполнить поиск по терминологии. Ответ возвращает соответствующие концепты с их идентификаторами, предпочтительными терминами и статусом активности, что позволяет ассистенту представить краткий список клинически значимых совпадений.

Операции FHIR и многодиапазонный Snowstorm

Для нативных операций Snowstorm (поиск, детали концепта) путь ветки терминологии автоматически используется для выбора нужного издания.

Для операций FHIR ($lookup, $validate-code, $subsumes) терминология маршрутизируется на правильный сервер бэкенда. В случае экземпляра Snowstorm с несколькими изданиями может также потребоваться указать параметр FHIR version для точного выбора издания, поскольку выбор издания FHIR определяется параметрами system/version, а не путями веток.

Дополнительные сведения о возможностях бэкенда и границах области действия v0.1 описаны в docs/v0.1-capability-matrix.md. Шаги по тегированию релиза и смоук-тестированию приведены в docs/release-v0.1-checklist.md.

Защитные механизмы производительности

Все инструменты, выполняющие HTTP-вызовы к бэкенду, используют общий набор защитных механизмов для предотвращения перегрузки экземпляра Snowstorm. Они действуют независимо от того, какой инструмент вызывается: server_health, server_capabilities, fhir_metadata, snomed_expand, snomed_lookup, snomed_validate_code, snomed_subsumes, все инструменты иерархии и все нативные инструменты snowstorm_*.

Защитные механизмы, которые действуют всегда:

Только в рамках процесса. Защитные механизмы используют состояние в памяти. Если вы запускаете несколько процессов сервера за балансировщиком нагрузки, каждый процесс обеспечивает собственные независимые ограничения. Для общих ограничений между процессами требуется реализация на основе Redis.

Ограничение скорости на сессию (только stdio)

MCP 2026-07-28 удалил сессии на уровне протокола. При использовании Streamable HTTP каждый запрос теперь независим, поэтому per_session_rate_limit_calls не имеет стабильного ключа и никогда не сработает — каждый запрос получает новое пустое окно. Сервер выводит предупреждение при запуске, если этот параметр задан. Механизм по-прежнему работает на stdio, где один процесс обслуживает ровно одного клиента. Для HTTP-развёртываний выполняйте ограничение на клиента на обратном прокси (Nginx limit_req, Caddy rate_limit, Cloudflare и т. п.), который использует сетевую идентификацию, которую протокол больше не передаёт.

Глобальное ограничение скорости является общим для всех вызывающих и не зависит от этого — оно остаётся механизмом, ограничивающим общую нагрузку на бэкенд:

guards:
  rate_limit_calls: 30            # global ceiling across all callers
  rate_limit_window_seconds: 60
  per_session_rate_limit_calls: 8 # stdio only; a no-op over HTTP

Когда задан per_session_rate_limit_calls, каждая сессия получает собственное независимое скользящее окно с использованием того же rate_limit_window_seconds. Сессии отслеживаются по идентичности объекта и автоматически удаляются, когда базовый объект сессии собирается сборщиком мусора.

Инструменты без защиты

Инструменты, работающие в памяти и не вызывающие бэкенд Snowstorm, намеренно оставлены без защиты: list_terminologies.

Ограничение нативного поиска Snowstorm (важно)

Инструмент MCP snowstorm_search_concepts вызывает нативный поисковый endpoint описаний Snowstorm (GET /browser/{branch}/descriptions), который может отклонять очень короткие запросы (например, AD, B2) с HTTP 400.

Практические рекомендации:

• Используйте не менее 3 доступных для поиска символов (букв/цифр).

• Для коротких аббревиатур добавляйте контекст (например, используйте более длинную фразу вместо AD).

MCP-сервер проверяет это заранее: слишком короткий термин возвращает успешный ответ с нулевым количеством совпадений и полем notice, объясняющим ограничение, без вызова Snowstorm. Ожидаемые отрицательные результаты (слишком короткий термин или несуществующий код для snomed_lookup) возвращаются в виде структурированных данных, а не ошибок инструмента, поэтому метрики ошибок MCP отражают только реальные сбои.

Политика конфиденциальности

Этот сервер действует как прокси без сохранения состояния между MCP-клиентом и настроенным бэкендом SNOMED CT (Snowstorm или Snowstorm Lite). Он не собирает, не хранит и не обрабатывает персональные данные и не передаёт данные третьим лицам, кроме настроенного бэкенда. Все содержимое запросов пересылается в бэкенд и удаляется после доставки ответа. Когда включено ограничение скорости на сессию, сервер хранит временные метки вызовов в памяти для каждой сессии исключительно для целей ограничения скорости; это состояние не содержит PII и автоматически удаляется при завершении сессии.

Ответы содержат терминологический контент SNOMED CT. Доступ к этому контенту через данный сервер регулируется Лицензионным соглашением браузера SNOMED CT (см. Лицензию ниже). При развёртывании в качестве хостинг-сервиса стандартные журналы доступа веб-сервера (IP-адрес, временная метка, путь запроса) могут сохраняться инфраструктурой хостинга в операционных целях.

Полную политику конфиденциальности см. в PRIVACY.md.

Поддержка

• Проблемы и отчёты об ошибках: GitHub Issues

• Лицензирование и контент SNOMED CT: SNOMED International

• Общие вопросы: info@snomed.org

Лицензия

Программное обеспечение сервера лицензировано под Apache 2.0.

Контент SNOMED CT, возвращаемый этим сервером, не покрывается указанной лицензией. Доступ к SNOMED CT через этот сервер регулируется Лицензионным соглашением браузера SNOMED CT — на тех же основаниях, на которых предоставляется публичный браузер SNOMED CT. Если кратко, конечные пользователи, не имеющие лицензии аффилированного лица SNOMED International, могут использовать этот сервер для изучения и оценки терминологии, но не могут:

• копировать идентификаторы SNOMED CT в систему записей, базу данных или документ (использовать в качестве «системы создания данных» или «системы анализа данных»);

• переводить или изменять контент SNOMED CT; или

• распространять или передавать контент SNOMED CT.

Если вы хотите самостоятельно разместить этот сервер, интегрировать SNOMED CT в продукт или сервис или иным образом использовать SNOMED CT за пределами изучения и оценки, вам следует получить полную лицензию SNOMED CT — см. Get SNOMED CT. Аффилированные лица SNOMED International могут использовать этот сервер в рамках условий своей лицензии аффилированного лица. SNOMED CT является © SNOMED International; «SNOMED» и «SNOMED CT» являются зарегистрированными товарными знаками.