beliq-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 beliq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# 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.
+
+beliq validates 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_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
+
+Requires Node.js >= 20.15. Published to npm, so clients can run it with `npx`:
+
+```
+npx -y beliq-mcp
+```
+
+The server is configured entirely through environment variables (see below).
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `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. |
+
+## Client setup
+
+### Claude Code
+
+```
+claude mcp add beliq -e BELIQ_API_KEY=your-key -- npx -y beliq-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings > Developer > Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "beliq": {
+      "command": "npx",
+      "args": ["-y", "beliq-mcp"],
+      "env": {
+        "BELIQ_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (or a project `.cursor/mcp.json`) using the same `mcpServers` block shown for Claude Desktop.
+
+## Reading a validation result
+
+`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.
+- `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`.
+
+A PDF (Factur-X / ZUGFeRD) must be passed by `documentPath`, 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.
+
+## 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.
+
+- `npm install`
+- `npm run build` - compile to `dist/`
+- `npm run typecheck`
+- `npm run lint`
+- `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
+
+Run the built server directly for a quick check:
+
+```
+BELIQ_API_KEY=your-key node dist/index.js
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/config.js

@@ -0,0 +1,14 @@
+import { DEFAULT_BASE_URL } from '@beliq/sdk';
+/**
+ * Build the typed config from the environment. Throws if BELIQ_API_KEY is
+ * missing so the server fails fast before connecting the transport.
+ */
+export function loadConfig(env = process.env) {
+    const apiKey = env.BELIQ_API_KEY?.trim();
+    if (!apiKey) {
+        throw new Error('BELIQ_API_KEY is required. Create a key in the beliq dashboard under API Keys and set it in the MCP server env.');
+    }
+    const baseUrl = (env.BELIQ_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const auth = env.BELIQ_AUTH?.trim().toLowerCase() === 'bearer' ? 'bearer' : 'header';
+    return { apiKey, baseUrl, auth };
+}

package/dist/deps.js

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// On stdio, stdout carries the JSON-RPC protocol. All diagnostics MUST go to
+// stderr; a stray console.log anywhere reachable from the running server
+// corrupts the protocol stream.
+import { createRequire } from 'node:module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Beliq } from '@beliq/sdk';
+import { loadConfig } from './config.js';
+import { registerAllTools } from './tools/register.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+async function main() {
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (err) {
+        console.error(`[beliq-mcp] ${err.message}`);
+        process.exit(1);
+    }
+    const client = new Beliq({ apiKey: config.apiKey, baseUrl: config.baseUrl, auth: config.auth });
+    const server = new McpServer({ name: 'beliq-mcp', version });
+    registerAllTools(server, { client });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[beliq-mcp] v${version} ready on stdio (base ${config.baseUrl})`);
+}
+main().catch((err) => {
+    console.error('[beliq-mcp] fatal:', err);
+    process.exit(1);
+});

package/dist/schema.js

@@ -0,0 +1,47 @@
+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.
+export const validateInputShape = {
+    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 PDF carrying embedded XML (Factur-X / ZUGFeRD). Provide this OR document.'),
+    format: z
+        .enum(['auto', 'cii', 'ubl'])
+        .optional()
+        .describe("Source syntax hint. 'auto' (default) detects CII vs UBL from the document."),
+    franceCtc: z
+        .boolean()
+        .optional()
+        .describe('Apply the French CTC (Factur-X / Chorus Pro) rule overlay during validation.'),
+};
+const issueShape = z.object({
+    ruleId: z.string(),
+    severity: z.string(),
+    location: z.string().optional(),
+    message: z.string(),
+});
+export const validateOutputShape = {
+    valid: z.boolean(),
+    format: z.string(),
+    profileDetected: z.string().optional(),
+    schematronVersion: z.string().optional(),
+    errorCount: z.number(),
+    warningCount: z.number(),
+    errors: z.array(issueShape),
+    warnings: z.array(issueShape),
+};
+export const checkAccountOutputShape = {
+    ok: z.boolean(),
+    status: z.number(),
+    plan: z.string().optional(),
+    message: z.string(),
+};
+const validateInputSchema = z.object(validateInputShape);

package/dist/summary.js

@@ -0,0 +1,36 @@
+/** How many issues to spell out before collapsing the rest into a count. */
+const MAX_LISTED_ISSUES = 20;
+function issueLine(issue) {
+    const where = issue.location ? ` at ${issue.location}` : '';
+    return `- ${issue.ruleId} (${issue.severity})${where}: ${issue.message}`;
+}
+function plural(n, word) {
+    return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
+function listSection(title, issues) {
+    if (!issues.length)
+        return [];
+    const shown = issues.slice(0, MAX_LISTED_ISSUES);
+    const lines = [`${title}:`, ...shown.map(issueLine)];
+    if (issues.length > shown.length) {
+        lines.push(`... and ${issues.length - shown.length} more.`);
+    }
+    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.
+ */
+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}. ` +
+        `${plural(errors.length, 'error')}, ${plural(warnings.length, 'warning')}.`;
+    return [header, ...listSection('Errors', errors), ...listSection('Warnings', warnings)].join('\n');
+}

package/dist/tools/checkAccount.js

@@ -0,0 +1,17 @@
+import { checkAccountOutputShape } from '../schema.js';
+import { runCheckAccount } from './shared.js';
+export function registerCheckAccount(server, deps) {
+    server.registerTool('beliq_check_account', {
+        title: 'beliq: Check Account',
+        description: 'Verify the configured beliq API key and report the plan and remaining quota. Calls GET /v1/me, which draws no quota. Use it as a connection and credential smoke test.',
+        inputSchema: {},
+        outputSchema: checkAccountOutputShape,
+        annotations: {
+            title: 'beliq: Check Account',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async () => runCheckAccount(deps));
+}

package/dist/tools/register.js

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

package/dist/tools/shared.js

@@ -0,0 +1,105 @@
+import { readFile } from 'node:fs/promises';
+import { BeliqApiError } from '@beliq/sdk';
+import { summarizeValidation } from '../summary.js';
+function errorResult(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/** A bad tool input that should come back as a normal (non-fatal) tool error. */
+class BeliqInputError extends Error {
+}
+/**
+ * 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.
+ */
+async function resolveDocument(input) {
+    const hasDoc = nonEmpty(input.document);
+    const hasPath = nonEmpty(input.documentPath);
+    if (hasDoc === hasPath) {
+        throw new BeliqInputError('Provide exactly one of document (XML text) or documentPath (a file path).');
+    }
+    if (hasDoc)
+        return input.document;
+    return readFile(input.documentPath.trim());
+}
+/**
+ * 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.
+ */
+export async function runValidate(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.validate(document, {
+            format: input.format,
+            franceCtc: input.franceCtc,
+        });
+        const errors = result.errors ?? [];
+        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,
+            },
+        };
+    }
+    catch (err) {
+        if (err instanceof BeliqApiError) {
+            const code = err.code ? ` (${err.code})` : '';
+            return errorResult(`beliq API error ${err.status}${code}: ${err.message}`);
+        }
+        throw err;
+    }
+}
+/**
+ * Verify the configured key against GET /v1/me, which draws no quota. Reports
+ * validity rather than throwing, so a rejected key is a normal (non-error)
+ * result the model can act on.
+ */
+export async function runCheckAccount(deps) {
+    const reply = (r) => ({
+        content: [{ type: 'text', text: r.message }],
+        structuredContent: { ...r },
+    });
+    try {
+        const account = await deps.client.me();
+        const plan = account.plan?.name ?? undefined;
+        const quota = account.quota;
+        const quotaText = quota
+            ? ` Quota: ${quota.used}/${quota.limit} used, ${quota.remaining} remaining.`
+            : '';
+        return reply({
+            ok: true,
+            status: 200,
+            plan,
+            message: `beliq credentials valid; the API key was accepted.${plan ? ` Plan: ${plan}.` : ''}${quotaText}`,
+        });
+    }
+    catch (err) {
+        if (err instanceof BeliqApiError) {
+            const message = err.status === 401
+                ? 'beliq API key rejected (401). Check the key set in BELIQ_API_KEY.'
+                : `Credential check failed (${err.status}): ${err.message}`;
+            return reply({ ok: false, status: err.status, message });
+        }
+        throw err;
+    }
+}

package/dist/tools/validate.js

@@ -0,0 +1,23 @@
+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.',
+].join(' ');
+export function registerValidate(server, deps) {
+    server.registerTool('beliq_validate_einvoice', {
+        title: 'beliq: Validate E-Invoice',
+        description,
+        inputSchema: validateInputShape,
+        outputSchema: validateOutputShape,
+        annotations: {
+            title: 'beliq: Validate E-Invoice',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => runValidate(args, deps));
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "beliq-mcp",
+  "version": "0.1.0",
+  "description": "beliq MCP server: validate EU e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) against authority-pinned, drift-checked rules, for MCP clients.",
+  "license": "MIT",
+  "type": "module",
+  "author": {
+    "name": "beliq",
+    "email": "hello@beliq.eu"
+  },
+  "homepage": "https://beliq.eu",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beliq-eu/beliq-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/beliq-eu/beliq-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "beliq",
+    "e-invoice",
+    "einvoice",
+    "xrechnung",
+    "zugferd",
+    "factur-x",
+    "peppol",
+    "en16931",
+    "validation",
+    "compliance"
+  ],
+  "engines": {
+    "node": ">=20.15"
+  },
+  "bin": {
+    "beliq-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "provenance": true
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --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.1.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",
+    "eslint": "^8.57.0",
+    "typescript": "^5.5.4",
+    "vitest": "^2.1.8"
+  }
+}