senado-br-mcp 3.5.1 → 3.6.0

package/dist/cli.js

@@ -14,7 +14,8 @@
  * This file is NOT imported by the Worker entrypoint (`src/index.ts`) and never
  * touches `agents/mcp`. It only depends on `createServer` + the stdio transport.
  */
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { unknownCursorError } from "./pagination.js";
 import { createServer } from "./server.js";
 // No Cloudflare bindings in Node: createServer defaults the base URLs when these
 // are empty, and every binding-dependent path is guarded. CACHE_KV is declared on
@@ -26,8 +27,30 @@ const env = {
 };
 async function main() {
     // No `ctx` → e-Cidadania detail write-through is a no-op (fire-and-forget skipped).
-    const server = createServer(env);
-    await server.connect(new StdioServerTransport());
+    // `serveStdio`, e não `server.connect(transport)` direto: ele serve a
+    // abertura MODERNA e a de 2025 no mesmo processo. Conectar o transporte na
+    // mão atende só o ciclo legado, e o mcpscore conta a prontidão para a spec
+    // 2026-07-28 dentro da nota principal — medido em 30/08/2026: 127/144 com
+    // `connect` direto contra 146/148 nos irmãos que usam `serveStdio`, sem UMA
+    // falha de diferença. Eram 17 pontos de regras que sequer eram avaliadas.
+    //
+    // O transporte é construído aqui, e não deixado a cargo do `serveStdio`, para
+    // que o guarda de cursor possa se pendurar nele. Cursor de paginação inválido
+    // -> -32602, o MESMO guarda que o Worker aplica no POST (src/pagination.ts).
+    // Substitui `onmessage` em vez de somar um ouvinte: só quem está NO lugar do
+    // `onmessage` pode interromper a entrega ao SDK, e é a interrupção que produz
+    // a recusa.
+    const transport = new StdioServerTransport();
+    serveStdio(() => createServer(env), { transport });
+    const entregaAoServidor = transport.onmessage;
+    transport.onmessage = (message) => {
+        const recusa = unknownCursorError(message);
+        if (recusa) {
+            void transport.send(recusa);
+            return;
+        }
+        entregaAoServidor?.(message);
+    };
     // Logs go to stderr (see src/utils/logger.ts); stdout carries only JSON-RPC.
     console.error(JSON.stringify({ level: "info", msg: "stdio_ready", ts: new Date().toISOString() }));
 }

package/dist/discover.js

@@ -0,0 +1,79 @@
+/**
+ * `server/discover` anuncia TODAS as revisões que o servidor atende, não só as
+ * modernas.
+ *
+ * O ACHADO. O `mcpscore` reprovava `protocol_version_supported_versions_include_negotiated`:
+ * o servidor negocia 2025-11-25 pelo handshake `initialize` — é a revisão que o
+ * próprio auditor negocia, e a que a maioria dos clientes fala hoje — mas o
+ * `server/discover` anunciava só `["2026-07-28"]`. A mensagem do auditor é
+ * explícita sobre as duas saídas: "add it to supportedVersions, or disable the
+ * legacy lifecycle". Desligar o ciclo legado trocaria 1 ponto por uma regressão
+ * de compatibilidade com quase todos os clientes; sobra anunciar a verdade.
+ *
+ * POR QUE O SDK NÃO FAZ ISSO. O `_ondiscover()` do
+ * `@modelcontextprotocol/server` 2.0.0 devolve
+ * `modernProtocolVersions(this._supportedProtocolVersions)`, um filtro que
+ * descarta por desenho toda revisão pré-2026 ("2025-era versions are negotiated
+ * via `initialize`"). Não há opção que o desligue. É uma leitura mais estrita
+ * que a do auditor, que se apoia em Basic §Versioning — onde o exemplo de
+ * `UnsupportedProtocolVersionError` lista revisões legadas em `supported`.
+ *
+ * POR QUE PATCH DE MÉTODO, E NÃO TROCA DE HANDLER. Registrar o nosso próprio
+ * handler de `server/discover` não gruda: a entrada HTTP do SDK chama
+ * `installModernOnlyHandlers` A CADA REQUEST, depois da nossa factory, e ela
+ * reinstala `() => server._ondiscover()` por cima. Como o que ela instala é uma
+ * closure que chama o MÉTODO, trocar o método vale para os dois caminhos — o
+ * handler do construtor e o reinstalado — e sobrevive à reinstalação. Trocar o
+ * handler valeria só no stdio, justamente onde o achado não aparece.
+ *
+ * A GUARDA. Isto mexe em `_ondiscover`, que é interno do SDK. O risco de um
+ * patch assim é virar silêncio: o SDK renomeia o método, o patch não aplica
+ * nada e ninguém percebe. Por isso `announceServedVersions` FALHA ALTO se a
+ * forma esperada não estiver lá — o servidor nem constrói — em vez de seguir
+ * com o anúncio antigo. `tests/discover.test.ts` prende o comportamento, e a
+ * catraca do mcpscore no CI pega a regressão pelo lado de fora.
+ */
+/**
+ * Ordena revisões datadas da mais nova para a mais antiga. São strings
+ * `AAAA-MM-DD`, então a ordem lexicográfica É a cronológica.
+ */
+export function maisNovaPrimeiro(versoes) {
+    return [...new Set(versoes)].sort().reverse();
+}
+/**
+ * Troca o `_ondiscover` da instância por um que anuncia todas as revisões
+ * atendidas. Só a lista muda: capacidades e instruções continuam vindo do
+ * cálculo do próprio SDK.
+ */
+export function announceServedVersions(server) {
+    const low = server.server;
+    if (typeof low._ondiscover !== "function") {
+        throw new Error("SDK mudou: Server._ondiscover sumiu — o anúncio de versões em src/discover.ts " +
+            "deixaria de aplicar em silêncio. Reveja o módulo contra a versão nova do " +
+            "@modelcontextprotocol/server antes de seguir.");
+    }
+    if (!Array.isArray(low._supportedProtocolVersions) ||
+        low._supportedProtocolVersions.some((v) => typeof v !== "string")) {
+        throw new Error("SDK mudou: Server._supportedProtocolVersions não é mais uma lista de strings — " +
+            "src/discover.ts não tem de onde tirar as revisões atendidas.");
+    }
+    const original = low._ondiscover.bind(low);
+    low._ondiscover = () => {
+        const base = original();
+        // LER NA HORA DA CHAMADA, não aqui na aplicação do patch. O
+        // `installDiscoverHandler` do SDK ACRESCENTA as revisões modernas a
+        // `_supportedProtocolVersions` por REATRIBUIÇÃO, já com o servidor
+        // construído: uma referência capturada agora ficaria presa ao array
+        // anterior. Foi o que aconteceu na primeira versão deste módulo — o anúncio
+        // saiu com as cinco revisões legadas e SEM a 2026-07-28, e a regra do
+        // auditor passou assim mesmo, porque ela só confere se a negociada está na
+        // lista. Trocar uma omissão por outra não é corrigir.
+        const agora = low._supportedProtocolVersions;
+        if (!Array.isArray(agora) || agora.some((v) => typeof v !== "string"))
+            return base;
+        // A lista vem do próprio SDK, nunca de literais nossas: anunciar uma
+        // revisão que o servidor não atende seria a mentira simétrica da que este
+        // módulo corrige.
+        return { ...base, supportedVersions: maisNovaPrimeiro(agora) };
+    };
+}

package/dist/metrics.js

@@ -3,6 +3,8 @@ const counters = {
     requests: 0,
     errors: 0,
     authFailures: 0,
+    /** Lista pedida com cursor de paginação que este servidor nunca emitiu. */
+    invalidCursor: 0,
     cacheL0Hits: 0,
     cacheL1Hits: 0,
     cacheMisses: 0,

package/dist/pagination.js

@@ -0,0 +1,71 @@
+/**
+ * Cursor de paginação inválido — a recusa que o SDK não faz.
+ *
+ * O PROBLEMA. Toda lista deste servidor cabe numa página só, então
+ * nenhuma resposta traz `nextCursor` e
+ * nenhum cursor emitido por este servidor existe. Os quatro handlers de lista do
+ * `@modelcontextprotocol/server` 2.x simplesmente IGNORAM `params.cursor` e
+ * devolvem a lista inteira — inclusive para um cursor que o servidor nunca
+ * emitiu. A spec (§Pagination, Error Handling, em toda revisão datada) diz que
+ * cursor inválido DEVE virar `-32602`, e o `mcpscore` reprovava os quatro
+ * endpoints. Medido aqui em 30/08/2026, logo depois da migração para o SDK v2:
+ * 161/173 local, e estes quatro eram 4 das 6 falhas reais.
+ *
+ * POR QUE AQUI, E NÃO NO HANDLER DO SDK. Sobrescrever `tools/list` exigiria
+ * reimplementar a listagem a partir do registro privado do McpServer
+ * (`_registeredTools`, com a conversão de schema junto) — trocar um defeito
+ * pequeno por uma cópia do SDK que envelhece sozinha. A recusa é uma decisão
+ * sobre a MENSAGEM, não sobre o conteúdo da lista, então mora na borda por onde
+ * a mensagem entra: o POST do Worker (src/index.ts) e o transporte stdio
+ * (src/cli.ts). O predicado é o mesmo nos dois — este módulo.
+ *
+ * ENQUANTO NÃO HOUVER SEGUNDA PÁGINA. Se algum dia uma lista passar a paginar de
+ * verdade, este módulo deixa de valer: a recusa passa a ser "cursor que não
+ * decodifica", e quem emite o cursor é quem sabe reconhecê-lo. O teste
+ * `pagination.test.ts` prende a premissa (nenhuma lista emite `nextCursor`) para
+ * que a mudança não passe em silêncio.
+ *
+ * Transplantado de bcb-br-mcp/src/pagination.ts, por sua vez transplantado do
+ * ilo-mcp-server — a implementação de referência do portfólio.
+ */
+/** Código JSON-RPC de parâmetro inválido (spec §Pagination, Error Handling). */
+export const INVALID_PARAMS = -32602;
+/** Os quatro métodos de lista paginável do MCP. */
+export const PAGINATED_LIST_METHODS = [
+    "tools/list",
+    "resources/list",
+    "resources/templates/list",
+    "prompts/list",
+];
+/**
+ * Devolve a recusa `-32602` quando a mensagem é uma requisição de lista que
+ * carrega `cursor`; `undefined` em qualquer outro caso (inclusive notificação,
+ * lote e mensagem malformada — nenhum deles é assunto deste guarda, e o SDK
+ * responde por eles).
+ */
+export function unknownCursorError(message) {
+    if (typeof message !== "object" || message === null || Array.isArray(message))
+        return undefined;
+    const { jsonrpc, id, method, params } = message;
+    if (jsonrpc !== "2.0")
+        return undefined;
+    // Sem id é notificação: não existe resposta para devolver.
+    if (typeof id !== "string" && typeof id !== "number")
+        return undefined;
+    if (typeof method !== "string")
+        return undefined;
+    if (!PAGINATED_LIST_METHODS.includes(method))
+        return undefined;
+    if (params === null || typeof params !== "object" || params.cursor === undefined)
+        return undefined;
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: INVALID_PARAMS,
+            message: `Invalid params: unknown pagination cursor for ${method}. ` +
+                "This server returns every list in a single page and never issues a nextCursor, " +
+                "so no cursor value is valid — retry without one.",
+        },
+    };
+}

package/dist/server.js

@@ -2,7 +2,7 @@
  * McpServer factory — creates a new instance per request (required by SDK 1.26.0+).
  * Registers all tools from each group module.
  */
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { registerReferenciaTools } from "./tools/referencia.js";
 import { registerSenadoresTools } from "./tools/senadores.js";
@@ -31,12 +31,19 @@ import { VERSION } from "./version.js";
 import { instructionsForProfile, isToolEnabledForProfile, minimizeToolResultForProfile, toolMetaForProfile, } from "./app-surface.js";
 import { registerOpenAiAppWidget } from "./openai-app-widget.js";
 import { titleForTool } from "./tool-titles.js";
+import { announceServedVersions } from "./discover.js";
 export function createServer(env, ctx, options = {}) {
     const toolProfile = options.toolProfile ?? "full";
     const server = new McpServer({
         name: "senado-br-mcp",
         version: VERSION,
-        websiteUrl: "https://github.com/SidneyBissoli/senado-br-mcp-cloudflare",
+        // `title` no serverInfo do handshake: existia no `server.json` — o que os
+        // diretórios leem — mas não no que o cliente recebe ao conectar, e o
+        // mcpscore mede o handshake (`server_title_present`).
+        title: "Dados Abertos Senado BR MCP",
+        // O DOMÍNIO PRÓPRIO, não o repositório: é o que o `server.json` declara e
+        // é quem serve o ícone logo abaixo. O par estava desalinhado.
+        websiteUrl: "https://senado.sidneybissoli.com",
         icons: [
             {
                 src: "https://senado.sidneybissoli.com/icon.jpg",
@@ -55,7 +62,12 @@ export function createServer(env, ctx, options = {}) {
     const outputSchema = z.object({}).passthrough();
     const registerTool = server.registerTool.bind(server);
     const analytics = env.SENADO_ANALYTICS;
-    server.tool = (name, description, shape, cb) => {
+    // O shim é instalado sobre a instância e o resultado é NOMEADO: os módulos de
+    // grupo recebem `host`, não `server`. Até a migração v2 eles declaravam
+    // `McpServer` e chamavam `.tool()` — método que a v1 expunha e a v2 não —, uma
+    // imprecisão que o tipo antigo tolerava. Ver src/tool-host.ts.
+    const host = server;
+    host.tool = (name, description, shape, cb) => {
         if (!isToolEnabledForProfile(name, toolProfile)) {
             return undefined;
         }
@@ -78,45 +90,45 @@ export function createServer(env, ctx, options = {}) {
     const baseUrl = env.SENADO_BASE_URL || "https://legis.senado.leg.br/dadosabertos";
     const admBaseUrl = env.SENADO_ADM_BASE_URL || "https://adm.senado.gov.br/adm-dadosabertos";
     // Group H — Reference/metadata (1 tool — enum `tabela`)
-    registerReferenciaTools(server, baseUrl);
+    registerReferenciaTools(host, baseUrl);
     // Group A — Senators (5 tools)
-    registerSenadoresTools(server, baseUrl);
+    registerSenadoresTools(host, baseUrl);
     // Group B — Bills (2 tools; votos_materia is registered in Group D)
-    registerMateriasTools(server, baseUrl);
+    registerMateriasTools(host, baseUrl);
     // Group D — Votes (3 tools)
-    registerVotacoesTools(server, baseUrl);
+    registerVotacoesTools(host, baseUrl);
     // Group E — Committees (7 tools)
-    registerComissoesTools(server, baseUrl);
+    registerComissoesTools(host, baseUrl);
     // Group F — Plenary (7 tools)
-    registerPlenarioTools(server, baseUrl);
+    registerPlenarioTools(host, baseUrl);
     // Group C — Processes (5 tools)
-    registerProcessosTools(server, baseUrl);
+    registerProcessosTools(host, baseUrl);
     // Group G — e-Cidadania (9 tools) — reads from D1 (env) and write-through detail (ctx)
-    registerECidadaniaTools(server, baseUrl, env, ctx);
+    registerECidadaniaTools(host, baseUrl, env, ctx);
     // Group I — Speeches (3 tools)
-    registerDiscursosTools(server, baseUrl);
+    registerDiscursosTools(host, baseUrl);
     // Group J — Blocs & Leadership (4 tools)
-    registerComposicaoTools(server, baseUrl);
+    registerComposicaoTools(host, baseUrl);
     // Group K — Budget (1 tool — enum `tipo`)
-    registerOrcamentoTools(server, baseUrl);
+    registerOrcamentoTools(host, baseUrl);
     // Group L — Federal Law (2 tools)
-    registerLegislacaoTools(server, baseUrl);
+    registerLegislacaoTools(host, baseUrl);
     // Group M — Committee Voting (1 tool — enum `por`)
-    registerVotacaoComissaoTools(server, baseUrl);
+    registerVotacaoComissaoTools(host, baseUrl);
     // Group N — Taquigrafia (2 tools)
-    registerTaquigrafiaTools(server, baseUrl);
+    registerTaquigrafiaTools(host, baseUrl);
     // Group O — Senadores/Administrativo (2 tools)
-    registerSenadoresAdminTools(server, admBaseUrl);
+    registerSenadoresAdminTools(host, admBaseUrl);
     // Group P — Servidores / Gestão de Pessoas (4 tools)
-    registerServidoresTools(server, admBaseUrl);
+    registerServidoresTools(host, admBaseUrl);
     // Group Q — Contratações (6 tools)
-    registerContratacoesTools(server, admBaseUrl);
+    registerContratacoesTools(host, admBaseUrl);
     // Group R — Suprimento de Fundos (1 tool)
-    registerSupridosTools(server, admBaseUrl);
+    registerSupridosTools(host, admBaseUrl);
     // Group S — Orçamento do Senado (1 tool)
-    registerOrcamentoSenadoTools(server);
+    registerOrcamentoSenadoTools(host);
     // Group T — Estrutura Organizacional (1 tool — árvore de órgãos, snapshot bundlado)
-    registerEstruturaTools(server);
+    registerEstruturaTools(host);
     // MCP prompts (4 reusable pt-BR workflow templates) and resources (5 static
     // context docs/tables) — advertised as the `prompts` and `resources` capabilities.
     registerPrompts(server);
@@ -124,5 +136,8 @@ export function createServer(env, ctx, options = {}) {
     if (toolProfile === "openai-app") {
         registerOpenAiAppWidget(server);
     }
+    // `server/discover` anuncia TODAS as revisões atendidas, não só as modernas
+    // que o SDK filtra — ver src/discover.ts.
+    announceServedVersions(server);
     return server;
 }

package/dist/tool-host.js

@@ -0,0 +1,19 @@
+/**
+ * O tipo que os 20 módulos de tools realmente falam.
+ *
+ * POR QUE ESTE ARQUIVO EXISTE. Até a migração para o SDK v2 os módulos
+ * declaravam receber `McpServer` e chamavam `server.tool(...)` — um método que
+ * a v1 expunha e a v2 NÃO expõe. O que eles sempre chamaram, na prática, foi o
+ * SHIM instalado por `createServer` (src/server.ts), que aplica título,
+ * anotações read-only, `outputSchema` permissivo, instrumentação e o filtro de
+ * perfil antes de delegar ao `registerTool` do SDK.
+ *
+ * Declarar `McpServer` era, portanto, uma imprecisão que a v1 tolerava: o tipo
+ * dizia "SDK" e o objeto entregava "SDK mais o shim". A v2 deixou de tolerar, e
+ * a correção não é um cast — é nomear o que os módulos consomem de fato.
+ *
+ * Efeito colateral que vale por si: com a assinatura do callback declarada
+ * aqui, o `params` de cada tool deixa de ser `any` implícito. Eram 65
+ * ocorrências, todas silenciosas sob a v1.
+ */
+export {};

package/dist/version.js

@@ -1,3 +1,3 @@
 /** Single source of truth for the server version (kept in sync with package.json). */
-export const VERSION = "3.5.1";
+export const VERSION = "3.6.0";
 export const USER_AGENT = `senado-br-mcp/${VERSION} (+https://senado.sidneybissoli.com; sbissoli76@gmail.com)`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "senado-br-mcp",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "description": "MCP server for Brazilian Senate open data — runs hosted on Cloudflare Workers or locally via npx (stdio)",
   "license": "MIT",
   "type": "module",
@@ -47,21 +47,23 @@
     "release:zenodo": "tsx scripts/build-dataset/zenodo-publish.ts"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/server": "^2.0.0",
     "@sbissoli/mcp-provenance": "^0.1.0",
-    "@sbissoli/mcp-stats": "^0.1.0",
-    "zod": "^4.0.0"
+    "@sbissoli/mcp-stats": "^0.2.0",
+    "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20250214.0",
+    "@cloudflare/workers-types": "^5.20260830.1",
+    "@modelcontextprotocol/client": "^2.0.0",
     "@sbissoli/mcp-evals": "^0.1.0",
-    "@types/node": "^25.9.3",
-    "agents": "^0.5.0",
+    "@types/node": "^26.4.0",
+    "agents": "^0.22.0",
     "exceljs": "^4.4.0",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.0",
-    "vitest": "^4.1.9",
-    "wrangler": "^4.105.0"
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
+    "wrangler": "^4.127.1"
   },
   "overrides": {
     "fast-uri": "^4.0.0",