v0.2.0 — MCP analítico (Fase 7)

Minor release — MCP analítico (Fase 7). Vira o servidor de "lookup transacional" para "agregação temporal + comparação". Resolve #17.

✨ Novidades

aggregate_licitacoes_por_periodo

Série temporal de contagem (e opcionalmente valor) sobre uma janela de até 5 anos, com bucketing por dia / semana / mes / ano. Filtros: modalidades, uf, codigoMunicipioIbge, cnpjOrgao, esfera.

• Modo rápido (count apenas, sem esfera): 1 call por bucket × modalidade — devolve totalRegistros do PNCP. Para 12 meses × 3 modalidades = 36 calls, em ~10s.
• Modo paginado (com esfera ou métricas de valor): caps em 50 páginas/bucket e 200 buckets-modalidade no total. Concurrency interna de 4 em paralelo.

Exemplo:

{
  "dataInicial": "20240101",
  "dataFinal": "20240630",
  "granularidade": "mes",
  "modalidades": [6],
  "metricas": ["count"]
}

Retorna [{periodo: "2024-01", count: 8185}, ..., {periodo: "2024-06", count: 32921}].

compare_periodos

Compara dois períodos lado-a-lado com os mesmos filtros, retornando totais por métrica + delta { absoluto, percentual }.

Caso de uso primário: questões como "Houve antecipação de licitações em Jun/2024 (eleitoral, pré-vedação) comparado a Jun/2025?"

{
  "periodoA": { "label": "Jun/2024 (eleitoral)", "dataInicial": "20240601", "dataFinal": "20240630" },
  "periodoB": { "label": "Jun/2025 (controle)", "dataInicial": "20250601", "dataFinal": "20250630" },
  "modalidades": [6, 8, 9]
}

Resultado da query acima rodando contra o PNCP ao vivo: +2,6% em 2025 vs 2024 — nenhuma antecipação eleitoral mensurável em junho do ano eleitoral.

Filtro esfera em todas as search tools

Disponível em search_licitacoes, search_contratos, search_atas_rp:

{ "esfera": "municipal", ... }

Valores: federal / estadual / municipal / distrital. Aplicado client-side sobre orgaoEntidade.esferaId (PNCP usa mapping F/E/M/D).

Limitações conhecidas

• search_pca ainda não suporta filtro esfera — o endpoint de PCA do PNCP não retorna esferaId. Cruze o orgaoCnpj retornado com get_orgao para esse recorte.
• Modo paginado em aggregate_licitacoes_por_periodo pode dar timeout em janelas grandes com filtro esfera — use janelas menores ou granularidade mais grossa.

Tools totais: 16 → 18

Install / Upgrade

npx -y @licinexusbr/mcp@latest

Ou no seu claude_desktop_config.json (ou equivalente do seu cliente MCP), forçar refresh:

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

v0.1.3 — fix PNCP 365-day window (#15)

Bug fix patch — resolve #15.

Fixed

• #15: search_licitacoes, search_contratos, search_atas_rp e search_pca agora validam que a janela dataInicial..dataFinal não excede 365 dias antes de chamar o PNCP. Janelas maiores retornavam apenas PNCP returned HTTP 422 for /contratacoes/publicacao, sem o corpo da mensagem do PNCP — o que dificultava o diagnóstico. Agora a tool devolve mensagem clara:

  Date range of N days exceeds the PNCP limit of 365 days. Reduce the window between dataInicial (...) and dataFinal (...).

• describeAxiosError agora extrai o campo message do corpo de erros 4xx do PNCP. A mensagem original do PNCP (ex.: "Período inicial e final maior que 365 dias.") aparece direto no output da tool em vez de só o status HTTP.

Changed

• Tool descriptions de search_licitacoes, search_contratos, search_atas_rp e search_pca documentam o limite de 365 dias por chamada — assim o LLM evita tentar janelas maiores.

Added

• PNCP_MAX_DATE_RANGE_DAYS, daysBetweenPncpDates, validatePncpDateRange em src/utils/dates.ts — utilitários reutilizáveis para validação de janela.

---

Próxima geração (v0.2.0): #17 — análise agregada e temporal. Aceitando feedback.

Install

npx -y @licinexusbr/mcp@latest

v0.1.2 — Docs expansion + stdio clarity

What's new

Documentation-only release responding to community feedback from the launch.

📖 Expanded usage guide (7 MCP clients)

Replaced the minimal Install section with a detailed guide covering Claude Desktop, Cursor, Continue.dev, Cline/Roo, Zed, ChatGPT (via OpenAI Agents SDK), and programmatic stdio access. Plus first prompts to try, how to verify it worked, and a Troubleshooting section.

Both PT 🇧🇷 and EN 🇺🇸 READMEs updated symmetrically.

⚠️ stdio behavior warning

Added prominent warning explaining the server is stdio-based, not meant to be run directly in terminal, and npx -y doesn't install globally.

This closes #14 (feedback from @ldutra).

🎬 Launch video with music

Re-rendered with royalty-free cinematic background track.

---

No API/code changes. All 16 tools and 4 prompts behave identically to v0.1.1.

Install

npx -y @licinexusbr/mcp

Full Changelog: v0.1.1...v0.1.2

v0.1.1 — BrasilAPI fallback + Official MCP Registry

What changed

Added

• BrasilAPI fallback for get_orgao — when PNCP returns 502/503/504 or times out, the tool now falls back to BrasilAPI's CNPJ endpoint and maps razao_social, nome_fantasia, natureza_juridica, descricao_situacao_cadastral, municipio, and uf into the Orgao schema. Fallback responses include a _source: "brasilapi-fallback" marker so clients can detect degraded mode.
• mcpName: "io.github.Licinexus/mcp" in package.json — required by the Official MCP Registry for ownership verification. Registration submission follows.

Tests

• 6 new unit tests cover the fallback paths (success, 502, 503, timeout, 404 non-fallback, fallback-also-fails). 44/44 total green.

Context

PNCP detail endpoints showed transient 502/503 errors during the v0.1.0 launch window (~40% failure rate over the previous 10 days). The fallback above keeps the most-used get_orgao tool working through PNCP backend incidents. Tools that have no public alternative still return isError: true with a structured error message instead of crashing.

Install

npx -y @licinexusbr/mcp@0.1.1

For Claude Desktop, no config change needed — npx -y @licinexusbr/mcp always picks up the latest published version.

Links

• npm: https://www.npmjs.com/package/@licinexusbr/mcp
• Full diff: v0.1.0...v0.1.1