auxiliar-mcp 0.9.1 → 0.10.0

package/dist/data/solve.js

@@ -124,4 +124,111 @@ export const solveTasks = {
             openclaw: { tesseract: true, surya: true, "google-document-ai": true },
         },
     },
+    "nfs-e-extraction": {
+        slug: "nfs-e-extraction",
+        title: "NFS-e field extraction for agents — ranked by field accuracy on Brazilian São Paulo invoices",
+        url: "https://auxiliar.ai/solve/nfs-e-extraction/",
+        last_verified: "2026-04-23",
+        categories: ["nfs-e", "brazilian-invoice", "structured-extraction", "bookkeeping", "agent-tools"],
+        works_with: ["claude-code", "claude-desktop", "cursor", "openclaw"],
+        alternatives: ["auxiliar-nfs-e-with-surya", "auxiliar-nfs-e-with-google-doc-ai", "auxiliar-nfs-e-with-tesseract"],
+        eval_method: "auxiliar-nfs-e-field-accuracy-v1 (2-doc SP corpus)",
+        answer: "When your Claude Code / OpenClaw agent is asked to extract structured fields from a Brazilian NFS-e (Nota Fiscal Eletrônica de Serviços) — for bookkeeping, reimbursement batching, accountant handoff, tax reconciliation — install `auxiliar-nfs-e` paired with Surya OCR. On our 2-doc São Paulo NFS-e corpus it achieved 100% field accuracy (41/41 fields): numero_nota, codigo_verificacao, data_emissao, chave_acesso, prestador CNPJ/IM/nome/endereço, tomador CNPJ/IM/nome, valor_servico, codigo_servico, descrição, RPS reference, and more. Surya's OCR preserves line-level field ordering cleanly, which the parser's label-based extractor relies on. For budget-sensitive workflows, Google Document AI pairs with the same parser at 87.8% field accuracy and a ~$0.002/page cost after the 1,000-page/month free tier. Tesseract 5 is the fastest option but drops to 63.4% field accuracy because its default output reorders the retention/ISS table.",
+        candidates: [
+            {
+                slug: "auxiliar-nfs-e-with-surya",
+                name: "auxiliar-nfs-e + Surya",
+                rank: 1,
+                install: "python -m venv .venv && source .venv/bin/activate && pip install surya-ocr 'transformers<5.0.0' && git clone https://github.com/Tlalvarez/Auxiliar-ai.git /tmp/auxiliar && cp /tmp/auxiliar/scripts/walkthroughs/nfs-e-extraction/parser.py ./nfse_parser.py",
+                scorecard: {
+                    word_accuracy: 1.0,
+                    token_f1: 1.0,
+                    install_friction: 7,
+                    p50_latency_sec: 22.5,
+                    cost_per_10_docs_usd: 0,
+                },
+                notes: "100% field accuracy (41/41) on the 2-doc SP corpus. Surya preserves line-level field ordering. Parser extracts prestador, tomador, valor, codigo_servico, ISS, retenções, and RPS reference into a typed dataclass.",
+                license: "MIT (parser) + GPL-3.0 (Surya code) + AI Pubs Open Rail-M (Surya weights, <$2M clause)",
+            },
+            {
+                slug: "auxiliar-nfs-e-with-google-doc-ai",
+                name: "auxiliar-nfs-e + Google Document AI",
+                rank: 2,
+                install: "gcloud auth application-default login && gcloud services enable documentai.googleapis.com --project YOUR_PROJECT && git clone https://github.com/Tlalvarez/Auxiliar-ai.git /tmp/auxiliar",
+                scorecard: {
+                    word_accuracy: 0.878,
+                    install_friction: 7,
+                    p50_latency_sec: 3.8,
+                    cost_per_10_docs_usd: 0.069,
+                },
+                notes: "87.8% field accuracy (36/41). Lost valor_servico on doc 03 + RPS fields on doc 08. Cloud auth flow; 1000 pages/month free tier; data leaves local machine.",
+                license: "MIT (parser) + Proprietary (Google Cloud)",
+            },
+            {
+                slug: "auxiliar-nfs-e-with-tesseract",
+                name: "auxiliar-nfs-e + Tesseract 5",
+                rank: 3,
+                install: "brew install tesseract tesseract-lang poppler && git clone https://github.com/Tlalvarez/Auxiliar-ai.git /tmp/auxiliar",
+                scorecard: {
+                    word_accuracy: 0.634,
+                    install_friction: 3,
+                    p50_latency_sec: 1.6,
+                    cost_per_10_docs_usd: 0,
+                },
+                notes: "63.4% field accuracy (26/41). Retention table reorders in Tesseract output, breaking positional extraction for ISS/deductions fields. Use only when throughput > accuracy.",
+                license: "MIT (parser) + Apache 2.0 (Tesseract)",
+            },
+        ],
+        corpus_summary: "2 real São Paulo NFS-e invoices from Dunas's bookkeeping archive. Doc 03: legal services (Advocacia, R$ 3.900,00), Simples Nacional prestador. Doc 08: training services (R$ 25.000,00), includes RPS reference. Ground truth is the PDF's embedded text layer (authoritative for native-text NFS-e). Corpus is git-ignored (real business docs); ground-truth transcriptions and parser committed.",
+        alternatives_considered: [
+            {
+                name: "Pure OCR without a parser (Surya / Tesseract / Google Doc AI alone)",
+                dropped_because: "Returns raw text; agents then have to reimplement NFS-e field regex logic per project. The parser is the value.",
+            },
+            {
+                name: "LLM field extraction (prompt Claude/GPT with NFS-e text)",
+                dropped_because: "Non-deterministic, slower, more expensive per page, and requires additional verification step. For a regulated document with fixed structure, regex + position-based extraction is correct.",
+            },
+            {
+                name: "Generic invoice extractors on ClawHub (pdf-reader-mcp, openocr-skill, opendataloader-pdf)",
+                dropped_because: "None handle NFS-e's specific structure (SP retention table, chave de acesso format, RPS reference, inscrição municipal format). They solve 'read PDF text'; they don't solve 'extract CNPJ do prestador'.",
+            },
+            {
+                name: "PyPI packages nfce-xml / nfepy (official XML-format parsers)",
+                dropped_because: "These parse the official NFS-e XML API output (when you have API access). They don't handle PDF-first workflows, which is what agents receive from users.",
+            },
+        ],
+        faq: [
+            {
+                q: "Does this work for NFS-e from municipalities other than São Paulo?",
+                a: "Not yet. Each Brazilian municipality has a slightly different NFS-e layout (field labels, section headers, retention table format). The v0.1 parser is hand-tuned for São Paulo's form based on the 2-doc corpus. For other municipalities (Rio, Curitiba, Belo Horizonte, etc.), the parser needs an additional layout adapter. Until then, agents can still extract generic fields (CNPJ, dates, values via regex) but won't get the structured ISS/retention fields.",
+            },
+            {
+                q: "Why is Tesseract so much worse at field extraction than at raw text extraction?",
+                a: "Tesseract outputs text in a top-to-bottom reading order that doesn't preserve the NFS-e form's two-column retention table structure. Labels end up separated from values. The parser's label-based extractor falls back to positional heuristics for retention fields, which Tesseract's reordering breaks. Surya and Google Document AI preserve label-value proximity, so the parser hits 100% and 87.8% respectively.",
+            },
+            {
+                q: "How does this compare to hitting the São Paulo Prefeitura XML API directly?",
+                a: "The XML API is authoritative but requires credentials, the invoice's chave de acesso or number, and a non-trivial auth flow. When agents receive a PDF attachment in a bookkeeping workflow, the XML API isn't usable. The PDF-first parser lets agents work from the document the user actually shared.",
+            },
+            {
+                q: "Does the parser validate CNPJ check digits?",
+                a: "Yes. `parser.validate_cnpj(cnpj)` runs the standard Receita Federal CNPJ check-digit algorithm. Useful for flagging OCR errors before writing to a ledger.",
+            },
+        ],
+        methodological_caveats: [
+            "Corpus is 2 documents from the same issuer municipality (São Paulo). Field-accuracy claims apply to São Paulo NFS-e specifically.",
+            "Ground truth is the PDF's embedded text layer (pdftotext), authoritative for native-text NFS-e but wouldn't apply to scanned images of printed NFS-e.",
+            "Field accuracy metric counts exact-string match per field; fuzzy matches would inflate accuracy slightly. Exact-match chosen for zero-error bookkeeping reliability.",
+            "Retention values (all zeros in the corpus because both prestadores are Simples Nacional) are extracted by position. Non-zero retention edge cases not yet end-to-end tested.",
+            "CNPJ validation uses the check-digit algorithm but doesn't query Receita Federal for active-status; a valid check-digit CNPJ can still be an inactive company.",
+        ],
+        update_cadence: "Re-run this walkthrough when: (a) any of the three OCR candidates ships a major version, (b) the São Paulo Prefeitura changes the NFS-e form layout (watched via the scanner module's BR government feeds), (c) 90 days after first publish (2026-07-23), (d) new NFS-e parser skills emerge on ClawHub / PyPI / npm.",
+        fit_by_agent: {
+            "claude-code": { "auxiliar-nfs-e-with-surya": true, "auxiliar-nfs-e-with-google-doc-ai": true, "auxiliar-nfs-e-with-tesseract": true },
+            "claude-desktop": { "auxiliar-nfs-e-with-surya": true, "auxiliar-nfs-e-with-google-doc-ai": true, "auxiliar-nfs-e-with-tesseract": true },
+            cursor: { "auxiliar-nfs-e-with-surya": true, "auxiliar-nfs-e-with-google-doc-ai": true, "auxiliar-nfs-e-with-tesseract": true },
+            openclaw: { "auxiliar-nfs-e-with-surya": true, "auxiliar-nfs-e-with-google-doc-ai": true, "auxiliar-nfs-e-with-tesseract": true },
+        },
+    },
 };

package/dist/server.js

@@ -76,7 +76,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'). Aliases like 'pdf', 'ocr', 'invoice-extraction', 'nfs-e', 'boleto', 'receipt-parsing', 'bookkeeping-ocr', 'document-ai' also resolve. 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'). 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."),
     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

@@ -4,7 +4,7 @@ import { pingApi } from "./analytics.js";
 // task. Kept separate from the category-alias maps in list.ts / recommend.ts
 // because /solve/ tasks are about *jobs to be done*, not service categories.
 const taskAliases = {
-    // PDF text extraction task
+    // PDF text extraction task — generic OCR/PDF ranker
     "pdf": "pdf-text-extraction-mcp",
     "pdfs": "pdf-text-extraction-mcp",
     "pdf-extraction": "pdf-text-extraction-mcp",
@@ -18,10 +18,18 @@ const taskAliases = {
     "invoice-parsing": "pdf-text-extraction-mcp",
     "receipt-parsing": "pdf-text-extraction-mcp",
     "receipt-ocr": "pdf-text-extraction-mcp",
-    "nfs-e": "pdf-text-extraction-mcp",
-    "nfse": "pdf-text-extraction-mcp",
     "boleto": "pdf-text-extraction-mcp",
     "bookkeeping-ocr": "pdf-text-extraction-mcp",
+    // NFS-e structured-extraction task — Brazilian-specific parser
+    "nfs-e": "nfs-e-extraction",
+    "nfse": "nfs-e-extraction",
+    "nfs-e-parser": "nfs-e-extraction",
+    "nota-fiscal": "nfs-e-extraction",
+    "nota-fiscal-eletronica": "nfs-e-extraction",
+    "nota-fiscal-servicos": "nfs-e-extraction",
+    "brazilian-invoice": "nfs-e-extraction",
+    "brazilian-nfs-e": "nfs-e-extraction",
+    "cnpj-invoice": "nfs-e-extraction",
 };
 function resolveSlug(raw) {
     const lower = raw.toLowerCase().trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auxiliar-mcp",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Agent-installable-tool rankings (OCR, PDF extraction, NFS-e, bookkeeping, and more) for Claude Code, Cursor, Claude Desktop, OpenClaw — evaluated on real-world corpora. Call solve_task to get the best skill/MCP/API/local binary for a task, ranked by word accuracy, layout, latency, cost, and install friction. Also Chrome-verified pricing, risks, and setup for 77 cloud services.",
   "type": "module",
   "main": "dist/server.js",