opf-br-mcp 0.6.1 → 0.8.0

package/README.md

@@ -21,6 +21,10 @@ acesso token-eficiente às regras do Open Finance Brasil.
 | `payments-common-rules` | Confluence público OFB (Serviços - SV) | Conteúdo comum aos produtos de Iniciação de Pagamentos (atores, Idempotência, Como Assinar o Payload, Convenções de data/fuso, Polling) — item por seção |
 | `payments-implementation-guides` | Confluence público OFB (Serviços - SV) | Guias de Implementação (Pix Automático, Agendamento Recorrente, Transferências Inteligentes, Liquidação de QR Codes) — item por seção |
 | `consents-v3-openapi` | GitHub Pages openbanking-brasil.github.io | Spec OpenAPI 3.3.1 da API de Consentimentos (Dados Cadastrais e Transacionais) |
+| `resources-v3-openapi` | GitHub Pages openbanking-brasil.github.io | Spec OpenAPI 3.1.0 da API de Recursos (`GET /resources`: status dos recursos compartilhados) |
+| `resources-v3-business-rules` | Confluence público OFB (Dados - DC) | Regras de negócio da API de Recursos 3.1.0 (Informações Gerais, Orientações) — item por seção |
+| `accounts-v2-openapi` | GitHub Pages openbanking-brasil.github.io | Spec OpenAPI 2.4.2 da API de Contas (listagem, saldos, transações, limites de cheque especial) |
+| `accounts-v2-business-rules` | Confluence público OFB (Dados - DC) | Regras de negócio da API de Contas 2.4.2 (Informações Gerais, Orientações — contraparte/IN BCB nº 371) — item por seção |
 | `pcm-openapi` | GitHub OpenBanking-Brasil/pcm-specs | Spec OpenAPI da PCM (reportes, hybrid-flow, opendata, consents/stock, credit-portabilities, payments/status) |
 | `pcm-business-rules` | Confluence público OFB | Regras de negócio da PCM (Reporte, Processamento, Divergências, Especificação Técnica, Manual de Integração) — item por seção |
 | `jornada-otimizada` | Confluence público OFB | Regras da Jornada Otimizada (Orientações Gerais, Transferências Inteligentes, Jornada sem Redirecionamento) — item por seção |
@@ -32,13 +36,25 @@ acesso token-eficiente às regras do Open Finance Brasil.
 
 ## Tools
 
-- `list_domains()` — descoberta: domínios, filtros e estado do cache
+- `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
 
 Fluxo recomendado para o agente: `list_domains` → `search` → `get_item`.
 
+### Qual versão estou usando?
+
+`list_domains` devolve `server: { name, version }` junto do catálogo, então o
+agente descobre a versão do server na mesma chamada com que descobre os domínios.
+Cada domínio que embrulha uma spec traz também o seu `specVersion`.
+
+Pela linha de comando:
+
+```bash
+npx opf-br-mcp --version
+```
+
 Domínios marcados como `live` (ex.: `portal`) consultam a fonte a cada chamada:
 não têm cache nem `refresh`, e `search` exige `query`. Quando um `search` em
 domínio comum retorna 0 resultados, a resposta inclui um `hint` sugerindo o
@@ -52,20 +68,28 @@ bem na janela de contexto de um agente, e despejá-la desperdiça tokens. A solu
 apenas o mínimo necessário em cada etapa do funil:
 
 1. **`list_domains`** — catálogo barato: quais domínios e filtros existem.
-2. **`search`** — índice **pesquisável e resumido**. Cada resultado traz só
-   `id`, `path`, `method`, `summary`/`name` e `required`; o nó pesado da spec
-   (`detail`) é removido do resumo, e o retorno ainda é compactado (omite `null`
-   e arrays vazios).
+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
+   resumo, e o retorno ainda é compactado (omite `null` e arrays vazios).
 3. **`get_item`** — só aqui o nó integral da spec é entregue, e apenas para o
    `id` que o agente escolheu.
 
 Como o Swagger/OpenAPI vira dados pesquisáveis: o parser "achata" a spec em itens
 com `id` estável — um por endpoint (`type: operation`, ex.
-`payments-v4:POST /pix/payments`) e um por schema (`type: schema`, ex.
-`payments-v4:schema:PixPayment`). O JSON completo de cada nó fica retido em
-`detail` até um `get_item` explícito. Os `id`s não são adivinháveis: sempre vêm
-de um `search`. Assim o agente localiza o endpoint/schema certo pagando poucos
-tokens e só "paga" o payload integral quando pede um item nomeado.
+`payments-v4:POST /pix/payments`) e um por component reutilizável: `type: schema`
+(`payments-v4:schema:PixPayment`), `type: response` (`webhook:response:202Webhook`),
+`type: parameter` (`webhook:parameter:xWebhookInteractionId`) e `type: header`
+(`payments:header:X-V`). O JSON completo de
+cada nó fica retido em `detail` até um `get_item` explícito. Os `id`s não são
+adivinháveis: sempre vêm de um `search`. Assim o agente localiza o endpoint/schema
+certo pagando poucos tokens e só "paga" o payload integral quando pede um item nomeado.
+
+Os `$ref` não são expandidos em linha (medimos 3–7x mais tokens por operação):
+em vez disso, o `get_item` de um item traz `refs` com os `id`s dos components que
+ele referencia — todos resolvíveis por `get_item`. Resolver
+`responses.202.$ref: '#/components/responses/202Webhook'` é uma chamada a mais,
+não uma ida ao YAML da fonte.
 
 Dados: extraídos das fontes públicas na primeira consulta (lazy), cache em
 `~/.cache/opf-br-mcp/` com TTL de 72h. Sem rede, serve cache expirado com aviso.

package/dist/index.js

@@ -46,7 +46,7 @@ function isFresh(entry, ttlHours, now = /* @__PURE__ */ new Date()) {
 }
 
 // src/core/version.ts
-var PACKAGE_VERSION = "0.6.1";
+var PACKAGE_VERSION = "0.8.0";
 
 // src/core/data.ts
 async function getDomainData(domain, force = false, ctx) {
@@ -352,6 +352,33 @@ var pcmDomain = {
 // src/domains/_openapi/parser.ts
 import { parse } from "yaml";
 var HTTP_METHODS = ["get", "post", "put", "patch", "delete"];
+var COMPONENT_KINDS = {
+  schemas: "schema",
+  responses: "response",
+  parameters: "parameter",
+  headers: "header"
+};
+var REF_PATTERN = /^#\/components\/(schemas|responses|parameters|headers)\/(.+)$/;
+function collectRefs(node, specName, out) {
+  if (Array.isArray(node)) {
+    for (const child of node) collectRefs(child, specName, out);
+    return;
+  }
+  if (node === null || typeof node !== "object") return;
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "$ref" && typeof value === "string") {
+      const match = REF_PATTERN.exec(value);
+      if (match) out.add(`${specName}:${COMPONENT_KINDS[match[1]]}:${match[2]}`);
+      continue;
+    }
+    collectRefs(value, specName, out);
+  }
+}
+function refsOf(node, specName) {
+  const out = /* @__PURE__ */ new Set();
+  collectRefs(node, specName, out);
+  return [...out];
+}
 function parseOpenApiSpec(yamlText, specName) {
   const spec = parse(yamlText);
   const items = [];
@@ -367,26 +394,38 @@ function parseOpenApiSpec(yamlText, specName) {
         summary: op.summary ?? null,
         description: op.description ?? null,
         tags: op.tags ?? [],
+        refs: refsOf(op, specName),
         detail: op
       });
     }
   }
-  for (const [name, schema] of Object.entries(spec.components?.schemas ?? {})) {
-    items.push({
-      id: `${specName}:schema:${name}`,
-      type: "schema",
-      name,
-      description: schema.description ?? null,
-      required: schema.required ?? [],
-      detail: schema
-    });
+  for (const [section, kind] of Object.entries(COMPONENT_KINDS)) {
+    for (const [name, node] of Object.entries(spec.components?.[section] ?? {})) {
+      items.push({
+        id: `${specName}:${kind}:${name}`,
+        type: kind,
+        name,
+        description: node.description ?? null,
+        ...kind === "schema" ? { required: node.required ?? [] } : {},
+        ...kind === "header" ? { required: node.required ?? null } : {},
+        // Em parameters a chave do componente (usada no $ref) difere do nome real
+        // do header/query; `paramName` e `in` preservam o nome usado na requisição.
+        ...kind === "parameter" ? { paramName: node.name ?? null, in: node.in ?? null, required: node.required ?? null } : {},
+        refs: refsOf(node, specName),
+        detail: node
+      });
+    }
+  }
+  const ids = new Set(items.map((i) => i.id));
+  for (const item of items) {
+    item.refs = item.refs.filter((ref) => ref !== item.id && ids.has(ref));
   }
   return items;
 }
 
 // src/domains/_openapi/domain.ts
 function summarize(item) {
-  const { detail: _detail, ...rest } = item;
+  const { detail: _detail, refs: _refs, ...rest } = item;
   return rest;
 }
 function createOpenApiDomain(config) {
@@ -394,11 +433,24 @@ function createOpenApiDomain(config) {
     id: config.id,
     title: config.title,
     description: config.description,
+    specVersion: config.specVersion,
     ttlHours: 72,
     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: "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)"
+      }
     ],
     async extract(ctx) {
       if (ctx?.signal?.aborted) throw new Error("Extra\xE7\xE3o cancelada pelo cliente");
@@ -414,13 +466,17 @@ function createOpenApiDomain(config) {
     search(data, query, filters = {}) {
       const path = filters.path ? normalize(filters.path) : void 0;
       const method = filters.method?.toUpperCase();
-      const schema = filters.schema ? normalize(filters.schema) : void 0;
       return data.items.filter((item) => {
         if (path && !normalize(String(item.path ?? "")).includes(path)) return false;
         if (method && item.method !== method) return false;
-        if (schema && !normalize(String(item.name ?? "")).includes(schema)) return false;
+        for (const type of ["schema", "response", "parameter", "header"]) {
+          const name = filters[type];
+          if (!name) continue;
+          if (item.type !== type) return false;
+          if (!normalize(String(item.name ?? "")).includes(normalize(name))) return false;
+        }
         if (query?.trim()) {
-          const haystack = [item.path, item.summary, item.description, item.name].map((v) => String(v ?? "")).join(" ");
+          const haystack = [item.path, item.summary, item.description, item.name, item.paramName].map((v) => String(v ?? "")).join(" ");
           if (!matchesQuery(haystack, query)) return false;
         }
         return true;
@@ -436,7 +492,7 @@ function createOpenApiDomain(config) {
 var paymentsConfig = {
   id: "payments-v4-openapi",
   title: "API de Pagamentos \u2014 spec OpenAPI 4.1.0",
-  description: "Spec OpenAPI oficial da API de Inicia\xE7\xE3o de Pagamentos (Pix) do Open Finance Brasil, vers\xE3o 4. Mesma fam\xEDlia da payments-v5-openapi (major mais recente); escolha o dom\xEDnio pela vers\xE3o que seu caso usa. Itens type=operation (endpoints, um por m\xE9todo+path) e type=schema (payloads). search devolve resumos; use get_item para o n\xF3 completo da spec.",
+  description: "Spec OpenAPI oficial da API de Inicia\xE7\xE3o de Pagamentos (Pix) do Open Finance Brasil, vers\xE3o 4. Mesma fam\xEDlia da payments-v5-openapi (major mais recente); escolha o dom\xEDnio pela vers\xE3o que seu caso usa. Itens type=operation (endpoints, um por m\xE9todo+path), type=schema (payloads) e os components reutiliz\xE1veis alvos dos $ref: type=response e type=parameter. search devolve resumos; use get_item para o n\xF3 completo da spec \u2014 nas opera\xE7\xF5es o campo `refs` traz os ids dos components referenciados, prontos para get_item.",
   pathExample: "/pix/payments",
   specName: "payments",
   specVersion: "4.1.0",
@@ -451,7 +507,7 @@ var paymentsDomain = createOpenApiDomain(paymentsConfig);
 var paymentsV5Config = {
   id: "payments-v5-openapi",
   title: "API de Pagamentos \u2014 spec OpenAPI 5.0.0",
-  description: "Spec OpenAPI oficial da API de Inicia\xE7\xE3o de Pagamentos (Pix) do Open Finance Brasil, vers\xE3o 5 (major mais recente). Mesma fam\xEDlia da payments-v4-openapi; escolha o dom\xEDnio pela vers\xE3o que seu caso usa. Itens type=operation (endpoints, um por m\xE9todo+path) e type=schema (payloads). search devolve resumos; use get_item para o n\xF3 completo da spec.",
+  description: "Spec OpenAPI oficial da API de Inicia\xE7\xE3o de Pagamentos (Pix) do Open Finance Brasil, vers\xE3o 5 (major mais recente). Mesma fam\xEDlia da payments-v4-openapi; escolha o dom\xEDnio pela vers\xE3o que seu caso usa. Itens type=operation (endpoints, um por m\xE9todo+path), type=schema (payloads) e os components reutiliz\xE1veis alvos dos $ref: type=response, type=parameter e type=header. search devolve resumos; use get_item para o n\xF3 completo da spec \u2014 nas opera\xE7\xF5es o campo `refs` traz os ids dos components referenciados, prontos para get_item.",
   pathExample: "/pix/payments",
   specName: "payments",
   specVersion: "5.0.0",
@@ -534,6 +590,7 @@ function createConfluenceSectionsDomain(config) {
     id: config.id,
     title: config.title,
     description: config.description,
+    specVersion: config.specVersion,
     ttlHours: 72,
     filters: [
       { name: "page", description: "Substring no t\xEDtulo da p\xE1gina Confluence" },
@@ -582,6 +639,7 @@ function createConfluenceSectionsDomain(config) {
 var paymentsV5BusinessRulesConfig = {
   id: "payments-v5-business-rules",
   title: "API de Pagamentos v5 \u2014 Regras de neg\xF3cio (SV)",
+  specVersion: "5.0.0",
   description: "Regras de neg\xF3cio da API de Inicia\xE7\xE3o de Pagamentos (Pix) vers\xE3o 5.0.0 do Open Finance Brasil, extra\xEDdas das p\xE1ginas Confluence de Servi\xE7os (SV): Informa\xE7\xF5es Gerais (vis\xE3o geral dos endpoints e dicion\xE1rio de dados), Escopo da API (formas de inicia\xE7\xE3o suportadas: Pix imediato, agendado, agendado recorrente, QR Code est\xE1tico/din\xE2mico, Pix Saque, Pix Troco, Pix Composto), M\xE1quina de Estados (status do consentimento e do pagamento), Diagrama de Sequ\xEAncia, Valida\xE7\xE3o de informa\xE7\xF5es no DICT e Adapta\xE7\xF5es para consultas de recursos entre 4.0.1 e 5.0.0. Complementa payments-v5-openapi, que traz a spec (endpoints e schemas) da mesma vers\xE3o. Conte\xFAdo que vale para todos os produtos de inicia\xE7\xE3o (idempot\xEAncia, assinatura de payload, polling, formatos de data) est\xE1 em payments-common-rules. Cada item \xE9 uma se\xE7\xE3o (heading) da p\xE1gina. 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,
@@ -603,7 +661,7 @@ var paymentsV5BusinessRulesDomain = createConfluenceSectionsDomain(paymentsV5Bus
 var enrollmentsV2Config = {
   id: "enrollments-v2-openapi",
   title: "API de V\xEDnculo de Dispositivo (Enrollments) \u2014 spec OpenAPI 2.3.0",
-  description: "Spec OpenAPI oficial da API de Enrollments (V\xEDnculo de Dispositivo) do Open Finance Brasil, vers\xE3o 2. Cobre o pagamento sem redirecionamento: v\xEDnculo de dispositivos (FIDO), autoriza\xE7\xE3o de consentimentos e Pix Autom\xE1tico. Endpoints /enrollments, /consents/{consentId}/authorise e /recurring-consents/{recurringConsentId}/authorise. Itens type=operation (endpoints, um por m\xE9todo+path) e type=schema (payloads). search devolve resumos; use get_item para o n\xF3 completo da spec.",
+  description: "Spec OpenAPI oficial da API de Enrollments (V\xEDnculo de Dispositivo) do Open Finance Brasil, vers\xE3o 2. Cobre o pagamento sem redirecionamento: v\xEDnculo de dispositivos (FIDO), autoriza\xE7\xE3o de consentimentos e Pix Autom\xE1tico. Endpoints /enrollments, /consents/{consentId}/authorise e /recurring-consents/{recurringConsentId}/authorise. Itens type=operation (endpoints, um por m\xE9todo+path), type=schema (payloads) e os components reutiliz\xE1veis alvos dos $ref: type=response, type=parameter e type=header. search devolve resumos; use get_item para o n\xF3 completo da spec \u2014 nas opera\xE7\xF5es o campo `refs` traz os ids dos components referenciados, prontos para get_item.",
   pathExample: "/enrollments",
   specName: "enrollments",
   specVersion: "2.3.0",
@@ -618,6 +676,7 @@ var enrollmentsV2Domain = createOpenApiDomain(enrollmentsV2Config);
 var enrollmentsV2BusinessRulesConfig = {
   id: "enrollments-v2-business-rules",
   title: "API de V\xEDnculo de Dispositivo v2 \u2014 Regras de neg\xF3cio (SV)",
+  specVersion: "2.2.0",
   description: "Regras de neg\xF3cio da API de V\xEDnculo de Dispositivo (Enrollments / Jornada Sem Redirecionamento) vers\xE3o 2.2.0 do Open Finance Brasil, extra\xEDdas das p\xE1ginas Confluence de Servi\xE7os (SV): Informa\xE7\xF5es Gerais, M\xE1quina de estados (vincula\xE7\xE3o de conta, autoriza\xE7\xE3o de consentimento e do consentimento recorrente), Edi\xE7\xE3o do v\xEDnculo de dispositivo (campos edit\xE1veis e condi\xE7\xF5es) e FAQ - JSR (perguntas e respostas por categoria). Complementa enrollments-v2-openapi, que traz a spec (endpoints e schemas) do mesmo major \u2014 hoje na 2.3.0, enquanto estas p\xE1ginas do Confluence ainda s\xE3o as da 2.2.0. Cada item \xE9 uma se\xE7\xE3o (heading) da p\xE1gina. 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,
@@ -639,7 +698,7 @@ var enrollmentsV2BusinessRulesDomain = createConfluenceSectionsDomain(
 var automaticPaymentsV2Config = {
   id: "automatic-payments-v2-openapi",
   title: "API de Pagamentos Autom\xE1ticos (Automatic Payments) \u2014 spec OpenAPI 2.2.0",
-  description: "Spec OpenAPI oficial da API de Automatic Payments do Open Finance Brasil, vers\xE3o 2. Cobre a inicia\xE7\xE3o de pagamentos autom\xE1ticos (Pix Autom\xE1tico e Transfer\xEAncias Inteligentes) mediante consentimento recorrente. Endpoints /recurring-consents (cria\xE7\xE3o, consulta e edi\xE7\xE3o/revoga\xE7\xE3o) e /pix/recurring-payments (cria\xE7\xE3o, retry, consulta e cancelamento); scope recurring-payments. Itens type=operation (endpoints, um por m\xE9todo+path) e type=schema (payloads). search devolve resumos; use get_item para o n\xF3 completo da spec.",
+  description: "Spec OpenAPI oficial da API de Automatic Payments do Open Finance Brasil, vers\xE3o 2. Cobre a inicia\xE7\xE3o de pagamentos autom\xE1ticos (Pix Autom\xE1tico e Transfer\xEAncias Inteligentes) mediante consentimento recorrente. Endpoints /recurring-consents (cria\xE7\xE3o, consulta e edi\xE7\xE3o/revoga\xE7\xE3o) e /pix/recurring-payments (cria\xE7\xE3o, retry, consulta e cancelamento); scope recurring-payments. Itens type=operation (endpoints, um por m\xE9todo+path), type=schema (payloads) e os components reutiliz\xE1veis alvos dos $ref: type=response, type=parameter e type=header. search devolve resumos; use get_item para o n\xF3 completo da spec \u2014 nas opera\xE7\xF5es o campo `refs` traz os ids dos components referenciados, prontos para get_item.",
   pathExample: "/pix/recurring-payments",
   specName: "automatic-payments",
   specVersion: "2.2.0",
@@ -654,6 +713,7 @@ var automaticPaymentsV2Domain = createOpenApiDomain(automaticPaymentsV2Config);
 var automaticPaymentsV2BusinessRulesConfig = {
   id: "automatic-payments-v2-business-rules",
   title: "API de Pagamentos Autom\xE1ticos v2 \u2014 Regras de neg\xF3cio (SV)",
+  specVersion: "2.2.0",
   description: "Regras de neg\xF3cio da API de Pagamentos Autom\xE1ticos (Pix Autom\xE1tico e Transfer\xEAncias Inteligentes) vers\xE3o 2.2.0 do Open Finance Brasil, extra\xEDdas das p\xE1ginas Confluence de Servi\xE7os (SV): Informa\xE7\xF5es Gerais (vis\xE3o geral dos endpoints e dicion\xE1rio de dados), M\xE1quina de Estados (status do consentimento recorrente e do pagamento), Edi\xE7\xE3o do consentimento (campos edit\xE1veis e condi\xE7\xF5es), Tentativas Intradia e Extradia para Pix Autom\xE1tico (janelas de liquida\xE7\xE3o, retentativas, e2eID) e Adapta\xE7\xF5es para consultas de recursos entre 1.0.0 e 2.2.0. Complementa automatic-payments-v2-openapi, que traz a spec (endpoints e schemas) da mesma vers\xE3o. O guia de implementa\xE7\xE3o passo a passo do Pix Autom\xE1tico est\xE1 em payments-implementation-guides. Cada item \xE9 uma se\xE7\xE3o (heading) da p\xE1gina. 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,
@@ -718,7 +778,7 @@ var paymentsImplementationGuidesDomain = createConfluenceSectionsDomain(
 var consentsV3Config = {
   id: "consents-v3-openapi",
   title: "API de Consentimentos \u2014 spec OpenAPI 3.3.1",
-  description: "Spec OpenAPI oficial da API de Consentimentos de compartilhamento de dados (Dados Cadastrais e Transacionais) do Open Finance Brasil, vers\xE3o 3.3.1. \xC9 o consentimento de dados \u2014 n\xE3o cobre consentimento de pagamento, que fica em payments-v4/v5-openapi (/consents) e automatic-payments-v2-openapi (/recurring-consents). Cobre cria\xE7\xE3o (POST /consents), consulta (GET /consents/{consentId}), revoga\xE7\xE3o (DELETE /consents/{consentId}), renova\xE7\xE3o (POST /consents/{consentId}/extends) e hist\xF3rico de renova\xE7\xF5es (GET /consents/{consentId}/extensions). Itens type=operation (um por m\xE9todo+path) e type=schema (payloads, ex.: CreateConsent, ResponseConsent, LoggedUser, BusinessEntity). search devolve resumos; use get_item para o n\xF3 completo da spec.",
+  description: "Spec OpenAPI oficial da API de Consentimentos de compartilhamento de dados (Dados Cadastrais e Transacionais) do Open Finance Brasil, vers\xE3o 3.3.1. \xC9 o consentimento de dados \u2014 n\xE3o cobre consentimento de pagamento, que fica em payments-v4/v5-openapi (/consents) e automatic-payments-v2-openapi (/recurring-consents). Cobre cria\xE7\xE3o (POST /consents), consulta (GET /consents/{consentId}), revoga\xE7\xE3o (DELETE /consents/{consentId}), renova\xE7\xE3o (POST /consents/{consentId}/extends) e hist\xF3rico de renova\xE7\xF5es (GET /consents/{consentId}/extensions). Itens type=operation (um por m\xE9todo+path), type=schema (payloads, ex.: CreateConsent, ResponseConsent, LoggedUser, BusinessEntity) e os components reutiliz\xE1veis alvos dos $ref: type=response (BadRequest, UnprocessableEntity, ...) e type=parameter (Authorization, xFapiInteractionId, ...). search devolve resumos; use get_item para o n\xF3 completo da spec \u2014 nas opera\xE7\xF5es o campo `refs` traz os ids dos components referenciados, prontos para get_item.",
   pathExample: "/consents/{consentId}",
   specName: "consents",
   specVersion: "3.3.1",
@@ -729,94 +789,95 @@ var consentsV3Config = {
 // src/domains/consents-v3-openapi/index.ts
 var consentsV3Domain = createOpenApiDomain(consentsV3Config);
 
+// src/domains/resources-v3-openapi/config.ts
+var resourcesV3Config = {
+  id: "resources-v3-openapi",
+  title: "API de Recursos \u2014 spec OpenAPI 3.1.0",
+  description: "Spec OpenAPI oficial da API de Recursos (Resources) do Open Finance Brasil, vers\xE3o 3.1.0. Endpoint \xFAnico (GET /resources) que lista os recursos compartilhados pelo cliente e o status de cada um, considerando a disponibilidade do recurso e o status do consentimento relacionado \u2014 \xE9 o ponto de partida de qualquer jornada de Dados Cadastrais e Transacionais, pois diz o que a receptora pode de fato consultar. O consentimento que a habilita fica em consents-v3-openapi; as contas em si, em accounts-v2-openapi. Itens type=operation, type=schema (ex.: ResponseResourceList, ResourceData com enum de status) e os components alvos dos $ref: type=response e type=parameter. Regras de neg\xF3cio da mesma API em resources-v3-business-rules. search devolve resumos; use get_item para o n\xF3 completo da spec \u2014 nas opera\xE7\xF5es o campo `refs` traz os ids dos components referenciados, prontos para get_item.",
+  pathExample: "/resources",
+  specName: "resources",
+  specVersion: "3.1.0",
+  url: "https://openbanking-brasil.github.io/openapi/swagger-apis/resources/3.1.0.yml",
+  retryDelaysMs: [2e3, 4e3, 8e3, 16e3]
+};
+
+// src/domains/resources-v3-openapi/index.ts
+var resourcesV3Domain = createOpenApiDomain(resourcesV3Config);
+
+// src/domains/resources-v3-business-rules/config.ts
+var resourcesV3BusinessRulesConfig = {
+  id: "resources-v3-business-rules",
+  title: "API de Recursos v3 \u2014 Regras de neg\xF3cio (DC)",
+  specVersion: "3.1.0",
+  description: "Regras de neg\xF3cio da API de Recursos (Resources) vers\xE3o 3.1.0 do Open Finance Brasil, extra\xEDdas das p\xE1ginas Confluence de Dados Cadastrais e Transacionais (DC): Informa\xE7\xF5es Gerais (vis\xE3o geral do GET /resources/v3/resources, status do recurso versus status do consentimento) e Orienta\xE7\xF5es - [DC] Recursos (quando um recurso volta a ficar dispon\xEDvel, uso do status code de erro apropriado quando a transmissora n\xE3o retorna as informa\xE7\xF5es) \u2014 esta \xFAltima n\xE3o \xE9 versionada e vale para todo o major v3. Complementa resources-v3-openapi, que traz a spec (endpoints e schemas) do mesmo major. Cada item \xE9 uma se\xE7\xE3o (heading) da p\xE1gina. 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],
+  pages: [
+    { pageId: "1267990545", title: "Informa\xE7\xF5es Gerais - [DC] Recursos - v3.1.0" },
+    { pageId: "219512943", title: "Orienta\xE7\xF5es - [DC] Recursos" }
+  ]
+};
+
+// src/domains/resources-v3-business-rules/index.ts
+var resourcesV3BusinessRulesDomain = createConfluenceSectionsDomain(
+  resourcesV3BusinessRulesConfig
+);
+
+// src/domains/accounts-v2-openapi/config.ts
+var accountsV2Config = {
+  id: "accounts-v2-openapi",
+  title: "API de Contas \u2014 spec OpenAPI 2.4.2",
+  description: "Spec OpenAPI oficial da API de Contas (Accounts) do Open Finance Brasil, vers\xE3o 2.4.2 \u2014 compartilhamento de contas de dep\xF3sito \xE0 vista, poupan\xE7a e pagamento pr\xE9-paga. Cobre listagem (GET /accounts), identifica\xE7\xE3o (GET /accounts/{accountId}), saldos (GET /accounts/{accountId}/balances), transa\xE7\xF5es (GET /accounts/{accountId}/transactions e /transactions-current) e limites de cheque especial (GET /accounts/{accountId}/overdraft-limits). \xC9 API de Dados Cadastrais e Transacionais: o consentimento que a habilita fica em consents-v3-openapi, e a listagem de recursos compartilhados em resources-v3-openapi. Itens type=operation (um por m\xE9todo+path), type=schema (payloads, ex.: AccountData, AccountBalancesData, AccountTransactionsData) e os components alvos dos $ref: type=response e type=parameter. Regras de neg\xF3cio da mesma API em accounts-v2-business-rules. search devolve resumos; use get_item para o n\xF3 completo da spec \u2014 nas opera\xE7\xF5es o campo `refs` traz os ids dos components referenciados, prontos para get_item.",
+  pathExample: "/accounts/{accountId}/transactions",
+  specName: "accounts",
+  specVersion: "2.4.2",
+  url: "https://openbanking-brasil.github.io/openapi/swagger-apis/accounts/2.4.2.yml",
+  retryDelaysMs: [2e3, 4e3, 8e3, 16e3]
+};
+
+// src/domains/accounts-v2-openapi/index.ts
+var accountsV2Domain = createOpenApiDomain(accountsV2Config);
+
+// src/domains/accounts-v2-business-rules/config.ts
+var accountsV2BusinessRulesConfig = {
+  id: "accounts-v2-business-rules",
+  title: "API de Contas v2 \u2014 Regras de neg\xF3cio (DC)",
+  specVersion: "2.4.2",
+  description: "Regras de neg\xF3cio da API de Contas (Accounts) vers\xE3o 2.4.2 do Open Finance Brasil, extra\xEDdas das p\xE1ginas Confluence de Dados Cadastrais e Transacionais (DC): Informa\xE7\xF5es Gerais (vis\xE3o geral dos endpoints, contas de dep\xF3sito \xE0 vista/poupan\xE7a/pagamento pr\xE9-paga, saldos, transa\xE7\xF5es e limites) e Orienta\xE7\xF5es - [DC] Contas (obrigatoriedade de informa\xE7\xF5es de contraparte pela IN BCB n\xBA 371, tratamento de transa\xE7\xF5es e casos de borda) \u2014 esta \xFAltima n\xE3o \xE9 versionada e vale para todo o major v2. Complementa accounts-v2-openapi, que traz a spec (endpoints e schemas) do mesmo major. Cada item \xE9 uma se\xE7\xE3o (heading) da p\xE1gina. 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],
+  pages: [
+    { pageId: "979566625", title: "Informa\xE7\xF5es Gerais - [DC] Contas - v2.4.2" },
+    { pageId: "1739096252", title: "Orienta\xE7\xF5es - [DC] Contas" }
+  ]
+};
+
+// src/domains/accounts-v2-business-rules/index.ts
+var accountsV2BusinessRulesDomain = createConfluenceSectionsDomain(
+  accountsV2BusinessRulesConfig
+);
+
 // src/domains/pcm-openapi/config.ts
 var pcmOpenapiConfig = {
   specName: "pcm",
-  specVersion: "1.0.0",
-  url: "https://raw.githubusercontent.com/OpenBanking-Brasil/pcm-specs/refs/heads/feature/correct-paths/PCM-current.openapi.yaml",
+  // A spec da PCM não declara `info.version` (o campo `openapi:` traz um valor
+  // fora do padrão). Identificar pelo commit é o único rótulo verificável — e
+  // deixa explícito, em list_domains, que este domínio está congelado no SHA.
+  specVersion: "commit 8a7f7b0",
+  url: "https://raw.githubusercontent.com/OpenBanking-Brasil/pcm-specs/8a7f7b03ddfab7eaf97bcfe68e67fac22a5eeb68/PCM-current.openapi.yaml",
   retryDelaysMs: [2e3, 4e3, 8e3, 16e3]
 };
 
-// src/domains/pcm-openapi/parser.ts
-import { parse as parse2 } from "yaml";
-var HTTP_METHODS2 = ["get", "post", "put", "patch", "delete"];
-function parseOpenApiSpec2(yamlText, specName) {
-  const spec = parse2(yamlText);
-  const items = [];
-  for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {
-    for (const method of HTTP_METHODS2) {
-      const op = pathItem[method];
-      if (!op) continue;
-      items.push({
-        id: `${specName}:${method.toUpperCase()} ${path}`,
-        type: "operation",
-        path,
-        method: method.toUpperCase(),
-        summary: op.summary ?? null,
-        description: op.description ?? null,
-        tags: op.tags ?? [],
-        detail: op
-      });
-    }
-  }
-  for (const [name, schema] of Object.entries(spec.components?.schemas ?? {})) {
-    items.push({
-      id: `${specName}:schema:${name}`,
-      type: "schema",
-      name,
-      description: schema.description ?? null,
-      required: schema.required ?? [],
-      detail: schema
-    });
-  }
-  return items;
-}
-
 // src/domains/pcm-openapi/index.ts
-function summarize3(item) {
-  const { detail: _detail, ...rest } = item;
-  return rest;
-}
-var pcmOpenapiDomain = {
+var pcmOpenapiDomain = createOpenApiDomain({
   id: "pcm-openapi",
-  title: `PCM \u2014 spec OpenAPI ${pcmOpenapiConfig.specVersion}`,
-  description: "Spec OpenAPI oficial da PCM (Plataforma de Coleta de M\xE9tricas) do Open Finance Brasil \u2014 a faceta swagger. Cobre os endpoints de reporte (report-api v1/v2), hybrid-flow, opendata, consents/stock, credit-portabilities, payments/status e token. Itens type=operation (um por m\xE9todo+path) e type=schema (payloads). Outras facetas da PCM: tabelas de obrigatoriedade do campo additionalInfo em pcm-additional-info; regras de neg\xF3cio (reporte, processamento, diverg\xEAncias) em pcm-business-rules. search devolve resumos; use get_item para o n\xF3 completo da spec.",
-  ttlHours: 72,
-  filters: [
-    { name: "path", description: "Substring no path do endpoint (ex.: /report-api/v1/private/report)" },
-    { name: "method", description: "Verbo HTTP exato (ex.: POST)" },
-    { name: "schema", description: "Substring no nome do schema (case-insensitive)" }
-  ],
-  async extract(ctx) {
-    if (ctx?.signal?.aborted) throw new Error("Extra\xE7\xE3o cancelada pelo cliente");
-    ctx?.onProgress?.(0, 1, `Baixando spec ${pcmOpenapiConfig.specName} ${pcmOpenapiConfig.specVersion}`);
-    const response = await fetchWithRetry(pcmOpenapiConfig.url, {
-      retryDelaysMs: pcmOpenapiConfig.retryDelaysMs,
-      signal: ctx?.signal
-    });
-    const yamlText = await response.text();
-    ctx?.onProgress?.(1, 1);
-    return { items: parseOpenApiSpec2(yamlText, pcmOpenapiConfig.specName) };
-  },
-  search(data, query, filters = {}) {
-    const path = filters.path ? normalize(filters.path) : void 0;
-    const method = filters.method?.toUpperCase();
-    const schema = filters.schema ? normalize(filters.schema) : void 0;
-    return data.items.filter((item) => {
-      if (path && !normalize(String(item.path ?? "")).includes(path)) return false;
-      if (method && item.method !== method) return false;
-      if (schema && !normalize(String(item.name ?? "")).includes(schema)) return false;
-      if (query?.trim()) {
-        const haystack = [item.path, item.summary, item.description, item.name].map((v) => String(v ?? "")).join(" ");
-        if (!matchesQuery(haystack, query)) return false;
-      }
-      return true;
-    }).map(summarize3);
-  },
-  getItem(data, id) {
-    return data.items.find((i) => i.id === id) ?? null;
-  }
-};
+  title: `PCM \u2014 spec OpenAPI (${pcmOpenapiConfig.specVersion})`,
+  description: "Spec OpenAPI oficial da PCM (Plataforma de Coleta de M\xE9tricas) do Open Finance Brasil \u2014 a faceta swagger. Cobre os endpoints de reporte (report-api v1/v2), hybrid-flow, opendata, consents/stock, credit-portabilities, payments/status e token. Itens type=operation (um por m\xE9todo+path), type=schema (payloads) e type=response (components reutiliz\xE1veis, alvos dos $ref). Outras facetas da PCM: tabelas de obrigatoriedade do campo additionalInfo em pcm-additional-info; regras de neg\xF3cio (reporte, processamento, diverg\xEAncias) em pcm-business-rules. search devolve resumos; use get_item para o n\xF3 completo da spec (opera\xE7\xF5es trazem `refs` com os ids dos components que referenciam).",
+  pathExample: "/report-api/v1/private/report",
+  ...pcmOpenapiConfig
+});
 
 // src/domains/pcm-business-rules/config.ts
 var pcmBusinessRulesConfig = {
@@ -883,7 +944,7 @@ var mqdDomain = createConfluenceSectionsDomain(mqdConfig);
 var webhookConfig = {
   id: "webhook-v1-openapi",
   title: "API de Webhook \u2014 spec OpenAPI 1.3.0",
-  description: "Spec OpenAPI oficial da API de Webhook do Open Finance Brasil, que notifica mudan\xE7as de estado das demais APIs. 5 opera\xE7\xF5es POST (type=operation): consentNotification e pixPaymentNotification (Pagamentos), enrollmentIdNotification (Enrollments), recurringConsentIdNotification e recurringPaymentIdNotification (Pagamentos Autom\xE1ticos); e schemas type=schema (RequestBodyWebhook, RequestBodyWebhookEvents, EventType, Timestamp, xWebhookInteractionId). search devolve resumos; use get_item para o n\xF3 completo da spec.",
+  description: "Spec OpenAPI oficial da API de Webhook do Open Finance Brasil, que notifica mudan\xE7as de estado das demais APIs. 5 opera\xE7\xF5es POST (type=operation): consentNotification e pixPaymentNotification (Pagamentos), enrollmentIdNotification (Enrollments), recurringConsentIdNotification e recurringPaymentIdNotification (Pagamentos Autom\xE1ticos); schemas type=schema (RequestBodyWebhook, RequestBodyWebhookEvents, EventType, Timestamp, xWebhookInteractionId); e os components reutiliz\xE1veis alvos dos $ref: type=response (202Webhook, 202WebhookPayments) e type=parameter (consentId, versionApi, xWebhookInteractionId, ...). search devolve resumos; use get_item para o n\xF3 completo da spec \u2014 nas opera\xE7\xF5es o campo `refs` traz os ids dos components referenciados, prontos para get_item.",
   pathExample: "/payments/{versionApi}/consents/{consentId}",
   specName: "webhook",
   specVersion: "1.3.0",
@@ -964,7 +1025,7 @@ function parseParticipants(jsonText) {
 }
 
 // src/domains/participantes/index.ts
-function summarize4(item) {
+function summarize3(item) {
   const { detail: _detail, ...rest } = item;
   return rest;
 }
@@ -1005,7 +1066,7 @@ var participantesDomain = {
         if (!matchesQuery(haystack, query)) return false;
       }
       return true;
-    }).map(summarize4);
+    }).map(summarize3);
   },
   getItem(data, id) {
     return data.items.find((i) => i.id === id) ?? null;
@@ -1086,6 +1147,10 @@ var domains = [
   paymentsCommonRulesDomain,
   paymentsImplementationGuidesDomain,
   consentsV3Domain,
+  resourcesV3Domain,
+  resourcesV3BusinessRulesDomain,
+  accountsV2Domain,
+  accountsV2BusinessRulesDomain,
   pcmOpenapiDomain,
   pcmBusinessRulesDomain,
   jornadaOtimizadaDomain,
@@ -1141,7 +1206,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 e o estado do cache local. 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`. Comece por aqui; depois use search(domain, ...) e get_item(domain, id).",
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -1151,20 +1216,24 @@ function createServer() {
     },
     async () => {
       const out = domains.map((d) => {
-        if (d.live) {
-          return { id: d.id, title: d.title, description: d.description, filters: d.filters, live: true };
-        }
-        const cached = readCache(d.id);
-        return {
+        const base = {
           id: d.id,
           title: d.title,
           description: d.description,
           filters: d.filters,
+          ...d.specVersion ? { specVersion: d.specVersion } : {}
+        };
+        if (d.live) {
+          return { ...base, live: true };
+        }
+        const cached = readCache(d.id);
+        return {
+          ...base,
           cachedItems: cached?.data.items.length ?? 0,
           extractedAt: cached?.extractedAt ?? null
         };
       });
-      return text(out);
+      return text({ server: { name: "opf-br-mcp", version: PACKAGE_VERSION }, domains: out });
     }
   );
   server2.registerTool(
@@ -1238,7 +1307,7 @@ function createServer() {
     "get_item",
     {
       title: "Detalhar um item",
-      description: "Devolve o registro completo de um item pelo `id` retornado por search (nos dom\xEDnios *-openapi e participantes inclui o n\xF3 integral da spec em `detail`; em pcm-additional-info devolve o registro completo, enquanto search devolve apenas um resumo).",
+      description: "Devolve o registro completo de um item pelo `id` retornado por search (nos dom\xEDnios *-openapi e participantes inclui o n\xF3 integral da spec em `detail`; em pcm-additional-info devolve o registro completo, enquanto search devolve apenas um resumo). Nos dom\xEDnios *-openapi os `$ref` n\xE3o v\xEAm expandidos: o campo `refs` lista os ids dos components referenciados (responses, parameters, schemas) \u2014 chame get_item neles para resolver.",
       inputSchema: {
         domain: domainIdSchema,
         id: z.string().describe("Id do item (vindo de search)")
@@ -1311,6 +1380,10 @@ function createServer() {
 }
 
 // src/index.ts
+if (process.argv.includes("--version") || process.argv.includes("-v")) {
+  console.log(PACKAGE_VERSION);
+  process.exit(0);
+}
 var server = createServer();
 await server.connect(new StdioServerTransport());
-console.error("[opf-br-mcp] server pronto (stdio)");
+console.error(`[opf-br-mcp] server pronto (stdio) \u2014 v${PACKAGE_VERSION}`);

package/package.json

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