diff --git a/docs/superpowers/specs/2026-08-11-mcp-server-nativo-n8n-syslife-design.md b/docs/superpowers/specs/2026-08-11-mcp-server-nativo-n8n-syslife-design.md new file mode 100644 index 0000000..c3c6209 --- /dev/null +++ b/docs/superpowers/specs/2026-08-11-mcp-server-nativo-n8n-syslife-design.md @@ -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://: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 ] → [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 ``** (`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.