csv2zugferd

Overview Schema Source Related Servers Discussions Admin

Trial run invoice mapping

csv2zugferd_invoice_get

Read-onlyIdempotent

Maps a CSV invoice to ZUGFeRD XML in memory without writing files, returning totals, tax breakdown, warnings, and optional line-item, party, and PDF template checks.

Instructions

Runs the real csv2zugferd mapping for one CSV file with the given configuration (configPath or configYaml) without writing any output file: reads the CSV, maps header, parties, line items and totals, builds the ZUGFeRD XML in memory and returns invoice number, type, totals, tax breakdown, warnings with codes and paths, and the XML size. includeLineItems and includeParties (default false) add details; pdfTemplatePath also embeds the XML into a temporary PDF copy to check format and template. Does not create the XML or PDF for production; that is done by the csv2zugferd CLI (csv2zugferd_config_file_create returns the command). Read-only for the user's files; a temporary PDF is created and deleted only with pdfTemplatePath.

Input Schema

Name	Required	Description
`csvPath`	Yes	Path to the CSV file with the invoice data.
`configPath`	No	Path to an existing YAML configuration file. Use either configPath or configYaml, not both.
`configYaml`	No	YAML configuration as text (the content of config.yml). Use either configPath or configYaml, not both.
`includeParties`	No	True adds seller and buyer (name, city, country) to the result.
`pdfTemplatePath`	No	Optional PDF template: the trial run also embeds the XML into a copy of this PDF in the temp directory (deleted afterwards) and reports its size, which checks zugferd.format and the template.
`includeLineItems`	No	True adds the mapped line items (name, quantity, unit, price, line total, tax rate) to the result.

Output Schema

Name	Required	Description
`format`	Yes	Effective XML syntax (applied in the PDF only).
`totals`	Yes	Document totals (BG-22).
`parties`	No	Seller and buyer; only with includeParties.
`profile`	Yes	Effective ZUGFeRD profile as library name; a configured EN16931 is reported as Comfort (same profile).
`version`	Yes	Effective ZUGFeRD version.
`currency`	Yes	Currency code (BT-5).
`pdfBytes`	No	Size of the generated PDF in bytes; only with pdfTemplatePath.
`rowCount`	Yes	Data rows read from the CSV.
`typeCode`	Yes	Invoice type code (BT-3), for example 380.
`warnings`	Yes	All findings of the run: document checks, fallbacks, unparsable values, ignored or missing sections.
`xmlBytes`	Yes	Size of the generated XML in bytes.
`lineItems`	No	Mapped line items; only with includeLineItems.
`invoiceDate`	Yes	Invoice date (BT-2) as yyyy-MM-dd; 0001-01-01 when the date could not be parsed.
`taxBreakdown`	Yes	VAT breakdown per rate and category (BG-23).
`invoiceNumber`	Yes	Invoice number (BT-1) as mapped.
`lineItemCount`	Yes	Line items in the invoice.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 9, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/non-destructive annotations, it discloses exactly what happens: reads the CSV, maps header, parties, line items and totals, builds XML in memory, returns specific result fields, and writes no output file. It also clarifies the one temporary side effect, a temporary PDF created and deleted only when pdfTemplatePath is supplied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The key dry-run behavior and no-production-output constraint are front-loaded, and every sentence carries useful information. It is somewhat dense as a single paragraph, and some return-value detail is redundant given the output schema, but it is not wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex mapping tool, the description covers the operation, the no-output-file guarantee, the temporary PDF caveat, the returned information, and the distinction from production generation. With the output schema present, no critical agent-facing context is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already documents every parameter, including the configPath/configYaml mutual exclusivity and the includeLineItems, includeParties, and pdfTemplatePath behaviors. The description reinforces those meanings but adds little beyond what the schema already provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific operation: running the real csv2zugferd mapping as a trial for one CSV file without writing production output. It clearly distinguishes this dry-run mapping from production XML/PDF creation, which it attributes to the csv2zugferd CLI, and confirms that config_file_create returns the command.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains the intended use as a trial/validation run and explicitly says it does not create the production XML or PDF. It names the alternative path, the csv2zugferd CLI, and explains that config_file_create returns the command to use for production.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server