# 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.