GustavoandClaude Sonnet 5
e2ed887a05
5 sub-workflows novos criados e validados (0 erros). Servidor MCP Server - Klingo atualizado com as 7 tools no total (agendar, consultar_horarios + as 5 novas), agendar/consultar_horarios confirmados intactos. Nada ativado nem testado com chamada HTTP real ainda -- sem clínica Klingo real disponível. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
170 lines
8.8 KiB
Markdown
170 lines
8.8 KiB
Markdown
# Design — Tools de apoio do Klingo (especialidade, profissional, convenio, unidade, preco)
|
|
|
|
**Data:** 2026-08-11
|
|
**Status:** Aprovado pelo usuário, aguardando plano de implementação.
|
|
|
|
## Objetivo
|
|
|
|
Adicionar ao MCP Server nativo do Klingo (já existente, ver
|
|
`docs/superpowers/specs/2026-08-11-mcp-server-nativo-n8n-klingo-design.md`)
|
|
as tools de apoio necessárias para um agendamento completo e correto —
|
|
mesmo raciocínio já aplicado ao SysLife nesta sessão: o agente precisa
|
|
conseguir perguntar/confirmar especialidade, médico, convênio/plano e
|
|
valor com o paciente usando dados reais e atuais da clínica, não dados
|
|
memorizados no prompt (que ficam desatualizados assim que um médico muda,
|
|
um convênio é descredenciado, ou um preço é reajustado).
|
|
|
|
## Contexto verificado
|
|
|
|
Exploração do Swagger completo (`gti-scheduling-mcp/docs/klingo-openapi.json`,
|
|
não usado integralmente até agora — o `KlingoAdapter` original só cobria
|
|
`/paciente/identificar`, `/agenda/horarios`, `/agenda/reservar`) revelou 6
|
|
endpoints de apoio não usados:
|
|
|
|
| Endpoint | Parâmetros | Retorna | Autenticação |
|
|
| --- | --- | --- | --- |
|
|
| `GET /agenda/especialidades` | `cnes`, `id_plano`, `cbos`, `consultas` (todos opcionais) | lista de `{codigo, nome, cbos, subespecialidade[]}` | `X-APP-TOKEN` ou Bearer |
|
|
| `GET /profissionais` | `especialidade` ou `id_especialidade`, `cnes` (todos opcionais) | lista de `{id, tratamento, numero (CRM), uf, conselho, nome, subespecialidade, foto}` | `X-APP-TOKEN` ou Bearer |
|
|
| `GET /agenda/profissionais` | `id_procedimento` (obrigatório), `id_plano` (obrigatório), `cnes` | mesma lista de profissionais | `X-APP-TOKEN` ou Bearer |
|
|
| `GET /convenios` | `cnes` (opcional) | lista de `{id, nome, reg_ans, planos: [{id, nome, codigo}]}` | `X-APP-TOKEN` ou Bearer |
|
|
| `GET /convenio/{cnpj}` | `cnpj` (path, obrigatório) | mesmo formato de `/convenios` | `X-APP-TOKEN` ou Bearer |
|
|
| `GET /unidades` | `classe_unidade` (opcional) | lista de `{nome, cep, cnes, local}` | `X-APP-TOKEN` ou Bearer |
|
|
| `GET /precos` | `id_plano` (obrigatório), `id_medico`, `id_unidade`, `page` (opcionais) | lista paginada de `{id_item_tabela, valor}` | `X-APP-TOKEN` ou Bearer |
|
|
| `GET /preco` | `id_procedimento` (obrigatório), `id_plano` (obrigatório), `id_medico`, `id_unidade` (opcionais) | `{id_item_tabela, valor}` | `X-APP-TOKEN` ou Bearer |
|
|
|
|
Todos aceitam autenticação por `X-APP-TOKEN` (mesma credencial já criada,
|
|
`Klingo APP Token - clínica pendente`) **ou** Bearer de sessão — ou seja,
|
|
diferente do `agendar` (que precisa da sessão do paciente via
|
|
`/paciente/identificar`), estas consultas não dependem de identificar
|
|
ninguém primeiro.
|
|
|
|
**Existem dois endpoints de profissionais.** `/agenda/profissionais`
|
|
exige `id_procedimento`, que não temos como resolver (ver lacuna abaixo).
|
|
`/profissionais` filtra só por especialidade/unidade, sem essa
|
|
dependência — é o escolhido para a tool `profissional`.
|
|
|
|
**Existem dois endpoints de preço.** `/precos` (plural, paginado, sem
|
|
exigir `id_procedimento`) e `/preco` (singular, exige `id_procedimento` —
|
|
mesma lacuna). Optamos por expor `/preco` mesmo assim, documentando
|
|
claramente na descrição da tool que só funciona se o chamador já souber o
|
|
`idProcedimento` por algum outro meio (ex.: informado manualmente por um
|
|
atendente) — não inventamos uma forma de obtê-lo, mesmo espírito de
|
|
`consultar_horarios`/`SLOT_MAPPING_UNAVAILABLE` já registrado.
|
|
|
|
## Lacuna que continua sem solução: `specialtyId`/`procedimento`
|
|
|
|
Nenhuma das tools desta rodada resolve o código de procedimento
|
|
(`specialtyId` no domínio genérico, `procedimento`/`id_procedimento` na
|
|
API do Klingo) exigido por `agendar()` e usado opcionalmente por `preco`.
|
|
O Swagger público não documenta nenhum endpoint `GET` de listagem de
|
|
procedimentos — o único endpoint relacionado
|
|
(`PUT /agenda/procedimento`) **altera** o procedimento de uma marcação já
|
|
existente, não lista os disponíveis. Isso é a mesma classe de lacuna já
|
|
registrada para `consultarHorarios()`
|
|
(`SLOT_MAPPING_UNAVAILABLE`) — não é resolvida aqui, nem inventamos uma
|
|
solução. Fica registrado como limitação conhecida, herdada do provider,
|
|
não desta rodada de trabalho.
|
|
|
|
## Escopo
|
|
|
|
**5 tools novas**, adicionadas ao servidor **já existente**
|
|
`MCP Server - Klingo` (`3eiFEnfOTLnutP78`) — não cria um servidor novo:
|
|
|
|
- `especialidade` → `GET /agenda/especialidades`
|
|
- `profissional` → `GET /profissionais`
|
|
- `convenio` → `GET /convenios`
|
|
- `unidade` → `GET /unidades`
|
|
- `preco` → `GET /preco`
|
|
|
|
Total de workflows do Klingo passa de 3 (servidor + `agendar` +
|
|
`consultar_horarios`) para **8**.
|
|
|
|
## Arquitetura
|
|
|
|
```
|
|
[MCP Server Trigger] ──Tools──┬── agendar (já existe, 5ZEOqTOk4Xex6jUQ)
|
|
("MCP Server - Klingo") ├── consultar_horarios (já existe, 7ikOIk6mdoBwClC3)
|
|
(3eiFEnfOTLnutP78) ├── especialidade ──▶ novo sub-workflow
|
|
├── profissional ──▶ novo sub-workflow
|
|
├── convenio ──▶ novo sub-workflow
|
|
├── unidade ──▶ novo sub-workflow
|
|
└── preco ──▶ novo sub-workflow
|
|
```
|
|
|
|
## Componentes: as 5 tools de apoio (mesmo esqueleto)
|
|
|
|
```
|
|
[Execute Workflow Trigger] → [Config Klingo] → [Montar query]* → [GET <endpoint>] → [Classificar resultado]
|
|
```
|
|
|
|
(*`Montar query` só existe nas tools com parâmetro de entrada —
|
|
`especialidade`, `convenio` e `unidade` não recebem nenhum parâmetro
|
|
obrigatório nesta implementação, então pulam direto pro `GET`, mesmo
|
|
padrão usado no `especialidade`/`convenio` do SysLife.)
|
|
|
|
- **Execute Workflow Trigger**: parâmetros por tool —
|
|
- `especialidade`: nenhum.
|
|
- `profissional`: `idEspecialidade` (opcional — sem ele lista todos).
|
|
- `convenio`: nenhum.
|
|
- `unidade`: nenhum.
|
|
- `preco`: `idProcedimento` (obrigatório), `idPlano` (obrigatório),
|
|
`idMedico`/`idUnidade` (opcionais).
|
|
- **Config Klingo** (`Set`): `baseUrl` desta clínica (placeholder, mesmo
|
|
já usado no `agendar`/`consultar_horarios`).
|
|
- **Montar query** (`Code`, quando aplicável): monta o corpo/query da
|
|
requisição só com os campos documentados, sem inventar campo.
|
|
- **GET `<endpoint>`** (`HTTP Request`): `authentication:
|
|
genericCredentialType`, `genericAuthType: httpHeaderAuth`
|
|
(`X-APP-TOKEN`, credencial já existente), `neverError: true` +
|
|
`fullResponse: true`.
|
|
- **Classificar resultado** (`Code`): 2xx → devolve o corpo cru como veio
|
|
(sem reformatar — mesmo raciocínio do SysLife: sem exemplo de resposta
|
|
real capturado pra validar contra, então não inventamos nenhum
|
|
envelope). Fora de 2xx → mesma taxonomia genérica já usada no
|
|
`agendar`/`consultar_horarios` do Klingo (`AUTHENTICATION_ERROR`
|
|
401/403, `NOT_FOUND` 404, `VALIDATION_ERROR` 400/422,
|
|
`KLINGO_API_ERROR` demais).
|
|
|
|
## Fora de escopo (adiado)
|
|
|
|
- Resolver o `specialtyId`/`procedimento` de verdade (ver lacuna acima) —
|
|
seria necessário documentação adicional do Klingo não disponível
|
|
agora.
|
|
- `/agenda/profissionais` (a variante que exige `id_procedimento`) e
|
|
`/convenio/{cnpj}` (variante por CNPJ específico de `/convenios`) —
|
|
redundantes com as tools já escolhidas para este escopo.
|
|
- `/precos` (plural, paginado) — optamos só por `/preco` (singular) nesta
|
|
rodada; adicionar paginação de catálogo completo de preços fica pra
|
|
quando houver necessidade real.
|
|
- Workflow de agente cliente para o Klingo — continua adiado (mesma
|
|
decisão já tomada), sem clínica real nem canal definido.
|
|
|
|
## Testes
|
|
|
|
Mesma disciplina já usada no restante do Klingo: sem clínica real
|
|
disponível, validação estrutural apenas (`n8n_validate_workflow`),
|
|
nenhuma chamada HTTP real nesta etapa.
|
|
|
|
## Status desta etapa (11/08/2026)
|
|
|
|
Os 5 sub-workflows novos foram criados e validados estruturalmente
|
|
(`n8n_validate_workflow`, 0 erros nos cinco):
|
|
|
|
- `MCP Server - Klingo - especialidade`: `VhDRpgVxC7Bq9ZMg`
|
|
- `MCP Server - Klingo - profissional`: `27HOTfmlTH0r5UiX`
|
|
- `MCP Server - Klingo - convenio`: `v8VGt7Du0zfbc2FT`
|
|
- `MCP Server - Klingo - unidade`: `Sms5egwOtmZkeIkw`
|
|
- `MCP Server - Klingo - preco`: `tSq0p8fRxS39CSWE`
|
|
|
|
O servidor `MCP Server - Klingo` (`3eiFEnfOTLnutP78`) foi atualizado (via
|
|
`addNode`/`addConnection`, sem recriar o workflow) e agora tem **7 tools
|
|
no total**: `agendar` e `consultar_horarios` (intactos, já existentes) +
|
|
as 5 novas. Validado sem erros, `agendar`/`consultar_horarios`
|
|
confirmados intactos via inspeção da estrutura pós-atualização.
|
|
|
|
**Nada foi ativado nem testado com chamada HTTP real.** Falta o
|
|
mapeamento manual `$fromAI(...)` na UI dos nodes `profissional` e `preco`
|
|
(únicas 2 das 5 novas tools com parâmetro de entrada), e — como o resto
|
|
do Klingo — `baseUrl` real, ativação, e workflow de agente cliente quando
|
|
houver uma clínica real.
|