opf-br-mcp

MCP server local que dá a agentes de codificação (Claude Code, GitHub Copilot) acesso token-eficiente às regras do Open Finance Brasil.

Domínios disponíveis

Tools

• 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. 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.

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:

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 portal.

Progressive disclosure (por que economiza contexto)

O problema que este servidor resolve: uma spec Swagger/OpenAPI inteira não cabe bem na janela de contexto de um agente, e despejá-la desperdiça tokens. A solução é 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. Os filtros idênticos a uma família inteira de domínios (os 8 *-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 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:POST /pix/payments) e um por component reutilizável: type: schema (payments: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 ids 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 ids 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.

Instalação

Requer Node >= 20. O servidor roda via npx, sem clone nem build.

Claude Code — .mcp.json na raiz do projeto consumidor:

{ "mcpServers": { "opf-br": { "command": "npx", "args": ["-y", "opf-br-mcp"] } } }

GitHub Copilot (VS Code) — .vscode/mcp.json:

{ "servers": { "opf-br": { "command": "npx", "args": ["-y", "opf-br-mcp"] } } }

Claude Desktop — claude_desktop_config.json (Settings → Developer → Edit Config):

{ "mcpServers": { "opf-br": { "command": "npx", "args": ["-y", "opf-br-mcp"] } } }

Windows

No Windows, o client não consegue executar npx diretamente (é o shim npx.cmd) e acaba abrindo um cmd.exe interativo, cujo banner (Microsoft Windows [Version ...]) vaza para o canal stdio e corrompe o protocolo JSON-RPC — o servidor falha na conexão com erros de JSON inválido. Envolva o comando em cmd /c para rodá-lo sem shell interativo:

{ "mcpServers": { "opf-br": { "command": "cmd", "args": ["/c", "npx", "-y", "opf-br-mcp"] } } }

Vale para qualquer client no Windows (Claude Desktop, Claude Code, VS Code) — ajuste apenas a chave externa (mcpServers ou servers).

Uso local (a partir do fonte)

git clone https://github.com/jrogeriosilva/opf-br-mcp.git && cd opf-br-mcp
npm install && npm run build

E aponte o client para o build local:

{ "mcpServers": { "opf-br": { "command": "node", "args": ["/caminho/para/opf-br-mcp/dist/index.js"] } } }

Adicionando um domínio novo

1. Criar src/domains/<id>/index.ts exportando um objeto Domain (src/core/types.ts): extract() busca e estrutura os dados; search/getItem consultam; filters documenta os filtros.

2. Registrar em src/core/registry.ts.

3. Adicionar fixture e builder em test/contract.test.ts — a suíte de conformidade valida o contrato automaticamente.

Desenvolvimento

npm test           # vitest (fixtures locais, sem rede)
npm run typecheck  # tsc --noEmit
npm run build      # tsup → dist/

Skills para manutenção dos domínios

As skills do projeto ficam em .agents/skills:

• auditar-dominios — compara os domínios com as fontes oficiais e lista versões, páginas ou cobertura que precisam de atualização, com evidências e sem editar o projeto.

• atualizar-dominios — aplica as atualizações solicitadas e verifica extração, fixtures, testes, tipos e build.

Exemplos de pedidos: “Use $auditar-dominios para listar os domínios desatualizados” e “Use $atualizar-dominios para atualizar Automatic Payments dentro do major atual”.