Skip to main content
Glama

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: tenant-scoped-crm

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.

Feld

Typ

Hinweise

clinic_id

string

Erforderlich

specialty

enum

general_practice

pediatrics

cardiology

dermatology

from_iso

string

Inklusiver ISO 8601 Start

to_iso

string

Exklusives ISO 8601 Ende

duration_minutes

int

15 bis 120, Standard 30

limit

int

1 bis 50, Standard 10

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.

Feld

Typ

Hinweise

clinic_id

string

Erforderlich

provider_id

string

Muss zu clinic_id gehören

patient_id

string

Muss zu clinic_id gehören

start_iso

string

ISO 8601

duration_minutes

int

15 bis 120, Standard 30

reason

string

1 bis 500 Zeichen

idempotency_key

string

8 bis 128 Zeichen, vom Aufrufer bereitgestellt

Gibt { appointment, idempotent_replay } zurück.

record_intake

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

Feld

Typ

Hinweise

clinic_id

string

Erforderlich

patient_id

string

Muss zu clinic_id gehören

symptoms

string[]

1 bis 20 Einträge

severity

int

1 bis 10, vom Patienten gemeldet

onset_iso

string

ISO 8601

notes

string

Optional, max. 2000 Zeichen

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.

Feld

Typ

Hinweise

clinic_id

string

Erforderlich

query

string

1 bis 500 Zeichen

limit

int

1 bis 20, Standard 5

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.

Feld

Typ

Hinweise

clinic_id

string

Erforderlich

appointment_id

string

Muss zu clinic_id gehören

reason

string

1 bis 500 Zeichen, wird an den Grund des Termins angehängt

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.

Available Tools

5 tools
book_appointmentBook an appointmentB

Create an appointment for a patient with a provider. Requires an idempotency_key; repeated calls with the same key return the original appointment instead of double-booking.

Inputs: clinic_id (required), provider_id (required), patient_id (required), start_iso (required), +3 more.

escalate_to_oncallEscalate an appointment to the on-call providerC

Mark an existing appointment as urgent and reassign it to the clinic's on-call provider.

Inputs: clinic_id (required), appointment_id (required), reason (required).

find_available_slotFind available appointment slotsB

Return open appointment slots for a given specialty in a date range. Filters by clinic_id and skips conflicts with existing appointments.

Inputs: clinic_id (required), specialty (required), from_iso (required), to_iso (required), +2 more.

record_intakeRecord patient intakeB

Persist a structured intake note (symptoms, severity, onset) for a patient and assign a triage level (routine / elevated / urgent).

Inputs: clinic_id (required), patient_id (required), symptoms (required), severity (required), +2 more.

search_protocolsSearch clinic protocol documentsB

Keyword search over the clinic's protocol library. Returns ranked snippets the model can cite when answering.

Inputs: clinic_id (required), query (required), limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: booking appointments, escalating to on-call, finding slots, recording intake, and searching protocols. No two tools overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case, making it easy to predict the action and resource for each tool.

    Tool Count5/5

    With exactly 5 tools, the server is well-scoped for a clinic domain, covering core patient-facing and administrative workflows without being overly heavy or thin.

    Completeness3/5

    The set covers appointment creation, urgent escalation, slot availability, intake recording, and protocol search. However, it lacks read/update/delete for appointments and any patient or provider management, which are notable gaps.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A reference MCP server demonstrating safe agent access to multi-tenant CRM data with tenant isolation enforced in the data layer, role-based permissions, and human confirmation on writes.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server reference implementation adding enterprise layers (identity, authorization, audit) around MCP, with sample shipment status and delayed shipment tools over a stateless transport.
      Apache 2.0