Skip to content

@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 ​

ItemValor
Caminho/mcp
TransporteStreamable HTTP (stateless, resposta JSON)
MétodosPOST (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.

GrupoFerramentasUpstream
Tempo especialpesquisa de códigos e textos de enquadramentoprev-api
RGPS tempocálculo, por grupos e leitura/cálculo .calcprev-api
Documentos RGPSleitura de CNIS, RDCTC, Carta de Concessão e PAPprev-documentos
RGPS atrasadosliquidação, valor da causa e leitura/cálculo .calcprev-api
RGPS RMIcálculo, por fundamento, fundamentos e marcos temporaisrmi-api
Índicestabela, reajuste, moedas, tábua, adiantamento, piso/teto, baixa renda e OS 121backoffice

rgps_tempo_especial_buscar pesquisa o catálogo de enquadramentos por termo (até 200 caracteres), listas decretos e tipos, pagina e tamanhoPagina (padrão 20, máximo 100). Todos os argumentos são opcionais; sem filtros, retorna a primeira página do catálogo. Os IDs de decreto e os tipos aceitos constam no schema da ferramenta. A resposta preserva os registros completos em result e os metadados page-info; para continuar, incremente pagina até last. Sinônimos, correção aproximada e fontes vêm da REST. A ferramenta não decide o enquadramento de um período trabalhado.

indices_limites consulta a série de salário mínimo, teto de contribuição e maior teto de benefício do RGPS, com suas fontes normativas. indices_limite_baixa_renda_reclusao consulta a série do limite de renda do segurado preso, com início de vigência e fundamento. As duas ferramentas devolvem a série completa e não recebem filtros; para restringir competências, use os parâmetros competenciaInicial e competenciaFinal dos endpoints REST correspondentes.

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.

Essas mesmas ferramentas aceitam permalink: true, com ou sem demonstrativo. A opção equivale a ?permalink=true da API REST e acrescenta, após o resultado, um bloco de texto JSON { "permalink": "https://…" } com a URL para reabrir o cálculo na calculadora. Quando as duas opções são solicitadas, o bloco do permalink precede a nota e os recursos dos PDFs. Quando a API retorna avisos públicos em messages, as mensagens textuais são preservadas em um bloco de texto JSON adicional, após os demais conteúdos. Isso inclui as alterações aplicadas na recuperação de um .calc, que devem ser apresentadas ao usuário para revisão. Sem avisos nem opções, a resposta mantém apenas o resultado. As ferramentas de leitura e rgps_atrasados_valor_causa não oferecem essas opções.

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 ​

  1. Confirme que o serviço upstream existe como ChaveServicoInterno (@fc/servicos-internos/topologia); adicione-o lá apenas se faltar.
  2. 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.
  3. Registre o novo arquivo de grupo em server/mcp/catalogo/index.ts.
  4. 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, permalink opcional, demonstrativos do envelope como recursos embutidos e erro MCP controlado.
  • /mcp (e2e) — handshake, tools/list e proteção por chave.

Honorários contratuais ​

O cálculo de Atrasados aceita o parâmetro opcional honorariosContratuais: { destacar: true, percentual: 0.3 }, equivalente a 30%. O percentual é uma fração de 0 a 1, com até quatro casas decimais (duas casas percentuais); ativação sem percentual é recusada. Ausência ou destacar: false desativa o destaque.

O resultado opcional honorariosContratuais contém percentual, valores discriminados de honorarios e autor, além de dadosRra quando disponível. A divisão incide sobre o Resultado Atrasados final, conserva valores e meses de RRA e mantém a condenação e os honorários sucumbenciais. JSON, .calc, MCP e PDF usam essa mesma regra. O quadro “Honorários Contratuais (Destaque)” aparece após Resultado Atrasados e fica oculto na apuração exclusiva de sucumbenciais.