Spec: MCP Server nativo no n8n para o Z-PRO (substitui node comunitario stdio)
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
257afe98c0
commit
3f10ab5efd
@@ -0,0 +1,139 @@
|
||||
# Design — MCP Server nativo no n8n para o Z-PRO
|
||||
|
||||
**Data:** 2026-08-10
|
||||
**Status:** Aprovado pelo usuário, aguardando plano de implementação.
|
||||
|
||||
## Objetivo
|
||||
|
||||
Reconstruir o "MCP Server" do Z-PRO **dentro do n8n**, usando nodes oficiais
|
||||
(`MCP Server Trigger` + `Call n8n Sub-Workflow Tool`), em vez de um processo
|
||||
Node.js externo (`gti-scheduling-mcp`) conectado via node comunitário stdio.
|
||||
|
||||
Motivação: o node comunitário (`n8n-nodes-mcp`) exigiu um dia inteiro de
|
||||
depuração (ver `docs/n8n-agendamento-runbook.md`) — campo de credencial
|
||||
quebrado, caminho absoluto de binário, mecanismo `toolParameters`/`$fromAI`
|
||||
não documentado. Um MCP Server nativo do n8n elimina essa camada inteira:
|
||||
usa só nodes oficiais dos dois lados (servidor e cliente), tudo editável
|
||||
visualmente, sem deploy de processo separado, sem SSH para manutenção.
|
||||
|
||||
## Relação com o trabalho anterior
|
||||
|
||||
Este design **substitui, para o Z-PRO**, o plano de monorepo
|
||||
TypeScript (`packages/zpro-mcp`, `packages/klingo-mcp`, etc.) discutido
|
||||
horas antes nesta mesma sessão. Aquele plano fica pausado — se a
|
||||
abordagem nativa do n8n se confirmar boa na prática, o mesmo padrão é
|
||||
replicado para Klingo/ClinicAll/SysLife depois; o monorepo TypeScript só
|
||||
volta a fazer sentido se algo aqui não funcionar bem.
|
||||
|
||||
O `gti-scheduling-mcp` (TypeScript, testado, com `ZProAdapter` e
|
||||
`KlingoAdapter` funcionando) **não é apagado** — fica como referência da
|
||||
lógica de negócio já validada (mapeamento de request/response, classificação
|
||||
de erro HTTP, proteção contra duplicidade) a ser replicada nos nodes do
|
||||
n8n. Este design é, na prática, uma **porta** dessa lógica já testada para
|
||||
nodes n8n — não um redesenho da regra de negócio em si.
|
||||
|
||||
## Contexto verificado (nodes reais, confirmados via n8n-mcp)
|
||||
|
||||
- **`MCP Server Trigger`** (`@n8n/n8n-nodes-langchain.mcpTrigger`, v2) —
|
||||
trigger baseado em webhook, expõe um `path` como endpoint MCP. Nó
|
||||
**oficial**, não comunitário.
|
||||
- **`Call n8n Sub-Workflow Tool`** (`@n8n/n8n-nodes-langchain.toolWorkflow`,
|
||||
v2.2) — empacota outro workflow inteiro como uma tool exposta ao MCP,
|
||||
com `name`, `description`, e `workflowInputs` (schema dos parâmetros que
|
||||
a tool aceita). O sub-workflow chamado precisa começar com um
|
||||
`Execute Workflow Trigger`.
|
||||
- Do lado cliente (o workflow de agendamento existente), o node oficial
|
||||
`MCP Client Tool` (`@n8n/n8n-nodes-langchain.mcpClientTool`) suporta
|
||||
conexão via **HTTP Streamable/SSE** — exatamente o transporte que o
|
||||
`MCP Server Trigger` expõe. Não precisa de nenhum pacote comunitário.
|
||||
|
||||
## Arquitetura
|
||||
|
||||
```
|
||||
[MCP Server Trigger] ──Tools──┬── [Call Sub-Workflow Tool: "agendar"] ──▶ "MCP Server - ZPRO - agendar"
|
||||
(workflow "MCP Server - ZPRO") │
|
||||
└── [Call Sub-Workflow Tool: "consultar_horarios"] ──▶ "MCP Server - ZPRO - consultar_horarios"
|
||||
```
|
||||
|
||||
Três workflows no total. O workflow de agendamento existente (AI Agent +
|
||||
prompt + memória) **não muda nada**, exceto o node MCP: sai o comunitário
|
||||
(stdio), entra o `MCP Client Tool` oficial (HTTP), apontando pra URL do
|
||||
`MCP Server Trigger`.
|
||||
|
||||
## Componentes
|
||||
|
||||
### Workflow "MCP Server - ZPRO" (o servidor)
|
||||
|
||||
- `MCP Server Trigger` — define o `path` do endpoint (ex.:
|
||||
`mcp-server-zpro-clinica-exemplo`).
|
||||
- Dois nodes `Call n8n Sub-Workflow Tool`, um por tool:
|
||||
- `agendar` → aponta pro sub-workflow "MCP Server - ZPRO - agendar".
|
||||
- `consultar_horarios` → aponta pro sub-workflow "MCP Server - ZPRO -
|
||||
consultar_horarios".
|
||||
|
||||
### Sub-workflow "MCP Server - ZPRO - agendar"
|
||||
|
||||
```
|
||||
[Execute Workflow Trigger] → [Config ZPRO] → [Montar corpo] → [HTTP Request] → [Classificar resultado]
|
||||
```
|
||||
|
||||
- **Execute Workflow Trigger**: recebe os parâmetros da tool — `clinicId`,
|
||||
`startAt`, `endAt`, `patient` (nome obrigatório; telefone, id, documento
|
||||
opcionais), `title` opcional. Mesmo contrato de hoje
|
||||
(`CreateAppointmentInput`/`agendarInputSchema`), definido no
|
||||
`workflowInputs` do node pai.
|
||||
- **Config ZPRO** (`Set`): `baseUrl` e `apiId` fixos desta clínica — ajustar
|
||||
ao duplicar pra outra clínica (mesmo espírito do `clinicId` fixo no
|
||||
"Normalizar entrada" do workflow de agendamento).
|
||||
- **Montar corpo** (`Code`): porta de `zpro.mapper.ts` —
|
||||
`title` default (`"Consulta - {nome}"` se não informado pelo cliente),
|
||||
inclui `contactId`/`contactPhone` só quando existirem no input,
|
||||
`status: "pending"` fixo.
|
||||
- **HTTP Request**: `POST {baseUrl}/v2/api/external/{apiId}/appointment/create`,
|
||||
Bearer token vindo de uma Credential do n8n. **Resposta completa/"Never
|
||||
Error" habilitado** — por padrão o n8n trata 4xx/5xx como falha e aborta
|
||||
o workflow; a classificação de erro precisa ser feita manualmente no
|
||||
próximo node, replicando exatamente o comportamento já validado.
|
||||
- **Classificar resultado** (`Code`): porta de `zpro.adapter.ts` +
|
||||
`zpro.errors.ts`:
|
||||
- **Qualquer HTTP 2xx é sucesso operacional**, sem exceção — mesma
|
||||
proteção contra duplicidade já validada em produção. Tenta mapear o
|
||||
envelope real conhecido (`{success:true, data:{id,startAt,endAt,status}}`,
|
||||
ver `docs/zpro-api-mapping.md`); 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 do intervalo 2xx: classifica em `AUTHENTICATION_ERROR` (401/403),
|
||||
`NOT_FOUND` (404), `VALIDATION_ERROR` (400/422), ou um erro genérico
|
||||
para o resto — mesmos códigos já usados hoje.
|
||||
|
||||
### Sub-workflow "MCP Server - ZPRO - consultar_horarios"
|
||||
|
||||
```
|
||||
[Execute Workflow Trigger] → [Code: retorna NOT_SUPPORTED]
|
||||
```
|
||||
|
||||
Sem chamada HTTP — mesma decisão de produto de hoje (o Z-PRO não expõe
|
||||
endpoint de disponibilidade de horários).
|
||||
|
||||
## Credenciais
|
||||
|
||||
Uma Credential HTTP (Bearer/Header Auth) no n8n, só com o
|
||||
`ZPRO_API_TOKEN`. `baseUrl`/`apiId` ficam no node `Config ZPRO` — não são
|
||||
segredo, precisam só ficar visíveis/editáveis por clínica ao duplicar o
|
||||
conjunto de workflows.
|
||||
|
||||
## Fora de escopo (adiado)
|
||||
|
||||
- Klingo, ClinicAll, SysLife via este mesmo padrão — replicar depois que o
|
||||
Z-PRO nativo estiver validado.
|
||||
- O monorepo TypeScript (`packages/*-mcp`) fica pausado, não descartado.
|
||||
- `consultar_horarios` continua não suportado pro Z-PRO (mesma decisão de
|
||||
produto já tomada, sem mudança).
|
||||
|
||||
## Testes
|
||||
|
||||
Sem testes automatizados (workflows do n8n, não código com framework de
|
||||
teste). Validação manual, seguindo a mesma disciplina já usada no projeto
|
||||
inteiro: dado fictício, execução única por vez, conferência visual no
|
||||
Z-PRO antes de qualquer nova tentativa — evitar duplicar agendamento
|
||||
durante os testes desta migração.
|
||||
Reference in New Issue
Block a user