Licinexus Mcp— agent skill

<p align="right"> 🇧🇷 Português · 🇺🇸 <a href="README.en.md"><b>English version</b></a> </p>

<p align="center"> <a href="https://licinexus.com.br"> <img src=".github/assets/logo.png" alt="Licinexus" width="380"> </a> </p>

<h1 align="center">@licinexusbr/mcp</h1>

<p align="center"> Acesso conversacional aos dados de licitações públicas brasileiras — direto do Claude Desktop, Cursor, Continue ou qualquer cliente compatível com MCP. </p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/licença-MIT-blue.svg" alt="MIT"></a> <a href="https://developercertificate.org/"><img src="https://img.shields.io/badge/DCO-obrigatório-green.svg" alt="DCO"></a> <a href="https://pncp.gov.br"><img src="https://img.shields.io/badge/dados-PNCP%20%2B%20Receita%20Federal-yellow.svg" alt="PNCP + Receita"></a> <a href="https://www.npmjs.com/package/@licinexusbr/mcp"><img src="https://img.shields.io/npm/v/@licinexusbr/mcp.svg?label=npm" alt="npm"></a> </p>

<p align="center"> Mantido pela <a href="https://licinexus.com.br"><b>Licinexus</b></a> como contribuição open source ao ecossistema brasileiro de govtech. </p>

<p align="center"> 🔔 <b>Quer notificações de novas versões?</b> Clica em <b>Watch → Custom → Releases</b> no topo do repositório — toda nova release cai na sua caixa de notificações sem encher o feed. </p>

<!-- BEGIN: hero demo --> <p align="center"> <img src=".github/assets/demo.gif" alt="Demo: Licinexus MCP em ação contra PNCP + Receita Federal" width="900"> </p> <!-- END: hero demo -->

📺 A demonstração acima é um script CLI chamando os mesmos adaptadores que o LLM usa, contra PNCP e BrasilAPI ao vivo. A experiência no Claude Desktop / Cursor é idêntica — mesmas ferramentas, mesmos dados, com o LLM fazendo a interpretação em linguagem natural.

O que faz

Encapsula os endpoints mais úteis do Portal Nacional de Contratações Públicas (PNCP) e dos dados de CNPJ da Receita Federal, para que um LLM consiga responder perguntas reais sobre contratações públicas brasileiras:

• _"Quais editais de TI no Sudeste publicados nos últimos 7 dias com valor acima de R$ 500 mil?"_
• _"Existe ata de registro de preço vigente com saldo para notebook no estado de SP?"_
• _"Qual o histórico de contratos do CNPJ X com órgãos públicos federais nos últimos 2 anos?"_
• _"O que a Prefeitura de Y planeja comprar este ano segundo o PCA?"_
• _"Resuma este edital e me dê uma lista de verificação de viabilidade."_

🚀 Como usar

Pré-requisitos

• Node.js 18 ou superior instalado (nodejs.org)
• Qualquer cliente compatível com MCP (lista abaixo)

Nenhuma chave de API, nenhum cadastro, nenhum banco local — o servidor consulta endpoints públicos diretamente.

⚠️ Importante: Este é um servidor MCP stdio-based. Você não roda ele diretamente no terminal — é o cliente MCP (Claude Desktop, Cursor, etc.) que invoca o servidor quando precisa, e a comunicação acontece por JSON-RPC via stdin/stdout. Se você executar npx @licinexusbr/mcp direto no terminal, vai parecer que "travou" — é normal, o servidor está esperando o cliente conectar.

>

Da mesma forma, npx -y @licinexusbr/mcp não é uma instalação global — apenas baixa o pacote pra um cache local (~/.npm/_npx/) e executa. O cliente MCP invoca npx toda vez que precisa do servidor; execuções subsequentes usam o cache e são instantâneas. (Você também pode usar npm exec em vez de npx — são equivalentes.)

1. Claude Desktop ⭐ (recomendado)

#### Caminho A — Via UI (Claude Desktop ≥ 4.x)

1. Abra o Claude Desktop
2. Cmd + , (macOS) ou Ctrl + , (Windows) → Configurações
3. Barra lateral → Conectores
4. Clica em "Editar Configuração" (Aplicativo desktop → Desenvolvedor)
5. Abre o arquivo claude_desktop_config.json no seu editor

Substitua (ou adicione dentro de mcpServers):

{
  "mcpServers": {
    "licinexus": {
      "command": "npx",
      "args": ["-y", "@licinexusbr/mcp"]
    }
  }
}

1. Salve o arquivo (Cmd+S)
2. Encerre o Claude completamente (Cmd+Q — não basta fechar a janela) e reabra

#### Caminho B — Editando o arquivo direto

#### Como verificar que funcionou

Após reabrir, na conversa nova:

• Em Configurações → Conectores → licinexus, você deve ver 18 ferramentas listadas (search_licitacoes, get_cnpj_data, etc.)
• No campo de prompt, digite:

Quais ferramentas do licinexus você tem disponíveis?

O Claude deve listar as 18 ferramentas. Pode prosseguir.

#### Primeiros prompts para testar

Me mostra os dados do CNPJ 00000000000191 (Banco do Brasil)

Tem ata de registro de preço vigente para notebook em São Paulo com saldo disponível?

O que a Prefeitura de Juiz de Fora planeja comprar este ano segundo o PCA?

Quais editais de tecnologia da informação foram publicados nos últimos 7 dias acima de R$ 200 mil?

2. Cursor

Cursor suporta MCP servers nativamente. Crie/edite o arquivo ~/.cursor/mcp.json:

{
  "mcpServers": {
    "licinexus": {
      "command": "npx",
      "args": ["-y", "@licinexusbr/mcp"]
    }
  }
}

Ou via UI: Cursor → Settings → MCP → Add new MCP server.

Reinicie o Cursor. As ferramentas aparecem no chat do Composer.

3. Continue.dev (VS Code / JetBrains)

Edite o arquivo ~/.continue/config.json (ou config.yaml):

{
  "mcpServers": [
    {
      "name": "licinexus",
      "command": "npx",
      "args": ["-y", "@licinexusbr/mcp"]
    }
  ]
}

Recarregue o Continue (Cmd+Shift+P → "Continue: Reload"). As ferramentas ficam disponíveis no chat.

4. Cline / Roo Code (extensão VS Code)

Pela UI do Cline:

1. Abra a extensão Cline na sidebar do VS Code
2. Ícone de configurações → MCP Servers → Edit MCP Settings
3. Adicione:

{
  "mcpServers": {
    "licinexus": {
      "command": "npx",
      "args": ["-y", "@licinexusbr/mcp"]
    }
  }
}

5. Zed editor

Edite ~/.config/zed/settings.json (macOS/Linux) e adicione:

{
  "context_servers": {
    "licinexus": {
      "command": {
        "path": "npx",
        "args": ["-y", "@licinexusbr/mcp"]
      }
    }
  }
}

Reinicie o Zed.

6. ChatGPT

O ChatGPT consumer (web) não suporta MCP stdio nativamente até o momento. Mas dá pra usar via:

#### Via OpenAI Agents SDK (Python)

from openai import OpenAI
from openai.agents import Agent, MCPServerStdio

server = MCPServerStdio(
    command="npx",
    args=["-y", "@licinexusbr/mcp"]
)

agent = Agent(
    name="Licinexus Assistant",
    instructions="Você é um analista de licitações públicas brasileiras.",
    mcp_servers=[server]
)

#### ChatGPT Desktop

Versões recentes têm suporte limitado a MCP — verifique a documentação oficial da OpenAI para o estado atual.

7. Programaticamente (qualquer LLM via stdio)

Você pode chamar o servidor diretamente via stdio em qualquer linguagem que suporte o protocolo JSON-RPC do MCP. Exemplo Node:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@licinexusbr/mcp'],
});

const client = new Client({ name: 'meu-app', version: '1.0.0' }, { capabilities: {} });
await client.connect(transport);

const tools = await client.listTools();
console.log(tools);

const result = await client.callTool({
  name: 'search_atas_rp',
  arguments: { palavraChave: 'notebook', somenteVigentes: true },
});

🔧 Troubleshooting

"Server failed to start" ou "command not found: npx"

Causa: Claude Desktop / outro cliente não acha o npx no PATH.

Solução: use o caminho absoluto. Descubra com:

which npx

E substitua no config:

{
  "mcpServers": {
    "licinexus": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@licinexusbr/mcp"]
    }
  }
}

"Ferramentas não aparecem após salvar config"

Solução: reinicie o cliente completamente. No Mac, Cmd+Q (não basta fechar a janela). MCP servers só são carregados na inicialização.

"EACCES" ou erro de permissão

Causa: cache do npx corrompido ou permissão de escrita.

Solução:

npm cache clean --force
npx -y @licinexusbr/mcp

Versão antiga sendo executada

Causa: npx mantém cache. Para forçar a versão mais recente:

npx -y @licinexusbr/mcp@latest

E no config:

"args": ["-y", "@licinexusbr/mcp@latest"]

Timeout em consultas grandes

Algumas consultas (busca por palavra-chave ampla, datas longas) podem demorar — o PNCP às vezes leva 15-30s para responder. O servidor já implementa retry budget. Se persistir, refine a consulta com filtros mais específicos.

Logs e debug

Para inspecionar requisições/respostas, rode manualmente no terminal:

LICINEXUS_LOG_LEVEL=debug npx -y @licinexusbr/mcp

E em outra janela, observe os logs enquanto o cliente faz chamadas.

Idioma das mensagens de erro

Por padrão, as mensagens de erro retornadas pelas tools estão em português. Para recebê-las em inglês:

LICINEXUS_LANG=en npx -y @licinexusbr/mcp

Valores aceitos: pt (padrão) ou en.

Ferramentas (18)

Compras / Licitações

Contratos

Atas de Registro de Preço

Órgãos / Fornecedores / PCA

Enriquecimento de CNPJ

Análise agregada (v0.2.0)

Prompts prontos (4)

Fluxos pré-construídos que seu assistente pode invocar diretamente:

Recursos (2)

Exemplo de sessão

Você:   Tem alguma ata de registro de preço vigente para notebooks?
Claude: [chama search_atas_rp com palavraChave="notebook", somenteVigentes=true]
        Encontrei 12 atas vigentes mencionando notebooks. As 3 mais relevantes:
        1. Ministério da Justiça — vigência até 2026-12-31, valor estimado R$ 2,4M
        2. Prefeitura de São Paulo — vigência até 2026-09-30...

Você:   Detalhes da primeira, com saldos por item?
Claude: [chama get_ata_rp includeItens=true]
        - Item 1: Notebook tipo I (16GB RAM, 512GB SSD) — saldo 1.200 unid, R$ 4.800/un
        - Item 2: Notebook tipo II ...

Roteiro de evolução

• [x] Fase 0 — Estrutura, governança, CI
• [x] Fase 1 — Licitações (5 ferramentas)
• [x] Fase 2 — Contratos + Aditivos + NFes (4 ferramentas)
• [x] Fase 3 — Atas RP (2 ferramentas)
• [x] Fase 4 — Órgãos + Fornecedores + PCA (4 ferramentas)
• [x] Fase 5 — CNPJ + 4 prompts + 2 recursos (1 ferramenta)
• [x] Teste de fumaça contra APIs reais (15/15 endpoints)
• [x] Fase 6 — Lançamento público (11/05/2026 · v0.1.0 no npm)
• [ ] Fase 7 — Adapters comunitários (TCE/TCM estaduais, ComprasNet legado)

Escopo

O que este MCP faz

• Encapsula APIs públicas do governo brasileiro (PNCP, BrasilAPI).
• Devolve dado bruto estruturado — o LLM faz a análise.
• Mantém cache local de respostas pesadas (LRU em memória, TTL curto).

O que este MCP não faz

• Não consulta nenhuma infraestrutura nem banco de dados privado da Licinexus.
• Não inclui o motor de correspondência (matchmaking), pontuação de fornecedores, agregação de preços, artefatos gerados por IA ou qualquer dado proprietário da Licinexus.
• Não substitui o produto Licinexus — é uma ferramenta open source complementar para a camada pública dos mesmos dados.

Veja docs/architecture.md para o modelo completo de separação em três paredes.

Precisa de matchmaking automático, alertas ou gestão de propostas?

O produto Licinexus é construído sobre essas mesmas fontes públicas, com motor de correspondência proprietário, pontuação inteligente e artefatos gerados por IA. Este MCP intencionalmente não replica esses recursos.

→ <https://licinexus.com.br>

Como contribuir

PRs são bem-vindos sob o DCO (Developer Certificate of Origin) — assine seus commits com git commit --signoff.

Por favor, abra uma issue antes para discutir qualquer mudança não trivial. Veja CONTRIBUTING.md.

Suporte

Projeto comunitário. Melhor esforço, sem SLA. Issues são triadas em até 7 dias quando possível.

Para suporte pago e funcionalidades do produto, veja licinexus.com.br.

Segurança

Encontrou uma vulnerabilidade? Veja SECURITY.md para divulgação responsável (não abra issues públicas).

Licença

MIT © Licinexus. Veja LICENSE.