beliq-mcp 0.1.1 → 0.3.0

package/README.md

@@ -1,12 +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** 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 other UBL/CII documents) against authority-pinned, drift-checked rules, and explain exactly what fails.
 
-beliq validates the compliant document. Transmission (Peppol, PDP, KSeF, SDI), archiving, and tax-authority reporting stay with your access point.
+beliq produces and checks the compliant 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_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
@@ -25,7 +28,7 @@ The server is configured entirely through environment variables (see below).
 |---|---|---|---|
 | `BELIQ_API_KEY` | yes | - | API key from the beliq dashboard (API Keys). |
 | `BELIQ_AUTH` | no | `header` | How the key is sent: `header` (X-API-Key) or `bearer` (Authorization: Bearer). |
-| `BELIQ_BASE_URL` | no | `https://api.beliq.eu` | Override for self-hosted or staging. |
+| `BELIQ_BASE_URL` | no | `https://api.beliq.eu` | Override for a self-hosted deployment; defaults to the production API. |
 
 ## Client setup
 
@@ -57,7 +60,7 @@ Add to `claude_desktop_config.json` (Settings > Developer > Edit Config):
 
 Add to `~/.cursor/mcp.json` (or a project `.cursor/mcp.json`) using the same `mcpServers` block shown for Claude Desktop.
 
-## Reading a validation result
+## Reading a result
 
 `beliq_validate_einvoice` returns a short text verdict plus a structured result:
 
@@ -66,7 +69,13 @@ Add to `~/.cursor/mcp.json` (or a project `.cursor/mcp.json`) using the same `mc
 - `schematronVersion` is the exact ruleset revision the check ran against.
 - `errors[]` and `warnings[]` each carry `ruleId`, `severity`, `location` (an XPath when available), and `message`.
 
-A PDF (Factur-X / ZUGFeRD) must be passed by `documentPath`, not inlined as text.
+`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.
+
+A PDF (Factur-X / ZUGFeRD) must be passed by `documentPath` for validate, parse, and convert, not inlined as text.
 
 ## Agent skill
 

package/dist/schema.js

@@ -1,7 +1,9 @@
 import { z } from 'zod';
-// Validate accepts the live, publicly offered source-syntax hints only. The
-// engine can technically detect more, but the public option set stays narrow
-// (LPD-1): callers pass the syntax family, not a country profile.
+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.
 export const validateInputShape = {
     document: z
         .string()
@@ -44,4 +46,160 @@ export const checkAccountOutputShape = {
     plan: z.string().optional(),
     message: z.string(),
 };
+// ── Parse ────────────────────────────────────────────────────────────────
+export const parseInputShape = {
+    document: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('The invoice as XML text. Provide this OR documentPath, not both.'),
+    documentPath: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Path to an invoice file on disk: a UBL/CII XML, or a Factur-X / ZUGFeRD PDF. Provide this OR document.'),
+    format: z
+        .enum(LIVE_PARSE_FORMATS)
+        .optional()
+        .describe("Source syntax hint. 'auto' (default) detects CII vs UBL from the document."),
+};
+// 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.
+export const parseOutputShape = {
+    format: z.string(),
+    profileDetected: z.string().optional(),
+    invoice: z.record(z.string(), z.unknown()),
+};
+// ── Generate ──────────────────────────────────────────────────────────────
+const partyAddress = z
+    .object({
+    city: z.string(),
+    postalCode: z.string(),
+    countryCode: z.string().describe('ISO 3166-1 alpha-2, e.g. DE.'),
+    street: z.string().optional(),
+})
+    .passthrough();
+const party = z
+    .object({
+    name: z.string(),
+    vatId: z.string().optional(),
+    address: partyAddress,
+})
+    .passthrough();
+const invoiceLine = z
+    .object({
+    description: z.string(),
+    quantity: z.number(),
+    unitCode: z.string().describe('UN/ECE Rec 20 unit code, e.g. HUR (hour), C62 (unit).'),
+    unitPrice: z.number(),
+    lineTotal: z.number(),
+    vatRate: z.number(),
+    vatCategoryCode: z.string().describe('UNCL5305 VAT category, e.g. S, Z, E.'),
+})
+    .passthrough();
+const invoice = z
+    .object({
+    number: z.string(),
+    issueDate: z.string().describe('ISO date, YYYY-MM-DD.'),
+    currencyCode: z.string().describe('ISO 4217, e.g. EUR.'),
+    seller: party,
+    buyer: party,
+    lines: z.array(invoiceLine).min(1),
+    totalNetAmount: z.number(),
+    totalTaxAmount: z.number(),
+    totalGrossAmount: z.number(),
+})
+    .passthrough()
+    .describe('The EN 16931 invoice to render. Extra fields (dueDate, buyerReference, paymentMeans, taxSummary, per-country blocks) are passed through to the API.');
+export const generateInputShape = {
+    standard: z.enum(LIVE_GENERATE_STANDARDS).describe('Target e-invoice standard to produce.'),
+    invoice,
+    output: z
+        .enum(['xml', 'pdf'])
+        .optional()
+        .describe("'xml' (default) returns the document inline. 'pdf' produces a Factur-X / ZUGFeRD hybrid PDF and needs outputPath to write it to."),
+    facturxProfile: z
+        .enum(LIVE_PROFILES)
+        .optional()
+        .describe('Profile for a Factur-X / ZUGFeRD PDF; applies only when standard is facturx or zugferd.'),
+    verify: z
+        .boolean()
+        .optional()
+        .describe('Validate the generated document before returning and fail if it is not compliant. Defaults to true.'),
+    outputPath: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Where to write the generated document on disk. Required for pdf output, optional for xml. The call fails if a file already exists at the path.'),
+};
+export const generateOutputShape = {
+    output: z.enum(['xml', 'pdf']),
+    contentType: z.string(),
+    schematronVersion: z.string().optional(),
+    pdfKind: z.string().optional(),
+    outputPath: z.string().optional(),
+    bytesWritten: z.number().optional(),
+    xml: z.string().optional(),
+    // The verify-it-yourself seal: sha256 of the returned document, the combined
+    // ruleset fingerprint it was checked against, and the validation verdict.
+    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(),
+};
+// ── Convert ────────────────────────────────────────────────────────────────
+export const convertInputShape = {
+    document: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('The source invoice as XML text. Provide this OR documentPath, not both.'),
+    documentPath: z
+        .string()
+        .min(1)
+        .optional()
+        .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.'),
+    sourceFormat: z
+        .enum(LIVE_CONVERT_SOURCE_FORMATS)
+        .optional()
+        .describe("Source format hint. 'auto' (default) detects it from the document."),
+    targetProfile: z
+        .enum(LIVE_PROFILES)
+        .optional()
+        .describe('Profile for a facturx or zugferd target; ignored for the XML targets.'),
+    dropFranceCtcOverlay: z
+        .boolean()
+        .optional()
+        .describe('Drop the French CTC (Factur-X / Chorus Pro) 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.'),
+};
+export const convertOutputShape = {
+    output: z.enum(['xml', '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(),
+    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);

package/dist/summary.js

@@ -34,3 +34,60 @@ export function summarizeValidation(result) {
         `${plural(errors.length, 'error')}, ${plural(warnings.length, 'warning')}.`;
     return [header, ...listSection('Errors', errors), ...listSection('Warnings', warnings)].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.
+ */
+export function summarizeParse(result) {
+    const invoice = result.invoice;
+    const profile = result.profileDetected ? ` (profile ${result.profileDetected})` : '';
+    const number = invoice?.number ? `invoice ${invoice.number}` : 'invoice';
+    const lines = invoice?.lines?.length ?? 0;
+    const gross = invoice?.totalGrossAmount != null
+        ? `, gross ${invoice.totalGrossAmount} ${invoice.currencyCode ?? ''}`.trimEnd()
+        : '';
+    return `Parsed a ${result.format}${profile} document: ${number}, ${plural(lines, 'line')}${gross}.`;
+}
+/**
+ * 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.
+ */
+export function summarizeGenerate(g) {
+    const checked = g.schematronVersion ? `, checked against Schematron ${g.schematronVersion}` : '';
+    const seal = g.sha256
+        ? ` Document sha256 ${g.sha256}${g.valid === undefined ? '' : `; validation ${g.valid ? 'passed' : 'failed'}`}.`
+        : '';
+    const header = `Generated a ${g.standard} ${g.output} document${checked}.${seal}`;
+    if (g.output === 'pdf') {
+        const where = g.outputPath ? ` Written to ${g.outputPath} (${plural(g.bytesWritten ?? 0, 'byte')}).` : '';
+        return `${header}${where}`;
+    }
+    const wrote = g.outputPath ? ` Written to ${g.outputPath}.` : '';
+    const body = g.xml ? `\n\n${g.xml}` : '';
+    return `${header}${wrote}${body}`;
+}
+/**
+ * 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.
+ */
+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 lost = c.lostElementsCount && c.lostElementsCount > 0
+        ? ` ${plural(c.lostElementsCount, 'element')} could not be carried across.`
+        : '';
+    const header = `Converted ${fromClause}to ${target}${profile}.${lost}`;
+    if (c.output === 'pdf') {
+        const where = c.outputPath ? ` Written to ${c.outputPath} (${plural(c.bytesWritten ?? 0, 'byte')}).` : '';
+        return `${header}${where}`;
+    }
+    const wrote = c.outputPath ? ` Written to ${c.outputPath}.` : '';
+    const body = c.xml ? `\n\n${c.xml}` : '';
+    return `${header}${wrote}${body}`;
+}

package/dist/tools/convert.js

@@ -0,0 +1,24 @@
+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.',
+    '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) {
+    server.registerTool('beliq_convert_einvoice', {
+        title: 'beliq: Convert E-Invoice',
+        description,
+        inputSchema: convertInputShape,
+        outputSchema: convertOutputShape,
+        annotations: {
+            title: 'beliq: Convert E-Invoice',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args) => runConvert(args, deps));
+}

package/dist/tools/generate.js

@@ -0,0 +1,24 @@
+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.',
+    "output 'xml' (default) returns the document inline; 'pdf' produces a Factur-X / ZUGFeRD hybrid PDF, which needs outputPath to write it to.",
+    '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.',
+].join(' ');
+export function registerGenerate(server, deps) {
+    server.registerTool('beliq_generate_einvoice', {
+        title: 'beliq: Generate E-Invoice',
+        description,
+        inputSchema: generateInputShape,
+        outputSchema: generateOutputShape,
+        annotations: {
+            title: 'beliq: Generate E-Invoice',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args) => runGenerate(args, deps));
+}

package/dist/tools/parse.js

@@ -0,0 +1,23 @@
+import { parseInputShape, parseOutputShape } from '../schema.js';
+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.',
+].join(' ');
+export function registerParse(server, deps) {
+    server.registerTool('beliq_parse_einvoice', {
+        title: 'beliq: Parse E-Invoice',
+        description,
+        inputSchema: parseInputShape,
+        outputSchema: parseOutputShape,
+        annotations: {
+            title: 'beliq: Parse E-Invoice',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => runParse(args, deps));
+}

package/dist/tools/register.js

@@ -1,7 +1,13 @@
 import { registerValidate } from './validate.js';
 import { registerCheckAccount } from './checkAccount.js';
+import { registerParse } from './parse.js';
+import { registerGenerate } from './generate.js';
+import { registerConvert } from './convert.js';
 /** Register every beliq tool on the server with the given dependencies. */
 export function registerAllTools(server, deps) {
     registerValidate(server, deps);
+    registerParse(server, deps);
+    registerGenerate(server, deps);
+    registerConvert(server, deps);
     registerCheckAccount(server, deps);
 }

package/dist/tools/shared.js

@@ -1,6 +1,6 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
 import { BeliqApiError } from '@beliq/sdk';
-import { summarizeValidation } from '../summary.js';
+import { summarizeConvert, summarizeGenerate, summarizeParse, summarizeValidation } from '../summary.js';
 function errorResult(message) {
     return { content: [{ type: 'text', text: message }], isError: true };
 }
@@ -10,10 +10,12 @@ 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']);
 /**
- * Resolve the tool input to the bytes/text the SDK validates. Exactly one of
- * document (inline XML) or documentPath (a file on disk) must be set; a file is
- * read as raw bytes so the SDK can sniff XML vs an embedded-XML PDF.
+ * 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
+ * file is read as raw bytes so the SDK can sniff XML vs an embedded-XML PDF.
  */
 async function resolveDocument(input) {
     const hasDoc = nonEmpty(input.document);
@@ -103,3 +105,198 @@ export async function runCheckAccount(deps) {
         throw err;
     }
 }
+/**
+ * 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
+ * self-correct; only unexpected faults throw.
+ */
+export async function runParse(input, deps) {
+    let document;
+    try {
+        document = await resolveDocument(input);
+    }
+    catch (err) {
+        if (err instanceof BeliqInputError)
+            return errorResult(err.message);
+        return errorResult(`Could not read the document: ${err.message}`);
+    }
+    try {
+        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,
+            },
+        };
+    }
+    catch (err) {
+        if (err instanceof BeliqApiError) {
+            const code = err.code ? ` (${err.code})` : '';
+            return errorResult(`beliq API error ${err.status}${code}: ${err.message}`);
+        }
+        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.
+ */
+export async function runGenerate(input, deps) {
+    const output = input.output ?? 'xml';
+    const outputPath = nonEmpty(input.outputPath) ? input.outputPath.trim() : undefined;
+    if (output === 'pdf' && !outputPath) {
+        return errorResult('A pdf output needs outputPath: the file path to write the generated PDF to.');
+    }
+    let result;
+    try {
+        result = await deps.client.generate({
+            standard: input.standard,
+            invoice: input.invoice,
+            output,
+            facturxProfile: input.facturxProfile,
+            verify: input.verify ?? true,
+            // Always seal so the tool can hand back the document sha256 and the
+            // validation verdict for the model to cite.
+            seal: true,
+        });
+    }
+    catch (err) {
+        if (err instanceof BeliqApiError) {
+            const code = err.code ? ` (${err.code})` : '';
+            return errorResult(`beliq API error ${err.status}${code}: ${err.message}`);
+        }
+        throw err;
+    }
+    let bytesWritten;
+    if (outputPath) {
+        try {
+            await writeFile(outputPath, result.bytes, { flag: 'wx' });
+            bytesWritten = result.bytes.byteLength;
+        }
+        catch (err) {
+            if (err.code === 'EEXIST') {
+                return errorResult(`A file already exists at ${outputPath}. Choose a path that does not exist.`);
+            }
+            return errorResult(`Could not write the document: ${err.message}`);
+        }
+    }
+    const vr = result.validationResult;
+    const text = summarizeGenerate({
+        standard: input.standard,
+        output,
+        schematronVersion: result.meta.schematronVersion,
+        outputPath,
+        bytesWritten,
+        xml: output === 'xml' ? result.xml : undefined,
+        sha256: result.sha256,
+        valid: vr?.valid,
+    });
+    return {
+        content: [{ type: 'text', text }],
+        structuredContent: {
+            output,
+            contentType: result.contentType,
+            schematronVersion: result.meta.schematronVersion,
+            pdfKind: result.meta.pdfKind,
+            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,
+        },
+    };
+}
+/**
+ * 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.
+ */
+export async function runConvert(input, deps) {
+    let document;
+    try {
+        document = await resolveDocument(input);
+    }
+    catch (err) {
+        if (err instanceof BeliqInputError)
+            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.`);
+    }
+    let result;
+    try {
+        result = await deps.client.convert(document, {
+            targetFormat: input.targetFormat,
+            sourceFormat: input.sourceFormat,
+            targetProfile: input.targetProfile,
+            dropFranceCtcOverlay: input.dropFranceCtcOverlay,
+        });
+    }
+    catch (err) {
+        if (err instanceof BeliqApiError) {
+            const code = err.code ? ` (${err.code})` : '';
+            return errorResult(`beliq API error ${err.status}${code}: ${err.message}`);
+        }
+        throw err;
+    }
+    const xml = output === 'xml' ? new TextDecoder().decode(result.bytes) : undefined;
+    const targetFormat = result.meta.targetFormat ?? input.targetFormat;
+    let bytesWritten;
+    if (outputPath) {
+        try {
+            await writeFile(outputPath, result.bytes, { flag: 'wx' });
+            bytesWritten = result.bytes.byteLength;
+        }
+        catch (err) {
+            if (err.code === 'EEXIST') {
+                return errorResult(`A file already exists at ${outputPath}. Choose a path that does not exist.`);
+            }
+            return errorResult(`Could not write the document: ${err.message}`);
+        }
+    }
+    const text = summarizeConvert({
+        output,
+        sourceFormat: result.meta.sourceFormat,
+        targetFormat,
+        profileDetected: result.meta.profileDetected,
+        lostElementsCount: result.meta.lostElementsCount,
+        outputPath,
+        bytesWritten,
+        xml,
+    });
+    return {
+        content: [{ type: 'text', text }],
+        structuredContent: {
+            output,
+            contentType: result.contentType,
+            sourceFormat: result.meta.sourceFormat,
+            targetFormat,
+            profileDetected: result.meta.profileDetected,
+            lostElementsCount: result.meta.lostElementsCount,
+            lostElements: result.meta.lostElements,
+            outputPath,
+            bytesWritten,
+            xml,
+        },
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "beliq-mcp",
-  "version": "0.1.1",
-  "description": "beliq MCP server: validate EU e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) against authority-pinned, drift-checked rules, for MCP clients.",
+  "version": "0.3.0",
+  "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.",
   "license": "MIT",
   "type": "module",
   "author": {
@@ -56,7 +56,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@beliq/sdk": "^0.1.0",
+    "@beliq/sdk": "^0.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3"
   },