Loading ToolBench
MCP server for Polish electronic invoicing — KSeF FA(3)/FA(2) and Peppol BIS 3.0/EN 16931, direct-to-KSeF, no intermediary
Strong domain-specific tool set with clear naming (verb_noun pattern) and comprehensive descriptions. All 17 tools have descriptions (194 - 500+ chars, well above 10-char minimum). Input schemas present with type declarations. However, output schemas are not documented in the visible code, and several tools lack parameter-level descriptions or constraints. Error handling guidance is minimal. Tool composition is sound (each does one thing), but some tools expose raw API complexity (e.g., session_token, confirmation_token parameters) rather than abstracting it. No tool annotations (readOnlyHint/destructiveHint) visible despite clear risk classifications in the spec.
Generate a KSeF-compliant FA(2) XML invoice from structured invoice data. Returns the FA(2) XML string ready for submission to KSeF. The seller's nip must be a Polish NIP (10 digits).
Generate a KSeF-compliant FA(3) XML invoice from structured invoice data. FA(3) is required for all new invoice submissions via KSeF API v2. Use this tool, not generate_fa2_invoice, before calling submit_invoice_to_ksef. The seller's nip must be a Polish NIP (10 digits). The buyer's nip may be a Polish NIP, eu_vat_country/eu_vat_id for EU cross-border, or neither (emits <BrakID>). Use the optional `options` parameter to supply: - IPKSeF / LinkDoPlatnosci payment identifiers (PL-2.2) - Correction invoice reference (rodzaj_faktury=KOR + correction block) (PL-4.1) - Supporting document attachments (<Zalacznik>) (PL-2.3) - Additional buyer entities (<Podmiot3>) (PL-2.4) - Authorised representative (<PodmiotUpowazniony>) (PL-2.4) Returns the FA(3) XML string ready for submit_invoice_to_ksef.
Generate a Peppol BIS 3.0 / EN 16931 UBL XML invoice from structured invoice data. Returns the UBL XML string ready for transmission via Peppol network or direct B2B exchange. The seller's party identifier must be a valid Peppol participant ID (scheme:value). Common schemes: 9945 (PL:VAT), 0088 (EAN), 0192 (ICD), etc. Use generate_fa3_invoice for KSeF submission; use this tool for Peppol/EN 16931 workflows.
Retrieve an EN 16931 codelist (e.g., country codes, currency codes, unit codes, VAT categories). Returns a list of valid codes and their descriptions.
Output schemas not documented. Tools return structured data but LLMs cannot see what fields to expect. Downstream tool chaining requires guesswork.
Tool annotations missing. submit_invoice_to_ksef is IRREVERSIBLE and search_ksef_invoices is READ_ONLY, but no readOnlyHint/destructiveHint visible in schema. LLMs cannot infer safety properties.
Parameter-level descriptions incomplete. 'codelist_name' in get_en16931_codelist lacks enum constraint or valid values list. 'subject_type' in search_ksef_invoices mentions case-insensitivity but no enum.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 62 | <=2025-11-25 | v2 |
Retrieve the processing status of a submitted KSeF invoice (API v2). Parameters ---------- reference_number: The 'reference_number' field from submit_invoice_to_ksef ("{sessionRef}:{invoiceRef}"). Pass just the sessionRef to retrieve the overall session status instead.
Parse a KSeF FA(2) XML invoice into a structured dictionary. Returns a nested dict with 'header', 'seller', 'buyer', 'invoice', and 'lines' keys.
Parse a Peppol BIS 3.0 / EN 16931 UBL XML invoice into a structured dictionary. Returns a nested dict with invoice header, seller, buyer, line items, and totals.
Look up a Peppol participant in the Service Metadata Publisher (SMP) network. Returns participant metadata including supported document types and endpoints.
Resolve Peppol DNS SMP discovery records (NAPTR) for a participant identifier. Diagnostic tool for troubleshooting Peppol network connectivity.
Query invoices stored in KSeF for a date range. Parameters ---------- date_from: Start date in YYYY-MM-DD format. date_to: End date in YYYY-MM-DD format. subject_type: 'Subject1' (seller), 'Subject2' (buyer), 'Subject3' (third party), or 'SubjectAuthorized' (authorised representative). Case-insensitive; normalized to the KSeF v2 PascalCase enum before submission.
Submit a FA(3) XML invoice to the KSeF platform (API v2). KSeF API v2 requires FA(3) format for submission. Use generate_fa3_invoice to produce FA(3) XML before calling this tool. HUMAN-IN-THE-LOOP: Call without confirmation_token first to receive a confirmation summary and token. Show the summary to the user, then call again with confirmation_token set to execute the actual submission. Parameters ---------- xml_content: FA(3) invoice XML string to submit. session_token: KSeF v2 AccessToken (overrides KSEF_SESSION_TOKEN env var). Obtain via the challenge → authenticate → redeem flow: https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md session_token_expires_at: ISO-8601 datetime when the token expires. A warning is logged if fewer than 60 seconds remain; submission is blocked if the token is already expired. confirmation_token: Token from the previous awaiting_confirmation response. Returns a dict with: session_reference — KSeF session reference number invoice_reference — per-invoice reference number reference_number — "{sessionRef}:{invoiceRef}" for get_ksef_invoice_status status — "submitted"
Validate a value against an EN 16931 codelist. Returns {'valid': bool, 'description': str}.
Validate a KSeF FA(2) XML invoice. Runs XSD validation (when the official schema is present) and Polish business-rule checks. Returns a DocumentValidationResult with errors and warnings.
Validate a KSeF FA(3) XML invoice before submission to KSeF API v2 (PL-6.2). Runs XSD validation against specs/schemat_FA(3)_v1-0E.xsd (requires lxml) and FA(3)-specific business-rule checks including namespace, mandatory Adnotacje sub-elements, JST/GV flags, and the absence of the FA(2) <FaWiersze> wrapper. Call this after generate_fa3_invoice and before submit_invoice_to_ksef. Returns a DocumentValidationResult with errors and warnings.
Validate a Peppol BIS 3.0 / EN 16931 UBL XML invoice. Runs XSD validation and Peppol business-rule checks (Schematron). Returns a DocumentValidationResult with errors and warnings.
Validate a Polish NIP (tax identification number). Applies the official 10-digit checksum algorithm. Accepts NIP with or without dashes/spaces. Returns {'valid': bool, 'nip': str, 'normalized': str}.
Validate a Polish REGON (business registry number). Applies the official checksum algorithm for both 9-digit and 14-digit REGON. Accepts REGON with or without dashes/spaces. Returns {'valid': bool, 'regon': str, 'normalized': str, 'length': int}.
Confirmation flow in submit_invoice_to_ksef exposes confirmation_token as a parameter. This is a multi-round-trip pattern (MRTR) but not formalized, no 'input_required' result type visible. LLMs may not recognize the two-step flow.
Error handling guidance absent. Tools do not document what errors are retryable, user-fixable, or fatal. No recovery hints (e.g., 'call search_ksef_invoices if reference_number is unknown').