advancedmd-connector

advancedmd-connector es el único proceso de la organización que se comunica con AdvancedMD. Cada consumidor de datos de AdvancedMD — los flujos de trabajo de backend (appointment-validator, srt-auths, note-audit, patient-intake), la comprobación de credenciales de admin-console y los agentes de IA (Adam y cualquier agente de Claude Code, Cursor o Desktop) — le envía una llamada de herramienta por HTTP o MCP y recibe un resultado JSON. Es el único que posee las credenciales de AdvancedMD, la única sesión de inicio de sesión y el único reloj de tasa.

Hoy quince procesos tienen cada uno credenciales de AdvancedMD, inician sesión de forma independiente y aplican su propia limitación de tasa frente a los límites por clave de oficina de AdvancedMD (que facturan $0.01 por llamada excedente y rechazan inicios de sesión más frecuentes que aproximadamente uno por minuto). El conector soluciona eso centralizando la sesión y el reloj: un solo proceso, un solo reloj de tasa, una única superficie de herramientas, y los mismos nombres de herramienta y formas de resultado para todos los consumidores existentes. Consulta SPEC.md para ver el contrato completo y docs/CONNECTOR_DECISIONS.md para conocer el motivo de cada decisión.

Arquitectura

 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

Un solo proceso. Un solo puerto (8820 por defecto). Todo lo que está por encima de la caja discontinua es un consumidor; nada fuera de la caja posee credenciales de AMD ni envía XML.

Related MCP server: Enterprise MCP Gateway and Tool Registry

Ejecutar localmente en cinco comandos

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 debería responder {"status": "starting"} o "ok" una vez que se complete el primer intento de inicio de sesión. docker compose up --build ejecuta lo mismo en contenedores, leyendo el mismo .env.

Conectar un agente

Los nombres de las herramientas, los esquemas de argumentos y las formas de resultado redactadas son idénticos en los tres métodos de conexión (SPEC 12.1), por lo que una configuración de agente puede pasar de uno a otro sin cambiar los prompts.

MCP remoto (agentes alojados, p. ej. Adam): apunta directamente a la superficie streamable-HTTP del conector:

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

Se sirven diez rutas: /mcp/patients, /mcp/visits, /mcp/providers, /mcp/codes, /mcp/billing, /mcp/payments, /mcp/masterfiles, /mcp/system, /mcp/ehr y /mcp/all (la unión).

Shim stdio local (agentes en una estación de trabajo): instala el paquete publicado advancedmd-mcp y apúntalo al conector a través de la red; no contiene credenciales ni lógica de herramientas:

{"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>"}}}}

Plugin de Claude Code: plugin/ declara los nueve servidores stdio con referencias de entorno ${ADVANCEDMD_CONNECTOR_URL} y ${ADVANCEDMD_CONNECTOR_TOKEN}:

claude plugin add <path or repo>/plugin

El mismo plugin/.mcp.json es válido para Cursor y Claude Desktop copiándolo.

Usarlo desde un flujo de trabajo

Los servicios de backend en Python usan el SDK en orlando-derm-backend/lib/advancedmd_connector/, que conserva todos los nombres de método existentes y los resultados tipados:

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

El SDK no contiene credenciales de AMD, ni XML, ni URL de AMD; es solo HTTP. Consulta SPEC 13 para ver la tabla completa de métodos y el mapeo de excepciones.

Emitir un token

Los tokens se emiten y revocan con la CLI connector incluida, contra el archivo de tabla de tokens (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

Un token en texto plano se imprime una vez al emitirse y nunca se almacena ni puede recuperarse. Consulta docs/OPERATIONS.md para la referencia completa de flags y docs/TOKENS.md para el modelo de tokens.

Dónde mirar cuando algo va lento

• GET /health (sin token, solo red interna): estado de la sesión, profundidad de la cola de entrada y espera más antigua, profundidad de la cola de solicitudes y uso/límite del reloj de tasa por nivel, todo en una sola llamada.

• GET /metrics (sin token): texto de Prometheus: recuentos de llamadas a herramientas e histogramas de espera por llamador/herramienta/resultado, recuentos de solicitudes AMD e histogramas de tiempo de POST por nivel, uso/límite/tiempo de suspensión del reloj por nivel, contadores de reinicio de sesión y de rechazo de inicio de sesión, profundidades de cola. Consulta SPEC 18 para ver la lista completa de métricas y las condiciones de alerta en SPEC 18.2.

• Una respuesta lenta de AMD nunca debe retrasar /health: el bucle del emisor y /health se ejecutan en el mismo bucle de eventos, pero la E/S bloqueante está prohibida (SPEC 4.4), por lo que una llamada AMD colgada se manifiesta como presión de reloj/cola en /health, no como un conector que no responde.

Programación por lotes

El conector en sí no ejecuta trabajos por lotes; serializa lo que envían sus llamadores de prioridad por lotes. Los consumidores actualmente programados contra él (tabla de migración SPEC 22) son appointment-validator (una ejecución nocturna), srt-auths (ejecuciones de escaneo y de eventos) y note-audit (una ejecución diaria). Las solicitudes de prioridad por lotes envejecen hasta su promoción después de BATCH_AGING_MS (60 s por defecto), de modo que un backlog de lotes largo no pueda privar indefinidamente de recursos a las llamadas interactivas (SPEC 5.3); los despliegues deberían evitar igualmente estas ventanas, ya que un reinicio elimina la sesión en memoria (SPEC 16.3).

Lecturas adicionales

• SPEC.md: el contrato de construcción completo.

• docs/CONNECTOR_DECISIONS.md: el motivo de cada decisión.

• docs/API.md: la API HTTP, reflejada desde SPEC 11.

• docs/OPERATIONS.md: CLI de tokens, despliegue, rollback, alertas y el procedimiento de fixtures.

• docs/TOOL_TO_XML_MAP.md: mapa de solicitudes AMD por herramienta y libro de verificación.