clinic-mcp

Эталонный сервер Model Context Protocol для записи на прием и первичного осмотра в клинике. Написан на TypeScript со строгой типизацией, структурированными ошибками и изоляцией арендаторов, обеспечиваемой на уровне данных. Данные являются синтетическими. Это не медицинское программное обеспечение.

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

Зачем нужен MCP

Приложения на базе LLM продолжают изобретать одни и те же способы взаимодействия: специальные определения функций для каждого провайдера, индивидуальный парсинг аргументов, отсутствие общего транспорта, отсутствие согласованной модели ошибок. MCP — это небольшой открытый протокол, который исправляет уровень взаимодействия. Сервер предоставляет список типизированных инструментов через stdio (или HTTP), и любой клиент, поддерживающий MCP (Claude Desktop, интеграции с IDE, пользовательские агенты), может обнаруживать и вызывать их с помощью одного и того же механизма.

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

Related MCP server: MCP Healthcare Server

Архитектура

flowchart LR
    Client["MCP client<br/>(Claude Desktop, custom agent)"]
    Server["clinic-mcp server"]
    Tools["Tools<br/>find_available_slot<br/>book_appointment<br/>record_intake<br/>search_protocols<br/>escalate_to_oncall"]
    Store["ClinicStore<br/>tenant-scoped accessors"]
    Seed[("seed.json<br/>synthetic clinics, providers,<br/>patients, protocols")]

    Client -->|stdio JSON-RPC| Server
    Server --> Tools
    Tools --> Store
    Store --> Seed

Каждый инструмент принимает clinic_id, и хранилище гарантирует, что все операции чтения и записи ограничены этой клиникой. Доступ между арендаторами вызывает TenantMismatchError, а не молчаливый возврат неверной строки. Это отражает шаблон безопасности на уровне строк, который производственное развертывание обеспечивало бы в Postgres, представленный здесь в коде приложения, чтобы гарантию можно было проверить в одном файле (src/store/index.ts).

Запуск локально

Требуются Node 20+ и pnpm.

git clone https://github.com/dominikstefanski/clinic-mcp.git
cd clinic-mcp
pnpm install
pnpm test          # 29 tests
pnpm typecheck
pnpm dev           # boots the server on stdio

Сервер считывает src/store/seed.json при запуске и обслуживает две синтетические клиники: clinic_north (общая практика, кардиология, дерматология) и clinic_west (педиатрия, общая практика).

Подключение к Claude Desktop

Добавьте это в конфигурацию Claude Desktop (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). Замените путь на ваш локальный клон.

{
  "mcpServers": {
    "clinic-mcp": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/clinic-mcp/src/server.ts"]
    }
  }
}

Перезапустите Claude Desktop. Пять инструментов появятся в меню подключений. Попробуйте запрос вроде "Найди свободное время для общей практики в clinic_north в следующий понедельник утром."

Справочник инструментов

Все инструменты возвращают { ok: true, ...result } в случае успеха или { ok: false, error: { code, message } } в случае ошибки. Входные данные проверяются с помощью zod; ошибки аргументов на уровне MCP возвращаются как ошибки validation с деталями по полям.

find_available_slot

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

book_appointment

Создание записи на прием. Требует предоставленный вызывающим объектом idempotency_key; повторные вызовы возвращают исходную запись вместо создания дубликата. Голосовые агенты будут повторять попытки, поэтому это поле обязательно.

Возвращает { appointment, idempotent_replay }.

record_intake

Сохранение структурированной заметки о первичном осмотре и назначение уровня сортировки (triage).

Правило сортировки: тяжесть >= 8 — urgent (срочно), >= 5 — elevated (повышенная), в противном случае — routine (планово).

search_protocols

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

Текущая реализация — это простой TF-скоринг с весом заголовка (3x). Он существует, чтобы продемонстрировать интерфейс инструмента поиска; в производственных развертываниях бэкенд был бы заменен на векторный поиск (см. примечания по проектированию).

escalate_to_oncall

Пометка существующей записи как срочной и переназначение ее на дежурного врача клиники.

Возвращает { appointment, on_call_provider, reassigned }.

Примечания по проектированию

Изоляция арендаторов обеспечивается в хранилище, а не в инструменте. Инструменты принимают clinic_id и передают его дальше. Хранилище проверяет право собственности при каждом доступе и выбрасывает TenantMismatchError при несовпадении. Если вы добавите новый инструмент завтра, вы не сможете случайно допустить утечку между клиниками; хранилище не позволит этого сделать.

Идемпотентность при записи. book_appointment требует idempotency_key. Реальные вызывающие стороны (голосовые агенты, циклы повторных попыток, сетевые сбои) будут повторять запросы, а система здравоохранения, которая реагирует на повторные попытки созданием дубликатов записей, — это система, которая теряет доверие с первого дня.

Структурированные ошибки вместо выброшенных строк. Каждая ошибка предметной области является типизированным подклассом DomainError со стабильным code. Обертка MCP превращает их в { ok: false, error: { code, message } }. Клиенты могут выполнять ветвление по code вместо использования регулярных выражений для message.

Инструмент поиска является временным решением. search_protocols использует TF-скоринг в памяти, поэтому репозиторий работает без внешних сервисов. В производстве это место, где вы подключаете Pinecone, pgvector или выбранный вами бэкенд поиска. Контракт ввода/вывода инструмента остается прежним.

Обработка времени упрощена. Рабочие часы провайдера интерпретируются в UTC для ясности. Реальное развертывание учитывало бы часовой пояс каждой клиники (уже есть в схеме). Я указываю на это явно, чтобы рецензенты знали, что это намеренно, а не недосмотр.

Чем это не является

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

• Не соответствует требованиям HIPAA. Данные поддельные, хранилище находится в оперативной памяти, журнал аудита отсутствует. Для производства потребовалось бы все это и многое другое.

• Не является полноценным EMR или бэкендом планирования. Цель состоит в том, чтобы показать форму MCP-сервера, а не поставлять систему для клиники.

Лицензия

MIT. См. LICENSE.