advancedmd-connector

advancedmd-connector — это единственный процесс в организации, который общается с AdvancedMD. Каждый потребитель данных AdvancedMD — бэкенд-воркфлоу (appointment-validator, srt-auths, note-audit, patient-intake), проверка учётных данных в admin-console и AI-агенты (Adam и любой агент Claude Code, Cursor или Desktop) — отправляет ему вызов инструмента по HTTP или MCP и получает обратно JSON-результат. Он хранит единственные учётные данные AdvancedMD, единственную сессию входа и единственный счётчик частоты запросов.

Сегодня пятнадцать процессов каждый хранят учётные данные AdvancedMD, входят в систему независимо и ограничивают частоту независимо в рамках пределов AdvancedMD по ключам офиса (которые взимают $0.01 за каждый сверхлимитный вызов и отклоняют входы чаще, чем примерно раз в минуту). Коннектор решает эту проблему, централизованно владея сессией и счётчиком: один процесс, один счётчик частоты, одна поверхность инструментов, без изменения имён инструментов и форм результатов для всех существующих потребителей. Полный контракт см. в SPEC.md и docs/CONNECTOR_DECISIONS.md — там объясняется, почему было принято каждое решение.

Архитектура

 backend workflows ------ JSON tool call ------> +-----------------------------+
 (validator, srt-auths,                          |    advancedmd-connector     |
  note-audit, intake,                            |                             |
  admin-console, chatbot)                        |  HTTP API   MCP surface     |
                                                  |      \        /             |
 agents ----------------- MCP tool call -------> |     receivers (one per      |
 (Adam via remote MCP;                           |       open request)         |
  Cursor, Claude Code,                           |          |                  |
  Desktop via stdio shim                         |     entry queue             |
  or remote MCP)                                 |          |                  |
                                                  |     worker loop  (1 at a    |
                                                  |          |        time)     |
                                                  |      handler                |
                                                  |          |                  |
                                                  |    request queue            |
                                                  |          |                  |
                                                  |     sender loop  (clock,    |
                                                  |          |        session)  |
                                                  +----------|------------------+
                                                             |  XML over HTTPS
                                                             v
                                                        AdvancedMD

Один процесс. Один порт (по умолчанию 8820). Всё, что выше пунктирной линии, — это потребители; ничто за пределами рамки не хранит учётные данные AMD и не отправляет XML.

Related MCP server: production-grade-mcp-agentic-system

Запуск локально за пять команд

cp .env.example .env                      # fill AMD_USERNAME, AMD_PASSWORD, AMD_OFFICE_KEY
pip install -e ".[dev]"
export $(cat .env | grep -v '^#' | xargs) CONNECTOR_TOKENS_PATH=/tmp/tokens.json
connector tokens add myapp --priority interactive --tools '*'   # prints a token once
uvicorn --factory connector.app:build_app --host 0.0.0.0 --port 8820

GET http://localhost:8820/health должен отвечать {"status": "starting"} или "ok" после завершения первой попытки входа. docker compose up --build запускает то же самое в контейнере, читая тот же .env.

Подключение агента

Имена инструментов, схемы аргументов и формы результатов с редактированием идентичны во всех трёх способах подключения (SPEC 12.1), поэтому конфиг агента можно перенести с одного на другой без изменения промптов.

Удалённый MCP (хостированные агенты, например Adam) — указывайте напрямую на потоковый HTTP-интерфейс коннектора:

{"mcpServers": {"amd-patients": {"type": "http",
  "url": "http://advancedmd-connector:8820/mcp/patients",
  "headers": {"Authorization": "Bearer <agent token>"}}}}

Обслуживаются десять маршрутов: /mcp/patients, /mcp/visits, /mcp/providers, /mcp/codes, /mcp/billing, /mcp/payments, /mcp/masterfiles, /mcp/system, /mcp/ehr и /mcp/all (объединение).

Локальный shim stdio (агенты на рабочей станции) — установите опубликованный пакет advancedmd-mcp и укажите его на коннектор по сети; он не хранит учётных данных и не содержит логики инструментов:

{"mcpServers": {"amd-patients": {"command": "uvx",
  "args": ["advancedmd-mcp", "--domain", "patients"],
  "env": {"ADVANCEDMD_CONNECTOR_URL": "http://100.94.62.115:8820",
          "ADVANCEDMD_CONNECTOR_TOKEN": "<agent token>"}}}}

Плагин Claude Code — plugin/ объявляет все девять серверов stdio с ссылками на переменные окружения ${ADVANCEDMD_CONNECTOR_URL} и ${ADVANCEDMD_CONNECTOR_TOKEN}:

claude plugin add <path or repo>/plugin

Тот же plugin/.mcp.json действителен для Cursor и Claude Desktop при копировании.

Использование из воркфлоу

Бэкенд-сервисы на Python используют SDK в orlando-derm-backend/lib/advancedmd_connector/, который сохраняет все существующие имена методов и типизированные результаты:

from lib.advancedmd_connector import AmdConnector

connector = AmdConnector.from_env()          # ADVANCEDMD_CONNECTOR_URL, ADVANCEDMD_CONNECTOR_TOKEN
bundle = await connector.get_patient_bundle(patient_id)
result = await connector.tool("getdemographic", patient_id=patient_id)   # generic call

SDK не хранит учётных данных AMD, XML и URL AMD — он работает только по HTTP. Полную таблицу методов и сопоставление исключений см. SPEC 13.

Выпуск токена

Токены выпускаются и отзываются с помощью встроенного CLI connector против файла таблицы токенов (CONNECTOR_TOKENS_PATH):

connector tokens add appointment-validator --priority batch --tools '*'
connector tokens add my-agent --priority interactive --tools getdemographic,lookuppatient
connector tokens list
connector tokens revoke my-agent

Токен в открытом виде печатается один раз при выпуске и никогда не хранится и не может быть восстановлен. Полный справочник флагов см. в docs/OPERATIONS.md и модель токенов — в docs/TOKENS.md.

Куда смотреть, когда что-то работает медленно

• GET /health (без токена, только внутренняя сеть) — состояние сессии, глубина и максимальное время ожидания в очереди входа, глубина очереди запросов и использованный/лимит счётчика частоты по уровням — всё в одном вызове.

• GET /metrics (без токена) — текст Prometheus: счётчики вызовов инструментов и гистограммы ожидания по вызывающему/инструменту/результату, счётчики запросов AMD и гистограммы времени после отправки по уровням, использованный/лимит/время сна счётчика по уровням, счётчики повторного входа и отказов входа, глубины очередей. Полный список метрик см. SPEC 18 и условия оповещения в SPEC 18.2.

• Медленный ответ AMD никогда не должен задерживать /health — цикл отправки и /health работают в одном цикле событий, но блокирующий ввод- вывод запрещён (SPEC 4.4), поэтому зависший вызов AMD проявляется как давление на счётчик/очередь в /health, а не как неотвечающий коннектор.

Расписание пакетных задач

Сам коннектор не выполняет пакетных задач; он сериализует всё, что отправляют его вызывающие с пакетным приоритетом. Потребители, в настоящее время запланированные против него (таблица миграции SPEC 22), — это appointment-validator (один ночной запуск), srt-auths (запуски сканирования и событий) и note-audit (один ежедневный запуск). Запросы с пакетным приоритетом стареют и повышаются после BATCH_AGING_MS (по умолчанию 60 с), чтобы длинная пакетная очередь не могла бесконечно голодать интерактивные вызовы (SPEC 5.3); при развёртывании всё же следует избегать этих окон, поскольку перезапуск сбрасывает сессию в памяти (SPEC 16.3).

Дополнительное чтение

• SPEC.md — полный контракт на сборку.

• docs/CONNECTOR_DECISIONS.md — почему было принято каждое решение.

• docs/API.md — HTTP API, зеркально отражённый из SPEC 11.

• docs/OPERATIONS.md — CLI токенов, развёртывание, откат, оповещения и процедура фикстуры.

• docs/TOOL_TO_XML_MAP.md — карта запросов AMD по каждому инструменту и журнал проверки.