clinic-mcp

Un servidor de referencia del Model Context Protocol para la programación y admisión en clínicas. Construido en TypeScript con tipado estricto, errores estructurados y aislamiento de inquilinos aplicado en la capa de datos. Los datos son sintéticos. Esto no es software clínico.

El objetivo es mostrar cómo se ve un servidor MCP con formato de producción para un sector que exige aislamiento de datos y resultados fundamentados: la misma forma de código que escribo en Rentive, con datos simulados y un dominio diferente para que los patrones sean revisables sin filtrar nada propietario.

Por qué MCP

Las aplicaciones LLM siguen reinventando el mismo cableado: definiciones de funciones ad-hoc por proveedor, análisis de argumentos a medida, sin transporte compartido, sin un modelo de error consistente. MCP es un pequeño protocolo abierto que soluciona la capa de cableado. Un servidor expone una lista de herramientas tipadas sobre stdio (o HTTP), y cualquier cliente compatible con MCP (Claude Desktop, integraciones de IDE, agentes personalizados) puede descubrirlas y llamarlas con el mismo mecanismo.

Para los backends de dominio, eso significa que escribes las herramientas una vez y funcionan en todas partes. Para los creadores de agentes, significa que dejas de crear esquemas de herramientas manualmente y empiezas a componer servidores.

Related MCP server: MCP Healthcare Server

Arquitectura

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

Cada herramienta toma un clinic_id y el almacén garantiza que todas las lecturas y escrituras estén limitadas a esa clínica. El acceso entre inquilinos lanza un TenantMismatchError en lugar de devolver silenciosamente la fila incorrecta. Esto refleja el patrón de seguridad a nivel de fila que una implementación de producción aplicaría en Postgres, expuesto aquí en el código de la aplicación para que la garantía sea revisable en un solo archivo (src/store/index.ts).

Ejecutarlo localmente

Requiere Node 20+ y 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

El servidor lee src/store/seed.json al iniciarse y sirve dos clínicas sintéticas: clinic_north (medicina general, cardiología, dermatología) y clinic_west (pediatría, medicina general).

Conectar a Claude Desktop

Añade esto a tu configuración de Claude Desktop (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). Reemplaza la ruta con tu clon local.

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

Reinicia Claude Desktop. Las cinco herramientas aparecerán en el menú de conexiones. Prueba un prompt como "Busca una cita de medicina general en clinic_north el próximo lunes por la mañana."

Referencia de herramientas

Todas las herramientas devuelven { ok: true, ...result } en caso de éxito o { ok: false, error: { code, message } } en caso de error. Las entradas se validan con zod; los errores de argumentos a nivel de MCP se devuelven como errores de validation con detalles del campo.

find_available_slot

Busca espacios de cita disponibles para una especialidad en un rango de fechas, omitiendo conflictos.

book_appointment

Crea una cita. Requiere una idempotency_key proporcionada por el llamador; las repeticiones devuelven la cita original en lugar de reservar doble. Los agentes de voz reintentarán, por lo que esto no es opcional.

Devuelve { appointment, idempotent_replay }.

record_intake

Persiste una nota de admisión estructurada y asigna un nivel de triaje.

Regla de triaje: severidad >= 8 es urgent, >= 5 es elevated, de lo contrario routine.

search_protocols

Búsqueda por palabras clave en la biblioteca de protocolos de la clínica. Devuelve fragmentos clasificados que el modelo puede citar al responder.

La implementación actual es una puntuación TF ingenua con ponderación de título (3x). Existe para demostrar la interfaz de una herramienta de recuperación; las implementaciones de producción cambiarían el backend por una búsqueda vectorial (ver notas de diseño).

escalate_to_oncall

Marca una cita existente como urgente y la reasigna al proveedor de guardia de la clínica.

Devuelve { appointment, on_call_provider, reassigned }.

Notas de diseño

El aislamiento de inquilinos se aplica en el almacén, no en la herramienta. Las herramientas aceptan un clinic_id y lo pasan hacia abajo. El almacén valida la propiedad en cada acceso y lanza un TenantMismatchError en caso de discrepancia. Si añades una nueva herramienta mañana, no puedes filtrar accidentalmente entre clínicas; el almacén no te lo permitirá.

Idempotencia en las escrituras. book_appointment requiere una idempotency_key. Los llamadores reales (agentes de voz, bucles de reintento, fallos de red) repetirán las solicitudes, y un sistema de salud que responde a los reintentos creando citas duplicadas es un sistema de salud que pierde la confianza desde el primer día.

Errores estructurados en lugar de cadenas lanzadas. Cada fallo de dominio es una subclase de DomainError tipada con un code estable. El envoltorio MCP los convierte en { ok: false, error: { code, message } }. Los clientes pueden ramificarse según el code en lugar de usar expresiones regulares en el message.

La herramienta de recuperación es un sustituto. search_protocols utiliza una puntuación TF en memoria para que el repositorio se ejecute sin servicios externos. En producción, esta es la unión donde conectarías Pinecone, pgvector o tu backend de recuperación preferido. El contrato de entrada/salida de la herramienta permanece igual.

El manejo del tiempo está simplificado. Los horarios de trabajo de los proveedores se interpretan en UTC para mayor claridad. Una implementación real respetaría la zona horaria de cada clínica (ya incluida en el esquema). Menciono esto explícitamente para que los revisores sepan que es intencional, no un descuido.

Lo que esto no es

• No es software clínico. La regla de triaje es un juguete y el corpus de protocolos es prosa escrita a mano. No lo uses para nada que involucre a pacientes reales.

• No cumple con HIPAA. Los datos son falsos, el almacenamiento es en memoria, no hay registro de auditoría. La producción necesitaría todo eso y más.

• No es un EMR completo ni un backend de programación. El objetivo es mostrar la forma de un servidor MCP, no lanzar un sistema clínico.

Licencia

MIT. Ver LICENSE.