@frihet/mcp-server 1.14.1 → 1.14.2

package/README.md

@@ -39,7 +39,7 @@
 | **ChatGPT Apps** | Coming soon | [chatgpt.com](https://chatgpt.com) |
 | **Anthropic Claude Directory** | Coming soon | [claude.ai/settings/connectors](https://claude.ai/settings/connectors) |
 
-> **Tool count:** npm `latest` (1.14.1) ships all 157 tools, same as the remote endpoint (`mcp.frihet.io`).
+> **Tool count:** npm `latest` (1.14.2) ships all 157 tools, same as the remote endpoint (`mcp.frihet.io`).
 
 ---
 

package/dist/__tests__/contract.test.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Output-schema CONTRACT tests.
+ *
+ * WHY THIS FILE EXISTS (the bug class it locks down forever):
+ *
+ * The MCP tools declare Zod `outputSchema`s and put the raw Cloud Function (CF)
+ * response into `structuredContent`. The CF response has TWO shapes that have
+ * historically drifted from the schemas and broken tools silently:
+ *
+ *   1. The `{ data, meta }` ENVELOPE. Single-object reads (e.g. the shipped
+ *      `/v1/fiscal/modelo/:code` CF) return `res.json({ data: <item>, meta })`;
+ *      list reads return `{ data: [<item>...], total, limit, offset }`. The
+ *      client unwraps single objects to `body.data` (`requestUnwrapped`) and
+ *      keeps the paginated envelope (`requestPaginated`). If the schema and the
+ *      unwrap disagree, the tool emits a structuredContent the model can't parse.
+ *
+ *   2. Firestore-TIMESTAMP-shaped fields. Firestore-direct reads can leak
+ *      `{ _seconds, _nanoseconds }` objects on date-ish fields instead of ISO
+ *      strings. The enumerated date fields are typed `z.string()`, so a raw
+ *      timestamp on `createdAt` would FAIL — but `.passthrough()` carries extra
+ *      Firestore-internal timestamp fields (`_syncedAt`, `lastTouchedAt`, …)
+ *      through untouched. This test pins BOTH facts: enumerated dates stay ISO
+ *      strings, and extra `{_seconds}` fields pass via `.passthrough()`.
+ *
+ * If a future refactor tightens a schema (drops `.passthrough()`, or retypes a
+ * passthrough timestamp field as `z.string()`), or the CF starts returning a
+ * shape the schema rejects, THIS test goes red in CI — instead of the bug
+ * reaching an LLM as an unparseable tool result.
+ *
+ * Run: npm test (after build) — node:test + node:assert.
+ */
+export {};
+//# sourceMappingURL=contract.test.d.ts.map

package/dist/__tests__/contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/contract.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG"}

package/dist/__tests__/contract.test.js

@@ -0,0 +1,208 @@
+/**
+ * Output-schema CONTRACT tests.
+ *
+ * WHY THIS FILE EXISTS (the bug class it locks down forever):
+ *
+ * The MCP tools declare Zod `outputSchema`s and put the raw Cloud Function (CF)
+ * response into `structuredContent`. The CF response has TWO shapes that have
+ * historically drifted from the schemas and broken tools silently:
+ *
+ *   1. The `{ data, meta }` ENVELOPE. Single-object reads (e.g. the shipped
+ *      `/v1/fiscal/modelo/:code` CF) return `res.json({ data: <item>, meta })`;
+ *      list reads return `{ data: [<item>...], total, limit, offset }`. The
+ *      client unwraps single objects to `body.data` (`requestUnwrapped`) and
+ *      keeps the paginated envelope (`requestPaginated`). If the schema and the
+ *      unwrap disagree, the tool emits a structuredContent the model can't parse.
+ *
+ *   2. Firestore-TIMESTAMP-shaped fields. Firestore-direct reads can leak
+ *      `{ _seconds, _nanoseconds }` objects on date-ish fields instead of ISO
+ *      strings. The enumerated date fields are typed `z.string()`, so a raw
+ *      timestamp on `createdAt` would FAIL — but `.passthrough()` carries extra
+ *      Firestore-internal timestamp fields (`_syncedAt`, `lastTouchedAt`, …)
+ *      through untouched. This test pins BOTH facts: enumerated dates stay ISO
+ *      strings, and extra `{_seconds}` fields pass via `.passthrough()`.
+ *
+ * If a future refactor tightens a schema (drops `.passthrough()`, or retypes a
+ * passthrough timestamp field as `z.string()`), or the CF starts returning a
+ * shape the schema rejects, THIS test goes red in CI — instead of the bug
+ * reaching an LLM as an unparseable tool result.
+ *
+ * Run: npm test (after build) — node:test + node:assert.
+ */
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { fiscalModeloSummaryOutput, verifactuStatusOutput, paginatedOutput, invoiceItemOutput, expenseItemOutput, clientItemOutput, } from "../tools/shared.js";
+// ── Fixtures: representative CF responses ────────────────────────────────────
+/** A Firestore Timestamp as it appears in a JSON-serialized CF response. */
+const FIRESTORE_TS = { _seconds: 1_771_200_000, _nanoseconds: 0 };
+/**
+ * The fiscal-summary CF body AFTER `requestUnwrapped` strips the `{ data, meta }`
+ * envelope — i.e. exactly what the tool receives. Includes the `model` (not
+ * `modeloCode`) shape the live CF emits, the `modelo303` totals block, a
+ * `summary` counts block, and a passthrough Firestore-timestamp field
+ * (`computedAt`) that is NOT in the schema's enumerated fields.
+ */
+const FISCAL_303_UNWRAPPED = {
+    model: "303",
+    period: "2026-Q1",
+    months: ["2026-01", "2026-02", "2026-03"],
+    modelo303: {
+        baseImponible: 10_000,
+        cuotaRepercutida: 2_100,
+        baseDeducible: 4_000,
+        cuotaDeducible: 840,
+        resultado: 1_260,
+    },
+    summary: { invoiceCount: 12, expenseCount: 7 },
+    readonly: true,
+    note: "Informational summary — never filed to AEAT.",
+    // Firestore-internal timestamp leaking through .passthrough() — must validate.
+    computedAt: FIRESTORE_TS,
+};
+/** The raw `{ data, meta }` envelope as the CF emits it pre-unwrap. */
+const FISCAL_303_ENVELOPE = {
+    data: FISCAL_303_UNWRAPPED,
+    meta: { generatedAt: FIRESTORE_TS, source: "cf:getFiscalModeloSummary" },
+};
+/** Mirror of `requestUnwrapped`: pull `.data` out of a single-object envelope. */
+function unwrap(body) {
+    if (body !== null && typeof body === "object" && !Array.isArray(body) && "data" in body) {
+        const inner = body.data;
+        if (inner !== null && typeof inner === "object" && !Array.isArray(inner)) {
+            return inner;
+        }
+    }
+    return body;
+}
+const VERIFACTU_STATUS = {
+    invoiceId: "inv_2026_001",
+    lastSubmissionAt: "2026-04-15T10:30:00.000Z", // enumerated date field stays ISO
+    hash: "a1b2c3",
+    status: "success",
+    aeatResponse: "Aceptado",
+    qrUrl: "https://www2.agenciatributaria.gob.es/qr/...",
+    // Firestore-internal timestamp via passthrough — must validate.
+    _chainTouchedAt: FIRESTORE_TS,
+};
+/** A paginated list envelope as `requestPaginated` keeps it: data[] + counts. */
+const INVOICE_LIST_ENVELOPE = {
+    data: [
+        {
+            id: "inv_1",
+            clientName: "ACME SL",
+            items: [{ description: "Consulting", quantity: 1, unitPrice: 1000 }],
+            issueDate: "2026-03-01",
+            dueDate: "2026-03-31",
+            status: "sent",
+            total: 1210,
+            createdAt: "2026-03-01T09:00:00.000Z", // enumerated date → ISO string
+            // Firestore-internal timestamp via passthrough.
+            _firestoreUpdatedAt: FIRESTORE_TS,
+        },
+    ],
+    total: 1,
+    limit: 20,
+    offset: 0,
+    nextCursor: "inv_1",
+};
+const EXPENSE_LIST_ENVELOPE = {
+    data: [
+        {
+            id: "exp_1",
+            description: "AWS",
+            amount: 42.5,
+            category: "software",
+            date: "2026-03-02",
+            taxDeductible: true,
+            createdAt: "2026-03-02T00:00:00.000Z",
+            _syncedAt: FIRESTORE_TS,
+        },
+    ],
+    total: 1,
+    limit: 20,
+    offset: 0,
+};
+const CLIENT_LIST_ENVELOPE = {
+    data: [
+        {
+            id: "cli_1",
+            name: "ACME SL",
+            email: "facturas@acme.es",
+            taxId: "B12345678",
+            address: { city: "Madrid", country: "ES" },
+            createdAt: "2026-01-10T00:00:00.000Z",
+            _importedAt: FIRESTORE_TS,
+        },
+    ],
+    total: 1,
+    limit: 20,
+    offset: 0,
+};
+// ── Tests ────────────────────────────────────────────────────────────────────
+describe("output-schema contract — fiscal single-object reads", () => {
+    test("fiscalModeloSummaryOutput accepts the unwrapped 303 CF body", () => {
+        const unwrapped = unwrap(FISCAL_303_ENVELOPE);
+        const parsed = fiscalModeloSummaryOutput.safeParse(unwrapped);
+        assert.equal(parsed.success, true, parsed.success ? "" : JSON.stringify(parsed.error.issues, null, 2));
+    });
+    test("unwrap() strips the { data, meta } envelope (matches client.requestUnwrapped)", () => {
+        const unwrapped = unwrap(FISCAL_303_ENVELOPE);
+        assert.equal(unwrapped.model, "303");
+        assert.equal("meta" in unwrapped, false, "meta must NOT leak into the unwrapped item");
+    });
+    test("a Firestore-Timestamp {_seconds} field survives via .passthrough()", () => {
+        const parsed = fiscalModeloSummaryOutput.safeParse(unwrap(FISCAL_303_ENVELOPE));
+        assert.equal(parsed.success, true);
+        if (parsed.success) {
+            const ts = parsed.data.computedAt;
+            assert.equal(ts?._seconds, FIRESTORE_TS._seconds, "timestamp field must pass through intact");
+        }
+    });
+    test("verifactuStatusOutput accepts the status CF body incl. passthrough timestamp", () => {
+        const parsed = verifactuStatusOutput.safeParse(VERIFACTU_STATUS);
+        assert.equal(parsed.success, true, parsed.success ? "" : JSON.stringify(parsed.error.issues, null, 2));
+    });
+    test("enumerated date fields MUST stay strings — a raw {_seconds} there is rejected", () => {
+        // This pins the contract: the CF must emit ISO strings for enumerated dates.
+        // If it ever leaks a raw timestamp onto `lastSubmissionAt`, the tool would
+        // emit garbage — so we assert the schema (correctly) refuses it.
+        const bad = { ...VERIFACTU_STATUS, lastSubmissionAt: FIRESTORE_TS };
+        const parsed = verifactuStatusOutput.safeParse(bad);
+        assert.equal(parsed.success, false, "raw timestamp on an enumerated z.string() date must fail");
+    });
+});
+describe("output-schema contract — core list reads ({ data, ... } envelope)", () => {
+    test("invoices list envelope validates against paginatedOutput(invoiceItemOutput)", () => {
+        const schema = paginatedOutput(invoiceItemOutput);
+        const parsed = schema.safeParse(INVOICE_LIST_ENVELOPE);
+        assert.equal(parsed.success, true, parsed.success ? "" : JSON.stringify(parsed.error.issues, null, 2));
+    });
+    test("a list item carrying a Firestore Timestamp passthrough field validates", () => {
+        const schema = paginatedOutput(invoiceItemOutput);
+        const parsed = schema.safeParse(INVOICE_LIST_ENVELOPE);
+        assert.equal(parsed.success, true);
+        if (parsed.success) {
+            const item = parsed.data.data[0];
+            const ts = item._firestoreUpdatedAt;
+            assert.equal(ts?._seconds, FIRESTORE_TS._seconds);
+        }
+    });
+    test("expenses list envelope validates against paginatedOutput(expenseItemOutput)", () => {
+        const schema = paginatedOutput(expenseItemOutput);
+        const parsed = schema.safeParse(EXPENSE_LIST_ENVELOPE);
+        assert.equal(parsed.success, true, parsed.success ? "" : JSON.stringify(parsed.error.issues, null, 2));
+    });
+    test("clients list envelope validates against paginatedOutput(clientItemOutput)", () => {
+        const schema = paginatedOutput(clientItemOutput);
+        const parsed = schema.safeParse(CLIENT_LIST_ENVELOPE);
+        assert.equal(parsed.success, true, parsed.success ? "" : JSON.stringify(parsed.error.issues, null, 2));
+    });
+    test("paginatedOutput requires the envelope counts (data/total/limit/offset)", () => {
+        const schema = paginatedOutput(invoiceItemOutput);
+        // Missing `total`/`limit`/`offset` (a bare array-ish body) must fail — this
+        // is the drift that breaks pagination if the CF stops emitting counts.
+        const parsed = schema.safeParse({ data: INVOICE_LIST_ENVELOPE.data });
+        assert.equal(parsed.success, false, "envelope without counts must be rejected");
+    });
+});
+//# sourceMappingURL=contract.test.js.map

package/dist/__tests__/contract.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.test.js","sourceRoot":"","sources":["../../src/__tests__/contract.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/einvoice-tools.test.js

@@ -119,7 +119,7 @@ describe("E-Invoice Tools — registerAllTools includes new tools (127→133)",
         assert.equal(server.tools.size, 10);
     });
 });
-describe("send_einvoice — stub response shape", () => {
+describe("send_einvoice — honest unavailable response (absent endpoint)", () => {
     let sendTool;
     beforeEach(async () => {
         const server = new StubMcpServer();
@@ -132,7 +132,7 @@ describe("send_einvoice — stub response shape", () => {
         assert.ok(sendTool, "send_einvoice not registered");
         assert.equal(sendTool.config.title, "Send E-Invoice");
     });
-    test("happy path — valid input returns queued status", async () => {
+    test("absent endpoint → isError + _unavailable, NEVER a fabricated queued status", async () => {
         assert.ok(sendTool, "send_einvoice not registered");
         const result = await sendTool.handler({
             invoiceId: "inv_test_123",
@@ -141,19 +141,23 @@ describe("send_einvoice — stub response shape", () => {
         });
         assert.ok(result.structuredContent, "structuredContent missing");
         const sc = result.structuredContent;
-        assert.equal(sc["status"], "queued", "status should be 'queued'");
-        assert.ok(typeof sc["workflowRunId"] === "string", "workflowRunId should be string");
-        assert.ok(typeof sc["estimatedCompletionSec"] === "number", "estimatedCompletionSec should be number");
-        assert.ok(sc["_stub"] === true, "_stub flag should be true");
+        // HONEST: no fabricated workflow/status, agent sees a failure.
+        assert.equal(result.isError, true, "must be isError:true");
+        assert.equal(sc["_unavailable"], true, "_unavailable flag should be true");
+        assert.equal(sc["_stub"], undefined, "must NOT carry a fake-success _stub flag");
+        assert.equal(sc["workflowRunId"], undefined, "must NOT fabricate a workflowRunId");
+        assert.equal(sc["status"], undefined, "must NOT fabricate a queued status");
+        assert.ok(typeof sc["_plannedEndpoint"] === "string", "_plannedEndpoint should be set");
     });
-    test("happy path — peppol-bis-3 format accepted", async () => {
+    test("peppol-bis-3 also returns honest unavailable", async () => {
         assert.ok(sendTool, "send_einvoice not registered");
         const result = await sendTool.handler({
             invoiceId: "inv_peppol_456",
             format: "peppol-bis-3",
             dispatchMode: "peppol",
         });
-        assert.equal(result.structuredContent["status"], "queued");
+        assert.equal(result.isError, true);
+        assert.equal(result.structuredContent["_unavailable"], true);
     });
     test("content block has type text", async () => {
         assert.ok(sendTool, "send_einvoice not registered");
@@ -165,10 +169,10 @@ describe("send_einvoice — stub response shape", () => {
         assert.ok(Array.isArray(result.content), "content should be array");
         assert.ok(result.content.length > 0, "content should have at least 1 block");
         assert.equal(result.content[0].type, "text");
-        assert.ok(typeof result.content[0].text === "string");
+        assert.ok(/unavailable/i.test(result.content[0].text), "text should say unavailable");
     });
 });
-describe("get_einvoice_status — stub response shape", () => {
+describe("get_einvoice_status — honest unavailable response (absent endpoint)", () => {
     let statusTool;
     beforeEach(async () => {
         const server = new StubMcpServer();
@@ -177,22 +181,19 @@ describe("get_einvoice_status — stub response shape", () => {
         registerEInvoiceTools(server, clientStub);
         statusTool = server.tools.get("get_einvoice_status");
     });
-    test("happy path — returns status shape", async () => {
+    test("absent endpoint → isError + _unavailable, NEVER a fabricated 'succeeded'", async () => {
         assert.ok(statusTool, "get_einvoice_status not registered");
         const result = await statusTool.handler({ workflowRunId: "wfr_stub_abc123" });
         const sc = result.structuredContent;
-        assert.ok(["queued", "running", "succeeded", "failed", "cancelled"].includes(sc["status"]), `status '${sc["status"]}' not in allowed values`);
-        assert.ok(typeof sc["step"] === "string", "step should be string");
-        assert.ok(sc["_stub"] === true, "_stub flag should be true");
-    });
-    test("ackId present in stub response", async () => {
-        assert.ok(statusTool, "get_einvoice_status not registered");
-        const result = await statusTool.handler({ workflowRunId: "wfr_stub_deadbeef" });
-        const sc = result.structuredContent;
-        assert.ok(typeof sc["ackId"] === "string", "ackId should be present as string");
+        assert.equal(result.isError, true, "must be isError:true");
+        assert.equal(sc["_unavailable"], true, "_unavailable flag should be true");
+        assert.equal(sc["status"], undefined, "must NOT fabricate a 'succeeded' status");
+        assert.equal(sc["ackId"], undefined, "must NOT fabricate an ackId");
+        assert.equal(sc["xmlUrl"], undefined, "must NOT fabricate an XML URL");
+        assert.equal(sc["_stub"], undefined, "must NOT carry a fake-success _stub flag");
     });
 });
-describe("validate_einvoice_xml — stub response shape", () => {
+describe("validate_einvoice_xml — honest unavailable response (absent endpoint)", () => {
     let validateTool;
     beforeEach(async () => {
         const server = new StubMcpServer();
@@ -201,45 +202,23 @@ describe("validate_einvoice_xml — stub response shape", () => {
         registerEInvoiceTools(server, clientStub);
         validateTool = server.tools.get("validate_einvoice_xml");
     });
-    test("happy path — returns valid=true with empty errors", async () => {
+    test("absent endpoint → isError + _unavailable, NEVER a fabricated valid=true", async () => {
         assert.ok(validateTool, "validate_einvoice_xml not registered");
         const result = await validateTool.handler({
             xml: "<Invoice><ID>TEST-001</ID></Invoice>",
             format: "xrechnung-cii",
         });
         const sc = result.structuredContent;
-        assert.equal(sc["valid"], true, "valid should be true (stub)");
-        assert.ok(Array.isArray(sc["errors"]), "errors should be array");
-        assert.equal(sc["errors"].length, 0, "errors should be empty (stub)");
-        assert.equal(sc["validator"], "kosit", "xrechnung-cii should use kosit validator");
-        assert.ok(typeof sc["durationMs"] === "number", "durationMs should be number");
-    });
-    test("facturx-en16931 uses mustang validator", async () => {
-        assert.ok(validateTool, "validate_einvoice_xml not registered");
-        const result = await validateTool.handler({
-            xml: "<rsm:CrossIndustryInvoice/>",
-            format: "facturx-en16931",
-        });
-        assert.equal(result.structuredContent["validator"], "mustang");
-    });
-    test("fatturapa uses xsd validator", async () => {
-        assert.ok(validateTool, "validate_einvoice_xml not registered");
-        const result = await validateTool.handler({
-            xml: "<FatturaElettronica/>",
-            format: "fatturapa",
-        });
-        assert.equal(result.structuredContent["validator"], "xsd");
-    });
-    test("peppol-bis-3 uses schematron validator", async () => {
-        assert.ok(validateTool, "validate_einvoice_xml not registered");
-        const result = await validateTool.handler({
-            xml: "<Invoice/>",
-            format: "peppol-bis-3",
-        });
-        assert.equal(result.structuredContent["validator"], "schematron");
+        assert.equal(result.isError, true, "must be isError:true");
+        assert.equal(sc["_unavailable"], true, "_unavailable flag should be true");
+        // A fabricated valid=true is the most dangerous stub — must never appear.
+        assert.equal(sc["valid"], undefined, "must NOT fabricate valid=true");
+        assert.equal(sc["validator"], undefined, "must NOT fabricate a validator verdict");
+        assert.equal(sc["_stub"], undefined, "must NOT carry a fake-success _stub flag");
+        assert.ok(typeof sc["_plannedEndpoint"] === "string", "_plannedEndpoint should be set");
     });
 });
-describe("export_datev — stub response shape", () => {
+describe("export_datev — honest unavailable response (absent endpoint)", () => {
     let datevTool;
     beforeEach(async () => {
         const server = new StubMcpServer();
@@ -248,7 +227,7 @@ describe("export_datev — stub response shape", () => {
         registerEInvoiceTools(server, clientStub);
         datevTool = server.tools.get("export_datev");
     });
-    test("happy path — extf-buchungsstapel returns correct shape", async () => {
+    test("absent endpoint → isError + _unavailable, NEVER a fabricated fileUrl", async () => {
         assert.ok(datevTool, "export_datev not registered");
         const result = await datevTool.handler({
             periodStart: "2026-01-01",
@@ -256,39 +235,12 @@ describe("export_datev — stub response shape", () => {
             format: "extf-buchungsstapel",
         });
         const sc = result.structuredContent;
-        assert.ok(typeof sc["fileUrl"] === "string", "fileUrl should be string");
-        assert.ok(typeof sc["filename"] === "string", "filename should be string");
-        assert.ok(typeof sc["rowCount"] === "number", "rowCount should be number");
-        assert.ok(typeof sc["fiscalPeriod"] === "string", "fiscalPeriod should be string");
-        assert.equal(sc["encoding"], "cp1252", "encoding must always be cp1252");
-        assert.ok(sc["_stub"] === true, "_stub flag should be true");
-    });
-    test("filename contains EXTF_Buchungsstapel for buchungsstapel format", async () => {
-        assert.ok(datevTool, "export_datev not registered");
-        const result = await datevTool.handler({
-            periodStart: "2026-01-01",
-            periodEnd: "2026-01-31",
-            format: "extf-buchungsstapel",
-        });
-        assert.ok(result.structuredContent["filename"].includes("EXTF_Buchungsstapel"), "filename should include EXTF_Buchungsstapel");
-    });
-    test("filename contains EXTF_Debitoren for extf-debitoren", async () => {
-        assert.ok(datevTool, "export_datev not registered");
-        const result = await datevTool.handler({
-            periodStart: "2026-03-01",
-            periodEnd: "2026-03-31",
-            format: "extf-debitoren",
-        });
-        assert.ok(result.structuredContent["filename"].includes("EXTF_Debitoren"), "filename should include EXTF_Debitoren");
-    });
-    test("fiscalPeriod derives from periodStart YYYY-MM", async () => {
-        assert.ok(datevTool, "export_datev not registered");
-        const result = await datevTool.handler({
-            periodStart: "2026-07-01",
-            periodEnd: "2026-07-31",
-            format: "extf-kreditoren",
-        });
-        assert.equal(result.structuredContent["fiscalPeriod"], "2026-07");
+        assert.equal(result.isError, true, "must be isError:true");
+        assert.equal(sc["_unavailable"], true, "_unavailable flag should be true");
+        assert.equal(sc["fileUrl"], undefined, "must NOT fabricate a download fileUrl");
+        assert.equal(sc["filename"], undefined, "must NOT fabricate a filename");
+        assert.equal(sc["_stub"], undefined, "must NOT carry a fake-success _stub flag");
+        assert.ok(typeof sc["_plannedEndpoint"] === "string", "_plannedEndpoint should be set");
     });
 });
 describe("Langfuse wrapper — patchServerWithTracing wraps all tool callbacks", () => {
@@ -347,54 +299,65 @@ function getValidArgs(toolName) {
     }
 }
 // ── 404-fallback tests ────────────────────────────────────────────────────────
-describe("404-fallback path — CF endpoint not yet deployed", () => {
+describe("absent-endpoint path — honest unavailable, NO fabricated success", () => {
     async function makeServer(client) {
         const server = new StubMcpServer();
         const { registerEInvoiceTools } = await import("../tools/einvoice.js");
         registerEInvoiceTools(server, client);
         return server;
     }
-    test("send_einvoice: 404 → stub with _stub=true, _plannedEndpoint set", async () => {
+    test("send_einvoice: 404 → isError + _unavailable + _plannedEndpoint, no fabricated data", async () => {
         const server = await makeServer(make404Client());
         const tool = server.tools.get("send_einvoice");
         const result = await tool.handler({ invoiceId: "inv_test", format: "xrechnung-cii", dispatchMode: "email" });
         const sc = result.structuredContent;
-        assert.equal(sc["_stub"], true, "_stub should be true on 404-fallback");
-        assert.equal(sc["_note"], "CF endpoint pending deploy");
+        assert.equal(result.isError, true, "must be isError:true");
+        assert.equal(sc["_unavailable"], true, "_unavailable should be true");
+        assert.equal(sc["_stub"], undefined, "must NOT be a fake-success stub");
         assert.ok(typeof sc["_plannedEndpoint"] === "string", "_plannedEndpoint should be set");
-        assert.equal(sc["status"], "queued", "fallback status should be queued");
-        assert.ok(typeof sc["workflowRunId"] === "string", "workflowRunId should be string");
+        assert.equal(sc["status"], undefined, "no fabricated queued status");
+        assert.equal(sc["workflowRunId"], undefined, "no fabricated workflowRunId");
     });
-    test("get_einvoice_status: 404 → stub with _stub=true, _plannedEndpoint set", async () => {
+    test("get_einvoice_status: 404 → isError + _unavailable + _plannedEndpoint", async () => {
         const server = await makeServer(make404Client());
         const tool = server.tools.get("get_einvoice_status");
         const result = await tool.handler({ workflowRunId: "wfr_pending_123" });
         const sc = result.structuredContent;
-        assert.equal(sc["_stub"], true, "_stub should be true on 404-fallback");
-        assert.equal(sc["_note"], "CF endpoint pending deploy");
+        assert.equal(result.isError, true, "must be isError:true");
+        assert.equal(sc["_unavailable"], true, "_unavailable should be true");
         assert.ok(typeof sc["_plannedEndpoint"] === "string", "_plannedEndpoint should be set");
-        assert.ok(sc["_plannedEndpoint"], "/v1/einvoice/status/wfr_pending_123");
+        assert.equal(sc["status"], undefined, "no fabricated status");
     });
-    test("validate_einvoice_xml: 404 → stub with _stub=true, validator derived from format", async () => {
+    test("validate_einvoice_xml: 404 → isError + _unavailable, NEVER a fabricated valid verdict", async () => {
         const server = await makeServer(make404Client());
         const tool = server.tools.get("validate_einvoice_xml");
         const result = await tool.handler({ xml: "<Invoice/>", format: "xrechnung-cii" });
         const sc = result.structuredContent;
-        assert.equal(sc["_stub"], true, "_stub should be true on 404-fallback");
-        assert.equal(sc["_note"], "CF endpoint pending deploy");
-        assert.equal(sc["validator"], "kosit", "validator should derive from format even in fallback");
-        assert.equal(sc["valid"], true);
+        assert.equal(result.isError, true, "must be isError:true");
+        assert.equal(sc["_unavailable"], true, "_unavailable should be true");
+        assert.equal(sc["valid"], undefined, "must NOT fabricate a valid verdict");
+        assert.equal(sc["validator"], undefined, "must NOT fabricate a validator");
     });
-    test("export_datev: 404 → stub with _stub=true, filename derived from params", async () => {
+    test("export_datev: 404 → isError + _unavailable, no fabricated file", async () => {
         const server = await makeServer(make404Client());
         const tool = server.tools.get("export_datev");
         const result = await tool.handler({ periodStart: "2026-03-01", periodEnd: "2026-03-31", format: "extf-buchungsstapel" });
         const sc = result.structuredContent;
-        assert.equal(sc["_stub"], true, "_stub should be true on 404-fallback");
-        assert.equal(sc["_note"], "CF endpoint pending deploy");
-        assert.ok(sc["filename"].includes("EXTF_Buchungsstapel"), "filename should include format prefix");
-        assert.equal(sc["fiscalPeriod"], "2026-03", "fiscalPeriod should derive from periodStart");
-        assert.equal(sc["encoding"], "cp1252");
+        assert.equal(result.isError, true, "must be isError:true");
+        assert.equal(sc["_unavailable"], true, "_unavailable should be true");
+        assert.equal(sc["fileUrl"], undefined, "must NOT fabricate a fileUrl");
+        assert.equal(sc["filename"], undefined, "must NOT fabricate a filename");
+    });
+    test("ksef_submit: forward-compat stub → isError + _unavailable + _notImplemented preserved", async () => {
+        const server = await makeServer(make404Client());
+        const tool = server.tools.get("ksef_submit");
+        const result = await tool.handler({ invoiceId: "inv_test", mode: "production" });
+        const sc = result.structuredContent;
+        assert.equal(result.isError, true, "must be isError:true");
+        assert.equal(sc["_unavailable"], true, "_unavailable should be true");
+        assert.equal(sc["_notImplemented"], true, "_notImplemented marker preserved for forward-compat");
+        assert.ok(typeof sc["_plannedEndpoint"] === "string", "_plannedEndpoint should be set");
+        assert.equal(sc["mode"], "production", "echoes the requested mode");
     });
 });
 // ── Success-path tests (live client mock) ─────────────────────────────────────