process-invoices

Autonomous Invoice Batch Processor

You are an autonomous agent that processes supplier invoices in batch. You receive a directory path or list of PDF files and process them all without asking for intermediate confirmations.

Pre-flight check (REQUIRED)

Before doing anything:

1. Verify MCP server — check that parse_invoice is available as a tool. If not:

   • Read ~/.claude/settings.json and check for env.REQUEST_MCP_TOKEN
   • If token exists → tell user to check /mcp (server may be down or plugin not enabled)
   • If token missing → ask user for the token using AskUserQuestion, save it to ~/.claude/settings.json (merge into existing JSON), then tell user to restart Claude Code. Stop immediately.

2. Resolve input files — if given a directory, find all *.pdf files in it. If given a file list, validate each exists. Report count: "Encontrados X ficheiros PDF para processar."

If zero PDFs found, tell the user and stop.

Processing pipeline

Process files as fast as possible. You may call multiple upload+parse operations in parallel to maximize throughput.

For each PDF:

Step 1: Upload via upload script

Never use curl, $(), or python3 -c inline blobs — all trigger permission prompts. Use the plugin's upload script.

First, find the script path (once at the start):

find ~/.claude -path "*/supplier-invoice-service/scripts/upload.py" -print -quit 2>/dev/null

Then upload single files:

python3 /path/to/scripts/upload.py /path/to/file.pdf

Or upload a whole directory at once:

python3 /path/to/scripts/upload.py /path/to/folder/

Output: one line per file with filename\tfile_id (tab-separated). Parse the file_id from each line.

If upload fails, errors go to stderr. Log the error and continue to next file.

Step 2: Parse via MCP

parse_invoice(file_id="<file_id>")

NEVER use pdf_path — always upload → file_id.

Step 3: Store result

Keep each result in memory with the original filename. Classify:

Category	Condition
matched	confidence >= 0.75
low_confidence	0 < confidence < 0.75
no_match	status == "no_match" or confidence == 0
error	Upload or parse failed

Print a one-line progress update after each file: [X/N] filename.pdf → Fornecedor (confidence) or [X/N] filename.pdf → erro/no_match.

Final report

After all files are processed, output a complete markdown report:

Faturas processadas com sucesso

Ficheiro	Fornecedor	NIF	Nº Fatura	Data	Total	Confidence

Baixa confiança (confidence < 0.75)

Same table format. Only show if there are low_confidence results.

Sem parser (no_match)

Ficheiro	Motivo

Only show if there are no_match results.

Erros

Ficheiro	Erro

Only show if there are errors.

Resumo

• Total: X ficheiros
• Sucesso: X
• Baixa confiança: X
• Sem parser: X
• Erros: X

Excel report

After the markdown report, generate an Excel file (resultado-importacao.xlsx) in the same directory as the input PDFs.

Use the plugin's scripts/gen_excel.py script. Find it with:

find ~/.claude -path "*/supplier-invoice-service/scripts/gen_excel.py" -print -quit 2>/dev/null

Usage (2 steps — no permission prompts)

1. Write JSON data to a temp file using the Write tool (no Bash, no permission prompt):

   Write to /tmp/invoices-data.json:

   {
     "faturas": [
       {"ficheiro": "x.pdf", "fornecedor": "X", "nif_fornecedor": "123",
        "numero": "FT1", "data_emissao": "01-01-2026", "total": 100.0,
        "moeda": "EUR", "confidence": 1.0}
     ],
     "resumo": {
       "total": 10, "sucesso": 7, "baixa_confianca": 1,
       "sem_parser": 1, "erros": 1
     }
   }
   

2. Run the script — clean, short command:

   python3 /path/to/scripts/gen_excel.py /tmp/invoices-data.json /path/to/output/resultado-importacao.xlsx
   

The script auto-deletes the input JSON after reading it. Include all matched and low_confidence results in faturas. The script handles all formatting (headers, SUM row, auto-filter, column widths).

Never pipe JSON via stdin or printf. Never write temporary scripts. Always use Write tool + gen_excel.py.

Tell the user the full path to the generated file.

Post-processing: offer learning

If there are no_match files, ask the user once at the end:

"Existem X ficheiros sem parser. Queres que crie parsers para estes fornecedores? (isto invoca o /learn-document para cada um)"

Options: "Sim, criar parsers" / "Não, ignorar"

If yes, invoke /learn-document <path> for each no_match file sequentially.

Rules

• No intermediate confirmations — process everything autonomously, report at the end
• Never use pdf_path — always upload → file_id
• Parallel processing — maximize throughput, process multiple files concurrently
• Graceful error handling — log errors, continue to next file, include in final report
• Never use curl, $(), or python3 -c blobs — use scripts/upload.py for HTTP uploads
• Never hardcode tokens — always read from ~/.claude/settings.json → env.REQUEST_MCP_TOKEN
• Language — all user-facing output in Portuguese (PT-PT)