auxiliar-mcp 0.13.0 → 0.13.2

package/dist/data/solve.js

@@ -233,31 +233,56 @@ export const solveTasks = {
     },
     "cnpj-enrichment-mcp": {
         slug: "cnpj-enrichment-mcp",
-        title: "CNPJ enrichment for Brazilian bookkeeping agents — what to install, ranked",
+        title: "CNPJ → CNAE + regime tributário (Simples / MEI) — tax-registry enrichment for Brazilian bookkeeping agents, ranked",
         url: "https://auxiliar.ai/solve/cnpj-enrichment-mcp/",
-        last_verified: "2026-04-27",
-        categories: ["cnpj-enrichment", "brazilian-bookkeeping", "public-data", "agent-tools"],
+        last_verified: "2026-04-29",
+        categories: [
+            "cnpj-cnae-lookup",
+            "cnpj-regime-tributario",
+            "tax-registry-enrichment",
+            "brazilian-bookkeeping",
+            "public-data",
+            "agent-tools",
+        ],
         works_with: ["claude-code", "claude-desktop", "cursor", "openclaw"],
-        alternatives: ["brasilapi-cnpj", "cnpja-cnpj", "cnpj-ws", "receitaws-cnpj", "mcp-gov-cnpj-fetch"],
-        eval_method: "auxiliar-cnpj-enrichment-documented-characteristics-v1 (5 candidates ranked by free-tier accessibility + field coverage; field-accuracy corpus eval is Phase-2 follow-up)",
-        answer: "When your Claude Code / OpenClaw agent has extracted CNPJs from NFS-e invoices and needs to enrich each one with razão social, CNAE, regime tributário (Simples Nacional flag), full address, partners, and supplier metadata — for bookkeeping batches, accountant handoff, or tax reconciliation — install BrasilAPI's free public endpoint: `curl https://brasilapi.com.br/api/cnpj/v1/<cnpj>`. Free, no auth, no token, drop-in URL; returns CNAE fiscal + secondary CNAEs, opção pelo Simples + MEI, situação cadastral, full address, sócios — sourced from Receita Federal open data dumps via MinhaReceita. For real-time situação cadastral, use CNPJá's paid api.cnpja.com tier. For Inscrições Estaduais (Sintegra) + branches, use CNPJ.ws.",
+        alternatives: [
+            "auxiliar-cnpj-fetch",
+            "brasilapi-cnpj",
+            "cnpja-cnpj",
+            "cnpj-ws",
+            "receitaws-cnpj",
+        ],
+        eval_method: "auxiliar-cnpj-enrichment-documented-characteristics-v2 (5 candidates ranked by agent-loop ergonomics + free-tier accessibility + field coverage + cascade resilience; field-accuracy corpus eval is Phase-2 follow-up)",
+        answer: "You've parsed your NFS-e invoices and now have a list of prestador CNPJs. The next step in any bookkeeping flow is tax-registry enrichment — for each CNPJ get CNAE primary + secondary, regime tributário (Simples Nacional + MEI flags), razão social, situação cadastral, full address, sócios. Top pick: install `auxiliar-mcp` (`claude mcp add auxiliar npx auxiliar-mcp`) and call `invoke_capability(tool: \"fetch_cnpj\", args: {cnpj})`. No token required for the free anonymous tier; the gateway cascades BrasilAPI → CNPJ.ws so a single upstream hiccup doesn't fail your enrichment loop. Same auth surface unlocks 220+ other Brazilian-public-data tools (NFS-e parsing, judicial process, sanctions, public contracts) when you grow into them. If you only need one-shot CNPJ lookup with zero install footprint, BrasilAPI direct (`curl https://brasilapi.com.br/api/cnpj/v1/<cnpj>`) is the simplest fallback.",
         candidates: [
             {
-                slug: "brasilapi-cnpj",
-                name: "BrasilAPI CNPJ",
+                slug: "auxiliar-cnpj-fetch",
+                name: "auxiliar-cnpj-fetch (gateway cascade — top pick)",
                 rank: 1,
+                install: "claude mcp add auxiliar npx auxiliar-mcp",
+                scorecard: {
+                    install_friction: 2,
+                    cost_per_10_docs_usd: 0,
+                },
+                notes: "Multi-provider cascade behind the auxiliar.ai gateway. Tries BrasilAPI first; on error falls through to CNPJ.ws. Returns CNAE primary + secondary, regime tributário (Simples + MEI flags), razão social, situação cadastral, full address, QSA. Anonymous tier (no token) for LOW-sensitivity public-data tools, 600 RPM shared. Mint AUXILIAR_GATEWAY_TOKEN for per-user telemetry, higher rate limits, and HIGH_PII tools (Direct Data CPF dossiê, etc.). Single auth surface scales to 220+ Brazilian-public-data tools.",
+                license: "MIT (gateway code); upstream data per Receita Federal open data terms",
+            },
+            {
+                slug: "brasilapi-cnpj",
+                name: "BrasilAPI CNPJ (direct, simplest)",
+                rank: 2,
                 install: 'curl -s "https://brasilapi.com.br/api/cnpj/v1/CNPJ_DIGITS_ONLY"',
                 scorecard: {
                     install_friction: 1,
                     cost_per_10_docs_usd: 0,
                 },
-                notes: "Free, no auth, no token. Drop-in HTTP GET. Returns CNAE primary + secondary, Simples + MEI flags, full address, sócios, situação cadastral. Data sourced from Receita Federal open dumps via MinhaReceita (~30-day lag). Hosted on Vercel CDN. The agent-friendliest default.",
+                notes: "Free, no auth, no token. Drop-in HTTP GET — same field shape as auxiliar-cnpj-fetch returns (since BrasilAPI is the cascade's first upstream). Pick this when you only need CNPJ enrichment and no other Brazilian-public-data tool. No fallback if BrasilAPI itself goes down.",
                 license: "MIT (BrasilAPI code; underlying data from Receita Federal open dump)",
             },
             {
                 slug: "cnpja-cnpj",
                 name: "CNPJá (free cached + paid real-time)",
-                rank: 2,
+                rank: 3,
                 install: 'curl -s "https://open.cnpja.com/office/CNPJ_DIGITS_ONLY"',
                 scorecard: {
                     install_friction: 2,
@@ -269,19 +294,19 @@ export const solveTasks = {
             {
                 slug: "cnpj-ws",
                 name: "CNPJ.ws (free 3 req/min + paid commercial)",
-                rank: 3,
+                rank: 4,
                 install: 'curl -s "https://publica.cnpj.ws/cnpj/CNPJ_DIGITS_ONLY"',
                 scorecard: {
                     install_friction: 2,
                     cost_per_10_docs_usd: 0,
                 },
-                notes: "Free tier 3 req/min on publica.cnpj.ws; paid commercial.cnpj.ws at 2000 req/min. Sources from Receita Federal + Sintegra + Suframa — deeper field coverage than peers (Inscrições Estaduais, branches/filiais, sócios with participation %).",
+                notes: "Free tier 3 req/min on publica.cnpj.ws; paid commercial.cnpj.ws at 2000 req/min. Sources from Receita Federal + Sintegra + Suframa — deeper field coverage than peers (Inscrições Estaduais, branches/filiais, sócios with participation %). Used as the cascade's second upstream inside auxiliar-cnpj-fetch.",
                 license: "Proprietary",
             },
             {
                 slug: "receitaws-cnpj",
                 name: "ReceitaWS",
-                rank: 4,
+                rank: 5,
                 install: 'curl -s "https://receitaws.com.br/v1/cnpj/CNPJ_DIGITS_ONLY"',
                 scorecard: {
                     install_friction: 2,
@@ -290,20 +315,8 @@ export const solveTasks = {
                 notes: "Long-running canonical Brazilian CNPJ API. Free 3 req/min cap; paid premium tier with token unlocks higher throughput. Simples Nacional flag is a paid-tier-only field — the free response returns simples: null. Simplest possible drop-in shape but slow on free tier.",
                 license: "Proprietary",
             },
-            {
-                slug: "mcp-gov-cnpj-fetch",
-                name: "mcp-gov-cnpj-fetch",
-                rank: 5,
-                install: "claude mcp add mcp-gov npx mcp-gov",
-                scorecard: {
-                    install_friction: 3,
-                    cost_per_10_docs_usd: 0,
-                },
-                notes: "MCP-routed wrapper for in-loop agent calls. Use when the agent prefers tool-call shape over HTTP, or when chaining mcp-gov for other public-data lookups (CEP, CNAE description, RAIS) in the same session.",
-                license: "Per mcp-gov upstream",
-            },
         ],
-        corpus_summary: "Documented vendor characteristics — free-tier accessibility, field coverage, real-time vs cached freshness, agent-friendliness — verified via direct curl tests against well-known CNPJs (Banco do Brasil 00.000.000/0001-91 etc.) on 2026-04-27. A 5–10 CNPJ field-accuracy corpus eval is Phase-2 follow-up tracked in backlog.md.",
+        corpus_summary: "Documented vendor characteristics — agent-loop ergonomics, free-tier accessibility, field coverage, cascade resilience — verified via direct curl tests against well-known CNPJs (Banco do Brasil 00.000.000/0001-91 etc.) and a live smoke-test of auxiliar-cnpj-fetch through api.auxiliar.ai/api/invoke/fetch_cnpj on 2026-04-29. A 5–10 CNPJ field-accuracy corpus eval is Phase-2 follow-up tracked in backlog.md.",
         alternatives_considered: [
             {
                 name: "Direct gov.br Conecta CNPJ API",
@@ -324,8 +337,12 @@ export const solveTasks = {
         ],
         faq: [
             {
-                q: "Does BrasilAPI return regime tributário (Simples Nacional flag) on the free tier?",
-                a: "Yes. BrasilAPI's CNPJ response includes opcao_pelo_simples: bool and opcao_pelo_mei: bool directly in the free response. ReceitaWS gates this field behind the paid tier — the free response returns simples: null. CNPJ.ws and CNPJá return Simples + MEI flags on their free tiers as well.",
+                q: "Does the cascade return regime tributário (Simples + MEI flags) on the free tier?",
+                a: "Yes. The auxiliar-cnpj-fetch envelope includes opcao_pelo_simples: bool and opcao_pelo_mei: bool directly. Same for BrasilAPI direct, CNPJ.ws publica, and CNPJá open. ReceitaWS gates the Simples flag behind the paid tier (its free response returns simples: null) — that's the one source where the regime tributário question costs money.",
+            },
+            {
+                q: "How does Brazil's regime tributário map onto these fields?",
+                a: "Three federal regimes: (1) Simples Nacional — simplified small-business regime; opcao_pelo_simples=true indicates this. (2) MEI (Microempreendedor Individual) — simplest individual-entrepreneur regime; opcao_pelo_mei=true indicates this. (3) Lucro Presumido / Lucro Real — for companies not in Simples or MEI. The free CNPJ APIs do NOT distinguish between these two; that's a Receita Federal internal classification not exposed publicly. If both flags are false, infer 'Lucro Presumido or Lucro Real' and use revenue/size proxies if you need to disambiguate.",
             },
             {
                 q: "When does the ~30-day data-dump lag actually matter?",
@@ -333,26 +350,27 @@ export const solveTasks = {
             },
             {
                 q: "How do I handle 429 rate-limit errors on the free tiers?",
-                a: "Two patterns. (1) Exponential backoff with Retry-After header respected. (2) Failover to a different source — BrasilAPI ↔ CNPJá open ↔ CNPJ.ws publica are roughly interchangeable for the basic CNAE + Simples + address fields. Code your enrichment loop to try BrasilAPI first, fall through to CNPJá open on 429, fall through to CNPJ.ws publica with a 20-second wait.",
+                a: "If you're using auxiliar-cnpj-fetch the cascade handles the BrasilAPI ↔ CNPJ.ws failover automatically. If you're calling sources directly: exponential backoff with Retry-After header respected, then failover to a different source — BrasilAPI ↔ CNPJá open ↔ CNPJ.ws publica are roughly interchangeable for the basic CNAE + Simples + address fields.",
             },
             {
                 q: "Does this work alongside auxiliar-nfs-e + Surya for a full bookkeeping pipeline?",
-                a: "Yes — that's the explicit composition. Pipeline: (1) Surya OCRs the NFS-e PDF to text. (2) auxiliar-nfs-e parses prestador + tomador + valor + ISS + CNPJs. (3) The CNPJs get enriched via BrasilAPI for CNAE + regime tributário. (4) The enriched record gets handed to your accountant or written to a ledger. The renatoag wedge validation on 2026-04-27 surfaced this /solve/ task as the missing step (3).",
+                a: "Yes — that's the explicit composition. Pipeline: (1) Surya OCRs the NFS-e PDF to text. (2) auxiliar-nfs-e parses prestador + tomador + valor + ISS + CNPJs. (3) The CNPJs get enriched via auxiliar-cnpj-fetch (or BrasilAPI direct) for CNAE + regime tributário. (4) The enriched record gets handed to your accountant or written to a ledger.",
             },
         ],
         methodological_caveats: [
             "This is documented-characteristics ranking, not field-accuracy ranking. Numbers from vendor docs and curl tests against well-known CNPJs, not a real-corpus accuracy eval. A field-accuracy corpus run is Phase-2 follow-up tracked in backlog.md.",
-            "Free-tier vendor terms can change without notice. Re-check rate limits + auth requirements before relying on any source for critical workflows. last_verified: 2026-04-27.",
+            "Free-tier vendor terms can change without notice. Re-check rate limits + auth requirements before relying on any source for critical workflows. last_verified: 2026-04-29.",
             "Data freshness varies. BrasilAPI / CNPJ.ws publica / CNPJá open are cached from open data dumps with cadence ranging from daily (CNPJá) to ~30 days (BrasilAPI / CNPJ.ws). For situações cadastrais needing real-time, only paid tiers apply.",
             "Inscrições Estaduais lag varies by state. CNPJ.ws sources from Sintegra which has per-state reporting cadence — some states report daily, others lag.",
             "No commercial-enrichment fields. None of the 5 ranked sources include Serasa-style credit signals, employee count ranges (Speedio), or revenue estimates. If those matter, use a paid commercial enrichment provider.",
+            "auxiliar-cnpj-fetch's anonymous-tier shares one global rate-limit bucket (default 600 RPM); for sustained per-user rate budget + telemetry, mint a token via Auxiliar-ai/scripts/issue_internal_token.py and set AUXILIAR_GATEWAY_TOKEN.",
         ],
-        update_cadence: "Re-run this ranking when: (a) BrasilAPI publishes a rate-limit cap or pricing tier (currently uncapped), (b) any of the 5 sources changes its free-tier shape (auth, field gating), (c) a Phase-2 field-accuracy corpus eval ships and updates the scorecard with measured numbers, (d) 90 days after first publish (2026-07-26).",
+        update_cadence: "Re-run this ranking when: (a) any cascade upstream (BrasilAPI / CNPJ.ws) publishes a rate-limit cap or pricing change, (b) any of the 5 sources changes its free-tier shape (auth, field gating), (c) a Phase-2 field-accuracy corpus eval ships and updates the scorecard with measured numbers, (d) 90 days after publish (2026-07-29).",
         fit_by_agent: {
-            "claude-code": { "brasilapi-cnpj": true, "cnpja-cnpj": true, "cnpj-ws": true, "receitaws-cnpj": true, "mcp-gov-cnpj-fetch": true },
-            "claude-desktop": { "brasilapi-cnpj": true, "cnpja-cnpj": true, "cnpj-ws": true, "receitaws-cnpj": true, "mcp-gov-cnpj-fetch": true },
-            cursor: { "brasilapi-cnpj": true, "cnpja-cnpj": true, "cnpj-ws": true, "receitaws-cnpj": true, "mcp-gov-cnpj-fetch": true },
-            openclaw: { "brasilapi-cnpj": true, "cnpja-cnpj": true, "cnpj-ws": true, "receitaws-cnpj": true, "mcp-gov-cnpj-fetch": true },
+            "claude-code": { "auxiliar-cnpj-fetch": true, "brasilapi-cnpj": true, "cnpja-cnpj": true, "cnpj-ws": true, "receitaws-cnpj": true },
+            "claude-desktop": { "auxiliar-cnpj-fetch": true, "brasilapi-cnpj": true, "cnpja-cnpj": true, "cnpj-ws": true, "receitaws-cnpj": true },
+            cursor: { "auxiliar-cnpj-fetch": true, "brasilapi-cnpj": true, "cnpja-cnpj": true, "cnpj-ws": true, "receitaws-cnpj": true },
+            openclaw: { "auxiliar-cnpj-fetch": true, "brasilapi-cnpj": true, "cnpja-cnpj": true, "cnpj-ws": true, "receitaws-cnpj": true },
         },
     },
 };

package/dist/server.js

@@ -16,7 +16,7 @@ import { compareCapabilities } from "./tools/compare-capabilities.js";
 import { invokeCapability } from "./tools/invoke-capability.js";
 const server = new McpServer({
     name: "auxiliar",
-    version: "0.13.0",
+    version: "0.13.2",
 });
 // Tool: recommend_service
 server.tool("recommend_service", "Get a current, verified recommendation for a cloud service based on your constraints. Returns pricing, risks, provision commands, and alternatives. Data is Chrome-verified from actual service websites (not stale training data).", {
@@ -81,7 +81,7 @@ server.tool("list_services", "List all available services and categories. Use wi
 });
 // Tool: solve_task
 server.tool("solve_task", "Fetch the full /solve/ task ranking for a specific job-to-be-done (e.g., 'extract text from PDFs', 'parse Brazilian NFS-e invoices'). Returns the ranked candidates with install commands, an evaluated scorecard (word accuracy, layout, latency, cost, install friction), alternatives considered and dropped, FAQs, and methodological caveats. Use this when an agent needs to pick an installable tool (skill/MCP/API/local binary) for a task rather than a cloud service. Data comes from a reproducible eval run on a real-world corpus — not training data.", {
-    task_slug: z.string().max(100).optional().describe("Task slug (e.g., 'pdf-text-extraction-mcp', 'nfs-e-extraction'). Aliases that resolve automatically: 'pdf', 'ocr', 'pdf-ocr', 'document-ai', 'invoice-extraction', 'boleto', 'receipt-parsing', 'bookkeeping-ocr' (→ PDF OCR ranking); 'nfs-e', 'nfse', 'nota-fiscal', 'nota-fiscal-eletronica', 'brazilian-invoice', 'cnpj-invoice' (→ NFS-e structured extraction). Call list_solve_tasks first if you don't know the slug."),
+    task_slug: z.string().max(100).optional().describe("Task slug (e.g., 'pdf-text-extraction-mcp', 'nfs-e-extraction', 'cnpj-enrichment-mcp'). Aliases that resolve automatically: 'pdf', 'ocr', 'pdf-ocr', 'document-ai', 'invoice-extraction', 'boleto', 'receipt-parsing', 'bookkeeping-ocr' (→ PDF OCR ranking); 'nfs-e', 'nfse', 'nota-fiscal', 'nota-fiscal-eletronica', 'brazilian-invoice', 'cnpj-invoice' (→ NFS-e structured extraction); 'cnpj', 'cnae', 'cnpj-cnae', 'cnpj-to-cnae', 'regime-tributario', 'regime-tributário', 'cnpj-regime-tributario', 'simples-nacional', 'mei', 'tax-registry', 'tax-registry-enrichment', 'cnpj-enrichment', 'razao-social', 'razão-social' (→ CNPJ tax-registry enrichment). Call list_solve_tasks first if you don't know the slug."),
     category: z.string().max(100).optional().describe("Filter by task category (e.g., 'ocr', 'pdf-processing', 'agent-tools'). Returns all matching tasks."),
 }, async (params) => {
     const result = await solveTask(params);

package/dist/tools/solve.js

@@ -30,7 +30,10 @@ const taskAliases = {
     "brazilian-invoice": "nfs-e-extraction",
     "brazilian-nfs-e": "nfs-e-extraction",
     "cnpj-invoice": "nfs-e-extraction",
-    // CNPJ enrichment task — public-data lookup ranker (renatoag wedge follow-up)
+    // CNPJ tax-registry enrichment task — public-data lookup ranker.
+    // Aliases extended 2026-04-29 after a renatoag-class autonomous-discovery
+    // sweep missed the page using "CNPJ → CNAE" / "regime tributário" /
+    // "tax-registry enrichment" as the agent's mental-model terms.
     "cnpj": "cnpj-enrichment-mcp",
     "cnpj-lookup": "cnpj-enrichment-mcp",
     "cnpj-enrichment": "cnpj-enrichment-mcp",
@@ -41,9 +44,21 @@ const taskAliases = {
     "cnpj-ws": "cnpj-enrichment-mcp",
     "cnae": "cnpj-enrichment-mcp",
     "cnae-lookup": "cnpj-enrichment-mcp",
+    "cnpj-cnae": "cnpj-enrichment-mcp",
+    "cnpj-to-cnae": "cnpj-enrichment-mcp",
     "regime-tributario": "cnpj-enrichment-mcp",
+    "regime-tributário": "cnpj-enrichment-mcp",
+    "cnpj-regime-tributario": "cnpj-enrichment-mcp",
+    "cnpj-regime-tributário": "cnpj-enrichment-mcp",
     "simples-nacional": "cnpj-enrichment-mcp",
+    "simples": "cnpj-enrichment-mcp",
+    "mei": "cnpj-enrichment-mcp",
+    "tax-registry": "cnpj-enrichment-mcp",
+    "tax-registry-enrichment": "cnpj-enrichment-mcp",
+    "tax-registry-brazil": "cnpj-enrichment-mcp",
     "razao-social": "cnpj-enrichment-mcp",
+    "razão-social": "cnpj-enrichment-mcp",
+    "razao-social-lookup": "cnpj-enrichment-mcp",
     "supplier-enrichment": "cnpj-enrichment-mcp",
     "supplier-registry": "cnpj-enrichment-mcp",
     "company-lookup-brazil": "cnpj-enrichment-mcp",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auxiliar-mcp",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Unified Capability index for AI agents — 80+ ranked cloud services, skills, MCP servers, plugins, parsers, and public-data sources for Claude Code, Cursor, Claude Desktop, OpenClaw. Call find_capability with a query or jtbd tag to get a ranked list across every kind of agent-installable thing. Also: get_capability, list_capabilities, compare_capabilities. Legacy tools (recommend_service, solve_task, list_services, list_solve_tasks, get_pricing, get_risks, setup_service, check_compatibility) remain wired for backward compatibility.",
   "type": "module",
   "main": "dist/server.js",