Spec: MCP Server nativo no n8n para o SysLife
Terceira aplicação do padrão nativo (MCP Server Trigger + Call n8n Sub-Workflow Tool), a partir do Manual WS SysLife V3.4 fornecido pelo usuário (sem adapter TypeScript prévio para este provider). Escopo "apenas agendamento" definido em conversa como 7 tools: 6 de consulta/apoio (especialidade, medico, convenio, paciente, procedimento, consultar_horarios) + agendar (PUT /Agenda). Auth Basic fixo do WebService, sem clínica real ainda -- validação estrutural apenas nesta etapa. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Gustavo
co-authored by
Claude Sonnet 5
Claude Sonnet 5
parent
4226c5f338
commit
209a0bc826
@@ -0,0 +1,150 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user