@lekteo/mcp 0.1.2

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@lekteo/mcp",
+  "version": "0.1.2",
+  "type": "module",
+  "description": "Lire une facture électronique — UBL, CII, Factur-X, ZUGFeRD, XRechnung — depuis un assistant, sans que le fichier quitte votre machine",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "e-invoice",
+    "einvoice",
+    "ubl",
+    "cii",
+    "factur-x",
+    "zugferd",
+    "xrechnung",
+    "peppol",
+    "en16931",
+    "facture-electronique"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://lekteo.eu",
+  "bin": {
+    "lekteo-mcp": "./dist/server.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md",
+    "README.fr.md",
+    "README.de.md",
+    "README.nl.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/bundle.mjs",
+    "prepublishOnly": "node scripts/bundle.mjs",
+    "lint": "eslint . --max-warnings 0",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.22.0"
+  },
+  "devDependencies": {
+    "@lekteo/config": "workspace:*",
+    "@lekteo/einvoice-core": "workspace:*",
+    "@types/node": "^22.20.1",
+    "esbuild": "^0.25.0",
+    "eslint": "^9.39.5",
+    "typescript": "~5.7.3",
+    "vitest": "^4.1.10"
+  }
+}

package/src/server.ts

@@ -0,0 +1,235 @@
+/**
+ * Lekteo as an MCP server.
+ *
+ * ## Why this exists, and why it runs locally
+ *
+ * The website reads an invoice inside the browser, and anyone can verify that
+ * nothing leaves the machine by opening the network tab or unplugging the
+ * network. That verifiable promise is the product.
+ *
+ * An assistant cannot open a browser tab. Serving the same feature over a
+ * hosted endpoint would have meant uploading invoices to us — the one thing
+ * the product exists not to do. So this runs **on the user's own machine**,
+ * over stdio, launched by `npx`. The file is read from their disk, parsed in
+ * their process, and the answer goes back to their assistant.
+ *
+ * The promise is not merely preserved, it widens: it now holds outside the
+ * browser too.
+ *
+ * ## How to check that claim rather than believe it
+ *
+ * This server performs **no network access of any kind**. There is no HTTP
+ * client, no telemetry, no update check. It is verifiable without reading a
+ * line of logic:
+ *
+ *     grep -c "fetch(\|https://\|http://" "$(npm root -g)/@lekteo/mcp/dist/server.js"
+ *
+ * The only addresses in the bundle are in comments and in error messages.
+ */
+
+import { readFile, stat } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type CallToolResult,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { readInvoiceFromBytes, toJson, type ReadResult } from '@lekteo/einvoice-core';
+import { isSupportedLocale, renderFinding } from '@lekteo/einvoice-core/i18n';
+
+const VERSION = '0.1.2';
+
+/**
+ * Language of the sentences handed back.
+ *
+ * The findings carry codes, never prose; the wording is produced here. An
+ * assistant conversing in German should not receive French diagnostics, so
+ * the language is a parameter of every tool rather than a setting of the
+ * server — the same session may switch.
+ */
+const DEFAULT_LOCALE = 'fr';
+function localeOf(value: unknown): string {
+  return typeof value === 'string' && isSupportedLocale(value) ? value : DEFAULT_LOCALE;
+}
+
+/**
+ * Refuse a path we were not given deliberately.
+ *
+ * The assistant chooses the path, not the user, and a model that has just
+ * been told "check my invoices" is entirely capable of trying `/etc/passwd`
+ * to see what happens. Reading is confined to real files, and the size guard
+ * of the engine applies unchanged.
+ */
+async function loadFile(path: unknown): Promise<{ bytes: Uint8Array; name: string }> {
+  if (typeof path !== 'string' || path.trim() === '') {
+    throw new Error('Le chemin du fichier est requis.');
+  }
+  const full = resolve(path);
+  const info = await stat(full).catch(() => null);
+  if (info === null) throw new Error(`Aucun fichier à cette adresse : ${full}`);
+  if (!info.isFile()) throw new Error(`Ce n'est pas un fichier : ${full}`);
+  return { bytes: new Uint8Array(await readFile(full)), name: basename(full) };
+}
+
+/** The findings, turned into sentences a human can act on. */
+function findingsOf(result: ReadResult, locale: string) {
+  return result.findings.map((finding) => {
+    const rendered = renderFinding(finding, locale);
+    return {
+      code: finding.code,
+      severity: finding.severity,
+      message: rendered.message,
+      explanation: rendered.explanation ?? null,
+      where: rendered.path ?? null,
+    };
+  });
+}
+
+/**
+ * The findings as an export wants them: the machine fields kept whole, the
+ * sentences added on top.
+ *
+ * `findingsOf` trims to what a human reads; a JSON export feeds a script,
+ * which may well need `params` and the structured path the caption is made
+ * from. Losing them to gain a sentence would be a poor trade.
+ */
+function findingsForExport(result: ReadResult, locale: string) {
+  return result.findings.map((finding) => {
+    const rendered = renderFinding(finding, locale);
+    return {
+      ...finding,
+      message: rendered.message,
+      explanation: rendered.explanation ?? null,
+      where: rendered.path ?? null,
+    };
+  });
+}
+
+function summaryOf(result: ReadResult) {
+  return {
+    readable: result.ok,
+    syntax: result.syntax,
+    profile: result.profile,
+    compliant: result.summary.compliant,
+    errors: result.summary.errors,
+    warnings: result.summary.warnings,
+    infos: result.summary.infos,
+  };
+}
+
+const text = (value: unknown): CallToolResult => ({
+  content: [
+    { type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) },
+  ],
+});
+
+const TOOLS = [
+  {
+    name: 'read_invoice',
+    description:
+      'Read an electronic invoice file (UBL 2.1, CII D22B, Factur-X, ZUGFeRD, XRechnung) and return it as readable data: parties, lines, VAT breakdown, totals, payment details. The file is read locally and never transmitted anywhere.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path to the .xml or .pdf file.',
+        },
+        locale: {
+          type: 'string',
+          enum: ['fr', 'en', 'de', 'nl'],
+          description: 'Language of the findings. Defaults to French.',
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'check_invoice',
+    description:
+      'Check an electronic invoice against the European EN 16931 standard without returning its content. Reports whether it is compliant and lists what fails: IBAN check digits, VAT amounts against their taxable base, mandatory fields, date consistency. Use this when the question is "is this file in order".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path to the .xml or .pdf file.',
+        },
+        locale: { type: 'string', enum: ['fr', 'en', 'de', 'nl'] },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'invoice_to_json',
+    description:
+      'Read an invoice and return the full canonical model as JSON, findings included. Use this to feed the data into a script or a spreadsheet rather than to read it.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute or relative path to the .xml or .pdf file.',
+        },
+        locale: { type: 'string', enum: ['fr', 'en', 'de', 'nl'] },
+      },
+      required: ['path'],
+    },
+  },
+];
+
+const server = new Server({ name: 'lekteo', version: VERSION }, { capabilities: { tools: {} } });
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const args = (request.params.arguments ?? {}) as Record<string, unknown>;
+  try {
+    const { bytes, name } = await loadFile(args.path);
+    const result = readInvoiceFromBytes(bytes, name);
+    const locale = localeOf(args.locale);
+
+    switch (request.params.name) {
+      case 'read_invoice':
+        return text({
+          file: name,
+          ...summaryOf(result),
+          invoice: result.invoice,
+          findings: findingsOf(result, locale),
+        });
+
+      case 'check_invoice':
+        return text({ file: name, ...summaryOf(result), findings: findingsOf(result, locale) });
+
+      case 'invoice_to_json':
+        return text(
+          toJson({
+            syntax: result.syntax,
+            profile: result.profile,
+            invoice: result.invoice,
+            findings: findingsForExport(result, locale),
+            fileName: name,
+          }),
+        );
+
+      default:
+        throw new Error(`Outil inconnu : ${request.params.name}`);
+    }
+  } catch (error) {
+    // Returned as a result rather than thrown: an unreadable file is an
+    // answer, not a crash. The assistant can relay the sentence to the user,
+    // which is the whole point of writing findings in plain language.
+    return {
+      isError: true,
+      content: [
+        { type: 'text', text: error instanceof Error ? error.message : 'Lecture impossible.' },
+      ],
+    };
+  }
+});
+
+await server.connect(new StdioServerTransport());