clinic-engine

Action Engine de agendamento da Clínica Horizonte.

O agente (Claude, ChatGPT, Cursor, um app ou a CLI) só pede o resultado. A política da clínica — expediente, buffer, aviso mínimo e quem atende o quê — mora aqui, uma vez, e todo mundo passa por engine.invoke.

paciente / recepção / agente
        ↓
appointments.list-valid-slots
appointments.schedule
appointments.reschedule
appointments.cancel
        ↓
política da clínica + calendário
        ↓
horário válido, consulta marcada, ou recusa estável

O que este engine faz

A clínica de demonstração:

• Expediente: segunda a sexta, 08:00–18:00; sábado, 08:00–12:00; domingo fechado

• Fuso: America/Sao_Paulo (-03:00)

• Buffer: 10 minutos entre consultas

• Aviso mínimo: 2 horas para marcar, remarcar ou cancelar

• Profissionais: Dra. Ana Souza (consulta-geral, retorno) e Dr. Carlos Mendes (consulta-geral, exame)

O calendário padrão é em memória, com duas consultas já marcadas no dia 2026-09-07, para o README e os testes serem determinísticos. O relógio padrão também está congelado nesse dia. Trocar para relógio real ou Google Calendar é só injetar outra dependência — as capabilities não mudam.

Related MCP server: northstar-clinic

Requisitos

• Node.js 22.20 ou posterior

Primeiro run

npm install
npm run check
npm run direct

npm run check typecheck, testa, builda e valida o catálogo MCP. npm run direct lista horários de consulta-geral no dia de demonstração.

CLI

A CLI entra como a recepção local (local:clinic-desk), então as actions autenticadas funcionam.

npm run build

npm run cli -- list

npm run cli -- run appointments.list-valid-slots --input '{"appointmentType":"consulta-geral","date":"2026-09-07"}'

npm run cli -- run appointments.schedule --input '{
  "patientName": "Ada Lovelace",
  "appointmentType": "consulta-geral",
  "practitionerId": "dra-ana-souza",
  "start": "2026-09-07T14:00:00-03:00"
}'

MCP stdio

npm run mcp:stdio
npm run mcp:install

Depois o Cursor, Claude Code ou outro cliente MCP local vê as quatro tools. mcp:uninstall remove o engine dos clientes gerenciados pelo Senda.

MCP HTTP

1. Copie .env.example para .env

2. Defina CLINIC_ENGINE_HTTP_TOKEN

3. Suba o servidor:

cp .env.example .env
npm run mcp:http

O endpoint é POST http://127.0.0.1:3000/mcp. Sem Authorization: Bearer <token> a resposta é 401. Não existe modo de desenvolvimento sem autenticação.

Devtools

npm run devtools

Abre o inspector do Senda (em geral em http://localhost:4100/). Dá para chamar a mesma capability por direct, CLI, MCP stdio ou MCP HTTP e comparar o resultado.

Como a fronteira funciona

• MCP, CLI e HTTP são tomadas. Eles não conhecem Google Calendar nem a regra de sábado.

• O Action Engine é o microsserviço de domínio. Ele valida entrada, autoriza, aplica a política e só então fala com o calendário.

• Google Calendar é um adapter. src/infrastructure/google-calendar.ts implementa o mesmo CalendarPort da agenda em memória via defineConnector. O default não chama a API do Google, para o clone do repositório funcionar sem credencial.

Para usar Google Calendar no composition root:

import { googleCalendarConnector } from "./infrastructure/google-calendar.js";

const { ports } = googleCalendarConnector.create(
  {
    calendarId: process.env.GOOGLE_CALENDAR_ID,
    accessToken: process.env.GOOGLE_CALENDAR_ACCESS_TOKEN,
  },
  {},
);

export const engine = createClinicEngine({
  calendar: ports.calendar,
  clock: { now: () => new Date() },
  createId: createIdFactory(),
});

Mapa do projeto

src/capabilities/     contratos públicos (input, output, access, run)
src/domain/           política da clínica e geração de slots
src/application/      CalendarPort e dependências
src/infrastructure/   agenda em memória e conector Google
src/engine.ts         um mapa de capabilities, um invoke
src/direct.ts         smoke test
src/cli.ts            CLI
src/mcp-stdio.ts      MCP local
src/mcp-http.ts       MCP Streamable HTTP
test/                 provas pela fronteira engine.invoke

Licença

MIT