opf-br-mcp 0.8.0 → 1.0.0

package/README.md

@@ -31,6 +31,8 @@ acesso token-eficiente às regras do Open Finance Brasil.
 | `mqd` | Confluence público OFB | Motor de Qualidade de Dados (Especificação Técnica, Arquitetura, Documentação da API, Manual de Instalação, Endpoints Validados, FAQ, Troubleshooting) — item por seção |
 | `webhook-v1-openapi` | GitHub OpenBanking-Brasil/all-services-repo | Spec OpenAPI 1.3.0 da API de Webhook (notificações de mudança de estado: pagamentos, enrollments, pagamentos automáticos) |
 | `seguranca` | Confluence público OFB | Segurança do Open Finance Brasil (Perfil de Segurança, FAPI, DCR, CIBA, Padrão de Certificados, Assinaturas, Casos de Erro, Redirecionamento App-to-App, Glossário, Versionamento) — item por seção |
+| `requisitos-nao-funcionais` | Confluence público OFB (Manual de APIs) | Requisitos não funcionais de todas as APIs (Desempenho, Disponibilidade, Timeout, Limites de tráfego, Limites operacionais, Indisponibilidade Programada) — item por seção |
+| `limites-por-endpoint` | Confluence público OFB (Manual de APIs) | SLA (p95), timeout, TPM, TPS e limite operacional de cada endpoint de todas as famílias de API — um item por endpoint |
 | `participantes` | Diretório OFB (data.directory.openbankingbrasil.org.br) | Organizações participantes, marcas (authorisation servers) e famílias de API suportadas com versões — um item por organização |
 | `portal` | Confluence público OFB (busca ao vivo) | Busca CQL em todo o Portal do Desenvolvedor (espaço OF) — sem cache, `query` obrigatória; fallback quando os domínios específicos não cobrem o assunto |
 
@@ -39,7 +41,9 @@ acesso token-eficiente às regras do Open Finance Brasil.
 - `list_domains()` — descoberta: domínios, filtros, versão da spec de origem e estado do cache
 - `search(domain, query?, filters?, limit?, offset?)` — busca filtrada, retorno compacto
 - `get_item(domain, id)` — registro completo
-- `refresh(domain?)` — força re-extração das fontes
+- `refresh(domain?)` — força re-extração das fontes. Prefira passar `domain`:
+  sem ele o server atualiza o que couber em 45s (o timeout padrão do cliente MCP
+  é 60s) e devolve o restante em `pendentes`, para o agente retomar um a um
 
 Fluxo recomendado para o agente: `list_domains` → `search` → `get_item`.
 
@@ -67,7 +71,12 @@ bem na janela de contexto de um agente, e despejá-la desperdiça tokens. A solu
 é **revelação progressiva** — o agente nunca recebe a spec completa de uma vez,
 apenas o mínimo necessário em cada etapa do funil:
 
-1. **`list_domains`** — catálogo barato: quais domínios e filtros existem.
+1. **`list_domains`** — catálogo barato: quais domínios e filtros existem. Os
+   filtros idênticos a uma família inteira de domínios (os 9 `*-openapi`, os 12
+   de seções do Confluence) saem uma única vez em `filterSets`; cada domínio
+   traz `filterSet` e só lista inline o que é próprio dele (em `*-openapi`,
+   apenas `path`, cujo exemplo varia por API). Os filtros aceitos por um domínio
+   são a união dos dois.
 2. **`search`** — índice **pesquisável e resumido**. Cada resultado traz só os
    campos leves (`id`, `type`, `path`, `method`, `summary`/`name`, `required`,
    `in`); o nó pesado da spec (`detail`) e a lista `refs` são removidos do

package/dist/index.js

@@ -18,14 +18,24 @@ function cacheDir() {
 function cachePath(domainId) {
   return join(cacheDir(), `${domainId}.json`);
 }
+function isCacheEntry(value) {
+  const entry = value;
+  return typeof entry === "object" && entry !== null && typeof entry.extractedAt === "string" && typeof entry.packageVersion === "string" && typeof entry.data === "object" && entry.data !== null && Array.isArray(entry.data.items);
+}
 function readCache(domainId) {
   const path = cachePath(domainId);
   if (!existsSync(path)) return null;
+  let parsed;
   try {
-    return JSON.parse(readFileSync(path, "utf8"));
+    parsed = JSON.parse(readFileSync(path, "utf8"));
   } catch {
     return null;
   }
+  if (!isCacheEntry(parsed)) {
+    console.error(`[opf-br-mcp] cache de ${domainId} tem forma inesperada; ignorando (${path})`);
+    return null;
+  }
+  return parsed;
 }
 function writeCache(domainId, data, packageVersion) {
   const entry = {
@@ -46,7 +56,7 @@ function isFresh(entry, ttlHours, now = /* @__PURE__ */ new Date()) {
 }
 
 // src/core/version.ts
-var PACKAGE_VERSION = "0.8.0";
+var PACKAGE_VERSION = "1.0.0";
 
 // src/core/data.ts
 async function getDomainData(domain, force = false, ctx) {
@@ -66,15 +76,52 @@ async function getDomainData(domain, force = false, ctx) {
   }
 }
 
+// src/core/filter-sets.ts
+var FILTER_SETS = {
+  openapi: [
+    { name: "method", description: "Verbo HTTP exato (ex.: POST)" },
+    { name: "schema", description: "Substring no nome do schema (case-insensitive)" },
+    {
+      name: "response",
+      description: "Substring no nome do components.responses, a chave usada no $ref (ex.: 202Webhook)"
+    },
+    {
+      name: "parameter",
+      description: "Substring no nome do components.parameters, a chave usada no $ref (ex.: xFapiInteractionId)"
+    },
+    {
+      name: "header",
+      description: "Substring no nome do components.headers, a chave usada no $ref (ex.: X-V)"
+    }
+  ],
+  sections: [
+    { name: "page", description: "Substring no t\xEDtulo da p\xE1gina Confluence" },
+    { name: "heading", description: "Substring no t\xEDtulo da se\xE7\xE3o (heading)" },
+    { name: "contains", description: "Substring no conte\xFAdo da se\xE7\xE3o" }
+  ]
+};
+
 // src/core/http.ts
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms, signal) {
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
 }
 async function fetchWithRetry(url, opts) {
   let lastError;
   for (let attempt = 0; attempt <= opts.retryDelaysMs.length; attempt++) {
     if (opts.signal?.aborted) break;
-    if (attempt > 0) await sleep(opts.retryDelaysMs[attempt - 1]);
+    if (attempt > 0) {
+      await sleep(opts.retryDelaysMs[attempt - 1], opts.signal);
+      if (opts.signal?.aborted) break;
+    }
     const timeout = AbortSignal.timeout(3e4);
     const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
     let response;
@@ -134,8 +181,14 @@ async function fetchConfluencePage(baseUrl, pageId, retryDelaysMs, signal) {
   const apiUrl = `${baseUrl}/wiki/rest/api/content/${pageId}?expand=body.view`;
   const response = await fetchWithRetry(apiUrl, { retryDelaysMs, headers: HEADERS, signal });
   const json = await response.json();
+  const html = json?.body?.view?.value;
+  if (typeof html !== "string") {
+    throw new Error(
+      `resposta da p\xE1gina ${pageId} n\xE3o traz body.view.value; n\xE3o \xE9 conte\xFAdo Confluence expandido`
+    );
+  }
   return {
-    html: json.body?.view?.value ?? "",
+    html,
     title: json.title,
     url: `${baseUrl}/wiki${json._links?.webui ?? ""}`
   };
@@ -310,8 +363,8 @@ var pcmDomain = {
     const total = pcmConfig.pages.length;
     const pages = [];
     for (const [i, page] of pcmConfig.pages.entries()) {
+      if (i > 0) await sleep(pcmConfig.interRequestDelayMs, ctx?.signal);
       if (ctx?.signal?.aborted) throw new Error("Extra\xE7\xE3o cancelada pelo cliente");
-      if (i > 0) await sleep(pcmConfig.interRequestDelayMs);
       ctx?.onProgress?.(i, total, `Extraindo "${page.title}"`);
       const { html, url } = await fetchConfluencePage(
         pcmConfig.confluenceBaseUrl,
@@ -380,7 +433,13 @@ function refsOf(node, specName) {
   return [...out];
 }
 function parseOpenApiSpec(yamlText, specName) {
-  const spec = parse(yamlText);
+  const parsed = parse(yamlText);
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed) || !("paths" in parsed) && !("components" in parsed)) {
+    throw new Error(
+      `resposta de ${specName} n\xE3o \xE9 uma spec OpenAPI (sem "paths" nem "components"); in\xEDcio do conte\xFAdo: ${JSON.stringify(yamlText.slice(0, 80))}`
+    );
+  }
+  const spec = parsed;
   const items = [];
   for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {
     for (const method of HTTP_METHODS) {
@@ -435,22 +494,10 @@ function createOpenApiDomain(config) {
     description: config.description,
     specVersion: config.specVersion,
     ttlHours: 72,
+    filterSet: "openapi",
     filters: [
       { name: "path", description: `Substring no path do endpoint (ex.: ${config.pathExample})` },
-      { name: "method", description: "Verbo HTTP exato (ex.: POST)" },
-      { name: "schema", description: "Substring no nome do schema (case-insensitive)" },
-      {
-        name: "response",
-        description: "Substring no nome do components.responses, a chave usada no $ref (ex.: 202Webhook)"
-      },
-      {
-        name: "parameter",
-        description: "Substring no nome do components.parameters, a chave usada no $ref (ex.: xFapiInteractionId)"
-      },
-      {
-        name: "header",
-        description: "Substring no nome do components.headers, a chave usada no $ref (ex.: X-V)"
-      }
+      ...FILTER_SETS.openapi
     ],
     async extract(ctx) {
       if (ctx?.signal?.aborted) throw new Error("Extra\xE7\xE3o cancelada pelo cliente");
@@ -592,17 +639,14 @@ function createConfluenceSectionsDomain(config) {
     description: config.description,
     specVersion: config.specVersion,
     ttlHours: 72,
-    filters: [
-      { name: "page", description: "Substring no t\xEDtulo da p\xE1gina Confluence" },
-      { name: "heading", description: "Substring no t\xEDtulo da se\xE7\xE3o (heading)" },
-      { name: "contains", description: "Substring no conte\xFAdo da se\xE7\xE3o" }
-    ],
+    filterSet: "sections",
+    filters: [...FILTER_SETS.sections],
     async extract(ctx) {
       const total = config.pages.length;
       const pages = [];
       for (const [i, page] of config.pages.entries()) {
+        if (i > 0) await sleep(config.interRequestDelayMs, ctx?.signal);
         if (ctx?.signal?.aborted) throw new Error("Extra\xE7\xE3o cancelada pelo cliente");
-        if (i > 0) await sleep(config.interRequestDelayMs);
         ctx?.onProgress?.(i, total, `Extraindo "${page.title}"`);
         const { html, url } = await fetchConfluencePage(
           config.confluenceBaseUrl,
@@ -988,6 +1032,175 @@ var segurancaConfig = {
 // src/domains/seguranca/index.ts
 var segurancaDomain = createConfluenceSectionsDomain(segurancaConfig);
 
+// src/domains/requisitos-nao-funcionais/config.ts
+var requisitosNaoFuncionaisConfig = {
+  id: "requisitos-nao-funcionais",
+  title: "Requisitos n\xE3o Funcionais \u2014 SLA, disponibilidade e limites (Manual de APIs)",
+  description: "Requisitos n\xE3o funcionais que valem para todas as APIs do Open Finance Brasil, extra\xEDdos das p\xE1ginas Confluence do Manual de APIs: Desempenho (SLA do percentil 95 do tempo de resposta por faixa de frequ\xEAncia do endpoint), Disponibilidade (m\xEDnimos por 24h e por trimestre), Timeout, Limites de tr\xE1fego (TPM por origem e TPS globais), Limites operacionais (teto de consultas por m\xEAs, por endpoint e por recurso, e pagina\xE7\xE3o com pagination-key) e Indisponibilidade Programada. Os n\xFAmeros por endpoint (SLA, timeout, TPM, TPS e limite operacional de cada rota) est\xE3o em limites-por-endpoint, um registro por endpoint. Cada item aqui \xE9 uma se\xE7\xE3o (heading) da p\xE1gina \u2014 as p\xE1ginas Desempenho e Timeout n\xE3o t\xEAm headings e viram um \xFAnico item `intro` cada, ent\xE3o nelas filtre por page ou contains, n\xE3o por heading. search devolve um snippet do conte\xFAdo; use get_item para o texto completo da se\xE7\xE3o.",
+  confluenceBaseUrl: "https://openfinancebrasil.atlassian.net",
+  interRequestDelayMs: 2e3,
+  retryDelaysMs: [2e3, 4e3, 8e3, 16e3],
+  // Fora da lista: a página-mãe "Requisitos não Funcionais" (17956981), que só
+  // nomeia as quatro faixas de frequência sem defini-las (página índice), e a
+  // página "Referência" (17957025), cujas tabelas de limites por endpoint têm
+  // parser próprio no domínio limites-por-endpoint.
+  pages: [
+    { pageId: "17891396", title: "Desempenho" },
+    { pageId: "17891406", title: "Disponibilidade" },
+    { pageId: "17891413", title: "Timeout" },
+    { pageId: "17989722", title: "Limites de tr\xE1fego" },
+    { pageId: "17924220", title: "Limites operacionais" },
+    { pageId: "1808269313", title: "Indisponibilidade Programada" }
+  ]
+};
+
+// src/domains/requisitos-nao-funcionais/index.ts
+var requisitosNaoFuncionaisDomain = createConfluenceSectionsDomain(
+  requisitosNaoFuncionaisConfig
+);
+
+// src/domains/limites-por-endpoint/config.ts
+var limitesPorEndpointConfig = {
+  confluenceBaseUrl: "https://openfinancebrasil.atlassian.net",
+  retryDelaysMs: [2e3, 4e3, 8e3, 16e3],
+  // Página única: a tabela "Referência" do Manual de APIs, com uma tabela por
+  // família de API e uma linha por endpoint.
+  pageId: "17957025",
+  pageTitle: "Refer\xEAncia"
+};
+
+// src/domains/limites-por-endpoint/parser.ts
+import * as cheerio3 from "cheerio";
+var HTTP_METHODS2 = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+function cellText3($, el) {
+  const clone = $(el).clone();
+  clone.find("br").replaceWith("\n");
+  return clone.text().replace(/[​‌‍]/g, "").replace(/ /g, " ").replace(/\s+/g, " ").trim();
+}
+function headerKey(raw) {
+  const h = raw.normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase().trim();
+  if (h.startsWith("endpoint")) return "path";
+  if (h.startsWith("frequencia")) return "frequencia";
+  if (h.startsWith("sla")) return "slaMs";
+  if (h.startsWith("timeout")) return "timeoutS";
+  if (h.startsWith("limite operacional")) return "limiteOperacional";
+  if (h === "tpm") return "tpm";
+  if (h === "tps") return "tps";
+  return null;
+}
+function splitEndpoint(cell) {
+  const [first, ...rest] = cell.split(" ");
+  if (HTTP_METHODS2.has(first.toUpperCase()) && rest.length > 0) {
+    return { metodo: first.toUpperCase(), path: rest.join(" ") };
+  }
+  return { metodo: null, path: cell };
+}
+function parseEndpointLimits(html) {
+  const $ = cheerio3.load(html);
+  $("style, script").remove();
+  const limits = [];
+  for (const table of $("table").toArray()) {
+    const rows = $(table).find("tr").toArray();
+    const cellsOf = (tr) => $(tr).find("th, td").toArray().map((c) => cellText3($, c));
+    const headerIdx = rows.findIndex(
+      (tr) => cellsOf(tr).some((c) => headerKey(c) === "path")
+    );
+    if (headerIdx === -1) continue;
+    const api = rows.slice(0, headerIdx).map((tr) => cellsOf(tr).filter(Boolean).join(" ")).filter(Boolean).join(" ").trim();
+    const keys = cellsOf(rows[headerIdx]).map(headerKey);
+    for (const tr of rows.slice(headerIdx + 1)) {
+      const cells = cellsOf(tr);
+      const limit = {
+        api,
+        metodo: null,
+        path: "",
+        frequencia: null,
+        slaMs: null,
+        timeoutS: null,
+        tpm: null,
+        tps: null,
+        limiteOperacional: null
+      };
+      cells.forEach((text2, i) => {
+        const key = keys[i];
+        if (!key || !text2) return;
+        if (key === "path") {
+          const { metodo, path } = splitEndpoint(text2);
+          limit.metodo = metodo;
+          limit.path = path;
+        } else {
+          limit[key] = text2;
+        }
+      });
+      if (limit.path) limits.push(limit);
+    }
+  }
+  return limits;
+}
+
+// src/domains/limites-por-endpoint/index.ts
+function slugify3(text2) {
+  return text2.normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function buildItems3(page, limits) {
+  const items = [];
+  const seen = /* @__PURE__ */ new Map();
+  for (const limit of limits) {
+    const base = `${page.pageId}:${slugify3(`${limit.api} ${limit.metodo ?? ""} ${limit.path}`)}`;
+    const count = (seen.get(base) ?? 0) + 1;
+    seen.set(base, count);
+    items.push({ ...limit, id: count > 1 ? `${base}-${count}` : base, page });
+  }
+  return items;
+}
+var limitesPorEndpointDomain = {
+  id: "limites-por-endpoint",
+  title: "Limites por endpoint \u2014 SLA, timeout, TPM, TPS e limite operacional",
+  description: 'Tabela de refer\xEAncia do Manual de APIs do Open Finance Brasil com os limites de cada endpoint de todas as fam\xEDlias de API (Dados Abertos, Dados Cadastrais e Transacionais, Servi\xE7os de Inicia\xE7\xE3o, Portabilidade de Cr\xE9dito, Webhook, Admin e Discovery). Um item por endpoint, com a faixa de frequ\xEAncia (alta, m\xE9dia-alta, m\xE9dia ou baixa), o SLA em ms do percentil 95 do tempo de resposta, o timeout em segundos, os limites de tr\xE1fego TPM e TPS e o limite operacional de consultas por m\xEAs. Responde perguntas do tipo "qual o SLA e o timeout do GET /resources". O texto normativo por tr\xE1s desses n\xFAmeros (como o SLA \xE9 medido e apurado, disponibilidade m\xEDnima, regras de limites de tr\xE1fego e operacionais) est\xE1 em requisitos-nao-funcionais. search devolve o registro completo \u2014 em TPM algumas linhas trazem a tabela de faixas QCA\u2192TPM como texto.',
+  ttlHours: 72,
+  filters: [
+    { name: "endpoint", description: "Substring na rota (ex.: /resources)" },
+    { name: "api", description: "Substring no nome da fam\xEDlia de API (ex.: Recursos, [SV] API Pagamentos)" },
+    { name: "method", description: "Verbo HTTP exato (ex.: GET)" },
+    { name: "frequencia", description: "Substring na faixa de frequ\xEAncia (ex.: Alta, Baixa)" }
+  ],
+  async extract(ctx) {
+    ctx?.onProgress?.(0, 1, `Extraindo "${limitesPorEndpointConfig.pageTitle}"`);
+    const { html, url } = await fetchConfluencePage(
+      limitesPorEndpointConfig.confluenceBaseUrl,
+      limitesPorEndpointConfig.pageId,
+      limitesPorEndpointConfig.retryDelaysMs,
+      ctx?.signal
+    );
+    ctx?.onProgress?.(1, 1);
+    const page = {
+      pageId: limitesPorEndpointConfig.pageId,
+      title: limitesPorEndpointConfig.pageTitle,
+      url
+    };
+    return { items: buildItems3(page, parseEndpointLimits(html)) };
+  },
+  search(data, query, filters = {}) {
+    const endpoint = filters.endpoint ? normalize(filters.endpoint) : void 0;
+    const api = filters.api ? normalize(filters.api) : void 0;
+    const metodo = filters.method?.trim().toUpperCase();
+    const frequencia = filters.frequencia ? normalize(filters.frequencia) : void 0;
+    return data.items.filter((item) => {
+      if (endpoint && !normalize(item.path).includes(endpoint)) return false;
+      if (api && !normalize(item.api).includes(api)) return false;
+      if (metodo && item.metodo !== metodo) return false;
+      if (frequencia && !normalize(item.frequencia ?? "").includes(frequencia)) return false;
+      if (query?.trim() && !matchesQuery(`${item.api} ${item.metodo ?? ""} ${item.path}`, query)) {
+        return false;
+      }
+      return true;
+    });
+  },
+  getItem(data, id) {
+    return data.items.find((i) => i.id === id) ?? null;
+  }
+};
+
 // src/domains/participantes/config.ts
 var participantesConfig = {
   id: "participantes",
@@ -1000,6 +1213,11 @@ var participantesConfig = {
 // src/domains/participantes/parser.ts
 function parseParticipants(jsonText) {
   const orgs = JSON.parse(jsonText);
+  if (!Array.isArray(orgs) || orgs.length === 0) {
+    throw new Error(
+      `resposta do diret\xF3rio n\xE3o \xE9 uma lista de organiza\xE7\xF5es n\xE3o-vazia; in\xEDcio do conte\xFAdo: ${JSON.stringify(jsonText.slice(0, 80))}`
+    );
+  }
   return orgs.map((org) => {
     const servers = org.AuthorisationServers ?? [];
     const families = /* @__PURE__ */ new Set();
@@ -1157,6 +1375,8 @@ var domains = [
   mqdDomain,
   webhookDomain,
   segurancaDomain,
+  requisitosNaoFuncionaisDomain,
+  limitesPorEndpointDomain,
   participantesDomain,
   portalDomain
 ];
@@ -1181,6 +1401,7 @@ function findDomain(id) {
   return domains.find((d) => d.id === id);
 }
 var validIds = () => domains.map((d) => d.id).join(", ");
+var REFRESH_BUDGET_MS = 45e3;
 var domainIdSchema = z.enum(domains.map((d) => d.id)).describe("Id do dom\xEDnio (ver list_domains)");
 function extractContext(extra) {
   const progressToken = extra._meta?.progressToken;
@@ -1195,7 +1416,7 @@ function extractContext(extra) {
     }
   };
 }
-function createServer() {
+function createServer(refreshBudgetMs = REFRESH_BUDGET_MS) {
   const server2 = new McpServer(
     { name: "opf-br-mcp", version: PACKAGE_VERSION },
     {
@@ -1206,7 +1427,7 @@ function createServer() {
     "list_domains",
     {
       title: "Listar dom\xEDnios",
-      description: "Lista os dom\xEDnios de conhecimento do Open Finance Brasil dispon\xEDveis neste server, com os filtros aceitos por cada um, a vers\xE3o da spec de origem e o estado do cache local. Devolve tamb\xE9m a vers\xE3o deste server em `server.version`. Comece por aqui; depois use search(domain, ...) e get_item(domain, id).",
+      description: "Lista os dom\xEDnios de conhecimento do Open Finance Brasil dispon\xEDveis neste server, com os filtros aceitos por cada um, a vers\xE3o da spec de origem e o estado do cache local. Devolve tamb\xE9m a vers\xE3o deste server em `server.version`. Os filtros aceitos por um dom\xEDnio s\xE3o a uni\xE3o de `filters` (os pr\xF3prios dele, pode vir ausente) com `filterSets[<filterSet>]` (o conjunto comum \xE0 fam\xEDlia, listado uma vez no topo). Comece por aqui; depois use search(domain, ...) e get_item(domain, id).",
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -1216,11 +1437,14 @@ function createServer() {
     },
     async () => {
       const out = domains.map((d) => {
+        const shared = d.filterSet ? FILTER_SETS[d.filterSet] : void 0;
+        const own = shared ? d.filters.filter((f) => !shared.some((s) => s.name === f.name && s.description === f.description)) : d.filters;
         const base = {
           id: d.id,
           title: d.title,
           description: d.description,
-          filters: d.filters,
+          ...d.filterSet ? { filterSet: d.filterSet } : {},
+          ...own.length > 0 ? { filters: own } : {},
           ...d.specVersion ? { specVersion: d.specVersion } : {}
         };
         if (d.live) {
@@ -1233,7 +1457,14 @@ function createServer() {
           extractedAt: cached?.extractedAt ?? null
         };
       });
-      return text({ server: { name: "opf-br-mcp", version: PACKAGE_VERSION }, domains: out });
+      const usedSets = Object.fromEntries(
+        Object.entries(FILTER_SETS).filter(([name]) => domains.some((d) => d.filterSet === name))
+      );
+      return text({
+        server: { name: "opf-br-mcp", version: PACKAGE_VERSION },
+        filterSets: usedSets,
+        domains: out
+      });
     }
   );
   server2.registerTool(
@@ -1349,7 +1580,7 @@ function createServer() {
     "refresh",
     {
       title: "Re-extrair fontes",
-      description: "For\xE7a re-extra\xE7\xE3o das fontes p\xFAblicas (ignora o TTL de 72h do cache). Sem `domain`, atualiza todos. Use quando suspeitar de dados desatualizados.",
+      description: "For\xE7a re-extra\xE7\xE3o das fontes p\xFAblicas (ignora o TTL de 72h do cache). Use quando suspeitar de dados desatualizados. Prefira passar `domain`: sem ele o server atualiza o que couber em 45s e devolve o restante em `pendentes`, que voc\xEA deve refazer chamando refresh(domain) para cada id.",
       inputSchema: {
         domain: domainIdSchema.optional().describe("Id do dom\xEDnio; omita para todos")
       },
@@ -1365,7 +1596,13 @@ function createServer() {
         (d) => !d.live && (!domain || d.id === domain)
       );
       const report = {};
+      const pendentes = [];
+      const inicio = Date.now();
       for (const d of targets) {
+        if (!domain && Date.now() - inicio > refreshBudgetMs) {
+          pendentes.push(d.id);
+          continue;
+        }
         try {
           const { data } = await getDomainData(d, true, extractContext(extra));
           report[d.id] = `ok: ${data.items.length} itens`;
@@ -1373,7 +1610,13 @@ function createServer() {
           report[d.id] = `erro: ${err.message}`;
         }
       }
-      return text(report);
+      return text({
+        atualizados: report,
+        ...pendentes.length > 0 ? {
+          pendentes,
+          nota: `Parei em ${refreshBudgetMs / 1e3}s para n\xE3o estourar o timeout do cliente. Chame refresh(domain) para cada id em pendentes.`
+        } : {}
+      });
     }
   );
   return server2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opf-br-mcp",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "description": "MCP server local com as regras do Open Finance Brasil (PCM additionalInfo, specs OpenAPI de Pagamentos)",
   "type": "module",
   "license": "MIT",