Doctor Appointment MCP Server

MCP-сервер на Python, реализующий Model Context Protocol (MCP), для управления приёмами к врачу через внешний REST API приёмов.

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

Что он делает

Сервер предоставляет пять MCP-инструментов:

Сервер также включает:

• Потоковый HTTP MCP-эндпоинт по адресу /mcp

• Эндпоинты проверки состояния по адресам / и /health

• Необязательную аутентификацию через пользовательские HTTP-заголовки

• Внешний REST API бэкенд, настраиваемый через APPOINTMENTS_API

• Асинхронные HTTP-запросы с использованием httpx

Related MCP server: MCP Appointment Booking Server

Архитектура

AI Agent / MCP Client
          |
          | Model Context Protocol
          v
      /mcp endpoint
          |
          v
       Uvicorn
          |
          v
      Starlette
          |
          v
       FastMCP
          |
   +------+------+------+------+------+
   |      |      |      |      |
   v      v      v      v      v
 Create  Find   Check  Cancel Reschedule
   |      |      |      |      |
   +------+------+------+------+------+
                 |
                 v
            HTTPX Client
                 |
                 | REST API
                 v
        Appointment Backend
         (MockAPI by default)

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

doctor-appointment-mcp/
├── server.py
├── requirements.txt
├── start.sh
├── run.sh
├── README.md
├── .gitignore
└── .gitattributes

Требования

• Рекомендуется Python 3.11 или новее

• pip

• REST API эндпоинт приёмов

Python-зависимости определены в requirements.txt:

fastmcp>=3.0
uvicorn[standard]>=0.30
httpx>=0.27

Локальная настройка

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

git clone https://github.com/josh747jr/doctor-appointment-mcp.git
cd doctor-appointment-mcp

2. Создайте виртуальное окружение

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Linux/macOS/WSL:

python3 -m venv .venv
source .venv/bin/activate

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

pip install -r requirements.txt

4. Настройте API приёмов

Задайте APPOINTMENTS_API как REST эндпоинт, который хранит записи о приёмах.

Windows PowerShell:

$env:APPOINTMENTS_API="https://YOUR-API-ENDPOINT/appointments"

Linux/macOS/WSL:

export APPOINTMENTS_API="https://YOUR-API-ENDPOINT/appointments"

Если APPOINTMENTS_API не задан, текущий server.py использует свой настроенный эндпоинт MockAPI.

Не коммитьте API-ключи, учётные данные и другие секреты в репозиторий.

Запуск сервера локально

Запустите Uvicorn:

python -m uvicorn server:app --host 127.0.0.1 --port 8000

MCP-эндпоинт будет доступен по адресу:

http://127.0.0.1:8000/mcp

Эндпоинт проверки состояния будет доступен по адресу:

http://127.0.0.1:8000/health

Успешная проверка состояния возвращает:

ok

MCP-инструменты

1. create_appointment

Создаёт новый приём к врачу.

Входные данные:

• patient_name

• doctor_name

• appointment_date

• appointment_time

• reason — необязательный

Пример аргументов инструмента:

{
  "patient_name": "John Doe",
  "doctor_name": "Dr. Mike",
  "appointment_date": "2026-09-18",
  "appointment_time": "2:00 PM",
  "reason": "Annual physical"
}

Новые приёмы сохраняются со статусом scheduled.

Пример пользовательского запроса:

Schedule an appointment for John Doe with Dr. Mike on September 18, 2026
at 2:00 PM for an annual physical.

2. find_appointments

Находит один или несколько существующих приёмов, когда ID приёма неизвестен.

Входные данные для поиска:

• patient_name — необязательный

• doctor_name — необязательный

• appointment_date — необязательный

• include_cancelled — необязательный логический параметр, по умолчанию false

Необходимо указать как минимум одно из значений: patient_name, doctor_name или appointment_date.

Поиск приёмов для пациента:

{
  "patient_name": "John Doe"
}

Поиск приёмов для пациента и врача:

{
  "patient_name": "John Doe",
  "doctor_name": "Dr. Mike"
}

Поиск приёмов на конкретную дату:

{
  "appointment_date": "2026-09-18"
}

Инструмент отправляет указанные поисковые поля в качестве параметров запроса в REST API приёмов и возвращает соответствующие записи приёмов.

Успешный результат включает:

{
  "success": true,
  "message": "Found 1 matching appointment(s).",
  "count": 1,
  "appointments": [
    {
      "id": "12",
      "patientName": "John Doe",
      "doctorName": "Dr. Mike",
      "appointmentDate": "2026-09-18",
      "appointmentTime": "2:00 PM",
      "reason": "Annual physical",
      "status": "scheduled"
    }
  ]
}

Если ни одна запись не совпадает, инструмент возвращает успешный ответ с count равным 0 и пустым массивом appointments.

Примеры пользовательских запросов:

Find my appointment with Dr. Mike.

What appointments does John Doe have?

Find John Doe's appointment on September 18, 2026.

3. check_appointment_status

Получает приём по его ID.

Входные данные:

• appointment_id

Пример:

{
  "appointment_id": "12"
}

Успешный ответ включает пациента, врача, дату приёма, время приёма, причину и статус.

Пример пользовательского запроса:

What is the status of appointment 12?

4. cancel_appointment

Отменяет существующий приём.

Входные данные:

• appointment_id

Пример:

{
  "appointment_id": "12"
}

Отмена не удаляет запись о приёме. Сервер изменяет её статус на:

cancelled

Сохранение записи позволяет вести историю приёмов.

Пример пользовательского запроса:

Cancel appointment 12.

5. reschedule_appointment

Изменяет дату и время существующего приёма.

Входные данные:

• appointment_id

• new_appointment_date

• new_appointment_time

Пример:

{
  "appointment_id": "12",
  "new_appointment_date": "2026-09-21",
  "new_appointment_time": "10:00 AM"
}

Текущая реализация не позволяет переносить отменённые приёмы.

Пример пользовательского запроса:

Move appointment 12 to September 21, 2026 at 10:00 AM.

Модель данных приёма

Ожидается, что REST бэкенд хранит записи, аналогичные:

{
  "id": "12",
  "patientName": "John Doe",
  "doctorName": "Dr. Mike",
  "appointmentDate": "2026-09-18",
  "appointmentTime": "2:00 PM",
  "reason": "Annual physical",
  "status": "scheduled"
}

Сервер использует REST-операции, эквивалентные:

POST /appointments
GET  /appointments
GET  /appointments/{id}
PUT  /appointments/{id}

find_appointments использует GET /appointments с такими параметрами запроса, как:

patientName
doctorName
appointmentDate

Пример рабочего процесса агента

Пользователь может сначала спросить:

Find my appointment with Dr. Mike.

MCP-клиент может вызвать:

find_appointments(patient_name="John Doe", doctor_name="Dr. Mike")

После того как соответствующая запись и ID приёма найдены, пользователь может сказать:

Move that appointment to September 21 at 10 AM.

Затем MCP-клиент может вызвать:

reschedule_appointment(
    appointment_id="12",
    new_appointment_date="2026-09-21",
    new_appointment_time="10:00 AM"
)

Это позволяет ИИ-агенту сначала найти приём, вместо того чтобы требовать от пользователя знать ID приёма.

Необязательная аутентификация через заголовки MCP

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

Если переменная не настроена, аутентификация через пользовательские заголовки отключена.

Простой заголовок

Windows PowerShell:

$env:MCP_REQUEST_HEADERS="my-secret"

Linux/macOS/WSL:

export MCP_REQUEST_HEADERS="my-secret"

Эта конфигурация ожидает, что MCP-запросы будут содержать заголовок с именем:

MCP_REQUEST_HEADERS

с настроенным значением.

Пользовательское имя заголовка

Переменная также может содержать JSON:

export MCP_REQUEST_HEADERS='{"X-API-Key":"my-secret"}'

Затем MCP-клиент должен отправить:

X-API-Key: my-secret

Эндпоинты / и /health остаются доступными без этой пользовательской аутентификации.

Примечание по безопасности: Этот проект является демонстрационной/учебной реализацией. Настоящее медицинское приложение требует значительно более надёжной аутентификации, авторизации, средств контроля конфиденциальности, журналирования аудита, управления секретами, защиты данных и нормативной экспертизы перед хранением реальной информации о пациентах.

Развёртывание

Репозиторий содержит:

start.sh
run.sh

Эти скрипты можно использовать для развёртывания на базе Linux.

start.sh устанавливает необходимые Python-пакеты в каталог зависимостей развёртывания.

run.sh запускает приложение с помощью Uvicorn и прослушивает порт из переменной окружения PORT, по умолчанию — порт 8080.

Обязательная переменная окружения для развёртывания:

APPOINTMENTS_API=https://YOUR-API-ENDPOINT/appointments

Необязательная аутентификация:

MCP_REQUEST_HEADERS=your-secret

После развёртывания MCP-эндпоинт обычно будет доступен по адресу:

https://YOUR-SERVER/mcp

а эндпоинт проверки состояния:

https://YOUR-SERVER/health

Тестирование сервера

Запустите приложение:

python -m uvicorn server:app --host 127.0.0.1 --port 8000

Проверьте эндпоинт проверки состояния:

curl http://127.0.0.1:8000/health

Ожидаемый ответ:

ok

Затем настройте MCP-совместимый клиент для подключения к:

http://127.0.0.1:8000/mcp

Клиент должен обнаружить следующие пять инструментов:

create_appointment
find_appointments
check_appointment_status
cancel_appointment
reschedule_appointment

Планируемые улучшения

Полезные следующие шаги включают:

• Добавить проверку доступности врачей и поиск временных слотов

• Предотвращать конфликтующие или дважды забронированные приёмы

• Добавить более строгую проверку даты и времени

• Добавить production-базу данных

• Добавить OAuth или другой механизм аутентификации production-уровня

• Добавить автоматизированные тесты

• Добавить структурированное журналирование аудита

• Интегрировать с реальным календарём или провайдером планирования

• Добавить средства контроля личности пациента и авторизации production-уровня

Статус разработки

Этот проект предназначен как проект для разработки и изучения MCP. Текущий бэкенд приёмов в дальнейшем можно заменить на production-сервис планирования или базу данных, сохранив интерфейс MCP-инструментов.

Безопасность и медицинские данные

Не используйте реальную информацию о пациентах или защищённую медицинскую информацию (PHI) с незащищённым демонстрационным бэкендом.

Production-медицинское приложение может подпадать под требования конфиденциальности, безопасности, соответствия и хранения данных, такие как HIPAA в США.

Репозиторий

https://github.com/josh747jr/doctor-appointment-mcp

Лицензия

Для этого репозитория ещё не указана лицензия. Добавьте файл LICENSE перед распространением или повторным использованием проекта на условиях конкретной лицензии.