@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 obackoffice. - A rota
/mcpfaz 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 |
|---|---|---|
| Tempo especial | pesquisa de códigos e textos de enquadramento | prev-api |
| 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, adiantamento, piso/teto, baixa renda e OS 121 | backoffice |
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
- 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). UsederivarCorpoDoSpec: truequando o corpo da requisição corresponder a um schema do/_openapi.jsonupstream. - 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 errosDesenvolvimento
bash
# Apenas este app
pnpm --filter @fc/mcp dev
# Ambiente local integrado (selecione "mcp" na lista)
pnpm dev:local
# Ambiente Docker integrado
pnpm dev:dockerSmoke 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,
inputSchemade objeto, mapeamento serviço/método/caminho. extrairSchemaCorpo— extração do schema dorequestBodydo 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 deRetry-After.executarFerramenta— extração do resultado, permalink opcional, demonstrativos do envelope como recursos embutidos e erro MCP controlado./mcp(e2e) — handshake,tools/liste 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.