@vantageos/mcp-boilerplate 0.4.0 → 0.6.0

package/dist/upstream/paginatedClient.js

@@ -11,15 +11,20 @@
  *   `UpstreamPageError` (`row_ceiling_exceeded`) naming the ceiling. A truncated set is never
  *   returned as if it were complete.
  * - `readPage(path, params, cursor?)` reads ONE upstream page per MCP call and returns
- *   `{ rows, nextCursor?, exhausted }`. The cursor is opaque: base64url of a small JSON object
- *   carrying a version, the upstream offset and a fingerprint of path + params. A cursor that
- *   does not decode, is replayed against another path or other params, or was altered without
- *   recomputing its fingerprint is refused with the `invalid_cursor` semantics of
- *   `src/pagination.ts` (`InvalidCursorError`), never read as page one. The fingerprint is an
- *   UNKEYED hash: it detects misuse, not forgery. Anyone can mint a well-formed cursor at any
- *   offset, which is acceptable because the offset carries no authority (the caller could ask
- *   for that offset anyway): a minted offset above the ceiling is refused before any request,
- *   and the same ceiling bounds the page-by-page walk.
+ *   `{ rows, nextCursor?, exhausted }`. The cursor carries a version, the upstream offset and a
+ *   fingerprint of path + params, and it is SIGNED (src/signedCursor.ts): the token is the
+ *   base64url payload and its HMAC-SHA256 tag under the client's `cursorSigner` key. The HMAC is
+ *   the guard; the fingerprint only binds the cursor to its request INSIDE the signed payload.
+ *   What it guarantees: a cursor this client did not issue (an edited offset, a fingerprint
+ *   recomputed for other params, a token minted from the public format, one signed under another
+ *   key) is refused with the `invalid_cursor` semantics of `src/pagination.ts`
+ *   (`InvalidCursorError`) BEFORE any upstream request, never read as page one; and an issued
+ *   cursor replayed against another path or other params is refused the same way. The ceiling
+ *   check on the decoded offset stays, as defence in depth for whoever holds the key.
+ *   Declared limit: the default signer's key is 32 random bytes drawn once per client, so a
+ *   process restart invalidates every outstanding cursor (the caller starts again without one),
+ *   and instances of a multi-instance deployment reject each other's cursors unless they are
+ *   given one shared key (`cursorSigner: createCursorSigner({ key })`, 32 bytes or more).
  *
  * ```ts
  * // src/upstream.ts — evaluated once per process, beside the token source
@@ -61,7 +66,8 @@
  * Errors are operator-facing (logged server-side), in English like `clientCredentials.ts`.
  */
 import { createHash } from "node:crypto";
-import { InvalidCursorError } from "../pagination.js";
+import { InvalidCursorError, createCursorSigner } from "../signedCursor.js";
+import { boundedFetch, configuredUpstreamTimeoutMs, upstreamSignal } from "./timeout.js";
 /** A refused or failed upstream page read. Carries no header, token, parameter or body. */
 export class UpstreamPageError extends Error {
     code;
@@ -87,14 +93,14 @@ const DEFAULT_PAGE_SIZE = 100;
 const DEFAULT_MAX_ATTEMPTS = 5;
 const DEFAULT_BASE_DELAY_MS = 500;
 const DEFAULT_MAX_DELAY_MS = 30_000;
-const DEFAULT_TIMEOUT_MS = 30_000;
 const RETRYABLE = new Set([429, 503]);
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
 /**
- * Cursor format. It mirrors `src/pagination.ts` (opaque base64url JSON with a version, refused as
+ * Cursor format. It mirrors `src/pagination.ts` (a signed JSON payload with a version, refused as
  * `InvalidCursorError`) but cannot reuse its `encodeCursor`/`decodeCursor`: those carry one
  * string key (`after`), and this cursor carries a numeric offset plus a fingerprint. The version
- * differs (2) so a `list_items` cursor is never read as an upstream cursor, nor the reverse.
+ * differs (2) so a `list_items` cursor is never read as an upstream cursor, nor the reverse, even
+ * when both are signed under one shared key.
  */
 const CURSOR_VERSION = 2;
 const isPositiveInteger = (n) => typeof n === "number" && Number.isSafeInteger(n) && n > 0;
@@ -134,27 +140,29 @@ function fingerprint(path, params) {
         .subarray(0, 16)
         .toString("base64url");
 }
-function encodeOffsetCursor(offset, print) {
-    return Buffer.from(JSON.stringify({ v: CURSOR_VERSION, o: offset, f: print })).toString("base64url");
+function encodeOffsetCursor(signer, offset, print) {
+    return signer.sign(JSON.stringify({ v: CURSOR_VERSION, o: offset, f: print }));
 }
-function decodeOffsetCursor(cursor, print) {
+/** The offset of a cursor this client issued for this request, or `InvalidCursorError`. */
+function decodeOffsetCursor(signer, cursor, print) {
+    // Verified first: nothing in an unsigned or edited token is read.
+    const payload = signer.verify(cursor);
     let decoded;
     try {
-        decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        decoded = JSON.parse(payload);
     }
     catch {
-        throw new InvalidCursorError();
+        throw new InvalidCursorError("malformed_payload");
     }
-    if (typeof decoded !== "object" || decoded === null)
-        throw new InvalidCursorError();
-    const { v, o, f } = decoded;
-    if (v !== CURSOR_VERSION || !isPositiveInteger(o) || f !== print) {
-        throw new InvalidCursorError();
+    if (typeof decoded !== "object" || decoded === null) {
+        throw new InvalidCursorError("malformed_payload");
     }
-    // Only the exact string this client issues is accepted: base64url decoding is lenient
-    // (trailing characters, extra fields), so the cursor is re-encoded and compared.
-    if (encodeOffsetCursor(o, print) !== cursor)
-        throw new InvalidCursorError();
+    const { v, o } = decoded;
+    if (v !== CURSOR_VERSION || !isPositiveInteger(o)) {
+        throw new InvalidCursorError("malformed_payload");
+    }
+    if (decoded.f !== print)
+        throw new InvalidCursorError("other_request");
     return o;
 }
 /** `Retry-After` (RFC 9110 §10.2.3) in ms, from delay-seconds or an HTTP date; else undefined. */
@@ -173,7 +181,12 @@ function isScalar(value) {
     return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
 }
 export function createPaginatedUpstreamClient(options) {
-    const { fetchImpl = (input, init) => fetch(input, init), baseUrl, allowedOrigins, offsetParam, limitParam, placement, pageSize = DEFAULT_PAGE_SIZE, rowCeiling, extractRows, extractTotal, headers: extraHeaders = {}, maxAttempts = DEFAULT_MAX_ATTEMPTS, baseDelayMs = DEFAULT_BASE_DELAY_MS, maxDelayMs = DEFAULT_MAX_DELAY_MS, timeoutMs = DEFAULT_TIMEOUT_MS, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), random = Math.random, now = Date.now, } = options;
+    const { fetchImpl: rawFetch = fetch, baseUrl, allowedOrigins, offsetParam, limitParam, placement, pageSize = DEFAULT_PAGE_SIZE, rowCeiling, extractRows, extractTotal, headers: extraHeaders = {}, maxAttempts = DEFAULT_MAX_ATTEMPTS, baseDelayMs = DEFAULT_BASE_DELAY_MS, maxDelayMs = DEFAULT_MAX_DELAY_MS, timeoutMs = configuredUpstreamTimeoutMs(), sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), random = Math.random, now = Date.now, cursorSigner = createCursorSigner(), } = options;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new Error("paginated upstream: timeoutMs must be a positive number");
+    }
+    // S-13: every page request, whatever fetch it goes through, carries the timeout.
+    const fetchImpl = boundedFetch(rawFetch, timeoutMs);
     if (!Array.isArray(allowedOrigins) || allowedOrigins.length === 0) {
         throw new Error("paginated upstream: allowedOrigins is required and must not be empty");
     }
@@ -224,8 +237,11 @@ export function createPaginatedUpstreamClient(options) {
             throw new Error(`paginated upstream: ${name} must be a non-negative number`);
         }
     }
-    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-        throw new Error("paginated upstream: timeoutMs must be a positive number");
+    if (cursorSigner === null ||
+        typeof cursorSigner !== "object" ||
+        typeof cursorSigner.sign !== "function" ||
+        typeof cursorSigner.verify !== "function") {
+        throw new Error("paginated upstream: cursorSigner must be a signer from createCursorSigner");
     }
     /** Resolves the path and refuses, before any network call, an origin not allowed. */
     const resolveUrl = (path) => {
@@ -303,7 +319,9 @@ export function createPaginatedUpstreamClient(options) {
                     body,
                     // A redirect is refused, never followed: the origin check above must stay total.
                     redirect: "error",
-                    signal: AbortSignal.timeout(timeoutMs),
+                    // Explicit at the call so the budget is readable (and statically checkable) here;
+                    // `boundedFetch` above bounds every other path to `fetchImpl` the same way.
+                    signal: upstreamSignal(timeoutMs),
                 });
             }
             catch (err) {
@@ -401,7 +419,7 @@ export function createPaginatedUpstreamClient(options) {
         const url = resolveUrl(path);
         checkParams(params, url.pathname);
         const print = fingerprint(url.pathname + url.search, params);
-        const offset = cursor === undefined ? 0 : decodeOffsetCursor(cursor, print);
+        const offset = cursor === undefined ? 0 : decodeOffsetCursor(cursorSigner, cursor, print);
         // A cursor at the ceiling may still meet an empty page (exact fit); beyond it, nothing is read.
         if (offset > rowCeiling)
             throw ceilingError(url.pathname);
@@ -415,7 +433,7 @@ export function createPaginatedUpstreamClient(options) {
             page.exhausted = true;
             return page;
         }
-        page.nextCursor = encodeOffsetCursor(offset + rows.length, print);
+        page.nextCursor = encodeOffsetCursor(cursorSigner, offset + rows.length, print);
         return page;
     };
     return { readAll, readPage };

package/dist/upstream/timeout.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one mechanism behind S-13 ("every request the server emits carries a configured timeout").
+ *
+ * CENSUS of outbound call sites in src/ (`rg -n '\bfetch\(|fetchImpl\(|undici|http\.request|https\.request' src`,
+ * plus the one site that hands `fetch` to a library, `ConvexHttpClient`). Each carries an
+ * AbortSignal timeout:
+ *   upstream/paginatedClient.ts  page request (fetchImpl, default global fetch)  boundedFetch, UPSTREAM_TIMEOUT_MS
+ *   upstream/clientCredentials.ts token request                                  boundedFetch, option timeoutMs (10 s)
+ *   upstream/clientCredentials.ts fetchWithToken (API request)                   boundedFetch, UPSTREAM_TIMEOUT_MS
+ *   oauth/clerk.ts               Backend API + JWKS (2 sites)                    per-call + total deadline (own signal)
+ *   oauth/clientRegistry.ts      CIMD metadata fetch                             own signal, option timeoutMs (5 s)
+ *   config.ts                    external-issuer JWKS fetch                      upstreamSignal, UPSTREAM_TIMEOUT_MS
+ *   lake/convex.ts               ConvexHttpClient `fetch` option                 boundedFetch, UPSTREAM_TIMEOUT_MS
+ * src/nodeAdapter.ts and src/httpApp.ts `.fetch(` are the INBOUND handler, not a request emitted.
+ * A new outbound site belongs in this list and uses `boundedFetch` or `upstreamSignal`.
+ */
+/** The configured budget: `UPSTREAM_TIMEOUT_MS`, validated at read (ConfigurationError if bad). */
+export declare function configuredUpstreamTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/** A timeout signal, combined with the caller's own signal when there is one (first to fire wins). */
+export declare function upstreamSignal(timeoutMs: number, callerSignal?: AbortSignal | null): AbortSignal;
+/**
+ * `fetchImpl` such that EVERY call carries the timeout, whatever the caller passed. A caller
+ * signal (in `init`, or on a `Request` input) still applies: the earlier of the two aborts.
+ * The abort surfaces as the fetch's own rejection (`TimeoutError`), for the call site to type.
+ */
+export declare function boundedFetch(fetchImpl: typeof fetch, timeoutMs: number): typeof fetch;

package/dist/upstream/timeout.js

@@ -0,0 +1,37 @@
+/**
+ * The one mechanism behind S-13 ("every request the server emits carries a configured timeout").
+ *
+ * CENSUS of outbound call sites in src/ (`rg -n '\bfetch\(|fetchImpl\(|undici|http\.request|https\.request' src`,
+ * plus the one site that hands `fetch` to a library, `ConvexHttpClient`). Each carries an
+ * AbortSignal timeout:
+ *   upstream/paginatedClient.ts  page request (fetchImpl, default global fetch)  boundedFetch, UPSTREAM_TIMEOUT_MS
+ *   upstream/clientCredentials.ts token request                                  boundedFetch, option timeoutMs (10 s)
+ *   upstream/clientCredentials.ts fetchWithToken (API request)                   boundedFetch, UPSTREAM_TIMEOUT_MS
+ *   oauth/clerk.ts               Backend API + JWKS (2 sites)                    per-call + total deadline (own signal)
+ *   oauth/clientRegistry.ts      CIMD metadata fetch                             own signal, option timeoutMs (5 s)
+ *   config.ts                    external-issuer JWKS fetch                      upstreamSignal, UPSTREAM_TIMEOUT_MS
+ *   lake/convex.ts               ConvexHttpClient `fetch` option                 boundedFetch, UPSTREAM_TIMEOUT_MS
+ * src/nodeAdapter.ts and src/httpApp.ts `.fetch(` are the INBOUND handler, not a request emitted.
+ * A new outbound site belongs in this list and uses `boundedFetch` or `upstreamSignal`.
+ */
+import { UPSTREAM_TIMEOUT_DEFAULT_MS, loadUpstreamSettings } from "../settings.js";
+/** The configured budget: `UPSTREAM_TIMEOUT_MS`, validated at read (ConfigurationError if bad). */
+export function configuredUpstreamTimeoutMs(env = process.env) {
+    return loadUpstreamSettings(env).upstreamTimeoutMs ?? UPSTREAM_TIMEOUT_DEFAULT_MS;
+}
+/** A timeout signal, combined with the caller's own signal when there is one (first to fire wins). */
+export function upstreamSignal(timeoutMs, callerSignal) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    return callerSignal ? AbortSignal.any([timeout, callerSignal]) : timeout;
+}
+/**
+ * `fetchImpl` such that EVERY call carries the timeout, whatever the caller passed. A caller
+ * signal (in `init`, or on a `Request` input) still applies: the earlier of the two aborts.
+ * The abort surfaces as the fetch's own rejection (`TimeoutError`), for the call site to type.
+ */
+export function boundedFetch(fetchImpl, timeoutMs) {
+    return ((input, init) => {
+        const caller = init?.signal ?? (input instanceof Request ? input.signal : undefined);
+        return fetchImpl(input, { ...init, signal: upstreamSignal(timeoutMs, caller) });
+    });
+}

package/examples/oauth.env.example

@@ -38,5 +38,12 @@ MCP_OAUTH_SIGNING_JWK=
 # MCP_MAX_BODY_BYTES=1048576
 # Browser origins allowed to call /register cross-origin (comma-separated; default none).
 # MCP_REGISTER_CORS_ORIGINS=https://inspector.example.com
+# Browser origins allowed to call /mcp (S-22; comma-separated, scheme://host[:port]; default none =
+# every request carrying an Origin header is refused 403; no Origin header = not a browser, passes).
+# A wildcard or a path stops the server at start. /register keeps its own list above.
+# MCP_ALLOWED_ORIGINS=https://claude.ai
+# Time budget of one outbound request to an upstream (S-13; integer milliseconds, 1000 to 300000,
+# default 30000). A value that is not an integer or is out of range stops the server at start.
+# UPSTREAM_TIMEOUT_MS=30000
 # Display name shown above the consent page title (default: none).
 # AUTHORIZE_BRAND_NAME=Acme MCP

package/mcp-server.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-boilerplate",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "capabilities": {
     "tools": {},
     "resources": {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/mcp-boilerplate",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Clonable MCP server skeleton on the official @modelcontextprotocol/server SDK v2 (protocol 2026-07-28 + 2025 legacy, stdio + stateless Streamable HTTP), with its own OAuth 2.1 authorization server (Clerk person + organisation, cloud-identity), MCP Apps UI, tenant scoping, FR/EN i18n and a declarative eval harness.",
   "description_fr": "Squelette de serveur MCP clonable sur le SDK officiel @modelcontextprotocol/server v2 (protocole 2026-07-28 + héritage 2025, stdio + Streamable HTTP sans état), avec son propre serveur d'autorisation OAuth 2.1 (personne + organisation Clerk, cloud-identity), UI MCP Apps, scoping tenant, i18n FR/EN et un harnais d'évaluations déclaratif.",
   "type": "module",
@@ -18,7 +18,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "mcp-boilerplate": "./dist/stdio.js"
+    "mcp-boilerplate": "./dist/stdio.js",
+    "mcp-readme-fr": "./scripts/readme-fr.mjs"
   },
   "files": [
     "dist",
@@ -36,7 +37,8 @@
     "scripts/generate-signing-key.mjs",
     "docs",
     "examples/claude-desktop.json",
-    "examples/oauth.env.example"
+    "examples/oauth.env.example",
+    "scripts/readme-fr.mjs"
   ],
   "publishConfig": {
     "access": "public"

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "vantage-mcp-boilerplate",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Clonable MCP server template: SDK v2 on protocol 2026-07-28 (stdio + stateless Streamable HTTP), its own OAuth 2.1 authorization server (Clerk person + organisation), MCP Apps UI, FR/EN i18n and a declarative eval harness. Scaffold, extend, publish.",
   "author": {
     "name": "ElPi Corp / Laurent Perello"

package/scripts/readme-fr.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * readme-fr — generate README.fr.md from a bilingual README.md (mcp-standard C-1: a French reader gets one French
+ * file). The French text is written once, in README.md, next to the English; README.fr.md is derived, never
+ * hand-copied, and `--check` fails when the two diverge.
+ *
+ * The language of a passage is read from an explicit marker, never guessed from its words. Census of the forms:
+ *   <!-- lang:en -->   opens a bilingual region; the lines that follow are its English part (dropped)
+ *   <!-- lang:fr -->   switches the open region to its French part (kept)
+ *   <!-- /lang -->     closes the region
+ * A marker stands alone on its line. Text outside a region is shared and copied as is (code blocks, tables, links).
+ * A fenced code block (``` or ~~~) is copied verbatim with the part it sits in; a marker inside it is text. An
+ * unclosed fence is an error naming its opening line.
+ * Errors, each naming its line (exit 2): an unknown language, a nested region, a French part before the English one,
+ * a region closed with no French part, a close with no open region, a region left open at the end of the file.
+ *
+ * Usage:
+ *   mcp-readme-fr --check [--dir <path>]   regenerate in memory; exit 1 naming the first differing line
+ *   mcp-readme-fr --write [--dir <path>]   write README.fr.md; refuses (exit 2) to overwrite a README.fr.md that
+ *                                          does not start with the generated-file banner (a hand translation)
+ * No dependencies: node built-ins only.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const BANNER =
+  "<!-- Généré depuis README.md par mcp-readme-fr (@vantageos/mcp-boilerplate) : ne pas modifier à la main. -->";
+
+const MARKER = /^\s*<!--\s*(lang:([A-Za-z-]+)|\/lang)\s*-->\s*$/;
+const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+
+/** README.md text -> { fr, errors }. `fr` is the README.fr.md content (banner first). */
+export function generate(text) {
+  const out = [BANNER, ""];
+  const errors = [];
+  let state = "shared"; // shared | en | fr
+  let openedAt = 0;
+  const lines = text.split("\n");
+  let fence = null; // { char, len, at } while inside a fenced code block
+  lines.forEach((line, i) => {
+    const n = i + 1;
+    // A fenced code block (``` or ~~~, CommonMark: up to 3 spaces of indent) is copied verbatim with the part it
+    // sits in: a marker inside it is text, never a region.
+    const f = FENCE.exec(line);
+    if (fence !== null) {
+      if (state !== "en") out.push(line);
+      if (f && f[1][0] === fence.char && f[1].length >= fence.len && f[2].trim() === "")
+        fence = null;
+      return;
+    }
+    if (f) {
+      fence = { char: f[1][0], len: f[1].length, at: n };
+      if (state !== "en") out.push(line);
+      return;
+    }
+    const m = MARKER.exec(line);
+    if (!m) {
+      if (state !== "en") out.push(line);
+      return;
+    }
+    if (m[1] === "/lang") {
+      if (state === "shared") errors.push(`line ${n}: <!-- /lang --> closes no open region`);
+      else if (state === "en")
+        errors.push(
+          `line ${n}: the region opened at line ${openedAt} has no French part (<!-- lang:fr -->)`
+        );
+      state = "shared";
+      return;
+    }
+    const lang = m[2].toLowerCase();
+    if (lang !== "en" && lang !== "fr") {
+      errors.push(`line ${n}: unknown language marker lang:${m[2]} (known: en, fr)`);
+      return;
+    }
+    if (lang === "en") {
+      if (state !== "shared")
+        errors.push(
+          `line ${n}: nested region (the region opened at line ${openedAt} is still open)`
+        );
+      state = "en";
+      openedAt = n;
+      return;
+    }
+    // lang === "fr"
+    if (state === "shared")
+      errors.push(
+        `line ${n}: lang:fr opens a region before its English part (<!-- lang:en --> first)`
+      );
+    else if (state === "fr")
+      errors.push(`line ${n}: a second lang:fr in the region opened at line ${openedAt}`);
+    state = "fr";
+  });
+  if (fence !== null)
+    errors.push(`line ${fence.at}: unclosed code fence (${fence.char.repeat(fence.len)})`);
+  if (state !== "shared")
+    errors.push(
+      `line ${lines.length}: the region opened at line ${openedAt} is unclosed (<!-- /lang -->)`
+    );
+  return { fr: out.join("\n"), errors };
+}
+
+export function main(argv, cwd = process.cwd()) {
+  const mode = argv.includes("--write") ? "write" : argv.includes("--check") ? "check" : null;
+  const dirAt = argv.indexOf("--dir");
+  const dir = resolve(cwd, dirAt >= 0 ? (argv[dirAt + 1] ?? ".") : ".");
+  if (mode === null) {
+    console.error("mcp-readme-fr: --check or --write is required");
+    return 2;
+  }
+  const readmePath = join(dir, "README.md");
+  const frPath = join(dir, "README.fr.md");
+  if (!existsSync(readmePath)) {
+    console.error(`mcp-readme-fr: ${readmePath} not found`);
+    return 2;
+  }
+  const { fr, errors } = generate(readFileSync(readmePath, "utf8"));
+  if (errors.length > 0) {
+    for (const e of errors) console.error(`README.md ${e}`);
+    return 2;
+  }
+  const current = existsSync(frPath) ? readFileSync(frPath, "utf8") : null;
+  if (mode === "write") {
+    if (current !== null && !current.startsWith(BANNER)) {
+      console.error(
+        `mcp-readme-fr: ${frPath} was not generated (no banner): refusing to overwrite a hand translation`
+      );
+      return 2;
+    }
+    writeFileSync(frPath, fr);
+    console.log(`mcp-readme-fr: wrote ${frPath}`);
+    return 0;
+  }
+  if (current === fr) {
+    console.log("mcp-readme-fr --check: README.fr.md matches README.md");
+    return 0;
+  }
+  const a = (current ?? "").split("\n");
+  const b = fr.split("\n");
+  let i = 0;
+  while (i < Math.max(a.length, b.length) && a[i] === b[i]) i++;
+  console.error(
+    `mcp-readme-fr --check: README.fr.md differs from what README.md generates at line ${i + 1} — run mcp-readme-fr --write`
+  );
+  return 1;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}