From a3ee6d3acd58d53b47cecd058cdab2e7f97821f9 Mon Sep 17 00:00:00 2001 From: Gustavo Date: Tue, 11 Aug 2026 00:20:14 -0300 Subject: [PATCH] Spec: tools de apoio do Klingo (especialidade, profissional, convenio, unidade, preco) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- ...2026-08-11-klingo-tools-de-apoio-design.md | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-11-klingo-tools-de-apoio-design.md diff --git a/docs/superpowers/specs/2026-08-11-klingo-tools-de-apoio-design.md b/docs/superpowers/specs/2026-08-11-klingo-tools-de-apoio-design.md new file mode 100644 index 0000000..da717e3 --- /dev/null +++ b/docs/superpowers/specs/2026-08-11-klingo-tools-de-apoio-design.md @@ -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 ] → [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 ``** (`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.