auxiliar-mcp 0.12.0 → 0.13.0

package/dist/data/capabilities.generated.json

@@ -513,6 +513,133 @@
         "page_url": "https://auxiliar.ai/service/authjs/",
         "external_homepage": "https://authjs.dev"
     },
+    {
+        "id": "auxiliar-cnpj-fetch",
+        "element_type": "data",
+        "name": "Auxiliar.ai CNPJ fetch (BrasilAPI → CNPJ.ws cascade)",
+        "description": "Drop-in CNPJ lookup. Returns razão social, primary + secondary CNAEs, regime tributário (Simples Nacional + MEI flags), situação cadastral, full address, QSA. Cascades BrasilAPI → CNPJ.ws on error. One auth surface for the rest of the auxiliar.ai gateway's 220+ Brazilian public-data tools.",
+        "jtbd_tags": [
+            "cnpj-enrichment",
+            "cnae-lookup",
+            "regime-tributario-lookup",
+            "simples-nacional-check",
+            "mei-lookup",
+            "brazilian-company-lookup",
+            "receita-federal",
+            "bookkeeping-enrichment",
+            "kyc-lookup",
+            "supplier-registry-enrichment",
+            "razao-social-lookup",
+            "situacao-cadastral-lookup"
+        ],
+        "aliases_search": [
+            "CNPJ lookup",
+            "CNPJ to CNAE",
+            "CNPJ regime tributário",
+            "Simples Nacional lookup",
+            "MEI lookup",
+            "Receita Federal CNPJ",
+            "razão social lookup",
+            "razao social lookup",
+            "CNAE primario",
+            "CNAE secundário",
+            "CNAE fiscal",
+            "empresa Receita Federal",
+            "supplier enrichment Brazil",
+            "bookkeeping CNPJ",
+            "auxiliar CNPJ",
+            "auxiliar-mcp CNPJ",
+            "fetch_cnpj",
+            "invoke_capability fetch_cnpj",
+            "api.auxiliar.ai cnpj"
+        ],
+        "categories": [
+            "public-data",
+            "brazilian-government",
+            "identifiers",
+            "bookkeeping"
+        ],
+        "works_with": [],
+        "fit_by_agent": {
+            "claude-code": true,
+            "claude-desktop": true,
+            "cursor": true,
+            "openclaw": true
+        },
+        "evals": [],
+        "cost": {
+            "type": "free",
+            "free_tier": "No-auth path goes through anonymous tier (LOW-sensitivity public data, 600 RPM shared across all unauth callers). Mint a personal token via Auxiliar-ai/scripts/issue_internal_token.py to upgrade to external tier (60 RPM per user) or internal tier (6000 RPM, for Dunas-class products) — gives you per-user telemetry and exclusive HIGH_PII tools (Direct Data CPF dossiê etc.). All CNPJ-enrichment fields are free at every tier; the upstream BrasilAPI / CNPJ.ws are themselves free.",
+            "hidden_costs": [
+                "Rate-limit hits return 429 — code your enrichment loop to back off and retry.",
+                "BrasilAPI / CNPJ.ws are sourced from Receita Federal open-data dumps with ~30-day lag; for real-time situação cadastral (KYC at supplier-onboarding time) the lag may matter."
+            ],
+            "cost_per_unit": {}
+        },
+        "pricing_tiers": [],
+        "compliance": [],
+        "risks": [
+            {
+                "severity": "medium",
+                "category": "regulatory",
+                "description": "Receita Federal open data has ~30-day publication lag. For real-time situação cadastral (a CNPJ that flipped to INAPTA / BAIXADA last week), use a paid commercial enrichment provider — out of scope for this free-tier cascade."
+            },
+            {
+                "severity": "low",
+                "category": "vendor_lockin",
+                "description": "The cascade order (BrasilAPI → CNPJ.ws) is a curated default. If you need a specific provider (e.g., CNPJ.ws for Inscrições Estaduais), call the provider's tool directly via invoke_capability(tool=\"<provider>_cnpj_fetch\") — the cascade is a convenience wrapper, not a gate."
+            }
+        ],
+        "deps": {
+            "requires": [
+                "auxiliar-mcp"
+            ],
+            "composes_with": [
+                "auxiliar-nfs-e",
+                "nfs-e-parser",
+                "brasilapi-cnpj",
+                "cnpj-ws"
+            ],
+            "conflicts": [],
+            "minimum_runtime": "Node 18+ (auxiliar-mcp's runtime); the gateway itself is hosted."
+        },
+        "install": {
+            "primary": {
+                "install_command": "claude mcp add auxiliar npx auxiliar-mcp",
+                "config_snippet": "# Once installed (no token needed for CNPJ — it's LOW-sensitivity),\n# invoke from your agent loop:\ninvoke_capability(\n  tool=\"fetch_cnpj\",\n  args={\"cnpj\": \"11.222.333/0001-81\"}\n)\n# Returns:\n# {\n#   \"tool\": \"fetch_cnpj\",\n#   \"source_module\": \"backend.sources.br.empresa.cnpj\",\n#   \"elapsed_ms\": 678,\n#   \"result\": {\n#     \"cnpj\": \"11222333000181\",\n#     \"razao_social\": \"BANCO DO BRASIL SA\",\n#     \"cnae_fiscal\": 6422100,\n#     \"cnae_fiscal_descricao\": \"Bancos múltiplos, com carteira comercial\",\n#     \"cnaes_secundarios\": [...],\n#     \"opcao_pelo_simples\": false,\n#     \"opcao_pelo_mei\": false,\n#     \"descricao_situacao_cadastral\": \"ATIVA\",\n#     \"logradouro\": \"...\", \"municipio\": \"...\", \"uf\": \"...\",\n#     \"qsa\": [...],\n#     \"source\": \"brasilapi\"   # or \"cnpjws\" if cascaded\n#   },\n#   \"scope\": {\"tier\": \"anonymous\", ...}\n# }\n",
+                "setup_url": "https://www.npmjs.com/package/auxiliar-mcp",
+                "estimated_minutes": 2
+            },
+            "by_agent": {
+                "claude-desktop": {
+                    "install_command": "Add to ~/Library/Application Support/Claude/claude_desktop_config.json",
+                    "config_snippet": "{\n  \"mcpServers\": {\n    \"auxiliar\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"auxiliar-mcp\"]\n    }\n  }\n}\n",
+                    "estimated_minutes": 5
+                },
+                "cursor": {
+                    "install_command": "Add via Cursor's MCP settings UI or .cursor/mcp.json",
+                    "config_snippet": "{ \"mcpServers\": { \"auxiliar\": { \"command\": \"npx\", \"args\": [\"-y\", \"auxiliar-mcp\"] } } }\n",
+                    "estimated_minutes": 3
+                },
+                "openclaw": {
+                    "install_command": "Direct HTTP — no MCP install required",
+                    "config_snippet": "# Renatoag-class agents that already speak HTTP can call the gateway directly:\ncurl -X POST https://api.auxiliar.ai/api/invoke/fetch_cnpj \\\n  -H \"content-type: application/json\" \\\n  -d '{\"cnpj\": \"11.222.333/0001-81\"}'\n# No auth required for CNPJ (anonymous tier, LOW-sensitivity).\n",
+                    "estimated_minutes": 1
+                }
+            },
+            "by_framework": {}
+        },
+        "last_verified": "2026-04-29",
+        "verification_method": "vendor-self-reported",
+        "alternatives_considered": [],
+        "compared_to": [],
+        "choose_if": "Your agent extracts CNPJs from invoices and needs to enrich them with CNAE (primary + secondary), regime tributário (Simples Nacional + MEI flags), razão social, full address, and QSA before writing to a ledger or coaching the user. Pick this over hand-rolling against BrasilAPI directly when you want (a) automatic fallback to CNPJ.ws on upstream errors, (b) one auth surface for the rest of your Brazilian-public-data agent flow (NFS-e parsing, judicial process, contracts, sanctions), (c) sub-second cached repeat lookups, (d) a clean upgrade path to per- user telemetry + higher rate limits when you mint a token.",
+        "avoid_if": "You only need a single CNPJ lookup and don't plan to use any other Brazilian-public-data tool — in that case curl BrasilAPI directly (`curl https://brasilapi.com.br/api/cnpj/v1/<cnpj>`) is one less dependency. Or, you need real-time situação cadastral (recently-flipped KYC status) — open-data lag means this cascade is ~30 days behind; use a paid commercial enrichment provider instead.",
+        "page_url": "https://auxiliar.ai/data/auxiliar-cnpj-fetch/",
+        "external_homepage": "https://api.auxiliar.ai/api/invoke/fetch_cnpj",
+        "repository": "https://github.com/Tlalvarez/Auxiliar-ai",
+        "license": "MIT (gateway code); upstream data per Receita Federal open data terms"
+    },
     {
         "id": "auxiliar-mcp",
         "element_type": "mcp",
@@ -1525,7 +1652,7 @@
             {
                 "severity": "low",
                 "category": "supply_chain",
-                "description": "BrasilAPI is community-maintained on Vercel. No SLA, no guaranteed uptime. Production workflows should cache responses and have a fallback (mcp-gov-cnpj-fetch or cnpj-ws)."
+                "description": "BrasilAPI is community-maintained on Vercel. No SLA, no guaranteed uptime. Production workflows should cache responses and have a fallback (auxiliar-cnpj-fetch or cnpj-ws)."
             }
         ],
         "deps": {
@@ -1535,7 +1662,7 @@
                 "nfs-e-parser",
                 "cnpja-cnpj",
                 "cnpj-ws",
-                "mcp-gov-cnpj-fetch"
+                "auxiliar-cnpj-fetch"
             ],
             "conflicts": [],
             "minimum_runtime": "Any HTTP client"
@@ -2373,7 +2500,7 @@
                 "cnpja-cnpj",
                 "cnpj-ws",
                 "receitaws-cnpj",
-                "mcp-gov-cnpj-fetch",
+                "auxiliar-cnpj-fetch",
                 "auxiliar-nfs-e",
                 "nfs-e-parser",
                 "auxiliar-mcp"
@@ -4565,101 +4692,6 @@
         "page_url": "https://auxiliar.ai/service/mailgun/",
         "external_homepage": "https://www.mailgun.com"
     },
-    {
-        "id": "mcp-gov-cnpj-fetch",
-        "element_type": "data",
-        "name": "mcp-gov: CNPJ fetch (Receita Federal)",
-        "description": "Public-data lookup: query Brazilian Receita Federal for CNPJ details (legal name, address, primary CNAE, regime tributário). Served via the mcp-gov MCP server.",
-        "jtbd_tags": [
-            "cnpj-enrichment",
-            "brazilian-company-lookup",
-            "receita-federal",
-            "bookkeeping-enrichment",
-            "kyc-lookup",
-            "cnae-lookup",
-            "regime-tributario-lookup",
-            "supplier-registry-enrichment"
-        ],
-        "aliases_search": [
-            "CNPJ lookup",
-            "Receita Federal CNPJ",
-            "mcp-gov CNPJ",
-            "Brazilian company lookup",
-            "razao social lookup",
-            "CNAE lookup",
-            "empresa Receita",
-            "regime tributário",
-            "Simples Nacional lookup",
-            "CNAE fiscal",
-            "supplier enrichment Brazil",
-            "bookkeeping CNPJ"
-        ],
-        "categories": [
-            "public-data",
-            "brazilian-government",
-            "identifiers"
-        ],
-        "works_with": [],
-        "fit_by_agent": {
-            "claude-code": true,
-            "claude-desktop": true,
-            "cursor": true,
-            "openclaw": true
-        },
-        "evals": [],
-        "cost": {
-            "type": "free",
-            "free_tier": "Receita Federal public endpoint; rate-limited per IP. mcp-gov adds no surcharge.",
-            "hidden_costs": [
-                "Rate-limit hits return cached or error responses — bursty consumers should batch with retries."
-            ],
-            "cost_per_unit": {}
-        },
-        "pricing_tiers": [],
-        "compliance": [],
-        "risks": [
-            {
-                "severity": "medium",
-                "category": "regulatory",
-                "description": "Receita Federal data is public but its publication cadence and field coverage change without notice. Agents writing to a ledger should validate that the returned CNPJ matches the queried one and treat missing fields as transient."
-            },
-            {
-                "severity": "low",
-                "category": "supply_chain",
-                "description": "mcp-gov is a third-party MCP server. Verify the install source and pin a version before deploying to a regulated workflow."
-            }
-        ],
-        "deps": {
-            "requires": [
-                "mcp-gov"
-            ],
-            "composes_with": [
-                "auxiliar-nfs-e",
-                "nfs-e-parser"
-            ],
-            "conflicts": [],
-            "minimum_runtime": "Python 3.10+ or Node 18+ (per mcp-gov runtime)"
-        },
-        "install": {
-            "primary": {
-                "install_command": "claude mcp add mcp-gov npx mcp-gov",
-                "config_snippet": "# Once mcp-gov is installed, the agent invokes:\ncnpj_fetch(cnpj=\"11.222.333/0001-81\")\n# Returns: {\"razao_social\": \"...\", \"nome_fantasia\": \"...\", \"endereco\": {...}, ...}\n",
-                "setup_url": "https://github.com/mcp-gov/mcp-gov",
-                "estimated_minutes": 3
-            },
-            "by_agent": {},
-            "by_framework": {}
-        },
-        "last_verified": "2026-04-26",
-        "verification_method": "vendor-self-reported",
-        "alternatives_considered": [],
-        "compared_to": [],
-        "choose_if": "Your agent extracts CNPJs from invoices and needs to enrich them with Receita Federal data (name, address, status) before writing to a ledger.",
-        "avoid_if": "You already have a paid commercial-enrichment provider (Serasa, Quod) or your workflow needs SLA-backed availability.",
-        "page_url": "https://auxiliar.ai/data/mcp-gov-cnpj-fetch/",
-        "external_homepage": "https://github.com/mcp-gov/mcp-gov",
-        "license": "Per mcp-gov upstream"
-    },
     {
         "id": "meilisearch",
         "element_type": "cloud_service",

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.12.0",
+    version: "0.13.0",
 });
 // 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).", {
@@ -166,7 +166,7 @@ server.tool("compare_capabilities", "Side-by-side comparison structure for 2-5 C
 // them. Routes to api.auxiliar.ai/api/invoke/<slug> where each slug is
 // a Python coroutine in backend/sources/<region>/. Returns the standard
 // envelope {tool, source_module, elapsed_ms, result}.
-server.tool("invoke_capability", "Execute a registered data-plane tool over HTTP. Use this to actually CALL a Capability the agent has discovered via find_capability/get_capability/list_capabilities — fetch a CNPJ, search Lei Rouanet projects, list Brasileirão standings, etc. Pass `tool` as the slug (e.g., 'fetch_cnpj', 'rouanet_projeto_fetch') and `args` as the kwargs dict the underlying function expects. Returns {tool, source_module, elapsed_ms, result}. Caching, rate limits, and retries are handled server-side.", {
+server.tool("invoke_capability", "Execute a registered data-plane tool over HTTP. Use this to actually CALL a Capability the agent has discovered via find_capability/get_capability/list_capabilities — fetch a CNPJ, search Lei Rouanet projects, list Brasileirão standings, etc. Pass `tool` as the slug (e.g., 'fetch_cnpj', 'rouanet_projeto_fetch') and `args` as the kwargs dict the underlying function expects. Returns {tool, source_module, elapsed_ms, result}. LOW-sensitivity tools work without auth — set AUXILIAR_GATEWAY_TOKEN for HIGH_PII tools (CPF dossiê, judicial process by CPF, etc.) and for higher rate limits. Caching, rate limits, and retries are handled server-side.", {
     tool: z.string().max(100).describe("Tool slug — the function name in the gateway registry (e.g., 'fetch_cnpj', 'rouanet_projeto_fetch', 'br_futebol_brasileirao_tabela'). Lowercase, underscore-separated, must start with a letter."),
     args: z.record(z.string(), z.unknown()).optional().describe("Keyword arguments for the tool. Pass an empty object for no-arg tools. Unknown args return 400; missing required args return 400."),
 }, async (params) => {

package/dist/tools/invoke-capability.d.ts

@@ -10,11 +10,22 @@
  * Caching, rate limiting, and retries already happen server-side inside
  * each source module — this client is intentionally thin.
  *
+ * Auth tiers (Phase 4A + Phase 4F):
+ *   - When AUXILIAR_GATEWAY_TOKEN is set, sent as ``Authorization: Bearer``.
+ *     Resolves to internal/external tier on the server with per-user
+ *     rate limits + per-(tenant, sub_tenant) cache scoping for HIGH_PII
+ *     tools. Mint via Auxiliar-ai/scripts/issue_internal_token.py.
+ *   - When unset, the request goes through unauthenticated. The gateway
+ *     dispatches LOW-sensitivity tools (CNPJ, NFS-e parser, public
+ *     records) under the anonymous tier. HIGH_PII tools (Direct Data
+ *     CPF dossiê, judicial-process-by-CPF, etc.) refuse anonymous with
+ *     HTTP 403 — set AUXILIAR_GATEWAY_TOKEN to access those.
+ *
  * Env knobs:
- *   - AUXILIAR_GATEWAY_URL   override base URL (default: api.auxiliar.ai)
- *   - AUXILIAR_GATEWAY_KEY   sent as x-auxiliar-key header when set
- *   - AUXILIAR_GATEWAY_TIMEOUT_MS  per-request timeout (default 60s,
- *                                  matching the longest budgeted source)
+ *   - AUXILIAR_GATEWAY_URL          override base URL (default api.auxiliar.ai)
+ *   - AUXILIAR_GATEWAY_TOKEN        Bearer token (preferred)
+ *   - AUXILIAR_GATEWAY_KEY          ops shared-key header (legacy break-glass)
+ *   - AUXILIAR_GATEWAY_TIMEOUT_MS   per-request timeout (default 60s)
  */
 export interface InvokeCapabilityParams {
     tool: string;

package/dist/tools/invoke-capability.js

@@ -10,11 +10,22 @@
  * Caching, rate limiting, and retries already happen server-side inside
  * each source module — this client is intentionally thin.
  *
+ * Auth tiers (Phase 4A + Phase 4F):
+ *   - When AUXILIAR_GATEWAY_TOKEN is set, sent as ``Authorization: Bearer``.
+ *     Resolves to internal/external tier on the server with per-user
+ *     rate limits + per-(tenant, sub_tenant) cache scoping for HIGH_PII
+ *     tools. Mint via Auxiliar-ai/scripts/issue_internal_token.py.
+ *   - When unset, the request goes through unauthenticated. The gateway
+ *     dispatches LOW-sensitivity tools (CNPJ, NFS-e parser, public
+ *     records) under the anonymous tier. HIGH_PII tools (Direct Data
+ *     CPF dossiê, judicial-process-by-CPF, etc.) refuse anonymous with
+ *     HTTP 403 — set AUXILIAR_GATEWAY_TOKEN to access those.
+ *
  * Env knobs:
- *   - AUXILIAR_GATEWAY_URL   override base URL (default: api.auxiliar.ai)
- *   - AUXILIAR_GATEWAY_KEY   sent as x-auxiliar-key header when set
- *   - AUXILIAR_GATEWAY_TIMEOUT_MS  per-request timeout (default 60s,
- *                                  matching the longest budgeted source)
+ *   - AUXILIAR_GATEWAY_URL          override base URL (default api.auxiliar.ai)
+ *   - AUXILIAR_GATEWAY_TOKEN        Bearer token (preferred)
+ *   - AUXILIAR_GATEWAY_KEY          ops shared-key header (legacy break-glass)
+ *   - AUXILIAR_GATEWAY_TIMEOUT_MS   per-request timeout (default 60s)
  */
 const DEFAULT_BASE_URL = "https://api.auxiliar.ai";
 const DEFAULT_TIMEOUT_MS = 60_000;
@@ -44,11 +55,18 @@ export async function invokeCapability(params) {
     const url = `${gatewayBaseUrl()}/api/invoke/${tool}`;
     const headers = {
         "content-type": "application/json",
-        "user-agent": "auxiliar-mcp/0.12",
+        "user-agent": "auxiliar-mcp/0.13",
     };
-    const apiKey = process.env.AUXILIAR_GATEWAY_KEY;
-    if (apiKey) {
-        headers["x-auxiliar-key"] = apiKey;
+    // Bearer token (preferred) wins over the shared-key fallback. With
+    // neither set, the request goes through unauthenticated and the
+    // gateway dispatches under anonymous tier.
+    const bearerToken = process.env.AUXILIAR_GATEWAY_TOKEN;
+    const sharedKey = process.env.AUXILIAR_GATEWAY_KEY;
+    if (bearerToken) {
+        headers["authorization"] = `Bearer ${bearerToken}`;
+    }
+    else if (sharedKey) {
+        headers["x-auxiliar-key"] = sharedKey;
     }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), gatewayTimeoutMs());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auxiliar-mcp",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "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",