KLINGO-CLINICAL-SYSLIFE-GCHAT/docs/superpowers/specs/2026-08-11-mcp-server-nativo-n8n-syslife-design.md

# Design — MCP Server nativo no n8n para o SysLife

**Data:** 2026-08-11
**Status:** Aprovado pelo usuário, aguardando plano de implementação.

## Objetivo

Terceira aplicação do padrão de "MCP Server" nativo do n8n (`MCP Server
Trigger` + `Call n8n Sub-Workflow Tool`), já validado em produção pro
Z-PRO e estruturalmente pronto pro Klingo, agora pro SysLife — a partir da
documentação real (`Manual WS SysLife V3.4.pdf`, fornecida pelo usuário
nesta sessão, texto completo extraído e conferido).

## Relação com o trabalho anterior

Mesma arquitetura de base do Z-PRO/Klingo (ver
`docs/superpowers/specs/2026-08-10-mcp-server-nativo-n8n-zpro-design.md`
e `docs/superpowers/specs/2026-08-11-mcp-server-nativo-n8n-klingo-design.md`).
Diferença: o SysLife não tem um `SchedulingAdapter` já testado em
`gti-scheduling-mcp` (nunca foi implementado em TypeScript para este
provider) — a fonte de verdade aqui é **exclusivamente** o manual PDF
fornecido pelo usuário, sem nenhum teste real prévio contra a API. Isso
exige mais cautela: nenhum contrato de erro é assumido além do que o
manual documenta explicitamente.

## Escopo: "apenas o agendamento"

O usuário pediu foco só no agendamento, não no CRM completo do SysLife
(que tem ~15 recursos documentados: agenda por WhatsApp, central
telefônica, faturamento, aniversariantes, pacientes ausentes, guias,
etc.). Definido em conversa que "apenas agendamento" inclui as consultas
de apoio necessárias para montar um agendamento correto e completo (nome
do médico, especialidade, convênio/plano, valores) — não só os dois
endpoints de leitura/escrita mais óbvios.

**7 tools, mapeando 7 recursos do manual:**

| Tool (n8n) | Recurso/Método (manual) | Resolve | Parâmetros de entrada |
| --- | --- | --- | --- |
| `especialidade` | `Especialidade` GET | `CodigoEspecialidade`, `CodigoOrigem` | nenhum |
| `medico` | `Medico` GET | `CodigoMedico` | `CodigoEspecialidade`, `CodigoOrigem` |
| `convenio` | `Convenio` GET | nomes de convênio/plano (`nmFantasiaConvenio`, `nmPlano`) para o agente confirmar com o paciente | nenhum |
| `paciente` | `Paciente` GET | `CodigoPaciente`, `NomePaciente`, `CodigoConvenio`, `CodigoPlano`, telefone | CPF, matrícula ou celular (mesmo campo, conforme documentado) |
| `procedimento` | `Procedimento` GET | `CodigoTabelaProcedimento`, `CodigoProcedimento`, valor (`vrProcedimento`) | `CodigoConvenio`, `CodigoPlano`, `CodigoMedico` |
| `consultar_horarios` | `Horario` GET | `NumeroConsulta`, `DataAtendimento`, `HoraAtendimento` disponíveis | `CodigoEspecialidade`, `CodigoOrigem`, `CodigoMedico` |
| `agendar` | `Agenda` PUT | cria o agendamento, retorna `CO_AGENDA` | todos os códigos acima |

**Fora de escopo** (não fazem parte de "realizar um agendamento"):
`AgendaWSApp`, `AgendaCentral`, `AgendaRetorno`, `AgendaStatus`,
`AgendaConfirmado` (consultas/confirmações via WhatsApp/central
telefônica — pós-agendamento, não criação), `Paciente/Aniversariante`,
`Paciente/Ausente` (campanhas, não agendamento), `Medico/PlanoNaoCredenciado`
(negativa de cobertura, não fluxo principal), `Guia/Doc` (faturamento),
`Versao` (diagnóstico de ambiente).

## Autenticação e configuração

**Basic Auth fixo** — usuário (`WebSysLife`) e senha únicos do
WebService, documentados literalmente no manual (não são por clínica nem
por paciente, ao contrário do X-APP-TOKEN do Klingo que varia por
clínica). Uma única Credential do tipo **Basic Auth** no n8n, reaproveitada
nos 7 sub-workflows que fazem chamada HTTP.

`baseUrl` = `http://<IP do servidor>:9000` (porta fixa documentada) — fica
num node `Set` ("Config SysLife") em cada sub-workflow, mesmo padrão do
`Config ZPRO`/`Config Klingo`. Placeholder nesta etapa, sem clínica
SysLife real disponível.

## Componentes

### Workflow "MCP Server - SysLife" (o servidor)

`MCP Server Trigger` (`path`: `mcp-server-syslife`) + 7 nodes `Call n8n
Sub-Workflow Tool`, um por tool da tabela acima, cada um apontando para
seu sub-workflow.

### Sub-workflows de consulta (`especialidade`, `medico`, `convenio`,
`paciente`, `procedimento`, `consultar_horarios`) — mesmo esqueleto

```
[Execute Workflow Trigger] → [Config SysLife] → [Montar query] → [GET <endpoint>] → [Classificar resultado]
```

- **Execute Workflow Trigger**: parâmetros específicos de cada tool (ver
  tabela acima — só `medico`, `paciente`, `procedimento` e
  `consultar_horarios` recebem parâmetros; `especialidade` e `convenio`
  não recebem nenhum).
- **Config SysLife** (`Set`): `baseUrl` fixo desta clínica.
- **Montar query** (`Code`): monta o corpo JSON da requisição GET a
  partir do input, só com os campos que o manual documenta para aquele
  endpoint — nunca inventa campo adicional.
- **GET `<endpoint>`** (`HTTP Request`): `authentication: genericCredentialType`,
  `genericAuthType: httpBasicAuth`, corpo JSON no método GET (documentado
  assim no manual — `Body: raw, JSON` mesmo em métodos GET, quando
  aplicável), `neverError: true` + `fullResponse: true` (mesmo padrão dos
  outros dois providers).
- **Classificar resultado** (`Code`): 2xx → sucesso, devolve o corpo cru
  como veio (array/objeto), sem reformatar campos — o manual não garante
  nenhum envelope fixo além do que está documentado, e não há exemplo de
  resposta real capturado para validar contra. Fora de 2xx → classificado
  só pelo status HTTP (não existe, no manual, nenhuma correspondência
  documentada entre código HTTP e significado de erro específico do
  SysLife — usa-se a mesma taxonomia genérica dos outros dois providers):
  `AUTHENTICATION_ERROR` (401/403), `NOT_FOUND` (404), `VALIDATION_ERROR`
  (400/422), `SYSLIFE_API_ERROR` (demais).

### Sub-workflow "agendar" (`Agenda`, PUT)

```
[Execute Workflow Trigger] → [Config SysLife] → [Montar corpo] → [PUT /Agenda] → [Classificar resultado]
```

- **Execute Workflow Trigger**: `dataAtendimento`, `horaAtendimento`,
  `numeroConsulta`, `codigoOrigem`, `codigoPaciente`, `nomePaciente`,
  `codigoConvenio`, `codigoPlano`, `codigoTabelaProcedimento`,
  `codigoProcedimento`, `codigoMedico`, `codigoEspecialidade`,
  `numeroCelular`, `numeroCelularDDD` — todos já resolvidos pelo agente
  usando as outras 6 tools antes de chamar esta.
- **Montar corpo** (`Code`): monta exatamente o JSON documentado do PUT
  de `Agenda`, sem campo extra.
- **PUT `/Agenda`**: Basic Auth, `neverError: true` + `fullResponse: true`.
- **Classificar resultado** (`Code`): mesma proteção contra duplicidade já
  usada no Z-PRO/Klingo — **qualquer 2xx é sucesso operacional**, sem
  exceção. Tenta mapear `CO_AGENDA`/`Status` do corpo documentado
  (`{"Status": "?", "CO_AGENDA": ?}`); se o corpo não bater com esse
  formato, devolve um resultado "aceito, mapeamento pendente" construído
  só com os dados do input (nunca inventa campos do corpo). Fora de 2xx:
  mesma classificação genérica por status HTTP das demais tools.

## Fora de escopo (adiado)

- Os endpoints do manual não ligados a criar um agendamento (listados
  acima, seção "Escopo").
- Workflow de agente cliente (AI Agent + prompt + MCP Client Tool) para o
  SysLife — fica para quando houver uma clínica real e um canal de
  mensagens definido, mesma decisão do Klingo.
- ClinicAll via este mesmo padrão — ainda sem documentação disponível.
- O monorepo TypeScript (`packages/*-mcp`) continua pausado; o SysLife
  nunca teve um adapter TypeScript, então não há nada para "portar" além
  do próprio manual.

## Testes

Sem clínica SysLife real disponível: validação estrutural apenas
(`n8n_validate_workflow`), nenhuma chamada HTTP real nesta etapa. Quando
houver uma clínica real, testar a cadeia completa na ordem que o agente
usaria de verdade — `especialidade` → `medico` → (`horario`/`convenio`/
`paciente`/`procedimento`, em qualquer ordem) → `agendar` — com dado
fictício, execução única por vez, conferência visual no SysLife antes de
qualquer nova tentativa.