clinic-mcp

Ein Referenz-Server für das Model Context Protocol zur Klinikplanung und Patientenaufnahme. Erstellt in TypeScript mit strenger Typisierung, strukturierten Fehlern und einer auf Datenebene erzwungenen Mandantentrennung. Die Daten sind synthetisch. Dies ist keine klinische Software.

Das Ziel ist es zu zeigen, wie ein MCP-Server in Produktionsqualität für einen Bereich aussieht, der Datenisolierung und fundierte Ausgaben erfordert: die gleiche Code-Struktur, die ich bei Rentive verwende, jedoch mit Mock-Daten und einer anderen Domäne, damit die Muster überprüfbar sind, ohne proprietäre Informationen preiszugeben.

Warum MCP

LLM-Anwendungen erfinden ständig dieselbe Verkabelung neu: Ad-hoc-Funktionsdefinitionen pro Anbieter, maßgeschneidertes Argument-Parsing, kein gemeinsamer Transport, kein konsistentes Fehlermodell. MCP ist ein kleines, offenes Protokoll, das die Verkabelungsebene vereinheitlicht. Ein Server stellt eine Liste typisierter Tools über stdio (oder HTTP) bereit, und jeder MCP-fähige Client (Claude Desktop, IDE-Integrationen, benutzerdefinierte Agenten) kann diese mit derselben Maschinerie entdecken und aufrufen.

Für Domänen-Backends bedeutet das: Sie schreiben Tools einmal und sie funktionieren überall. Für Agenten-Entwickler bedeutet es, dass Sie aufhören, Tool-Schemas von Hand zu erstellen, und anfangen, Server zu kombinieren.

Related MCP server: MCP Healthcare Server

Architektur

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

Jedes Tool akzeptiert eine clinic_id, und der Speicher stellt sicher, dass alle Lese- und Schreibvorgänge auf diese Klinik beschränkt sind. Ein mandantenübergreifender Zugriff löst einen TenantMismatchError aus, anstatt stillschweigend die falsche Zeile zurückzugeben. Dies spiegelt das Row-Level-Security-Muster wider, das eine Produktionsbereitstellung in Postgres erzwingen würde, hier jedoch im Anwendungscode abgebildet, damit die Garantie in einer Datei (src/store/index.ts) überprüfbar ist.

Lokal ausführen

Erfordert Node 20+ und 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

Der Server liest beim Start src/store/seed.json und bedient zwei synthetische Kliniken: clinic_north (Allgemeinmedizin, Kardiologie, Dermatologie) und clinic_west (Pädiatrie, Allgemeinmedizin).

In Claude Desktop einbinden

Fügen Sie dies Ihrer Claude Desktop-Konfiguration hinzu (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). Ersetzen Sie den Pfad durch Ihren lokalen Klon.

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

Starten Sie Claude Desktop neu. Die fünf Tools erscheinen im Verbindungsmenü. Versuchen Sie eine Eingabeaufforderung wie: "Finde einen Termin für Allgemeinmedizin in der clinic_north am nächsten Montagmorgen."

Tool-Referenz

Alle Tools geben bei Erfolg { ok: true, ...result } oder bei Fehler { ok: false, error: { code, message } } zurück. Eingaben werden mit zod validiert; MCP-Ebene-Argumentfehler werden als validation-Fehler mit Felddetails zurückgegeben.

find_available_slot

Findet freie Terminslots für ein Fachgebiet in einem Datumsbereich und überspringt Konflikte.

book_appointment

Erstellt einen Termin. Erfordert einen vom Aufrufer bereitgestellten idempotency_key; Wiederholungen geben den ursprünglichen Termin zurück, anstatt doppelt zu buchen. Sprachagenten werden es erneut versuchen, daher ist dies nicht optional.

Gibt { appointment, idempotent_replay } zurück.

record_intake

Speichert eine strukturierte Aufnahmenotiz und weist eine Triage-Stufe zu.

Triage-Regel: Schweregrad >= 8 ist urgent, >= 5 ist elevated, ansonsten routine.

search_protocols

Stichwortsuche in der Protokollbibliothek der Klinik. Gibt bewertete Snippets zurück, die das Modell beim Antworten zitieren kann.

Die aktuelle Implementierung ist ein naiver TF-Score mit Titelgewichtung (3x). Sie dient dazu, die Schnittstelle eines Retrieval-Tools zu demonstrieren; Produktionsbereitstellungen würden das Backend durch eine Vektorsuche ersetzen (siehe Design-Hinweise).

escalate_to_oncall

Markiert einen bestehenden Termin als dringend und weist ihn dem diensthabenden Anbieter der Klinik neu zu.

Gibt { appointment, on_call_provider, reassigned } zurück.

Design-Hinweise

Mandantentrennung wird im Speicher erzwungen, nicht im Tool. Tools akzeptieren eine clinic_id und geben sie weiter. Der Speicher validiert den Besitz bei jedem Zugriff und löst bei Nichtübereinstimmung einen TenantMismatchError aus. Wenn Sie morgen ein neues Tool hinzufügen, können Sie nicht versehentlich Daten zwischen Kliniken preisgeben; der Speicher lässt dies nicht zu.

Idempotenz bei Schreibvorgängen. book_appointment erfordert einen idempotency_key. Echte Aufrufer (Sprachagenten, Wiederholungsschleifen, Netzwerkprobleme) werden Anfragen wiederholen, und ein Gesundheitssystem, das auf Wiederholungen mit der Erstellung doppelter Termine reagiert, ist ein System, das vom ersten Tag an das Vertrauen verliert.

Strukturierte Fehler statt geworfener Strings. Jeder Domänenfehler ist eine typisierte DomainError-Unterklasse mit einem stabilen code. Der MCP-Wrapper wandelt sie in { ok: false, error: { code, message } } um. Clients können nach code verzweigen, anstatt message mit Regex zu durchsuchen.

Das Retrieval-Tool ist ein Platzhalter. search_protocols verwendet einen In-Memory-TF-Score, damit das Repo ohne externe Dienste läuft. In der Produktion ist dies die Schnittstelle, an der Sie Pinecone, pgvector oder Ihr bevorzugtes Retrieval-Backend anschließen. Der Input/Output-Vertrag des Tools bleibt gleich.

Zeitbehandlung ist vereinfacht. Die Arbeitszeiten der Anbieter werden zur Klarheit in UTC interpretiert. Eine echte Bereitstellung würde die Zeitzone jeder Klinik berücksichtigen (bereits im Schema vorhanden). Dies wird explizit erwähnt, damit Prüfer wissen, dass es beabsichtigt ist und kein Versehen.

Was dies nicht ist

• Keine klinische Software. Die Triage-Regel ist ein Spielzeug und das Protokoll-Korpus ist handgeschriebene Prosa. Verwenden Sie es nicht für Dinge, die echte Patienten betreffen.

• Nicht HIPAA-konform. Die Daten sind gefälscht, die Speicherung erfolgt im Arbeitsspeicher, es gibt kein Audit-Log. Die Produktion würde all das und mehr erfordern.

• Kein vollständiges EMR- oder Planungs-Backend. Der Punkt ist, die Form des MCP-Servers zu zeigen, nicht ein Kliniksystem auszuliefern.

Lizenz

MIT. Siehe LICENSE.