beliq-mcp 0.3.1 → 0.3.3

package/README.md

@@ -71,9 +71,26 @@ Add to `~/.cursor/mcp.json` (or a project `.cursor/mcp.json`) using the same `mc
 
 `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.
+`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.
+- `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 verdict on the generated document: `valid`, the `schematronVersion` it ran, and `errors[]`/`warnings[]` in the same shape as validate returns. With the default `verify: true`, a document that fails validation comes back as a tool error instead of a result. With `verify: false` no ruleset runs: `valid` is false and `errors`/`warnings` are empty because nothing checked the document, not because it failed.
+
+`beliq_convert_einvoice` returns a short text summary (with the XML document appended for an XML target) plus a structured result:
+
+- `output` is `pdf` for a facturx or zugferd target and `xml` for the others, and `contentType` is the matching media type (`application/pdf` or `application/xml`).
+- `xml` is the converted document inline, present only for an XML target.
+- `outputPath` and `bytesWritten` are set when the document was written to disk: always for a PDF target, and for an XML target 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.
+- `lostElementsCount` and `lostElements` count and name the source elements that had no equivalent in the target format; `0` means nothing was lost at the element level.
 
 A PDF (Factur-X / ZUGFeRD) must be passed by `documentPath` for validate, parse, and convert, not inlined as text.
 
@@ -83,7 +100,7 @@ A PDF (Factur-X / ZUGFeRD) must be passed by `documentPath` for validate, parse,
 
 ## Development
 
-This server depends on the published [`@beliq/sdk`](https://www.npmjs.com/package/@beliq/sdk), which carries the request, transport, and result-shaping logic. No lockfile is committed; `@beliq/sdk` is resolved fresh at install time.
+This server depends on the published [`@beliq/sdk`](https://www.npmjs.com/package/@beliq/sdk), which carries the request, transport, and result-shaping logic. `package-lock.json` is committed, and CI and the release build install from it with `npm ci`.
 
 - `npm install`
 - `npm run build` - compile to `dist/`

package/dist/schema.js

@@ -117,11 +117,11 @@ export const generateInputShape = {
     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."),
+        .describe("'xml' (default) returns the document inline. 'pdf' needs outputPath to write it to: for facturx and zugferd it is a hybrid PDF/A-3 with the XML embedded; xrechnung and peppol-bis have no hybrid form, so it is a visualization with no XML inside it, and their legal document stays the XML."),
     facturxProfile: z
         .enum(LIVE_PROFILES)
         .optional()
-        .describe('Profile for a Factur-X / ZUGFeRD PDF; applies only when standard is facturx or zugferd.'),
+        .describe('Profile for a Factur-X / ZUGFeRD document; ignored for xrechnung and peppol-bis. extended-ctc-fr is Factur-X only: zugferd accepts basicwl, en16931 and extended.'),
     verify: z
         .boolean()
         .optional()
@@ -199,7 +199,3 @@ export const convertOutputShape = {
     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/tools/generate.js

@@ -3,7 +3,7 @@ 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.",
+    "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.',
 ].join(' ');

package/dist/tools/shared.js

@@ -1,5 +1,5 @@
 import { readFile, writeFile } from 'node:fs/promises';
-import { BeliqApiError } from '@beliq/sdk';
+import { BeliqApiError, isProfileAllowedForStandard, profilesForStandard, } from '@beliq/sdk';
 import { summarizeConvert, summarizeGenerate, summarizeParse, summarizeValidation } from '../summary.js';
 function errorResult(message) {
     return { content: [{ type: 'text', text: message }], isError: true };
@@ -153,6 +153,15 @@ export async function runGenerate(input, deps) {
     if (output === 'pdf' && !outputPath) {
         return errorResult('A pdf output needs outputPath: the file path to write the generated PDF to.');
     }
+    // The SDK drops facturxProfile outside the Factur-X / ZUGFeRD family. Inside
+    // it the pair is still pinned: extended-ctc-fr is Factur-X only, and the API
+    // answers it on zugferd with 422 PROFILE_STANDARD_MISMATCH. Name the legal
+    // values rather than spend a call on a pair that cannot succeed.
+    const hybrid = input.standard === 'facturx' || input.standard === 'zugferd';
+    if (hybrid && input.facturxProfile && !isProfileAllowedForStandard(input.standard, input.facturxProfile)) {
+        return errorResult(`facturxProfile '${input.facturxProfile}' is not available for ${input.standard}. ` +
+            `Use one of: ${profilesForStandard(input.standard).join(', ')}.`);
+    }
     let result;
     try {
         result = await deps.client.generate({
@@ -160,6 +169,10 @@ export async function runGenerate(input, deps) {
             invoice: input.invoice,
             output,
             facturxProfile: input.facturxProfile,
+            // XRechnung and Peppol BIS have no hybrid PDF, and the API refuses PDF
+            // for them unless the request names a visual to render. Factur-X and
+            // ZUGFeRD render theirs either way, so this is inert for them.
+            template: output === 'pdf' ? 'standard' : undefined,
             verify: input.verify ?? true,
             // Always seal so the tool can hand back the document sha256 and the
             // validation verdict for the model to cite.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beliq-mcp",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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",
@@ -56,16 +56,16 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@beliq/sdk": "^0.3.0",
+    "@beliq/sdk": "^0.4.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
     "eslint": "^8.57.0",
     "typescript": "^5.5.4",
-    "vitest": "^3.2.6"
+    "vitest": "^4.0.0"
   }
 }