Spec: tools de apoio do Klingo (especialidade, profissional, convenio, unidade, preco)
Adiciona 5 tools ao MCP Server nativo do Klingo já existente (mesmo servidor, sem criar um novo), a partir de endpoints do Swagger não usados até agora pelo KlingoAdapter original. Todas usam a credencial X-APP-TOKEN já existente (sem precisar de sessão de paciente). Registra explicitamente a lacuna que continua sem solução: não há endpoint GET de listagem de procedimentos no Klingo, então specialtyId/procedimento continua sem uma tool que resolva (mesma classe de limitação já registrada para SLOT_MAPPING_UNAVAILABLE). 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
012f762555
commit
a3ee6d3acd
@@ -0,0 +1,146 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user