Skip to main content
Glama
Dev10x-Guru

ksef-mcp

by Dev10x-Guru
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

render_invoice_pdf

Create an official PDF copy of an archived KSeF invoice locally, reproducing the exact format the Ministry's verification portal shows.

Instructions

Write one archived invoice as the PDF the Ministry's own application shows.

ksef_number names an invoice already in the archive. Nothing is fetched: this call spends none of the twenty metadata queries an hour and works with no network at all. An invoice that has not been synchronised yet is refused rather than downloaded, so the answer never depends on a query budget.

The document is produced by the Ministry's own generator, run locally from a build vendored with this package — the same code the verification portal loads into a browser. Fidelity is therefore official rather than approximate, and generator_version names the build, the same string the footer of the document carries.

working_directory overrides the directory declared during onboarding for this one call, under the same rules as the statement: created 0700 if new, refused inside the cache or data root, and reported in warnings when its path looks like a cloud sync folder or its permissions are wider than 0700. A synced directory the taxpayer acknowledged during onboarding is not reported again. The PDF names the counterparty exactly as the statement does.

On production the document carries the QR code and verification link, and verification_url repeats it here. Test and demo invoices have no verification surface, so both are absent rather than pointing at a page that would not resolve.

Requires Node — uvx cannot install it and a Python package cannot depend on it. Without Node this one call fails with a message saying what to install; synchronisation, the CSV statement and the listing are unaffected.

The generator accepts FA(1), FA(2), FA(3), UPO and PEF, but only FA(3) has been exercised end to end. Treat a refusal on an older schema as untested rather than impossible, and report it.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
ksef_numberYes
working_directoryNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
nipYes
pathYes
messageYes
warningsNo
byte_countYes
environmentYes
ksef_numberYes
verification_urlYes
generator_versionYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.3.4
    • changedOutput schema / description
      Previous value: -"Where the document is and what it was made with. Never its content."New value: +"Where the document is and what it was made with. Never its content.\n\nA PDF carries the same counterparty personal data the CSV statement does, so\nthe working-directory caveats inherited in `warnings` travel with it too\n(#172)."
    • addedOutput schema / properties / message
      Added value: +{
+  "title": "Message",
+  "type": "string"
+}
    • addedOutput schema / properties / warnings
      Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "title": "Warnings",
+  "type": "array"
+}
    • changedOutput schema / required
      Previous value: -[
-  "nip",
-  "environment",
-  "ksef_number",
-  "path",
-  "byte_count",
-  "generator_version",
-  "verification_url"
-]New value: +[
+  "nip",
+  "environment",
+  "message",
+  "ksef_number",
+  "path",
+  "byte_count",
+  "generator_version",
+  "verification_url"
+]
  2. Addedv0.3.0

TDQS

A4.8/5.0
Behavior5/5

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

There are no annotations, so the description carries the entire burden and meets it: no-network/no-quota behavior, vendored official generator, Node requirement with a precise failure mode, working-directory permission and warning rules, production-only verification URL, and untested FA schema variants are all disclosed.

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

Conciseness5/5

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

The description is front-loaded with a one-sentence purpose and then moves through quota, fidelity, directory behavior, output surface, runtime, and schema compatibility. Each paragraph adds a distinct piece of operational knowledge, and there is no filler.

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 tool with no annotations and a bare input schema, the description covers prerequisites, failure modes, supported schema variants, directory semantics, and output-surface differences. An agent has everything needed to decide whether and how to call it.

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

Parameters5/5

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

With 0% schema description coverage, the description fully compensates: ksef_number is explained as the archived-invoice identifier and 'refused' when unsynchronised, and working_directory's override semantics, 0700 creation, refusal locations, and warning conditions are all spelled out.

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 first sentence names a specific action and target: 'Write one archived invoice as the PDF the Ministry's own application shows.' It also distinguishes the tool from the period-statement, listing, and synchronisation siblings by limiting scope to a single archived invoice and stressing that nothing is fetched.

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

Usage Guidelines4/5

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

The description clearly situates the tool: use it for one already-synchronised invoice when an official local PDF is needed without spending metadata quota or requiring network. It stops short of explicitly naming sibling tools as alternatives or listing when-not-to-use cases, so a fully explicit routing statement is missing.

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

Deploy Server

Other Tools