senado-br-mcp 3.12.1 → 3.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +2 -1
  2. package/dist/discovery.js +4 -0
  3. package/dist/server.js +18 -4
  4. package/dist/utils/provenance.js +15 -7
  5. package/dist/version.js +1 -1
  6. package/package.json +4 -4
package/README.md CHANGED
@@ -268,6 +268,7 @@ npm run deploy
268
268
  | `/health` | GET | Health check — returns `ok` (always public) |
269
269
  | `/status` | GET | JSON: `status`, `version`, and last-deploy metadata (`deploy.id`/`tag`/`timestamp`) — liveness + current build, no MCP handshake needed (always public) |
270
270
  | `/metrics` | GET | JSON counters: requests, tool calls, cache hits/misses, upstream calls/retries/errors, auth failures (always public) |
271
+ | `/.well-known/mcp/server-card.json` | GET | MCP server card for directory scanners (Smithery): `serverInfo`, `authentication`, tools/resources/prompts — generated from the live `full` profile by `@sbissoli/mcp-surface/card` (always public) |
271
272
 
272
273
  ## MCP Request Examples
273
274
 
@@ -752,7 +753,7 @@ Reads a bundled snapshot of the Senate's organizational tree (crawled from the i
752
753
 
753
754
  ### Group U — Deep Research (2 tools)
754
755
 
755
- The [OpenAI Deep Research contract](#chatgpt-deep-research): the only two tools without the `senado_` prefix, because the names are fixed by the contract. Registered through the same shim as the others (read-only annotations, permissive `outputSchema`, per-tool telemetry) and served on `/mcp` only — the curated ChatGPT app profile does not include them. The index (senators in office + active committees, ~300 documents) is built on first use from the same two list endpoints the `senado_listar_*` tools read, and kept for 24 h.
756
+ The [OpenAI Deep Research contract](#chatgpt-deep-research): the only two tools without the `senado_` prefix, because the names are fixed by the contract. Registered through the same shim as the others (read-only annotations, the shared output envelope — open data plus required `provenance` + `attribution` —, per-tool telemetry) and served on `/mcp` only — the curated ChatGPT app profile does not include them. The index (senators in office + active committees, ~300 documents) is built on first use from the same two list endpoints the `senado_listar_*` tools read, and kept for 24 h.
756
757
 
757
758
  | Tool | Description |
758
759
  |------|-------------|
package/dist/discovery.js CHANGED
@@ -51,6 +51,10 @@ export function robotsTxt() {
51
51
  "Disallow: /status",
52
52
  "Disallow: /metrics",
53
53
  "Disallow: /.well-known/",
54
+ // O server card é feito para scanners de diretório (Smithery) lerem. Pela
55
+ // RFC 9309 vale a regra mais longa que casa, então este Allow vence o
56
+ // Disallow acima só para ele.
57
+ "Allow: /.well-known/mcp/server-card.json",
54
58
  "",
55
59
  `Sitemap: ${SITE_URL}/sitemap.xml`,
56
60
  "",
package/dist/server.js CHANGED
@@ -4,6 +4,7 @@
4
4
  */
5
5
  import { McpServer } from "@modelcontextprotocol/server";
6
6
  import { z } from "zod";
7
+ import { ConciseBlockSchema } from "@sbissoli/mcp-provenance";
7
8
  import { registerReferenciaTools } from "./tools/referencia.js";
8
9
  import { registerSenadoresTools } from "./tools/senadores.js";
9
10
  import { registerMateriasTools } from "./tools/materias.js";
@@ -83,10 +84,23 @@ export function createServer(env, ctx, options = {}) {
83
84
  // reaches external systems (Senate APIs / e-Cidadania) whose data is an open, changing
84
85
  // set; and every tool returns a JSON object via toolResult(). Rather than repeat that
85
86
  // metadata at every call site, wrap the group modules' `server.tool(name, desc, shape, cb)`
86
- // calls and route them through registerTool() with shared annotations and a permissive
87
- // object outputSchema. toolResult() supplies the matching structuredContent. The callback
88
- // is also wrapped with instrumentTool() so every invocation is counted per tool.
89
- const outputSchema = z.object({}).passthrough();
87
+ // calls and route them through registerTool() with shared annotations and ONE shared
88
+ // outputSchema. The callback is also wrapped with instrumentTool() so every invocation
89
+ // is counted per tool.
90
+ //
91
+ // O schema de saída é o ENVELOPE COMUM (decisão do dono, 04/10/2026): aberto — a forma
92
+ // dos dados de cada tool segue sem contrato, como decidido em
93
+ // docs/_local/_checklist-melhorias-arquiteturais.pt-BR.md ("passthrough foi decisão
94
+ // deliberada") —, mas com o que TODA resposta de sucesso das 69 carrega obrigatório:
95
+ // `provenance` + `attribution`, que `resultWithProvenance`/`provenanceExtras` sempre
96
+ // montam. O bloco é o schema IMPORTADO do @sbissoli/mcp-provenance, nunca transcrito:
97
+ // a cópia à mão de um bloco selado derrubou quatro irmãos quando o contrato ganhou
98
+ // `retrieval`. `provenance` é objeto com uma fonte e LISTA quando a chamada passa
99
+ // várias (o índice do Deep Research), então os dois.
100
+ const outputSchema = z.looseObject({
101
+ provenance: z.union([ConciseBlockSchema, z.array(ConciseBlockSchema).min(1)]),
102
+ attribution: z.array(z.string()),
103
+ });
90
104
  const registerTool = server.registerTool.bind(server);
91
105
  const analytics = env.SENADO_ANALYTICS;
92
106
  // O shim é instalado sobre a instância e o resultado é NOMEADO: os módulos de
package/dist/utils/provenance.js CHANGED
@@ -1,19 +1,27 @@
1
1
  /**
2
- * Vetor A — Proveniência no payload, contrato v1.0 do portfólio.
2
+ * Vetor A — Proveniência no payload, contrato do portfólio (pacote
3
+ * `@sbissoli/mcp-provenance` 0.3.0: contrato v1.2 publicado, v1.1 emitida por padrão).
3
4
  *
4
5
  * pt-BR adapter over `@sbissoli/mcp-provenance`: o modelo canônico, os modos
5
6
  * (`concise`/`detailed`), o determinismo de serialização, o fuso e o rodapé vivem no
6
- * pacote (contrato v1.0 — ver `docs/contrato-proveniencia-v1.md` lá); este módulo mantém
7
+ * pacote (ver `docs/contrato-proveniencia-v1.md` lá); este módulo mantém
7
8
  * a API interna que as 20 tools consomem (`provenanceFor`, `resultWithProvenance`,
8
9
  * `withFieldSources`…), aceitando os nomes de entrada históricos do senado
9
10
  * (`dataset_id`, `reference_period`) e mapeando-os ao canônico (`dataset.id`,
10
11
  * `data_vintage`).
11
12
  *
12
- * O QUE O v1.0 MUDOU NA RESPOSTA (release 3.5.0 — ver README/CHANGELOG):
13
- * - `structuredContent.provenance` e o espelho em `_meta` passam a ser a projeção
14
- * **concise** do contrato: exatamente 6 chaves — `source`, `source_url`,
15
- * `data_vintage` (ex-`reference_period`), `retrieved_at`, `citation`, `license` —
16
- * com `null` explícito quando desconhecido (antes: campos opcionais omitidos).
13
+ * VERSÕES DO CONTRATO NA RESPOSTA (ver README/CHANGELOG):
14
+ * - v1.0 (release 3.5.0): `structuredContent.provenance` e o espelho em `_meta`
15
+ * passam a ser a projeção **concise** do contrato, com `null` explícito quando
16
+ * desconhecido (antes: campos opcionais omitidos).
17
+ * - v1.1 (release 3.11.0, a que este servidor EMITE — `contractVersion` default do
18
+ * pacote): o concise tem exatamente 7 chaves — `source`, `source_url`,
19
+ * `data_vintage` (ex-`reference_period`), `retrieved_at`, `citation`, `license` e
20
+ * `retrieval` (diagnóstico medido da ida à origem, ou `null`).
21
+ * - v1.2 (aceita pelos schemas desde o pacote 0.3.0, NÃO ligada aqui): acrescenta ao
22
+ * concise a chave opcional `field_sources` (sub-fontes por campo; item com
23
+ * `served_from_cache` opcional). O `outputSchema` já a declara; ligar
24
+ * `contractVersion: "1.2"` é um passo separado.
17
25
  * - O rodapé de texto segue a redação fixada do contrato: linha de fonte
18
26
  * ("Fonte: … · url · dados de … · extraído em …"), linha de licença e o aviso ao
19
27
  * leitor de que a referência completa pode ser solicitada na própria conversa.
package/dist/version.js CHANGED
@@ -1,3 +1,3 @@
1
1
  /** Single source of truth for the server version (kept in sync with package.json). */
2
- export const VERSION = "3.12.1";
2
+ export const VERSION = "3.14.0";
3
3
  export const USER_AGENT = `senado-br-mcp/${VERSION} (+https://senado.sidneybissoli.com; sbissoli76@gmail.com)`;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "senado-br-mcp",
3
- "version": "3.12.1",
3
+ "version": "3.14.0",
4
4
  "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -51,10 +51,10 @@
51
51
  },
52
52
  "dependencies": {
53
53
  "@modelcontextprotocol/server": "^2.0.0",
54
- "@sbissoli/mcp-provenance": "^0.2.0",
54
+ "@sbissoli/mcp-provenance": "^0.3.0",
55
55
  "@sbissoli/mcp-search": "^0.9.0",
56
56
  "@sbissoli/mcp-stats": "^0.3.0",
57
- "@sbissoli/mcp-upstream": "^0.3.0",
57
+ "@sbissoli/mcp-upstream": "^0.4.0",
58
58
  "zod": "^4.5.4"
59
59
  },
60
60
  "devDependencies": {
@@ -62,7 +62,7 @@
62
62
  "@modelcontextprotocol/client": "^2.0.0",
63
63
  "@modelcontextprotocol/sdk": "^1.30.0",
64
64
  "@sbissoli/mcp-evals": "^0.1.0",
65
- "@sbissoli/mcp-surface": "^0.1.1",
65
+ "@sbissoli/mcp-surface": "^0.3.0",
66
66
  "@types/node": "^26.5.1",
67
67
  "agents": "^0.24.0",
68
68
  "exceljs": "^4.4.0",