Snapshot: gti-scheduling-mcp (Z-PRO + Klingo adapters) e workflow n8n de agendamento funcionando de ponta a ponta
- gti-scheduling-mcp: MCP server com ZProAdapter e KlingoAdapter (agendar() completo pros dois) - Workflow n8n 'Agendamento - GChat - Z-PRO': webhook -> AI Agent -> MCP -> Z-PRO, testado com sucesso real - Documentacao: specs, plano, runbook de problemas reais e export do workflow Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Gustavo
Claude Sonnet 5
@@ -0,0 +1,263 @@
|
||||
# Runbook — Workflow de Agendamento no n8n (GChat/Z-PRO + gti-scheduling-mcp)
|
||||
|
||||
> Registra problemas reais encontrados ao montar o workflow
|
||||
> `Agendamento - GChat - Z-PRO (clínica exemplo)` (id `yG2mi6ECBpPv4Hmn`, servidor
|
||||
> `srvdevn8ngti` / `devn8n.gtigrupo.com.br`), e como foram resolvidos — para não
|
||||
> repetir o mesmo processo de descoberta ao duplicar este workflow para uma nova
|
||||
> clínica. Ver também `docs/superpowers/specs/2026-08-10-n8n-agendamento-workflow-design.md`
|
||||
> (design) e `docs/superpowers/plans/2026-08-10-n8n-agendamento-workflow.md` (plano).
|
||||
|
||||
## 1. Node MCP: qual usar e como instalar
|
||||
|
||||
- O node **oficial** do n8n (`MCP Client Tool`, `@n8n/n8n-nodes-langchain`) só
|
||||
conecta em MCP remoto via HTTP Streamable/SSE — **não** roda comando local
|
||||
(stdio). Para rodar o `gti-scheduling-mcp` como subprocesso local, use o
|
||||
pacote **comunitário** `n8n-nodes-mcp` (autor `nerding-io`).
|
||||
- Instalação: **Settings → Community Nodes → Install a community node** →
|
||||
`n8n-nodes-mcp`.
|
||||
- Ao conectar como tool de um AI Agent, o **tipo do node no JSON do workflow**
|
||||
precisa ser `n8n-nodes-mcp.mcpClientTool` (não `n8n-nodes-mcp.mcpClient`) —
|
||||
é uma variante "Tool" que o n8n gera automaticamente para nodes marcados
|
||||
como usáveis em AI Agents. Usar `mcpClient` na conexão `ai_tool` falha a
|
||||
validação com "cannot output ai_tool connections".
|
||||
- É necessário setar a variável de ambiente do **processo do n8n**
|
||||
(não é configurável pela UI):
|
||||
```
|
||||
N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
|
||||
```
|
||||
Nesse servidor, o n8n roda via **systemd** (`n8n.service`), com
|
||||
`EnvironmentFile=/opt/n8n.env`. A variável foi adicionada nesse arquivo,
|
||||
seguido de `systemctl restart n8n`. (Se o n8n rodasse em Docker, seria em
|
||||
`environment:` no `docker-compose.yml`.)
|
||||
|
||||
## 2. Credencial MCP (STDIO) — dois bugs reais
|
||||
|
||||
Tipo de credencial: `mcpClientApi` ("MCP Client (STDIO) API"), campos:
|
||||
`command`, `args`, `environments`.
|
||||
|
||||
- **Bug 1 — `command: "node"` sozinho falhou** com "Connection closed". O
|
||||
serviço systemd tem um `PATH` mais restrito que um shell interativo. Fix:
|
||||
usar o **caminho absoluto** (`which node` no servidor → `/usr/bin/node`).
|
||||
|
||||
- **Bug 2 — o campo "Environments" é um `<input>` de uma linha só (mascarado
|
||||
como senha) na UI do n8n.** O código real do node
|
||||
(`nodes/McpClient/McpClient.node.ts` no pacote `n8n-nodes-mcp`) espera o
|
||||
formato `NOME=VALOR` **separado por quebra de linha real** (`split('\n')`),
|
||||
mas navegadores removem quebras de linha ao digitar OU colar em campos de
|
||||
uma linha — então múltiplas variáveis nunca conseguem ser inseridas
|
||||
corretamente pela UI (tentamos: uma por linha, vírgula, espaço — todas
|
||||
colapsam a mesma forma, e a primeira variável acaba recebendo o resto do
|
||||
texto como valor, quebrando a validação).
|
||||
|
||||
**Fix**: criar/recriar a credencial via **API REST do n8n**, que aceita o
|
||||
JSON com `\n` de verdade (não passa pelo campo quebrado da UI):
|
||||
|
||||
```bash
|
||||
# 1. Gerar uma API key: Settings → n8n API → Create an API key
|
||||
# 2. DELETE na credencial antiga (se existir), depois POST na nova:
|
||||
curl -X POST "https://devn8n.gtigrupo.com.br/api/v1/credentials" \
|
||||
-H "X-N8N-API-KEY: <chave>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "Client (STDIO) account",
|
||||
"type": "mcpClientApi",
|
||||
"data": {
|
||||
"command": "/usr/bin/node",
|
||||
"args": "/opt/gti-scheduling-mcp/dist/index.js",
|
||||
"environments": "SCHEDULING_PROVIDER=zpro\nZPRO_BASE_URL=https://...\nZPRO_API_TOKEN=...\nZPRO_API_ID=..."
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Sintoma quando esse bug está presente: o log do n8n
|
||||
(`journalctl -u n8n -f`) mostra exatamente a mensagem de erro do
|
||||
`gti-scheduling-mcp` (`Falha ao carregar a configuração: SCHEDULING_PROVIDER
|
||||
deve ser "zpro" ou "klingo".`), seguida de `MCP error -32000: Connection
|
||||
closed` — o processo sobe e cai na validação de config antes de completar o
|
||||
handshake stdio.
|
||||
|
||||
## 3. Deploy do `gti-scheduling-mcp` no servidor do n8n
|
||||
|
||||
O `node dist/index.js` executado pela credencial precisa estar no **mesmo
|
||||
host** onde o n8n roda (o node comunitário spawna o processo localmente).
|
||||
Processo usado (sem repositório git configurado ainda neste projeto):
|
||||
`tar` local (excluindo `node_modules`/`dist`) → `scp` pro servidor → `npm
|
||||
install && npm run build` lá. Publicado em `/opt/gti-scheduling-mcp`.
|
||||
|
||||
## 4. Modelo de IA (OpenAI Chat Model node) — gotchas de configuração
|
||||
|
||||
Mesmo usando um provider "compatível com OpenAI" (ex.: Z.ai/GLM), o node
|
||||
`OpenAI Chat Model` (`@n8n/n8n-nodes-langchain.lmChatOpenAi`, v1.3) tem
|
||||
comportamento por padrão que quebra com endpoints não-OpenAI:
|
||||
|
||||
- **`responsesApiEnabled` é `true` por padrão** nessa versão — usa a
|
||||
"Responses API" da OpenAI (`/responses`), um endpoint proprietário que
|
||||
providers OpenAI-compatíveis geralmente não implementam (eles só têm
|
||||
`/chat/completions`). Sintoma: `404 Not Found` /
|
||||
`MODEL_NOT_FOUND`. **Fix**: setar `responsesApiEnabled: false`
|
||||
explicitamente.
|
||||
- **Campo `model`** é um `resourceLocator` — precisa de `{mode: "id", value:
|
||||
"nome-do-modelo"}` explícito. Omitir `mode` pode fazer o n8n tentar listar
|
||||
modelos via uma chamada de API (`GET /models`) que o provider alternativo
|
||||
pode não suportar do mesmo jeito, gerando erro parecido com o anterior.
|
||||
- **Base URL da credencial**: o campo correto na credencial `openAiApi` é
|
||||
`url` (aparece como "Base URL" na UI, geralmente atrás de "Add Option").
|
||||
|
||||
## 5. Expressões em sub-nodes de IA (Memory/Tools) dentro do AI Agent
|
||||
|
||||
Dentro de nodes conectados via `ai_memory`/`ai_tool`/`ai_languageModel`
|
||||
(sub-nodes do AI Agent), referenciar um node upstream explicitamente
|
||||
(`={{ $('Normalizar entrada').item.json.sessionId }}`) falhou com "Key
|
||||
parameter is empty" — mesmo com o dado presente no item que chegou no AI
|
||||
Agent. **Fix**: usar `={{ $json.sessionId }}` (referência ao item atual, sem
|
||||
nome de node) — é o padrão que o próprio n8n usa por padrão nesse campo, e
|
||||
funciona porque sub-nodes de IA herdam o item do node pai (AI Agent) na
|
||||
execução.
|
||||
|
||||
## 6. Contrato do webhook do Z-PRO/GChat (verificado, não documentado
|
||||
oficialmente em lugar nenhum)
|
||||
|
||||
- Uma execução do workflow **por mensagem** do cliente — o Z-PRO não
|
||||
enfileira mensagens seguintes se o workflow não responder imediatamente.
|
||||
- Corpo recebido: `{step, entrada, number, contactName, protocol}` — `step`
|
||||
deve ser `"process"`; `protocol` é o identificador do **atendimento**
|
||||
(não do telefone).
|
||||
- Resposta esperada: **texto puro**, nunca JSON — node `Respond to Webhook`
|
||||
em modo `text`.
|
||||
|
||||
## 7. Z.ai/GLM como modelo temporário — limitação real de tool-calling
|
||||
|
||||
Usado como substituto temporário enquanto a chave da OpenAI não chegava.
|
||||
Dois endpoints testados:
|
||||
|
||||
- **`https://api.z.ai/api/coding/paas/v4`** ("GLM Coding Plan"): funciona
|
||||
bem para chat simples, mas é **restrito a ferramentas oficialmente
|
||||
suportadas** (Claude Code, Goose, etc. — ver
|
||||
`https://docs.z.ai/devpack/faq`). Ao anexar uma tool MCP genérica ao AI
|
||||
Agent, o modelo passou a devolver respostas **vazias silenciosamente**
|
||||
(sem erro) em qualquer mensagem, mesmo sem chamar a tool. Confirmado
|
||||
desabilitando a tool: a conversa voltou a funcionar normalmente.
|
||||
- **`https://api.z.ai/api/paas/v4/`** (endpoint geral, mesma conta): suporta
|
||||
tool-calling arbitrário segundo a documentação, mas apresentou timeout
|
||||
consistente nesta conta/plano (possivelmente saldo separado do "Coding
|
||||
Plan").
|
||||
- **Conclusão**: Z.ai/GLM não é uma substituição direta e confiável da
|
||||
OpenAI para um AI Agent com tools neste projeto. Recomendado usar a chave
|
||||
real da OpenAI (ou outro provider com suporte robusto e testado de
|
||||
function-calling) assim que disponível — só trocar a credencial e o
|
||||
`model`/`responsesApiEnabled` de volta, sem tocar no resto do workflow.
|
||||
|
||||
## 8. Tratamento de erro adicionado
|
||||
|
||||
`Normalizar entrada` e `AI Agent` têm `onError: "continueErrorOutput"`,
|
||||
ambos roteados para um node `Set` ("Erro - Resposta padrão") com uma
|
||||
mensagem fixa amigável, que alimenta o `Respond to Webhook`. Isso garante
|
||||
que o Z-PRO **sempre** recebe alguma resposta, mesmo se a normalização
|
||||
lançar uma exceção ou o AI Agent falhar (timeout, erro de modelo, etc.) —
|
||||
testado com um timeout real do endpoint geral do Z.ai, confirmado
|
||||
funcionando.
|
||||
|
||||
## 9. Bug crítico — `toolParameters` do node MCP nunca era preenchido pelo modelo
|
||||
|
||||
**Sintoma**: toda chamada de `agendar` falhava com
|
||||
`MCP error -32602: Input validation error: Invalid arguments for tool
|
||||
agendar: Required at clinicId, Required at startAt, Required at endAt,
|
||||
Required at patient.` — mesmo com o prompt do sistema explicando o formato
|
||||
esperado em detalhe.
|
||||
|
||||
**Causa raiz**: o node `n8n-nodes-mcp` (operação `executeTool`) tem um
|
||||
campo próprio **`toolParameters`** (JSON, obrigatório, valor padrão
|
||||
`'{}'`) que carrega os argumentos reais enviados à tool. Ele **não é
|
||||
preenchido automaticamente** só por a tool estar conectada a um AI Agent —
|
||||
é preciso configurá-lo explicitamente com o helper `$fromAI()` do n8n, que
|
||||
é o mecanismo real usado para "deixar o modelo decidir este valor em cada
|
||||
chamada". Sem isso, o campo fica travado no `{}` padrão, e nenhum valor
|
||||
que o modelo "pensa" que está enviando chega de fato ao MCP.
|
||||
|
||||
**Fix**: configurar `toolParameters` assim (mistura valores fixos vindos
|
||||
do próprio workflow com `$fromAI()` só para o que o modelo precisa mesmo
|
||||
decidir):
|
||||
|
||||
```
|
||||
={{ JSON.stringify({
|
||||
clinicId: $('Normalizar entrada').item.json.clinicId,
|
||||
startAt: $fromAI('startAt', 'Data e hora de início, ISO 8601 completo', 'string'),
|
||||
endAt: $fromAI('endAt', 'Data e hora de término, ISO 8601 completo', 'string'),
|
||||
patient: {
|
||||
name: $fromAI('patientName', 'Nome completo confirmado do paciente', 'string'),
|
||||
phone: $('Normalizar entrada').item.json.telefone
|
||||
}
|
||||
}) }}
|
||||
```
|
||||
|
||||
## 10. Bug crítico — `systemMessage` do AI Agent nunca era avaliado como expressão
|
||||
|
||||
**Sintoma**: um agendamento de teste foi criado com o campo de telefone
|
||||
contendo literalmente o texto `{{ $('Normalizar entrada').item.json.telefone
|
||||
}}` em vez de um número de telefone real.
|
||||
|
||||
**Causa raiz**: o campo `parameters.options.systemMessage` do node AI Agent
|
||||
só é avaliado como expressão do n8n se o **valor inteiro do campo** começar
|
||||
com `=`. Sem esse prefixo, tudo — inclusive trechos `{{ ... }}` escritos
|
||||
"como exemplo" dentro do texto — é enviado ao modelo como **texto literal**,
|
||||
e o modelo, sem saber que aquilo deveria virar um valor real, às vezes
|
||||
copia o placeholder ao pé da letra.
|
||||
|
||||
**Fix**: sempre prefixar o campo inteiro com `=` quando ele precisar
|
||||
referenciar dados reais do workflow (`={{ $('Normalizar entrada')... }}`).
|
||||
|
||||
**Consequência que isso causou (transparência total)**: dois agendamentos
|
||||
de teste fictícios ficaram duplicados no Z-PRO (`Consulta - TESTE-N8N
|
||||
Paciente Final`, mesma data/hora) antes desse bug ser identificado — uma
|
||||
chamada que o agente reportou como "erro" na verdade teve sucesso
|
||||
silenciosamente no lado do Z-PRO. Os testes fictícios foram apagados
|
||||
manualmente depois. Isso reforça por que a disciplina de "uma execução por
|
||||
vez, conferir visualmente antes de tentar de novo" existe em todos os
|
||||
testes reais deste projeto — mesmo seguindo ela, um bug de configuração
|
||||
ainda pode gerar um resultado inesperado, e só a conferência visual pega
|
||||
isso.
|
||||
|
||||
## 11. Bug — modelo não sabe a data de hoje
|
||||
|
||||
**Sintoma**: pedido de agendamento para "amanhã" resultou em uma data no
|
||||
passado (2023) sendo enviada ao Z-PRO.
|
||||
|
||||
**Causa raiz**: modelos de linguagem não têm acesso à data/hora real do
|
||||
momento da conversa — sem essa informação no prompt, o modelo "chuta" uma
|
||||
data (geralmente relacionada à data de corte do treinamento).
|
||||
|
||||
**Fix**: incluir a data/hora atual no `systemMessage` via expressão do
|
||||
próprio n8n:
|
||||
```
|
||||
A data de hoje é {{ $now.setZone('America/Sao_Paulo').toFormat('yyyy-MM-dd (cccc)') }}
|
||||
```
|
||||
|
||||
## 12. Bug — horário criado 3h adiantado/atrasado (fuso horário)
|
||||
|
||||
**Sintoma**: cliente pediu "sexta às 10h", o agendamento foi criado em produção
|
||||
às 7h — exatamente 3h a menos (o offset de America/Sao_Paulo, UTC-3).
|
||||
|
||||
**Causa raiz**: o exemplo de formato dado ao modelo usava sufixo `Z` (UTC)
|
||||
— ex. `2026-04-20T18:00:00.000Z`. O modelo tratou o horário local que o
|
||||
cliente pediu (10h) como se já fosse UTC, sem converter, e o Z-PRO (que
|
||||
aparentemente armazena/exibe em UTC) mostrou 10h UTC como 7h local.
|
||||
|
||||
**Fix**: instruir o modelo a **nunca usar `Z`/UTC** e sempre escrever o
|
||||
mesmo número de hora que o cliente pediu, com offset `-03:00` explícito
|
||||
(ex.: cliente pediu 10h → `2026-08-14T10:00:00-03:00`). Isso evita
|
||||
qualquer aritmética de fuso horário pelo modelo — ele só copia o número
|
||||
que o cliente já disse, sem calcular nada. Ajustado tanto na descrição do
|
||||
`$fromAI('startAt', ...)`/`$fromAI('endAt', ...)` quanto numa regra
|
||||
explícita no `systemMessage`.
|
||||
|
||||
**Se isso acontecer nas próximas clínicas**: o offset `-03:00` só está
|
||||
certo para fuso de Brasília. Se uma clínica futura estiver em outro fuso,
|
||||
ajustar o offset (e o `$now.setZone(...)` do prompt) de acordo.
|
||||
|
||||
## Status final (10/08/2026)
|
||||
|
||||
Testado de ponta a ponta com sucesso, com a chave real da OpenAI
|
||||
(`gpt-4o-mini`): telefone correto, data correta, um único agendamento por
|
||||
teste, confirmado visualmente no Z-PRO. Workflow deixado **desativado**
|
||||
propositalmente — só ativar quando o Z-PRO de uma clínica real for
|
||||
configurado para apontar pra esse webhook.
|
||||
Reference in New Issue
Block a user