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.