advancedmd-connector

advancedmd-connector ist der eine Prozess in der Organisation, der mit AdvancedMD spricht. Jeder Verbraucher von AdvancedMD-Daten – Backend-Workflows (appointment-validator, srt-auths, note-audit, patient-intake), die Admin-Konsolen-Anmeldeprüfung und KI-Agenten (Adam sowie beliebige Claude-Code-, Cursor- oder Desktop-Agenten) – sendet ihm einen Tool-Aufruf über HTTP oder MCP und erhält ein JSON-Ergebnis zurück. Er hält die einzigen AdvancedMD-Anmeldedaten, die einzige Anmeldesitzung und die einzige Rate-Limit-Uhr.

Heute besitzen fünfzehn Prozesse AdvancedMD-Anmeldedaten, melden sich unabhängig an und begrenzen die Rate unabhängig gemäß den Pro-Office-Key-Grenzwerten von AdvancedMD (die 0,01 $ pro überschüssigem Aufruf berechnen und Anmeldungen verweigern, die schneller als etwa einmal pro Minute erfolgen). Der Connector behebt das, indem er die Sitzung und die Uhr zentral verwaltet: ein Prozess, eine Rate-Limit-Uhr, eine Tool-Oberfläche, unveränderte Tool-Namen und Ergebnisschemata für alle vorhandenen Verbraucher. Siehe SPEC.md für den vollständigen Vertrag und docs/CONNECTOR_DECISIONS.md für die Begründung jeder Entscheidung.

Architektur

 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

Ein Prozess. Ein Port (Standard 8820). Alles oberhalb der gestrichelten Box ist ein Verbraucher; nichts außerhalb der Box besitzt AMD-Anmeldedaten oder sendet XML.

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

Lokal mit fünf Befehlen ausführen

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 sollte {"status": "starting"} oder "ok" antworten, sobald der erste Anmeldeversuch abgeschlossen ist. docker compose up --build führt dasselbe containerisiert aus und liest dieselbe .env.

Einen Agenten anbinden

Toolnamen, Argumentschemata und geschwärzte Ergebnisschemata sind bei allen drei Anbindungsmethoden identisch (SPEC 12.1), sodass eine Agentenkonfiguration ohne Änderung der Prompts von einer zur anderen wechseln kann.

Remote-MCP (gehostete Agenten, z. B. Adam) – zeigen Sie direkt auf die Streamable-HTTP-Oberfläche des Connectors:

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

Zehn Routen werden bereitgestellt: /mcp/patients, /mcp/visits, /mcp/providers, /mcp/codes, /mcp/billing, /mcp/payments, /mcp/masterfiles, /mcp/system, /mcp/ehr und /mcp/all (die Vereinigungsmenge).

Lokaler Stdio-Shim (Agenten auf einer Workstation) – installieren Sie das veröffentlichte Paket advancedmd-mcp und richten Sie es über das Netzwerk auf den Connector; es enthält weder Anmeldedaten noch Tool-Logik:

{"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 – plugin/ deklariert alle neun Stdio-Server mit den Umgebungsreferenzen ${ADVANCEDMD_CONNECTOR_URL} und ${ADVANCEDMD_CONNECTOR_TOKEN}:

claude plugin add <path or repo>/plugin

Dieselbe plugin/.mcp.json gilt per Kopie für Cursor und Claude Desktop.

Verwendung aus einem Workflow

Backend-Python-Dienste verwenden das SDK in orlando-derm-backend/lib/advancedmd_connector/, das alle vorhandenen Methodennamen und typisierten Ergebnisse beibehält:

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

Das SDK enthält keine AMD-Anmeldedaten, kein XML und keine AMD-URL – es ist reines HTTP. Siehe SPEC 13 für die vollständige Methodentabelle und Ausnahmebehandlung.

Ein Token ausstellen

Tokens werden mit dem mitgelieferten connector-CLI gegen die Tokentabellendatei (CONNECTOR_TOKENS_PATH) ausgestellt und widerrufen:

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

Ein Klartext-Token wird bei der Ausstellung einmalig ausgegeben und weder gespeichert noch wiederhergestellt. Die vollständige Flag-Referenz finden Sie in docs/OPERATIONS.md und das Tokenmodell in docs/TOKENS.md.

Wo man nachschaut, wenn etwas langsam ist

• GET /health (kein Token, nur internes Netzwerk) – Sitzungsstatus, Tiefe der Eingangswarteschlange und älteste Wartezeit, Tiefe der Anforderungswarteschlange sowie die verwendete/Rate-Limit-Uhr pro Stufe, alles in einem Aufruf.

• GET /metrics (kein Token) – Prometheus-Text: Toolaufrufzahlen und Wartezeithistogramme nach Aufrufer/Tool/Ergebnis, AMD-Anforderungszahlen und Post-Zeit-Histogramme nach Stufe, Uhr verwendet/Grenzwert/Schlafzeit pro Stufe, Zähler für erneute Anmeldungen und Anmeldeverweigerungen, Warteschlangentiefen. Die vollständige Metrikliste und die Alarmbedingungen finden Sie in SPEC 18 bzw. SPEC 18.2.

• Eine langsame AMD-Antwort darf /health niemals verzögern – die Sender-Schleife und /health laufen in derselben Ereignisschleife, aber blockierende E/A ist verboten (SPEC 4.4). Ein hängender AMD-Aufruf zeigt sich also als Uhr-/Warteschlangendruck auf /health, nicht als nicht reagierender Connector.

Batch-Zeitplan

Der Connector selbst führt keine Batch-Jobs aus; er serialisiert, was seine Aufrufer mit Batch-Priorität senden. Die derzeit damit geplanten Verbraucher (Migrationsübersicht in SPEC 22) sind appointment-validator (ein nächtlicher Lauf), srt-auths (Scan- und Ereignisläufe) und note-audit (ein täglicher Lauf). Batch-Prioritätsanfragen altern nach BATCH_AGING_MS (Standard 60 s) in die Höherstufung, sodass ein langer Batch-Rückstau interaktive Aufrufe nicht unbegrenzt aushungern kann (SPEC 5.3); Bereitstellungen sollten diese Fenster dennoch meiden, da ein Neustart die In-Memory-Sitzung verwirft (SPEC 16.3).

Weiterführende Informationen

• SPEC.md – der vollständige Build-Vertrag.

• docs/CONNECTOR_DECISIONS.md – warum jede Entscheidung getroffen wurde.

• docs/API.md – die HTTP-API, gespiegelt aus SPEC 11.

• docs/OPERATIONS.md – Token-CLI, Bereitstellung, Rollback, Warnungen und die Fixture-Prozedur.

• docs/TOOL_TO_XML_MAP.md – pro Tool die AMD-Anforderungszuordnung und das Verifizierungsprotokoll.