@fc/mcp — Servidor MCP da Fábrica de Cálculos

App Nitro que expõe um servidor MCP (Model Context Protocol) em /mcp, permitindo que agentes de IA usem as calculadoras previdenciárias do TRF3 como ferramentas.

Visão geral

O app é uma fachada fina sobre as APIs REST públicas já existentes: cada ferramenta MCP traduz uma chamada do agente em uma requisição HTTP a uma rota REST de prev-api, prev-documentos, rmi-api ou backoffice. Não há lógica de domínio aqui — as camadas de cálculo (@fc/calculos-previdenciarios, @fc/indices) não são importadas.

Agente IA ──/mcp (x-api-key)──▶ @fc/mcp ──▶ APIs públicas da Fábrica

Estende ../base-api, herdando os middlewares e a validação de chave.
Transporte Streamable HTTP em modo stateless (SDK oficial @modelcontextprotocol/sdk): cada requisição cria seu próprio servidor e transporte, sem sessão.

Endpoint

Item	Valor
Caminho	`/mcp`
Transporte	Streamable HTTP (stateless, resposta JSON)
Métodos	`POST` (JSON-RPC do MCP); `GET`/`DELETE` → 405

Autenticação

A proteção do /mcp reutiliza, sem código novo, o mecanismo de chave de cliente de base-api:

A chave viaja no cabeçalho x-api-key — a mesma chave de API usada nas demais APIs públicas, validada remotamente contra o backoffice.
A rota /mcp faz parte estruturalmente do conjunto protegido e exige chave nos ambientes publicados. A inicialização falha se a configuração efetiva estiver vazia, contiver glob inválido ou não cobrir essa rota.
A chave recebida do agente é repassada às rotas REST upstream (essas rotas são protegidas pelo mesmo mecanismo de chave de cliente).

Cuidados com a chave: guarde-a no mecanismo de segredos do seu cliente MCP e configure esse valor no header x-api-key, conforme a documentação do cliente. A chave é anexada na camada HTTP e nunca é vista pelo agente: ele não precisa conhecê-la para usar as ferramentas. Não a inclua em prompts, em conversas nem em arquivos versionados.

Catálogo de ferramentas

As ferramentas são declaradas em um catálogo declarativo em server/mcp/catalogo/. Cada descritor define nome, título, descrição, serviço, método, caminho e a montagem da requisição.

Grupo	Ferramentas	Upstream
RGPS tempo	cálculo, por grupos e leitura/cálculo `.calc`	`prev-api`
Documentos RGPS	leitura de CNIS, RDCTC, Carta de Concessão e PAP	`prev-documentos`
RGPS atrasados	liquidação, valor da causa e leitura/cálculo `.calc`	`prev-api`
RGPS RMI	cálculo, por fundamento, fundamentos e marcos temporais	`rmi-api`
Índices	tabela, reajuste, moedas, tábua de mortalidade, adiantamento e OS 121	`backoffice`

As ferramentas de cálculo de RMI preservam o campo conclusao recebido da rmi-api. O agente deve verificar conclusao.completo em cada bloco; quando for false, motivoInterrupcao: LIMITE_ITERACOES e limitesAtingidos explicam por que o resultado é parcial. A regra continua pertencendo à API de RMI: o MCP apenas repassa o corpo e a documenta no catálogo.

As oito ferramentas de cálculo (rgps_tempo_calcular, rgps_tempo_calcular_por_grupos, rgps_tempo_calc_calcular, rgps_tempo_calc_calcular_por_grupos, rgps_rmi_calcular, rgps_rmi_calcular_por_fundamento, rgps_atrasados_calcular e rgps_atrasados_calc_calcular) aceitam demonstrativo: true. É a mesma opção ?demonstrativo=true das rotas REST: a resposta traz, além do result em texto, uma nota em texto com campo, nome do arquivo, páginas, tamanho e URI de cada demonstrativo, seguida de um recurso embutido (application/pdf, base64) por PDF — o principal e, quando a API os produz, os complementares (descartes da RMI, alçada dos atrasados). O PDF embute o permalink do cálculo. Sem a flag, nada muda no conteúdo.

rgps_atrasados_valor_causa recebe os mesmos dados de rgps_atrasados_calcular e devolve apenas a comparação do valor da causa com o limite de alçada dos Juizados Especiais Federais: situação, valor, limite e excedente. O cálculo executado é o mesmo — o que muda é o tamanho da resposta, que cai de dezenas ou centenas de KB para algumas centenas de bytes. Use-a quando a pergunta for sobre competência, e a ferramenta de liquidação quando for sobre os valores.

As leituras de CNIS, RDCTC e Carta de Concessão aceitam PDF (em base64) ou o texto puro do documento; a leitura de PAP aceita apenas PDF em base64. O corpo JSON-RPC do /mcp é limitado a 8 MiB — como o base64 infla ~33%, o teto efetivo é de ~6 MB de PDF; arquivos maiores (PAPs integrais chegam a dezenas de MB) devem usar a API REST diretamente.

Schema de entrada — derivado do contrato OpenAPI

O inputSchema de cada ferramenta é um JSON Schema. Para as ferramentas de cálculo (derivarCorpoDoSpec: true), o schema do campo dados é lido em runtime do /_openapi.json do serviço upstream — a fonte de verdade é o contrato que a API publica, não tipos internos. O documento OpenAPI é buscado sob demanda e mantido em cache (server/mcp/openapi/).

Se um spec estiver indisponível, a ferramenta continua listada com o schema literal de fallback do descritor (degradação graciosa).

O servidor não revalida a entrada contra o inputSchema: a rota REST de destino é a dona do contrato e recusa dados inválidos com HTTP 400, cujas mensagens são repassadas ao agente. Revalidar aqui duplicaria a regra e divergiria em silêncio quando o contrato upstream evoluísse.

Como adicionar uma ferramenta

Confirme que o serviço upstream existe como ChaveServicoInterno (@fc/servicos-internos/topologia); adicione-o lá apenas se faltar.
Acrescente um descritor ao arquivo de grupo apropriado em server/mcp/catalogo/ferramentas/ (ou crie um novo arquivo de grupo). Use derivarCorpoDoSpec: true quando o corpo da requisição corresponder a um schema do /_openapi.json upstream.
Registre o novo arquivo de grupo em server/mcp/catalogo/index.ts.
Atualize a lista de ferramentas exibida na página pública de integração (apps/docs-api/app/pages/mcp.vue), que é um espelho manual do catálogo.

Estrutura

server/
  routes/mcp/index.ts        Endpoint /mcp — ponte h3 ↔ transporte do SDK MCP
  mcp/
    criarServidorMcp.ts      Monta o servidor MCP e registra as ferramentas
    executarFerramenta.ts    Executa uma ferramenta e trata erros
    constantes.ts
    catalogo/
      tipos.ts               DescritorFerramenta, RequisicaoUpstream
      index.ts               Catálogo consolidado
      ferramentas/           Descritores por grupo (rgps-tempo, rgps-rmi, indices)
    openapi/                 Leitura/cache do /_openapi.json upstream e
                             derivação do inputSchema das ferramentas
  utils/
    chamarServicoUpstream.ts Cliente HTTP upstream + normalização de erros

Desenvolvimento

bash

# Apenas este app
pnpm --filter @fc/mcp dev

# Ambiente local integrado (selecione "mcp" na lista)
pnpm dev:local

# Ambiente Docker integrado
pnpm dev:docker

Smoke test com o MCP Inspector apontando para o endereço informado pelo assistente local.

Configuração de implantação

Endereços de serviços, credenciais e parâmetros operacionais são fornecidos no início da execução. O catálogo dessas chaves e a topologia não fazem parte da superfície pública.

Testes

bash

pnpm --filter @fc/mcp test:run

Catálogo — nomes únicos, inputSchema de objeto, mapeamento serviço/método/caminho.
extrairSchemaCorpo — extração do schema do requestBody do spec OpenAPI e reescrita de refs para #/$defs/.
chamarServicoUpstream — montagem da requisição e normalização de erros (400/401/403/404/413/422/429/5xx/timeout) sem vazar detalhes internos; no 429, orienta nova tentativa e preserva o intervalo numérico de Retry-After.
executarFerramenta — extração do resultado, demonstrativos do envelope como recursos embutidos e erro MCP controlado.
/mcp (e2e) — handshake, tools/list e proteção por chave.

@fc/mcp — Servidor MCP da Fábrica de Cálculos ​

Visão geral ​

Endpoint ​

Autenticação ​

Catálogo de ferramentas ​

Schema de entrada — derivado do contrato OpenAPI ​

Como adicionar uma ferramenta ​

Estrutura ​

Desenvolvimento ​

Configuração de implantação ​

Testes ​