{
  "markdown": "<p align=\"right\">\n  🇧🇷 Português  ·  🇺🇸 <a href=\"README.en.md\"><b>English version</b></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://licinexus.com.br\">\n    <img src=\".github/assets/logo.png\" alt=\"Licinexus\" width=\"380\">\n  </a>\n</p>\n\n<h1 align=\"center\">@licinexusbr/mcp</h1>\n\n<p align=\"center\">\n  Acesso conversacional aos dados de licitações públicas brasileiras — direto do Claude Desktop, Cursor, Continue ou qualquer cliente compatível com MCP.\n</p>\n\n<p align=\"center\">\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/licença-MIT-blue.svg\" alt=\"MIT\"></a>\n  <a href=\"https://developercertificate.org/\"><img src=\"https://img.shields.io/badge/DCO-obrigatório-green.svg\" alt=\"DCO\"></a>\n  <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>\n  <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>\n</p>\n\n<p align=\"center\">\n  Mantido pela <a href=\"https://licinexus.com.br\"><b>Licinexus</b></a> como contribuição open source ao ecossistema brasileiro de govtech.\n</p>\n\n<p align=\"center\">\n  🔔 <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.\n</p>\n\n<!-- BEGIN: hero demo -->\n<p align=\"center\">\n  <img src=\".github/assets/demo.gif\" alt=\"Demo: Licinexus MCP em ação contra PNCP + Receita Federal\" width=\"900\">\n</p>\n<!-- END: hero demo -->\n\n> 📺 **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.\n\n---\n\n## O que faz\n\nEncapsula 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:\n\n- _\"Quais editais de TI no Sudeste publicados nos últimos 7 dias com valor acima de R$ 500 mil?\"_\n- _\"Existe ata de registro de preço vigente com saldo para `notebook` no estado de SP?\"_\n- _\"Qual o histórico de contratos do CNPJ X com órgãos públicos federais nos últimos 2 anos?\"_\n- _\"O que a Prefeitura de Y planeja comprar este ano segundo o PCA?\"_\n- _\"Resuma este edital e me dê uma lista de verificação de viabilidade.\"_\n\n## 🚀 Como usar\n\n### Pré-requisitos\n\n- **Node.js 18 ou superior** instalado ([nodejs.org](https://nodejs.org))\n- Qualquer cliente compatível com MCP (lista abaixo)\n\nNenhuma chave de API, nenhum cadastro, nenhum banco local — o servidor consulta endpoints públicos diretamente.\n\n> ⚠️ **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.\n>\n> 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.)\n\n---\n\n### 1. Claude Desktop ⭐ (recomendado)\n\n#### Caminho A — Via UI (Claude Desktop ≥ 4.x)\n\n1. Abra o **Claude Desktop**\n2. `Cmd + ,` (macOS) ou `Ctrl + ,` (Windows) → **Configurações**\n3. Barra lateral → **Conectores**\n4. Clica em **\"Editar Configuração\"** (Aplicativo desktop → Desenvolvedor)\n5. Abre o arquivo `claude_desktop_config.json` no seu editor\n\nSubstitua (ou adicione dentro de `mcpServers`):\n\n```json\n{\n  \"mcpServers\": {\n    \"licinexus\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@licinexusbr/mcp\"]\n    }\n  }\n}\n```\n\n6. Salve o arquivo (`Cmd+S`)\n7. **Encerre o Claude completamente** (`Cmd+Q` — não basta fechar a janela) e reabra\n\n#### Caminho B — Editando o arquivo direto\n\n| SO          | Caminho                                                           |\n| ----------- | ----------------------------------------------------------------- |\n| **macOS**   | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| **Windows** | `%APPDATA%\\Claude\\claude_desktop_config.json`                     |\n| **Linux**   | _Não oficialmente suportado pelo Claude Desktop ainda_            |\n\n#### Como verificar que funcionou\n\nApós reabrir, na conversa nova:\n\n- Em **Configurações → Conectores → licinexus**, você deve ver **18 ferramentas** listadas (`search_licitacoes`, `get_cnpj_data`, etc.)\n- No campo de prompt, digite:\n\n```\nQuais ferramentas do licinexus você tem disponíveis?\n```\n\nO Claude deve listar as 18 ferramentas. Pode prosseguir.\n\n#### Primeiros prompts para testar\n\n```\nMe mostra os dados do CNPJ 00000000000191 (Banco do Brasil)\n```\n\n```\nTem ata de registro de preço vigente para notebook em São Paulo com saldo disponível?\n```\n\n```\nO que a Prefeitura de Juiz de Fora planeja comprar este ano segundo o PCA?\n```\n\n```\nQuais editais de tecnologia da informação foram publicados nos últimos 7 dias acima de R$ 200 mil?\n```\n\n---\n\n### 2. Cursor\n\nCursor suporta MCP servers nativamente. Crie/edite o arquivo `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"licinexus\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@licinexusbr/mcp\"]\n    }\n  }\n}\n```\n\nOu via UI: **Cursor → Settings → MCP → Add new MCP server**.\n\nReinicie o Cursor. As ferramentas aparecem no chat do Composer.\n\n---\n\n### 3. Continue.dev (VS Code / JetBrains)\n\nEdite o arquivo `~/.continue/config.json` (ou `config.yaml`):\n\n```json\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"licinexus\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@licinexusbr/mcp\"]\n    }\n  ]\n}\n```\n\nRecarregue o Continue (`Cmd+Shift+P` → \"Continue: Reload\"). As ferramentas ficam disponíveis no chat.\n\n---\n\n### 4. Cline / Roo Code (extensão VS Code)\n\nPela UI do Cline:\n\n1. Abra a extensão Cline na sidebar do VS Code\n2. Ícone de configurações → **MCP Servers** → **Edit MCP Settings**\n3. Adicione:\n\n```json\n{\n  \"mcpServers\": {\n    \"licinexus\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@licinexusbr/mcp\"]\n    }\n  }\n}\n```\n\n---\n\n### 5. Zed editor\n\nEdite `~/.config/zed/settings.json` (macOS/Linux) e adicione:\n\n```json\n{\n  \"context_servers\": {\n    \"licinexus\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"-y\", \"@licinexusbr/mcp\"]\n      }\n    }\n  }\n}\n```\n\nReinicie o Zed.\n\n---\n\n### 6. ChatGPT\n\nO **ChatGPT consumer (web)** não suporta MCP stdio nativamente até o momento. Mas dá pra usar via:\n\n#### Via OpenAI Agents SDK (Python)\n\n```python\nfrom openai import OpenAI\nfrom openai.agents import Agent, MCPServerStdio\n\nserver = MCPServerStdio(\n    command=\"npx\",\n    args=[\"-y\", \"@licinexusbr/mcp\"]\n)\n\nagent = Agent(\n    name=\"Licinexus Assistant\",\n    instructions=\"Você é um analista de licitações públicas brasileiras.\",\n    mcp_servers=[server]\n)\n```\n\n#### ChatGPT Desktop\n\nVersões recentes têm suporte limitado a MCP — verifique a documentação oficial da OpenAI para o estado atual.\n\n---\n\n### 7. Programaticamente (qualquer LLM via stdio)\n\nVocê pode chamar o servidor diretamente via stdio em qualquer linguagem que suporte o protocolo JSON-RPC do MCP. Exemplo Node:\n\n```typescript\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';\n\nconst transport = new StdioClientTransport({\n  command: 'npx',\n  args: ['-y', '@licinexusbr/mcp'],\n});\n\nconst client = new Client({ name: 'meu-app', version: '1.0.0' }, { capabilities: {} });\nawait client.connect(transport);\n\nconst tools = await client.listTools();\nconsole.log(tools);\n\nconst result = await client.callTool({\n  name: 'search_atas_rp',\n  arguments: { palavraChave: 'notebook', somenteVigentes: true },\n});\n```\n\n---\n\n## 🔧 Troubleshooting\n\n### \"Server failed to start\" ou \"command not found: npx\"\n\n**Causa:** Claude Desktop / outro cliente não acha o `npx` no `PATH`.\n\n**Solução:** use o caminho absoluto. Descubra com:\n\n```bash\nwhich npx\n```\n\nE substitua no config:\n\n```json\n{\n  \"mcpServers\": {\n    \"licinexus\": {\n      \"command\": \"/opt/homebrew/bin/npx\",\n      \"args\": [\"-y\", \"@licinexusbr/mcp\"]\n    }\n  }\n}\n```\n\n### \"Ferramentas não aparecem após salvar config\"\n\n**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.\n\n### \"EACCES\" ou erro de permissão\n\n**Causa:** cache do `npx` corrompido ou permissão de escrita.\n\n**Solução:**\n\n```bash\nnpm cache clean --force\nnpx -y @licinexusbr/mcp\n```\n\n### Versão antiga sendo executada\n\n**Causa:** `npx` mantém cache. Para forçar a versão mais recente:\n\n```bash\nnpx -y @licinexusbr/mcp@latest\n```\n\nE no config:\n\n```json\n\"args\": [\"-y\", \"@licinexusbr/mcp@latest\"]\n```\n\n### Timeout em consultas grandes\n\nAlgumas 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.\n\n### Logs e debug\n\nPara inspecionar requisições/respostas, rode manualmente no terminal:\n\n```bash\nLICINEXUS_LOG_LEVEL=debug npx -y @licinexusbr/mcp\n```\n\nE em outra janela, observe os logs enquanto o cliente faz chamadas.\n\n### Idioma das mensagens de erro\n\nPor padrão, as mensagens de erro retornadas pelas tools estão em português. Para recebê-las em inglês:\n\n```bash\nLICINEXUS_LANG=en npx -y @licinexusbr/mcp\n```\n\nValores aceitos: `pt` (padrão) ou `en`.\n\n## Ferramentas (18)\n\n### Compras / Licitações\n\n| Ferramenta                  | O que faz                                                                   |\n| --------------------------- | --------------------------------------------------------------------------- |\n| `search_licitacoes`         | Busca editais por data, modalidade, UF, CNPJ do órgão, valor, palavra-chave |\n| `get_licitacao`             | Detalhes completos de um edital pelo número de controle PNCP                |\n| `list_licitacao_itens`      | Itens (lotes) de um edital: descrições, quantidades, valores                |\n| `list_licitacao_resultados` | Resultados da disputa por item: vencedores, preços, fornecedores            |\n| `list_licitacao_arquivos`   | Documentos do edital (PDFs, anexos, termos de referência)                   |\n\n### Contratos\n\n| Ferramenta                   | O que faz                                                 |\n| ---------------------------- | --------------------------------------------------------- |\n| `search_contratos`           | Busca contratos por data, órgão, fornecedor, valor        |\n| `get_contrato`               | Detalhes completos de um contrato                         |\n| `list_contrato_termos`       | Termos aditivos (prorrogações, alterações de valor/prazo) |\n| `list_contrato_instrumentos` | Instrumentos de cobrança (NFes, faturas)                  |\n\n### Atas de Registro de Preço\n\n| Ferramenta       | O que faz                                                                      |\n| ---------------- | ------------------------------------------------------------------------------ |\n| `search_atas_rp` | Busca atas de RP — apenas vigentes por padrão. Encontra contratos utilizáveis. |\n| `get_ata_rp`     | Detalhes completos da ata + itens (com saldo disponível) + arquivos            |\n\n### Órgãos / Fornecedores / PCA\n\n| Ferramenta                 | O que faz                                                          |\n| -------------------------- | ------------------------------------------------------------------ |\n| `get_orgao`                | Perfil de órgão público (poder, esfera, natureza jurídica)         |\n| `get_fornecedor_contratos` | Contratos públicos de um CNPJ como fornecedor                      |\n| `search_pca`               | Plano de Contratação Anual — sinal antecipado do que será comprado |\n| `list_pca_itens`           | Itens planejados de um PCA específico                              |\n\n### Enriquecimento de CNPJ\n\n| Ferramenta      | O que faz                                                                                                                                                        |\n| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `get_cnpj_data` | Cadastro da Receita Federal (CNAEs, sócios, capital, situação) via [BrasilAPI](https://brasilapi.com.br) (padrão) ou MinhaReceita (`CNPJ_PROVIDER=minhareceita`) |\n\n### Análise agregada (v0.2.0)\n\n| Ferramenta                          | O que faz                                                                                                              |\n| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |\n| `aggregate_licitacoes_por_periodo`  | Série temporal de contagem (e opcional valor) sobre janela de até 5 anos, com bucketing dia/semana/mês/ano. Filtros por modalidade, UF, município, CNPJ, **esfera de governo** |\n| `compare_periodos`                  | Compara dois períodos lado-a-lado retornando totais + delta absoluto e percentual. Útil pra perguntas tipo \"houve antecipação em ano eleitoral?\" |\n\n## Prompts prontos (4)\n\nFluxos pré-construídos que seu assistente pode invocar diretamente:\n\n| Prompt                   | O que faz                                                          |\n| ------------------------ | ------------------------------------------------------------------ |\n| `analyze_edital`         | Lista de verificação de viabilidade de um edital                   |\n| `analyze_orgao`          | Perfil 360° de um órgão público                                    |\n| `find_arp_opportunities` | Encontra atas vigentes com saldo disponível para uma palavra-chave |\n| `check_supplier`         | Verificação básica de dado público sobre um CNPJ fornecedor        |\n\n## Recursos (2)\n\n| URI                       | Conteúdo                                              |\n| ------------------------- | ----------------------------------------------------- |\n| `licitacao://modalidades` | Tabela de referência de modalidades PNCP (Lei 14.133) |\n| `licinexus://scope`       | O que este MCP faz e o que não faz                    |\n\n## Exemplo de sessão\n\n```\nVocê:   Tem alguma ata de registro de preço vigente para notebooks?\nClaude: [chama search_atas_rp com palavraChave=\"notebook\", somenteVigentes=true]\n        Encontrei 12 atas vigentes mencionando notebooks. As 3 mais relevantes:\n        1. Ministério da Justiça — vigência até 2026-12-31, valor estimado R$ 2,4M\n        2. Prefeitura de São Paulo — vigência até 2026-09-30...\n\nVocê:   Detalhes da primeira, com saldos por item?\nClaude: [chama get_ata_rp includeItens=true]\n        - Item 1: Notebook tipo I (16GB RAM, 512GB SSD) — saldo 1.200 unid, R$ 4.800/un\n        - Item 2: Notebook tipo II ...\n```\n\n## Roteiro de evolução\n\n- [x] Fase 0 — Estrutura, governança, CI\n- [x] Fase 1 — Licitações (5 ferramentas)\n- [x] Fase 2 — Contratos + Aditivos + NFes (4 ferramentas)\n- [x] Fase 3 — Atas RP (2 ferramentas)\n- [x] Fase 4 — Órgãos + Fornecedores + PCA (4 ferramentas)\n- [x] Fase 5 — CNPJ + 4 prompts + 2 recursos (1 ferramenta)\n- [x] Teste de fumaça contra APIs reais (15/15 endpoints)\n- [x] **Fase 6 — Lançamento público** (11/05/2026 · v0.1.0 no [npm](https://www.npmjs.com/package/@licinexusbr/mcp))\n- [ ] Fase 7 — Adapters comunitários (TCE/TCM estaduais, ComprasNet legado)\n\n## Escopo\n\n### O que este MCP faz\n\n- Encapsula APIs **públicas** do governo brasileiro (PNCP, BrasilAPI).\n- Devolve dado bruto estruturado — o LLM faz a análise.\n- Mantém cache local de respostas pesadas (LRU em memória, TTL curto).\n\n### O que este MCP **não** faz\n\n- **Não** consulta nenhuma infraestrutura nem banco de dados privado da Licinexus.\n- **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- **Não** substitui o produto [Licinexus](https://licinexus.com.br) — é uma ferramenta open source complementar para a camada pública dos mesmos dados.\n\nVeja [docs/architecture.md](docs/architecture.md) para o modelo completo de separação em três paredes.\n\n## Precisa de matchmaking automático, alertas ou gestão de propostas?\n\nO 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.**\n\n→ <https://licinexus.com.br>\n\n## Como contribuir\n\nPRs são bem-vindos sob o [DCO](https://developercertificate.org/) (Developer Certificate of Origin) — assine seus commits com `git commit --signoff`.\n\nPor favor, **abra uma issue antes** para discutir qualquer mudança não trivial. Veja [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Suporte\n\nProjeto comunitário. **Melhor esforço, sem SLA.** Issues são triadas em até 7 dias quando possível.\n\nPara suporte pago e funcionalidades do produto, veja [licinexus.com.br](https://licinexus.com.br).\n\n## Segurança\n\nEncontrou uma vulnerabilidade? Veja [SECURITY.md](SECURITY.md) para divulgação responsável (não abra issues públicas).\n\n## Licença\n\nMIT © Licinexus. Veja [LICENSE](LICENSE).\n",
  "bytes": 17628,
  "sha": "4076642cc66f6c0f2e98e329a4161dd8d19e5cf4bb14cb8193c56c07a82c76f4",
  "repo_slug": "licinexus/licinexus-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_licinexus_mcp_4bd53edf/readme"
}