beliq-mcp 0.3.2 → 0.4.0

package/README.md

@@ -1,15 +1,15 @@
 # beliq-mcp
 
-An [MCP](https://modelcontextprotocol.io) server for [beliq](https://beliq.eu), the EU e-invoicing compliance API. It lets MCP clients (Claude Desktop, Claude Code, Cursor, and others) **validate**, **parse**, **generate**, and **convert** electronic invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS, and other UBL/CII documents) against authority-pinned, drift-checked rules, and explain exactly what fails.
+An [MCP](https://modelcontextprotocol.io) server for [beliq](https://beliq.eu), the EU e-invoicing compliance API. It lets MCP clients (Claude Desktop, Claude Code, Cursor, and others) **validate**, **parse**, **generate**, and **convert** electronic invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS, and the other formats the API carries), and explain exactly what fails. Every verdict states how deep its check went.
 
-beliq produces and checks the compliant document. Transmission (Peppol, PDP, KSeF, SDI), archiving, and tax-authority reporting stay with your access point.
+beliq produces and checks the document. Transmission (Peppol, PDP, KSeF, SDI), archiving, and tax-authority reporting stay with your access point.
 
 ## Tools
 
-- **`beliq_validate_einvoice`** - validate a UBL/CII XML invoice (inline or by file path) or a Factur-X/ZUGFeRD PDF (by file path). Returns the verdict, the detected format and profile, the ruleset (Schematron) version it was checked against, and every error and warning with its rule id, severity, location, and message.
-- **`beliq_parse_einvoice`** - parse a UBL/CII XML invoice or a Factur-X/ZUGFeRD PDF into a structured EN 16931 invoice (number, dates, currency, seller, buyer, lines, totals). Returns the detected format and profile and the extracted invoice.
-- **`beliq_generate_einvoice`** - generate a compliant document (XRechnung, ZUGFeRD, Factur-X, or Peppol BIS) from an EN 16931 invoice object. XML comes back inline; a PDF is written to the `outputPath` you give. Validates the result before returning by default (`verify`), so a non-compliant document fails rather than coming back.
-- **`beliq_convert_einvoice`** - convert a document from one EN 16931 format to another (`targetFormat` of cii, ubl, xrechnung, peppol-bis, facturx, or zugferd). An XML target comes back inline; a PDF target is written to `outputPath`. Reports any elements the conversion could not carry across.
+- **`beliq_validate_einvoice`** - validate an invoice XML (inline or by file path) or a Factur-X/ZUGFeRD PDF (by file path). Returns the verdict, how deep the check went, the detected format and profile, the ruleset versions it was checked against, and every error and warning with its rule id, severity, location, and message. For a PDF the verdict is about the embedded XML; the PDF itself is not checked.
+- **`beliq_parse_einvoice`** - parse a UBL/CII XML invoice or a Factur-X/ZUGFeRD PDF into a structured EN 16931 invoice (number, dates, currency, seller, buyer, lines, totals). Returns the detected format and profile, the extracted invoice, and warnings that say what the document holds and the parsed invoice does not.
+- **`beliq_generate_einvoice`** - generate a document from an EN 16931 invoice object. XML comes back inline; a PDF is written to the `outputPath` you give. By default (`verify`) the API validates the document before returning it, and a document that fails comes back as a tool error with the failed rules. The tool description tells the model to ask for missing invoice data instead of making it up.
+- **`beliq_convert_einvoice`** - convert a document from one EN 16931 format to another. The result is XML, inline, for every target, `facturx` and `zugferd` included; a PDF comes back only when a hybrid PDF source already is the target, and is written to `outputPath`. Reports how many source elements the engine recorded as having no target equivalent.
 - **`beliq_check_account`** - verify the configured API key and report the plan and remaining quota. Calls `GET /v1/me`, which draws no quota; useful as a connection and credential smoke test.
 
 ## Installation
@@ -64,22 +64,56 @@ Add to `~/.cursor/mcp.json` (or a project `.cursor/mcp.json`) using the same `mc
 
 `beliq_validate_einvoice` returns a short text verdict plus a structured result:
 
-- `valid` is true only when there are no errors; warnings do not make a document invalid.
+- `valid` is the API's verdict: the document passed the rule packs and schemas beliq runs for its format, in the versions this result names. It does not mean every recipient, validation tool or tax authority accepts it. Warnings do not make a document invalid, with one case to read beside it: `franceCtcBlockingRuleIds`.
+- `verificationBadgeLabel` is the check depth as English display text, and the text verdict prints it beside `VALID` or `INVALID`. [How verification works](https://docs.beliq.eu/compliance/how-verification-works/) explains each depth. Where the API sends no label, the text says `check depth not stated` and names no depth. `verificationBadge` and `verificationTier` are the ids behind the label.
+- `franceCtcBlockingRuleIds` lists the French CTC rule ids the API reports as ending a transmission through a French platform. It can be present where `valid` is true, and the text verdict then leads with it. The result stays a normal result, not a tool error. `franceCtcApplied`, `franceCtcVersion` and `franceExtendedCtcApplied` say which French packs ran.
+- `pdfInput` is present when the document was a PDF: `attachmentName`, `attachmentFoundBy` and `attachmentCandidates` say which embedded file the verdict is about, and `containerChecked` is always false because the PDF itself is not checked.
 - `format` and `profileDetected` report the detected syntax and business profile.
-- `schematronVersion` is the exact ruleset revision the check ran against.
-- `errors[]` and `warnings[]` each carry `ruleId`, `severity`, `location` (an XPath when available), and `message`.
-
-`beliq_parse_einvoice` returns the detected `format` and `profileDetected` plus the extracted `invoice` object (EN 16931 fields: number, dates, currency, seller, buyer, lines, totals, and any national extensions present).
-
-`beliq_generate_einvoice` returns the `output` kind (`xml` or `pdf`), the `contentType`, and the `schematronVersion` the document was checked against. An XML document is also returned inline as `xml`; a PDF (and an XML when you set `outputPath`) is written to disk, and the call reports `outputPath` and `bytesWritten`. It does not overwrite an existing file: pick a path that does not exist.
-
-`beliq_convert_einvoice` returns the `output` kind, the resolved `sourceFormat` and `targetFormat`, and `lostElementsCount`/`lostElements` for anything the conversion could not carry across. An XML target comes back inline as `xml`; a PDF target (facturx / zugferd) is written to `outputPath`. Like generate, it never overwrites an existing file.
+- `schematronVersion` is the ruleset revision the check ran against. The versions of the other packs and schema bundles that ran come in `ciusVersion`, `peppolVersion`, `facturxProfile`, `facturxVersion`, `italyFatturapaXsdBundle`, `italyFatturapaRuntimeVersion`, `italySdiMessaggiXsdBundle`, `italySdiMessaggiXsdVersion`, `spainFacturaeXsdBundle`, `spainFacturaeRuntimeVersion`, `sloveniaEslogXsdBundle`, `sloveniaEslogRuntimeVersion`, `polandKsefFa3XsdBundle`, `polandKsefFa3RuntimeVersion`, `romaniaRoCiusVersion` and `netherlandsNlciusVersion`, each present only when it applies.
+- `rulesetChannel` is present when a ruleset channel was selected, which an organisation whose default channel is `previous` does with no input of this tool. `rulesetFellBack` and `rulesetSunsetsOn` come with it when they apply.
+- `sha256` is the hash of the document that was checked, `rulesetSha256` and `rulesetArtifacts` fingerprint the rule files that ran, and `driftCheckedAt` is when those files were last confirmed to match their upstream sources.
+- `verified` is false only when no ruleset ran, which validate never returns; see generate below.
+- `errors` and `warnings` each carry `ruleId`, `severity`, `location` (an XPath when available), and `message`. `errorCount` and `warningCount` are their lengths.
+
+The structured result carries every field of the API's validation result. Its shape is checked against the SDK's type, so a field the API adds cannot go missing here without failing the build.
+
+`beliq_parse_einvoice` returns a text summary plus a structured result:
+
+- `format`, `profileDetected` and `profileUrn` report the detected syntax and profile; `businessProcessId` and `franceCtcDetected` are present when the document states them.
+- `invoice` is the extracted invoice object (EN 16931 fields: number, dates, currency, seller, buyer, lines, totals). A field the API holds no value for is left out.
+- `warnings` says what the document holds and the parsed invoice does not: each entry has a `code`, a `message`, and, by code, a `field`, the `terms` (EN 16931 business groups) or the `elements` (paths with counts) concerned. The text summary lists them.
+
+`beliq_generate_einvoice` returns a short text summary (with the XML document appended for XML output) plus a structured result:
+
+- `output` is `xml` or `pdf`, as requested, and `contentType` is the matching media type (`application/xml` or `application/pdf`).
+- `xml` is the generated document inline, present only for XML output.
+- `outputPath` and `bytesWritten` are set when the document was written to disk: always for a PDF, and for XML when you set `outputPath`. The call never overwrites an existing file, so pick a path that does not exist.
+- `pdfKind` is present only for PDF output: `hybrid` (a PDF/A-3 with the XML embedded, for facturx and zugferd) or `visualization` (rendered pages with no XML inside, for xrechnung and peppol-bis, whose legal document stays the XML).
+- `schematronVersion` is the ruleset (Schematron) revision the document was checked against.
+- `outputEnvelope` is the envelope the document is wrapped in, when the API names one.
+- `sha256` is the lowercase-hex SHA-256 of the returned document bytes, so `sha256sum` on the file at `outputPath` reproduces it.
+- `rulesetSha256` is one combined fingerprint of the rule artifacts the document was checked against, present when a ruleset ran.
+- `livemode` is true for a `blq_live_` key and false for a `blq_test_` sandbox key, whose output is [marked as a specimen](https://docs.beliq.eu/api-reference/test-mode/#sandbox-markers) and is not a production invoice.
+- `validationResult` is the API's verdict on the generated document, with every field validate returns, the check depth in `verificationBadgeLabel` included; the text summary names that depth. The verdict is about the invoice XML, so for a PDF the text says so and names the kind of PDF. With the default `verify: true`, a document that fails validation comes back as a tool error that lists the failed rules. With `verify: false` no ruleset runs: `verified` is false, `errors` and `warnings` are empty because nothing checked the document, and the text says `not validated`.
+
+`beliq_convert_einvoice` returns a short text summary (with the XML document appended for an XML target) plus a structured result:
+
+- `output` is what came back, read from the response: `xml` for every target when the source is XML, `facturx` and `zugferd` included, and `pdf` only when a hybrid PDF source already is the `facturx` or `zugferd` target. `contentType` is the matching media type.
+- `xml` is the converted document inline, present only when XML came back.
+- `outputPath` and `bytesWritten` are set when the document was written to disk: always for a PDF, and for XML when you set `outputPath`. Like generate, it never overwrites an existing file.
+- `sourceFormat` is the format the engine read, and `targetFormat` the format it produced (the `targetFormat` you asked for when the API does not name one).
+- `profileDetected` is the profile the engine recognised on the source document, when it recognised one.
+- `conversionTools` names the toolchain that did the conversion, when the API names one.
+- `livemode` is true for a `blq_live_` key and false for a `blq_test_` sandbox key.
+- `lostElementsCount` and `lostElements` count and name the source elements the engine recorded as having no target equivalent. A loss the engine does not detect is not counted, so `0` does not say that every field of the source arrived.
+
+A successful convert means the API validated the converted XML before returning it. For a `facturx` or `zugferd` target at profile `en16931` that validation is the one for plain EN 16931 CII: no Factur-X profile schema is checked. It carries no verdict and no check depth. A converted document that fails comes back as a tool error that lists the failed rules.
 
 A PDF (Factur-X / ZUGFeRD) must be passed by `documentPath` for validate, parse, and convert, not inlined as text.
 
 ## Agent skill
 
-[`skill/SKILL.md`](./skill/SKILL.md) is a portable agent skill that teaches a model when to validate, how to read `errors`/`warnings`, and how to report a verdict, using the tools above. Drop it into a skills directory for an agent that should validate invoices on request.
+[`skill/SKILL.md`](./skill/SKILL.md) is a portable agent skill that teaches a model when to validate, how to read `errors`/`warnings`, and how to report a verdict with its check depth, using the tools above. Drop it into a skills directory for an agent that should validate invoices on request.
 
 ## Development
 
@@ -87,8 +121,8 @@ This server depends on the published [`@beliq/sdk`](https://www.npmjs.com/packag
 
 - `npm install`
 - `npm run build` - compile to `dist/`
-- `npm run typecheck`
-- `npm run lint`
+- `npm run typecheck` - src and tests
+- `npm run lint` - ESLint with type information, whole repository
 - `npm test` - unit tests (result summary) and an in-memory MCP round-trip with a fake SDK client
 - `BELIQ_API_KEY=your-key npm run test:integration` - live smoke tests against the real API
 - `npm run scrub:check` - check for em-dashes in source and docs

package/dist/schema.js

@@ -1,9 +1,11 @@
 import { z } from 'zod';
-import { LIVE_CONVERT_SOURCE_FORMATS, LIVE_CONVERT_TARGET_FORMATS, LIVE_GENERATE_STANDARDS, LIVE_PARSE_FORMATS, LIVE_PROFILES, } from '@beliq/sdk';
-// The tools expose the LIVE, authority-pinned public option sets (LPD-1),
-// imported from the SDK so this stays one source of truth: callers pass a
-// syntax family or a live standard, never a provisional/withheld profile. The
-// engine can detect more; the public surface stays narrow.
+import { LIVE_CONVERT_SOURCE_FORMATS, LIVE_CONVERT_TARGET_FORMATS, LIVE_GENERATE_STANDARDS, LIVE_PARSE_FORMATS, LIVE_PROFILES, LIVE_VALIDATE_FORMATS, } from '@beliq/sdk';
+// The tools expose the SDK's LIVE_* option sets, imported rather than retyped
+// so this stays one source of truth. Each carries every value the API accepts
+// for its operation: generate offers all eight standards, the four national
+// XSD ones included, while convert offers fewer because the API's own convert
+// enums do. GET /v1/rulesets carries the badge saying how deep each format's
+// check goes.
 export const validateInputShape = {
     document: z
         .string()
@@ -14,15 +16,15 @@ export const validateInputShape = {
         .string()
         .min(1)
         .optional()
-        .describe('Path to an invoice file on disk: a UBL/CII XML, or a PDF carrying embedded XML (Factur-X / ZUGFeRD). Provide this OR document.'),
+        .describe('Path to an invoice file on disk: an XML document, or a PDF carrying embedded XML (Factur-X / ZUGFeRD). Provide this OR document.'),
     format: z
-        .enum(['auto', 'cii', 'ubl'])
+        .enum(LIVE_VALIDATE_FORMATS)
         .optional()
-        .describe("Source syntax hint. 'auto' (default) detects CII vs UBL from the document."),
+        .describe("Source syntax hint. 'auto' (default) detects the format from the document."),
     franceCtc: z
         .boolean()
         .optional()
-        .describe('Apply the French CTC (Factur-X / Chorus Pro) rule overlay during validation.'),
+        .describe('Also apply the French CTC rules (BR-FR-CTC) during validation.'),
 };
 const issueShape = z.object({
     ruleId: z.string(),
@@ -30,16 +32,75 @@ const issueShape = z.object({
     location: z.string().optional(),
     message: z.string(),
 });
-export const validateOutputShape = {
-    valid: z.boolean(),
+const text = () => z.string().optional();
+/**
+ * Every field of the SDK's ValidationResult, passed on as the API sent it. The
+ * `satisfies` holds this list to the SDK's type, so a field the API gains
+ * fails the typecheck at the SDK bump instead of being dropped without notice.
+ */
+const validationResultShape = {
+    valid: z
+        .boolean()
+        .describe('Whether the document passed the rule packs and schemas beliq runs for its format, in the versions this result names. Not a statement that every recipient or tax authority accepts it.'),
+    verified: z
+        .boolean()
+        .optional()
+        .describe('False only when no ruleset ran (generate with verify: false). Then valid says nothing about the document.'),
     format: z.string(),
-    profileDetected: z.string().optional(),
-    schematronVersion: z.string().optional(),
-    errorCount: z.number(),
-    warningCount: z.number(),
+    profileDetected: text(),
+    verificationTier: text(),
+    verificationBadge: text().describe('Id of the check depth. Compare this, not the label.'),
+    verificationBadgeLabel: text().describe('The check depth as English display text. Print it as it is. Absent when the API states no depth for this verdict: then say the check depth was not stated, and name none.'),
+    schematronVersion: text(),
+    ciusVersion: text(),
+    peppolVersion: text(),
+    facturxProfile: text(),
+    facturxVersion: text(),
+    franceCtcApplied: z.boolean().optional(),
+    franceCtcVersion: text(),
+    franceExtendedCtcApplied: z.boolean().optional(),
+    franceCtcBlockingRuleIds: z
+        .array(z.string())
+        .optional()
+        .describe('French CTC rule ids the API reports as ending a transmission through a French platform. Present also where valid is true, and never empty: when present, lead with it.'),
+    italyFatturapaXsdBundle: text(),
+    italyFatturapaRuntimeVersion: text(),
+    italySdiMessaggiXsdBundle: text(),
+    italySdiMessaggiXsdVersion: text(),
+    spainFacturaeXsdBundle: text(),
+    spainFacturaeRuntimeVersion: text(),
+    sloveniaEslogXsdBundle: text(),
+    sloveniaEslogRuntimeVersion: text(),
+    polandKsefFa3XsdBundle: text(),
+    polandKsefFa3RuntimeVersion: text(),
+    romaniaRoCiusVersion: text(),
+    netherlandsNlciusVersion: text(),
+    rulesetChannel: text(),
+    rulesetFellBack: z.boolean().optional(),
+    rulesetSunsetsOn: text(),
+    pdfInput: z
+        .object({
+        containerChecked: z.boolean(),
+        attachmentName: z.string().optional(),
+        attachmentFoundBy: z.string(),
+        attachmentCandidates: z.number(),
+    })
+        .optional()
+        .describe('Present when the document was a PDF: which embedded file the verdict is about. containerChecked is always false, because the PDF itself is not checked.'),
+    sha256: text(),
+    rulesetSha256: text(),
+    rulesetArtifacts: z
+        .array(z.object({ key: z.string(), version: z.string(), fileSha256: z.string() }))
+        .optional(),
+    driftCheckedAt: text(),
     errors: z.array(issueShape),
     warnings: z.array(issueShape),
 };
+export const validateOutputShape = {
+    ...validationResultShape,
+    errorCount: z.number(),
+    warningCount: z.number(),
+};
 export const checkAccountOutputShape = {
     ok: z.boolean(),
     status: z.number(),
@@ -65,10 +126,23 @@ export const parseInputShape = {
 };
 // The extracted invoice is passed through verbatim from the API; the shape is
 // documented on the endpoint, so the tool reports it without re-modelling it.
+// The other fields are held to the SDK's type like the validation result.
 export const parseOutputShape = {
     format: z.string(),
-    profileDetected: z.string().optional(),
+    profileDetected: text(),
+    profileUrn: text(),
+    businessProcessId: text(),
+    franceCtcDetected: z.boolean().optional(),
     invoice: z.record(z.string(), z.unknown()),
+    warnings: z
+        .array(z.object({
+        code: z.string(),
+        message: z.string(),
+        field: z.string().optional(),
+        terms: z.array(z.string()).optional(),
+        elements: z.array(z.object({ path: z.string(), count: z.number() })).optional(),
+    }))
+        .describe('What the document holds and the parsed invoice does not. Report these with the invoice: an empty list is the only case in which the invoice is all the API read.'),
 };
 // ── Generate ──────────────────────────────────────────────────────────────
 const partyAddress = z
@@ -125,7 +199,7 @@ export const generateInputShape = {
     verify: z
         .boolean()
         .optional()
-        .describe('Validate the generated document before returning and fail if it is not compliant. Defaults to true.'),
+        .describe('Validate the generated document before returning it, and fail if it does not pass. Defaults to true.'),
     outputPath: z
         .string()
         .min(1)
@@ -137,6 +211,7 @@ export const generateOutputShape = {
     contentType: z.string(),
     schematronVersion: z.string().optional(),
     pdfKind: z.string().optional(),
+    outputEnvelope: z.string().optional(),
     outputPath: z.string().optional(),
     bytesWritten: z.number().optional(),
     xml: z.string().optional(),
@@ -145,14 +220,7 @@ export const generateOutputShape = {
     sha256: z.string().optional(),
     rulesetSha256: z.string().optional(),
     livemode: z.boolean().optional(),
-    validationResult: z
-        .object({
-        valid: z.boolean(),
-        schematronVersion: z.string().optional(),
-        errors: z.array(issueShape),
-        warnings: z.array(issueShape),
-    })
-        .optional(),
+    validationResult: z.object(validationResultShape).optional(),
 };
 // ── Convert ────────────────────────────────────────────────────────────────
 export const convertInputShape = {
@@ -168,7 +236,7 @@ export const convertInputShape = {
         .describe('Path to the source invoice on disk: a UBL/CII XML, or a Factur-X / ZUGFeRD PDF. Provide this OR document.'),
     targetFormat: z
         .enum(LIVE_CONVERT_TARGET_FORMATS)
-        .describe('Format to convert to. cii, ubl, xrechnung, and peppol-bis come back as XML inline; facturx and zugferd produce a PDF and need outputPath.'),
+        .describe('Format to convert to. Every target comes back as XML inline, facturx and zugferd included. A PDF comes back only when a hybrid PDF source already is the facturx or zugferd target, and then needs outputPath.'),
     sourceFormat: z
         .enum(LIVE_CONVERT_SOURCE_FORMATS)
         .optional()
@@ -180,26 +248,54 @@ export const convertInputShape = {
     dropFranceCtcOverlay: z
         .boolean()
         .optional()
-        .describe('Drop the French CTC (Factur-X / Chorus Pro) overlay from the converted document.'),
+        .describe('Drop the French CTC overlay from the converted document.'),
     outputPath: z
         .string()
         .min(1)
         .optional()
-        .describe('Where to write the converted document on disk. Required for a facturx/zugferd (PDF) target, optional for an XML target. The call fails if a file already exists at the path.'),
+        .describe('Where to write the converted document on disk. Required when a PDF source goes to a facturx or zugferd target, optional otherwise. The call fails if a file already exists at the path.'),
 };
 export const convertOutputShape = {
-    output: z.enum(['xml', 'pdf']),
+    output: z.enum(['xml', 'pdf']).describe('What came back, read from the response: xml, or pdf for a returned hybrid PDF.'),
     contentType: z.string(),
     sourceFormat: z.string().optional(),
     targetFormat: z.string().optional(),
     profileDetected: z.string().optional(),
     lostElementsCount: z.number().optional(),
     lostElements: z.array(z.string()).optional(),
+    conversionTools: z.string().optional(),
+    livemode: z.boolean().optional(),
     outputPath: z.string().optional(),
     bytesWritten: z.number().optional(),
     xml: z.string().optional(),
 };
-const validateInputSchema = z.object(validateInputShape);
-const parseInputSchema = z.object(parseInputShape);
-const generateInputSchema = z.object(generateInputShape);
-const convertInputSchema = z.object(convertInputShape);
+export const GENERATE_RESULT_FIELDS = {
+    contentType: 'contentType',
+    bytes: { omitted: 'the document itself: inline as xml, or written to outputPath' },
+    xml: 'xml',
+    sha256: 'sha256',
+    validationResult: 'validationResult',
+    meta: { omitted: 'flattened, see GENERATE_META_FIELDS' },
+};
+export const GENERATE_META_FIELDS = {
+    schematronVersion: 'schematronVersion',
+    pdfKind: 'pdfKind',
+    outputEnvelope: 'outputEnvelope',
+    rulesetSha256: 'rulesetSha256',
+    rulesetArtifacts: { omitted: 'validationResult.rulesetArtifacts carries the same list' },
+    livemode: 'livemode',
+};
+export const CONVERT_RESULT_FIELDS = {
+    contentType: 'contentType',
+    bytes: { omitted: 'the document itself: inline as xml, or written to outputPath' },
+    meta: { omitted: 'flattened, see CONVERT_META_FIELDS' },
+};
+export const CONVERT_META_FIELDS = {
+    sourceFormat: 'sourceFormat',
+    targetFormat: 'targetFormat',
+    profileDetected: 'profileDetected',
+    lostElementsCount: 'lostElementsCount',
+    lostElements: 'lostElements',
+    conversionTools: 'conversionTools',
+    livemode: 'livemode',
+};

package/dist/summary.js

@@ -1,3 +1,4 @@
+import { checkDepth, franceBlockLines, pdfInputLine, rulesetChannelLine, verdictWord } from './verdict.js';
 /** How many issues to spell out before collapsing the rest into a count. */
 const MAX_LISTED_ISSUES = 20;
 function issueLine(issue) {
@@ -18,26 +19,40 @@ function listSection(title, issues) {
     return lines;
 }
 /**
- * A compact human-readable verdict for the MCP text content: the pass/fail
- * line with format, profile, and ruleset version, then the errors and warnings
- * (capped). The full structured result rides alongside in structuredContent.
+ * A compact human-readable verdict for the MCP text content. A France CTC
+ * block leads, because the API reports it where `valid` is true and a reader
+ * of the verdict line alone would miss it. Then the API's verdict word with
+ * the check depth, the format, the profile and the ruleset version, what the
+ * API says about the ruleset channel and a PDF input, and the errors and
+ * warnings (capped). The full structured result rides alongside in
+ * structuredContent.
  */
 export function summarizeValidation(result) {
     const errors = (result.errors ?? []);
     const warnings = (result.warnings ?? []);
-    const verdict = result.valid ? 'VALID' : 'INVALID';
     const profile = result.profileDetected ? ` (profile ${result.profileDetected})` : '';
-    const schematron = result.schematronVersion
-        ? `, checked against Schematron ${result.schematronVersion}`
-        : '';
-    const header = `Validation: ${verdict}. Format ${result.format}${profile}${schematron}. ` +
+    // Nothing ran when `verified` is false, so there is no depth and no ruleset to name.
+    const ran = result.verified !== false;
+    const depth = ran ? ` (${checkDepth(result)})` : '';
+    const schematron = ran && result.schematronVersion ? `, checked against Schematron ${result.schematronVersion}` : '';
+    const header = `Validation: ${verdictWord(result)}${depth}. Format ${result.format}${profile}${schematron}. ` +
         `${plural(errors.length, 'error')}, ${plural(warnings.length, 'warning')}.`;
-    return [header, ...listSection('Errors', errors), ...listSection('Warnings', warnings)].join('\n');
+    return [
+        ...franceBlockLines(result),
+        header,
+        rulesetChannelLine(result),
+        pdfInputLine(result),
+        ...listSection('Errors', errors),
+        ...listSection('Warnings', warnings),
+    ]
+        .filter((line) => line !== undefined)
+        .join('\n');
 }
 /**
- * A one-line human-readable summary of a parse: the detected syntax and
- * profile, then the invoice number, currency, line count, and gross total. The
- * full structured invoice rides alongside in structuredContent.
+ * A human-readable summary of a parse: the detected syntax and profile, then
+ * the invoice number, currency, line count, and gross total, then each warning
+ * the API sent about what the document holds and the parsed invoice does not.
+ * The full structured result rides alongside in structuredContent.
  */
 export function summarizeParse(result) {
     const invoice = result.invoice;
@@ -47,20 +62,41 @@ export function summarizeParse(result) {
     const gross = invoice?.totalGrossAmount != null
         ? `, gross ${invoice.totalGrossAmount} ${invoice.currencyCode ?? ''}`.trimEnd()
         : '';
-    return `Parsed a ${result.format}${profile} document: ${number}, ${plural(lines, 'line')}${gross}.`;
+    const head = `Parsed a ${result.format}${profile} document: ${number}, ${plural(lines, 'line')}${gross}.`;
+    const warnings = result.warnings ?? [];
+    if (warnings.length === 0)
+        return head;
+    const listed = warnings.map((w) => {
+        const field = w.field ? ` (field ${w.field})` : '';
+        const terms = w.terms?.length ? ` Terms: ${w.terms.join(', ')}.` : '';
+        const elements = w.elements?.length
+            ? ` ${plural(w.elements.length, 'element path')}; the structured result lists them.`
+            : '';
+        return `- ${w.code}${field}: ${w.message}${terms}${elements}`;
+    });
+    return [head, `${plural(warnings.length, 'warning')}:`, ...listed].join('\n');
 }
 /**
- * A human-readable summary of a generate. For an XML result the document is
- * appended in full so a client without structured output still receives it; a
- * PDF is reported by the path it was written to. When the seal is present the
- * document sha256 and validation verdict are stated so the model can cite them.
+ * A human-readable summary of a generate, with the check depth of the
+ * validation the API ran on the document, or that none ran. The verdict is
+ * about the invoice XML, so for a PDF the summary says so and names the kind
+ * of PDF. A France CTC block in the verdict leads. For an XML result
+ * the document is appended in full so a client without structured output still
+ * receives it; a PDF is reported by the path it was written to. The document
+ * sha256 and the verdict are stated so the model can cite them.
  */
 export function summarizeGenerate(g) {
-    const checked = g.schematronVersion ? `, checked against Schematron ${g.schematronVersion}` : '';
+    const ran = g.verdict?.verified !== false;
+    const schematron = ran && g.schematronVersion ? `checked against Schematron ${g.schematronVersion}` : '';
+    const depth = g.verdict === undefined ? '' : ran ? checkDepth(g.verdict) : 'not validated';
+    const check = [schematron, depth].filter((part) => part !== '').join(', ');
+    const pdfKind = g.output === 'pdf' && g.pdfKind ? ` (${g.pdfKind})` : '';
+    const checked = check === '' ? '' : g.output === 'pdf' ? `; invoice XML ${check}` : `, ${check}`;
+    const france = g.verdict ? franceBlockLines(g.verdict).map((line) => `${line}\n`).join('') : '';
     const seal = g.sha256
-        ? ` Document sha256 ${g.sha256}${g.valid === undefined ? '' : `; validation ${g.valid ? 'passed' : 'failed'}`}.`
+        ? ` Document sha256 ${g.sha256}${g.verdict === undefined ? '' : `; verdict ${verdictWord(g.verdict)}`}.`
         : '';
-    const header = `Generated a ${g.standard} ${g.output} document${checked}.${seal}`;
+    const header = `${france}Generated a ${g.standard} ${g.output} document${pdfKind}${checked}.${seal}`;
     if (g.output === 'pdf') {
         const where = g.outputPath ? ` Written to ${g.outputPath} (${plural(g.bytesWritten ?? 0, 'byte')}).` : '';
         return `${header}${where}`;
@@ -71,18 +107,22 @@ export function summarizeGenerate(g) {
 }
 /**
  * A human-readable summary of a convert: the source and target formats, any
- * profile, and how many elements the conversion could not carry across (so a
- * lossy conversion is visible). For an XML target the document is appended in
- * full; a PDF target is reported by the path it was written to.
+ * profile, that the API validated the result, and how many source elements the
+ * engine recorded as having no target equivalent. A convert carries no verdict,
+ * so no check depth is named. For XML the document is appended in full; a PDF
+ * is reported by the path it was written to.
  */
 export function summarizeConvert(c) {
     const fromClause = c.sourceFormat ? `${c.sourceFormat} ` : '';
     const target = c.targetFormat ?? 'the target format';
     const profile = c.profileDetected ? ` (profile ${c.profileDetected})` : '';
+    const checked = c.output === 'pdf'
+        ? ' The API validated the embedded XML before returning it; the PDF around it was not checked.'
+        : ' The API validated the converted XML before returning it.';
     const lost = c.lostElementsCount && c.lostElementsCount > 0
-        ? ` ${plural(c.lostElementsCount, 'element')} could not be carried across.`
+        ? ` The engine recorded ${plural(c.lostElementsCount, 'source element')} with no target equivalent.`
         : '';
-    const header = `Converted ${fromClause}to ${target}${profile}.${lost}`;
+    const header = `Converted ${fromClause}to ${target}${profile}, returned as ${c.output === 'pdf' ? 'a PDF' : 'XML'}.${checked}${lost}`;
     if (c.output === 'pdf') {
         const where = c.outputPath ? ` Written to ${c.outputPath} (${plural(c.bytesWritten ?? 0, 'byte')}).` : '';
         return `${header}${where}`;

package/dist/tools/convert.js

@@ -2,9 +2,10 @@ import { convertInputShape, convertOutputShape } from '../schema.js';
 import { runConvert } from './shared.js';
 const description = [
     'Convert an EU electronic invoice from one EN 16931 format to another.',
-    'Pass the source document (inline via document, or a file via documentPath) and set targetFormat to cii, ubl, xrechnung, peppol-bis, facturx, or zugferd.',
-    'An XML target (cii, ubl, xrechnung, peppol-bis) comes back inline; a PDF target (facturx, zugferd) is written to the outputPath you give.',
-    'The result reports any elements the conversion could not carry across, so a lossy conversion is visible rather than silent.',
+    'Pass the source document (inline via document, or a file via documentPath) and set targetFormat.',
+    'The converted document comes back as XML inline for every target, facturx and zugferd included: an XML source is not wrapped into a hybrid PDF. A PDF comes back only when a hybrid PDF source already is the target, and is then written to the outputPath you give.',
+    'A successful result means the API validated the converted XML before returning it. For a facturx or zugferd target at profile en16931 that validation is the one for plain EN 16931 CII: no Factur-X profile schema is checked. It carries no verdict and no check depth; a converted document that fails comes back as an error that lists the failed rules.',
+    'lostElementsCount is how many source elements the engine recorded as having no target equivalent. A loss the engine does not detect is not counted, so 0 does not say that every field of the source arrived.',
     'beliq produces the converted document; transmission (Peppol, PDP, KSeF, SDI), archiving, and tax-authority reporting stay with your access point.',
 ].join(' ');
 export function registerConvert(server, deps) {

package/dist/tools/generate.js

@@ -1,11 +1,12 @@
 import { generateInputShape, generateOutputShape } from '../schema.js';
 import { runGenerate } from './shared.js';
 const description = [
-    'Generate a compliant EU electronic invoice from an EN 16931 invoice object.',
-    'Set standard to the target (xrechnung, zugferd, facturx, or peppol-bis) and pass the invoice fields.',
+    'Generate an EU electronic invoice from an EN 16931 invoice object.',
+    'Set standard to the target format and pass the invoice fields.',
+    'Use only invoice data the user gave. When a field the target format requires is missing, ask the user for it: do not make up a value so that validation passes.',
     "output 'xml' (default) returns the document inline; 'pdf' needs outputPath to write it to, and is a hybrid PDF/A-3 with the XML embedded for facturx and zugferd, or a visualization with no embedded XML for xrechnung and peppol-bis (whose legal document stays the XML).",
-    'By default the result is validated before it is returned (verify), so a non-compliant document fails rather than coming back.',
-    'beliq produces the compliant document; transmission (Peppol, PDP, KSeF, SDI), archiving, and tax-authority reporting stay with your access point.',
+    'By default the API validates the document before returning it (verify), and a document that fails comes back as an error that lists the failed rules. validationResult carries the verdict, with the check depth of that validation in verificationBadgeLabel.',
+    'beliq produces the document; transmission (Peppol, PDP, KSeF, SDI), archiving, and tax-authority reporting stay with your access point.',
 ].join(' ');
 export function registerGenerate(server, deps) {
     server.registerTool('beliq_generate_einvoice', {

package/dist/tools/parse.js

@@ -3,8 +3,8 @@ import { runParse } from './shared.js';
 const description = [
     'Parse an EU electronic invoice into a structured EN 16931 invoice object.',
     'Accepts a UBL or CII XML document (inline via document, or a file via documentPath), or a Factur-X / ZUGFeRD PDF via documentPath.',
-    'Returns the detected format and profile and the extracted invoice (number, dates, currency, seller, buyer, lines, totals, and more).',
-    'Use it to read the contents of an invoice; use validate to check compliance.',
+    'Returns the detected format and profile, the extracted invoice (number, dates, currency, seller, buyer, lines, totals, and more), and warnings that say what the document holds and the parsed invoice does not.',
+    'Report the warnings with the invoice. Use it to read the contents of an invoice; use validate to check it against the rules.',
 ].join(' ');
 export function registerParse(server, deps) {
     server.registerTool('beliq_parse_einvoice', {

package/dist/tools/shared.js

@@ -1,5 +1,6 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { BeliqApiError, isProfileAllowedForStandard, profilesForStandard, } from '@beliq/sdk';
+import { sniffContentType, toBytes } from '@beliq/sdk/helpers';
 import { summarizeConvert, summarizeGenerate, summarizeParse, summarizeValidation } from '../summary.js';
 function errorResult(message) {
     return { content: [{ type: 'text', text: message }], isError: true };
@@ -10,8 +11,19 @@ function nonEmpty(value) {
 /** A bad tool input that should come back as a normal (non-fatal) tool error. */
 class BeliqInputError extends Error {
 }
-/** Convert targets that produce a PDF rather than an inline XML document. */
-const PDF_CONVERT_TARGETS = new Set(['facturx', 'zugferd']);
+/** The convert targets for which the API can hand a hybrid PDF source back as a PDF. */
+const HYBRID_CONVERT_TARGETS = new Set(['facturx', 'zugferd']);
+/**
+ * An API error as a tool error. A 422 from generate or convert carries the
+ * validation result of the document the API refused, so the failed rules are
+ * appended for the model to act on.
+ */
+function apiErrorResult(err) {
+    const code = err.code ? ` (${err.code})` : '';
+    const refused = err.details?.validationResult;
+    const rules = refused && typeof refused === 'object' ? `\n${summarizeValidation(refused)}` : '';
+    return errorResult(`beliq API error ${err.status}${code}: ${err.message}${rules}`);
+}
 /**
  * Resolve a document-carrying input to the bytes/text the SDK reads. Exactly
  * one of document (inline XML) or documentPath (a file on disk) must be set; a
@@ -29,8 +41,10 @@ async function resolveDocument(input) {
 }
 /**
  * Validate one document and shape the MCP result: a human-readable verdict in
- * the text content plus the full structured result. Input and API errors come
- * back as isError so the model can self-correct; only unexpected faults throw.
+ * the text content plus every field of the API result. A document that is not
+ * valid, or that carries France CTC blocking rule ids, is a normal result:
+ * isError is for input and API errors, so the model can self-correct. Only
+ * unexpected faults throw.
  */
 export async function runValidate(input, deps) {
     let document;
@@ -51,23 +65,12 @@ export async function runValidate(input, deps) {
         const warnings = result.warnings ?? [];
         return {
             content: [{ type: 'text', text: summarizeValidation(result) }],
-            structuredContent: {
-                valid: result.valid,
-                format: result.format,
-                profileDetected: result.profileDetected,
-                schematronVersion: result.schematronVersion,
-                errorCount: errors.length,
-                warningCount: warnings.length,
-                errors,
-                warnings,
-            },
+            structuredContent: { ...result, errorCount: errors.length, warningCount: warnings.length, errors, warnings },
         };
     }
     catch (err) {
-        if (err instanceof BeliqApiError) {
-            const code = err.code ? ` (${err.code})` : '';
-            return errorResult(`beliq API error ${err.status}${code}: ${err.message}`);
-        }
+        if (err instanceof BeliqApiError)
+            return apiErrorResult(err);
         throw err;
     }
 }
@@ -107,8 +110,8 @@ export async function runCheckAccount(deps) {
 }
 /**
  * Parse one document into a structured EN 16931 invoice and shape the MCP
- * result: a one-line summary in the text content plus the full invoice in
- * structuredContent. Input and API errors come back as isError so the model can
+ * result: a summary with the API's warnings in the text content plus the full
+ * result in structuredContent. Input and API errors come back as isError so the model can
  * self-correct; only unexpected faults throw.
  */
 export async function runParse(input, deps) {
@@ -125,27 +128,21 @@ export async function runParse(input, deps) {
         const result = await deps.client.parse(document, { format: input.format });
         return {
             content: [{ type: 'text', text: summarizeParse(result) }],
-            structuredContent: {
-                format: result.format,
-                profileDetected: result.profileDetected,
-                invoice: result.invoice,
-            },
+            structuredContent: { ...result, warnings: result.warnings ?? [] },
         };
     }
     catch (err) {
-        if (err instanceof BeliqApiError) {
-            const code = err.code ? ` (${err.code})` : '';
-            return errorResult(`beliq API error ${err.status}${code}: ${err.message}`);
-        }
+        if (err instanceof BeliqApiError)
+            return apiErrorResult(err);
         throw err;
     }
 }
 /**
- * Generate a compliant document from an EN 16931 invoice. XML comes back inline
- * in the text content; a PDF (or an XML with outputPath set) is written to disk
- * and reported by path. verify defaults to true so the tool fails closed rather
- * than hand back a non-compliant document. Input and API errors come back as
- * isError so the model can self-correct.
+ * Generate a document from an EN 16931 invoice. XML comes back inline in the
+ * text content; a PDF (or an XML with outputPath set) is written to disk and
+ * reported by path. verify defaults to true, so the API refuses a document
+ * that fails its own validation instead of handing it back. Input and API
+ * errors come back as isError so the model can self-correct.
  */
 export async function runGenerate(input, deps) {
     const output = input.output ?? 'xml';
@@ -180,10 +177,8 @@ export async function runGenerate(input, deps) {
         });
     }
     catch (err) {
-        if (err instanceof BeliqApiError) {
-            const code = err.code ? ` (${err.code})` : '';
-            return errorResult(`beliq API error ${err.status}${code}: ${err.message}`);
-        }
+        if (err instanceof BeliqApiError)
+            return apiErrorResult(err);
         throw err;
     }
     let bytesWritten;
@@ -208,7 +203,8 @@ export async function runGenerate(input, deps) {
         bytesWritten,
         xml: output === 'xml' ? result.xml : undefined,
         sha256: result.sha256,
-        valid: vr?.valid,
+        pdfKind: result.meta.pdfKind,
+        verdict: vr,
     });
     return {
         content: [{ type: 'text', text }],
@@ -217,29 +213,24 @@ export async function runGenerate(input, deps) {
             contentType: result.contentType,
             schematronVersion: result.meta.schematronVersion,
             pdfKind: result.meta.pdfKind,
+            outputEnvelope: result.meta.outputEnvelope,
             outputPath,
             bytesWritten,
             xml: output === 'xml' ? result.xml : undefined,
             sha256: result.sha256,
             rulesetSha256: result.meta.rulesetSha256,
             livemode: result.meta.livemode,
-            validationResult: vr
-                ? {
-                    valid: vr.valid,
-                    schematronVersion: vr.schematronVersion,
-                    errors: vr.errors ?? [],
-                    warnings: vr.warnings ?? [],
-                }
-                : undefined,
+            validationResult: vr ? { ...vr, errors: vr.errors ?? [], warnings: vr.warnings ?? [] } : undefined,
         },
     };
 }
 /**
- * Convert a document from one EN 16931 format to another. An XML target comes
- * back inline; a PDF target (facturx / zugferd) is written to disk and reported
- * by path. Any elements the conversion could not carry across are surfaced, so
- * a lossy conversion is visible. Input and API errors come back as isError so
- * the model can self-correct.
+ * Convert a document from one EN 16931 format to another. The API returns XML
+ * for every target, facturx and zugferd included, and it comes back inline. A
+ * PDF comes back only when a hybrid PDF source already is the target; it is
+ * written to disk and reported by path. The count of lost elements is what the
+ * engine recorded, and a loss it does not detect is not in it. Input and API
+ * errors come back as isError so the model can self-correct.
  */
 export async function runConvert(input, deps) {
     let document;
@@ -251,10 +242,10 @@ export async function runConvert(input, deps) {
             return errorResult(err.message);
         return errorResult(`Could not read the document: ${err.message}`);
     }
-    const output = PDF_CONVERT_TARGETS.has(input.targetFormat) ? 'pdf' : 'xml';
     const outputPath = nonEmpty(input.outputPath) ? input.outputPath.trim() : undefined;
-    if (output === 'pdf' && !outputPath) {
-        return errorResult(`Converting to ${input.targetFormat} produces a PDF and needs outputPath: the file path to write it to.`);
+    const pdfSource = sniffContentType(toBytes(document)) === 'application/pdf';
+    if (pdfSource && HYBRID_CONVERT_TARGETS.has(input.targetFormat) && !outputPath) {
+        return errorResult(`A PDF source converted to ${input.targetFormat} can come back as a PDF and needs outputPath: the file path to write it to.`);
     }
     let result;
     try {
@@ -266,12 +257,14 @@ export async function runConvert(input, deps) {
         });
     }
     catch (err) {
-        if (err instanceof BeliqApiError) {
-            const code = err.code ? ` (${err.code})` : '';
-            return errorResult(`beliq API error ${err.status}${code}: ${err.message}`);
-        }
+        if (err instanceof BeliqApiError)
+            return apiErrorResult(err);
         throw err;
     }
+    const output = result.contentType.includes('pdf') ? 'pdf' : 'xml';
+    if (output === 'pdf' && !outputPath) {
+        return errorResult('The API returned a PDF, which needs outputPath: the file path to write it to.');
+    }
     const xml = output === 'xml' ? new TextDecoder().decode(result.bytes) : undefined;
     const targetFormat = result.meta.targetFormat ?? input.targetFormat;
     let bytesWritten;
@@ -307,6 +300,8 @@ export async function runConvert(input, deps) {
             profileDetected: result.meta.profileDetected,
             lostElementsCount: result.meta.lostElementsCount,
             lostElements: result.meta.lostElements,
+            conversionTools: result.meta.conversionTools,
+            livemode: result.meta.livemode,
             outputPath,
             bytesWritten,
             xml,

package/dist/tools/validate.js

@@ -1,10 +1,13 @@
 import { validateInputShape, validateOutputShape } from '../schema.js';
 import { runValidate } from './shared.js';
 const description = [
-    'Validate an EU electronic invoice against authority-pinned, drift-checked rules and report whether it is compliant.',
-    'Accepts a UBL or CII XML document (inline via document, or a file via documentPath), or a Factur-X / ZUGFeRD PDF via documentPath.',
-    'Returns the verdict (valid or not), the detected format and profile, the ruleset (Schematron) version it was checked against, and every error and warning with its rule id, severity, location, and message.',
-    'beliq validates the compliant document; transmission (Peppol, PDP, KSeF, SDI), archiving, and tax-authority reporting stay with your access point.',
+    'Validate an EU electronic invoice and report the verdict together with how deep the check went.',
+    'Accepts an invoice XML document (inline via document, or a file via documentPath), or a Factur-X / ZUGFeRD PDF via documentPath. For a PDF the verdict is about the embedded XML: the PDF itself is not checked, and pdfInput says which embedded file was read.',
+    'Returns valid, the detected format and profile, the check depth in verificationBadgeLabel, the ruleset versions the check ran, and every error and warning with its rule id, severity, location, and message.',
+    'valid means the document passed the rule packs and schemas beliq runs for its format, in the versions the result names. It does not mean every recipient, validation tool or tax authority accepts it.',
+    'Report the check depth beside the verdict, in the words of verificationBadgeLabel. When that field is absent, say the check depth was not stated and name none.',
+    'When the result carries franceCtcBlockingRuleIds, lead with them: the API reports those French CTC rule ids as ending a transmission through a French platform, also where valid is true.',
+    'beliq validates the document; transmission (Peppol, PDP, KSeF, SDI), archiving, and tax-authority reporting stay with your access point.',
 ].join(' ');
 export function registerValidate(server, deps) {
     server.registerTool('beliq_validate_einvoice', {

package/dist/verdict.js

@@ -0,0 +1,68 @@
+/**
+ * Printed where the API sent no badge label for a verdict. It names no depth,
+ * so it claims none.
+ */
+export const DEPTH_NOT_STATED = 'check depth not stated';
+/** The API's own entry in `warnings` that explains `franceCtcBlockingRuleIds`. */
+const FRANCE_BLOCK_ENTRY = 'FRANCE_CTC_FINDINGS_BLOCK_TRANSMISSION';
+/**
+ * The verdict in the API's own words. `verified: false` means no ruleset ran
+ * (generate with verify off), so neither word applies.
+ */
+export function verdictWord(result) {
+    if (result.verified === false)
+        return 'NOT VALIDATED';
+    return result.valid ? 'VALID' : 'INVALID';
+}
+/** The badge label the API sent, printed as it came, or the mark for none. */
+export function checkDepth(result) {
+    return result.verificationBadgeLabel ?? DEPTH_NOT_STATED;
+}
+/** The France CTC rule ids the API reports as ending a transmission; empty when it sent none. */
+export function franceBlockingRuleIds(result) {
+    return result.franceCtcBlockingRuleIds ?? [];
+}
+/**
+ * The lines that explain a France CTC block: the API's own message for it when
+ * the result carries one, and the rule ids unless that message already names
+ * every one of them.
+ */
+export function franceBlockLines(result) {
+    const ids = franceBlockingRuleIds(result);
+    if (ids.length === 0)
+        return [];
+    const entry = (result.warnings ?? []).find((w) => w.ruleId === FRANCE_BLOCK_ENTRY);
+    const idLine = `France CTC blocking rule ids: ${ids.join(', ')}`;
+    if (!entry)
+        return [idLine];
+    const named = new Set(entry.message.split(/[^A-Za-z0-9_-]+/));
+    return ids.every((id) => named.has(id)) ? [entry.message] : [entry.message, idLine];
+}
+/**
+ * The embedded file's name comes from the uploaded PDF. Control and format
+ * characters, line separators and the double quote are replaced, so a crafted
+ * name can neither start a line of its own nor close the quotes around it.
+ */
+function printable(name) {
+    return name.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}"]/gu, '?');
+}
+/** What the API says about a PDF input: which embedded file was read, and that the PDF was not checked. */
+export function pdfInputLine(result) {
+    const pdf = result.pdfInput;
+    if (!pdf)
+        return undefined;
+    const name = pdf.attachmentName ? ` "${printable(pdf.attachmentName)}"` : '';
+    const others = pdf.attachmentCandidates > 1
+        ? ` ${pdf.attachmentCandidates} embedded files could be taken for the invoice, and nothing compared them.`
+        : '';
+    return (`PDF input: the verdict is about the embedded XML${name} (found by ${pdf.attachmentFoundBy}). ` +
+        `The PDF itself was not checked.${others}`);
+}
+/** Which ruleset channel the API says served the request, when the result names one. */
+export function rulesetChannelLine(result) {
+    if (!result.rulesetChannel)
+        return undefined;
+    const fellBack = result.rulesetFellBack ? ', which had nothing to reach, so the latest ruleset ran' : '';
+    const sunset = result.rulesetSunsetsOn ? `; the retained ruleset is served until ${result.rulesetSunsetsOn}` : '';
+    return `Ruleset channel: ${result.rulesetChannel}${fellBack}${sunset}`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "beliq-mcp",
-  "version": "0.3.2",
-  "description": "beliq MCP server: validate, parse, generate, and convert EU e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) against authority-pinned, drift-checked rules, for MCP clients.",
+  "version": "0.4.0",
+  "description": "beliq MCP server: validate, parse, generate, and convert EU e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) for MCP clients. Every verdict states how deep its check went.",
   "license": "MIT",
   "type": "module",
   "author": {
@@ -47,25 +47,26 @@
     "build": "npm run clean && tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
     "test": "vitest run --exclude test/integration.test.ts",
     "test:integration": "vitest run test/integration.test.ts",
     "scrub:check": "bash scripts/scrub-check.sh",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@beliq/sdk": "^0.4.0",
+    "@beliq/sdk": "^0.5.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^20.14.0",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
-    "eslint": "^8.57.0",
+    "eslint": "^10.11.0",
+    "globals": "^17.12.0",
     "typescript": "^5.5.4",
+    "typescript-eslint": "^8.70.1",
     "vitest": "^4.0.0"
   }
 }