sih-br-mcp 0.15.7 → 0.17.0

package/README.md

@@ -159,7 +159,7 @@ domínio, rate limit, autenticação opcional e medição — desenho e custos e
 
 ```bash
 npm ci && npm run build
-npm test                    # vitest: decisão de rota (puro) + envelope das 12 (caso cheio e caso magro)
+npm test                    # vitest: decisão de rota (puro) + envelope e outputSchema das 12 (caso cheio e caso magro)
 npm run smoke:stdio         # superfície das ferramentas × baselines/surface-stdio.json
 npm run smoke:http          # mesma superfície e chamadas pelo transporte HTTP (dist/http.js)
 npm run golden:tools        # 12 ferramentas byte a byte × baselines/golden-tools.json (fixture 2023/RR)
@@ -178,10 +178,13 @@ O CI (`.github/workflows/ci.yml`) roda tudo isso em Node 22 e 24. A fixture
 A divisão de trabalho entre as duas famílias: os scripts em `scripts/*.mjs`
 pinam VALORES (mudou um número, o baseline acusa); a suíte de `tests/*.test.ts`
 afirma INVARIANTES (qual cubo responde a pergunta; toda resposta sai com
-proveniência e com o texto igual à estrutura), e por isso republicar um cubo
-não a move. Cada ferramenta tem ali um caso CHEIO e um caso MAGRO — a resposta
-com os campos opcionais ausentes, que o golden, sempre com fixture cheia, não
-alcança.
+proveniência, com o texto igual à estrutura e obedecendo ao `outputSchema` que
+o `tools/list` publica — validado com o mesmo validador do SDK), e por isso
+republicar um cubo não a move. Cada ferramenta tem ali um caso CHEIO e um caso
+MAGRO — a resposta com os campos opcionais ausentes, que o golden, sempre com
+fixture cheia, não alcança — e o caminho de erro-mole ("ano sem dado") também
+é validado. Os esquemas de saída estão em `src/output-schemas.ts`, escritos à
+mão a partir das formas medidas, como os de entrada.
 
 ## Documentação
 

package/dist/output-schemas.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `outputSchema` das doze ferramentas — JSON Schema escrito à mão, servido
+ * verbatim (como o `inputSchema` em src/tools.ts; molde do bcb-br-mcp).
+ *
+ * De onde vêm as formas. NÃO foram inventadas a partir do código: foram MEDIDAS
+ * em 16/09/2026 contra o servidor de verdade (`createServer`, transporte em
+ * memória, fixture 2023/RR) — os 36 casos do golden, os 27 casos cheio/magro
+ * de tests/output-contract.test.ts e mais 38 variantes de `group_by`, filtro,
+ * universo e ano ausente, 101 chamadas ao todo — e depois conferidas contra
+ * cada handler, porque a fixture não alcança tudo (raça nula em 1998–2007,
+ * município nulo em 1992–1997, o `catch` de cada handler). A medição de 14/09
+ * (decisão 37 do CONTEXT.md) já dizia o essencial: a forma NÃO varia com
+ * `group_by`; varia com o caminho de erro-mole.
+ *
+ * O que "honesto" quer dizer aqui, e por que importa: cliente que valida (o
+ * MCP Inspector valida) rejeita a resposta INTEIRA quando o `structuredContent`
+ * não obedece ao esquema anunciado. Um esquema que promete mais do que o
+ * servidor cumpre — campo obrigatório que a fonte omite, `number` onde vem
+ * `null` — transforma resposta certa em erro no cliente. Por isso:
+ *
+ * - campo que algum caminho omite é opcional (fora do `required`);
+ * - medida que vem NULA em recorte vazio (`get_hospitalizations` sem linha)
+ *   é `["number", "null"]`;
+ * - coluna de agrupamento que a FONTE anula (raça antes de 2008, município
+ *   antes de 1994, grupo CSAP das internações não sensíveis, `exclusion`) é
+ *   anulável, mesmo que a fixture de 2023 nunca a mostre nula;
+ * - o CAMINHO DE ERRO-MOLE — resposta de sucesso (não `isError`) que carrega
+ *   `error` em vez dos dados: "ano sem dado" do funil (decisão 38), grupo
+ *   CSAP inexistente, o `catch` de cada handler, cobertura populacional — é
+ *   um ramo do `anyOf`, ao lado do caminho feliz. Ramo do caminho feliz exige
+ *   os campos de dados; ramo de erro-mole exige `error`. Resposta que não
+ *   cumpre nenhum dos dois reprova — é isso que dá dente ao gate
+ *   (tests/output-contract.test.ts).
+ *
+ * Todos os `properties` ficam declarados no topo, com descrição; o `anyOf` só
+ * carrega `required`. Cliente que renderiza `properties` vê tudo; validador
+ * aplica a exclusividade.
+ *
+ * Erros de verdade (`isError: true`, sem `structuredContent`) ficam fora: o
+ * SDK v2 só exige `structuredContent` em sucesso.
+ */
+import type { JsonSchemaType } from "@modelcontextprotocol/server";
+type Schema = Record<string, unknown>;
+/**
+ * Projeção `concise` do bloco de proveniência (contrato @sbissoli/mcp-provenance
+ * v1.0, `ConciseBlock` em render.ts): a forma que `withProvenance` põe em
+ * `structuredContent`. Transcrito do PROVENANCE_BLOCK_SCHEMA do bcb-br-mcp
+ * (src/provenance.ts) — o pacote comum publica o esquema canônico em zod, não
+ * a projeção concise em JSON Schema, então cada servidor a escreve.
+ */
+export declare const PROVENANCE_BLOCK_SCHEMA: Schema;
+/**
+ * O `outputSchema` da ferramenta, pronto para o `tools/list`. Recebe o
+ * `inputSchema` porque `filters_applied` ecoa os argumentos e é descrito pelas
+ * mesmas propriedades. Lança para ferramenta desconhecida: ferramenta nova
+ * entra em src/tools.ts e reprova aqui até ganhar o seu esquema.
+ */
+export declare function outputSchemaFor(name: string, inputSchema: JsonSchemaType): JsonSchemaType;
+export {};
+//# sourceMappingURL=output-schemas.d.ts.map

package/dist/output-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-schemas.d.ts","sourceRoot":"","sources":["../src/output-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAwCtC;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAWrC,CAAC;AAwrBF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,GAAG,cAAc,CAIzF"}