@vantageos/mcp-boilerplate 0.5.0 → 0.6.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vantage-mcp-boilerplate",
   "displayName": "VantageOS MCP Boilerplate",
-  "version": "0.5.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/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-11-01
+
+### Added
+- `mcp-readme-fr` (bin, `scripts/readme-fr.mjs`): generates `README.fr.md` from a bilingual `README.md` whose passages carry explicit `<!-- lang:en -->` / `<!-- lang:fr -->` / `<!-- /lang -->` markers (mcp-standard C-1: one French file, never hand-copied). `--check` fails when the two diverge, a malformed marker is an error naming its line, and a hand-written `README.fr.md` (no banner) is never overwritten. `tests/readmeFr.test.ts`.
+
+### Fixed
+- The CHANGELOG link block covers every version: a GitHub compare or tag link where a tag exists (v0.1.1, v0.1.2, v0.3.0, v0.4.0), the npm page of the version otherwise (0.1.0, 0.2.x, 0.5.0; the dead `v0.1.0` tag link is replaced). `[Unreleased]` compares the newest tag, v0.4.0. `tests/changelogLinks.test.ts` fails when a `## [x]` heading has no link line, a link has no heading, or a URL is of no known form.
+
 ## [0.5.0] - 2026-10-29
 
 > **Breaking for multi-instance deployments.** Cursors are now signed under a key drawn once per
@@ -479,6 +487,16 @@ Initial published release.
 - Reproducible build via `npm ci`; 52/52 tests passing at release time.
 - MIT license, clonable as a starter template.
 
-[Unreleased]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.1.1...HEAD
-[0.1.1]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.1.0...v0.1.1
-[0.1.0]: https://github.com/elpiarthera/vantage-mcp-boilerplate/releases/tag/v0.1.0
+[Unreleased]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.4.0...HEAD
+[0.6.0]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.6.0
+[0.5.0]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.5.0
+[0.4.0]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.1.2...v0.3.0
+[0.2.4]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.2.4
+[0.2.3]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.2.3
+[0.2.2]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.2.2
+[0.2.1]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.2.1
+[0.2.0]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.2.0
+[0.1.2]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/elpiarthera/vantage-mcp-boilerplate/releases/tag/v0.1.1
+[0.1.0]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.1.0

package/README.fr.md

@@ -517,6 +517,24 @@ le client envoie `X-MCP-Locale: fr|en` (défaut `en`) ; le sélecteur navigateur
 convention `<Namespace>.<category>.<key>` de `@vantageos/mosaic-i18n`, FR et EN en
 parité.
 
+## Un README français généré depuis un README bilingue
+
+Un serveur dont le `README.md` porte l'anglais et le français côte à côte livre un `README.fr.md` généré depuis lui
+(mcp-standard C-1), jamais recopié à la main. Marquez chaque passage bilingue, puis lancez le générateur :
+
+```markdown
+<!-- lang:en -->
+A demo server.
+<!-- lang:fr -->
+Un serveur de démonstration.
+<!-- /lang -->
+```
+
+Le texte hors d'une région marquée (code, tableaux, liens) est copié dans les deux. `npx mcp-readme-fr --write` écrit
+`README.fr.md` ; `npx mcp-readme-fr --check` (à mettre dans `npm test`) échoue quand les deux divergent. Un marqueur
+mal formé est une erreur qui nomme sa ligne, et le générateur n'écrase jamais un `README.fr.md` écrit à la main (sans
+sa bannière). Ce dépôt garde sa propre traduction écrite à la main.
+
 ## Tests
 
 ```bash

package/README.md

@@ -489,6 +489,24 @@ client sends `X-MCP-Locale: fr|en` (default `en`); the browser picker follows
 `<Namespace>.<category>.<key>` convention of `@vantageos/mosaic-i18n`, FR and EN
 in lockstep.
 
+## A French README generated from a bilingual one
+
+A server whose `README.md` carries English and French side by side ships a `README.fr.md` generated from it
+(mcp-standard C-1), never hand-copied. Mark each bilingual passage, then run the generator:
+
+```markdown
+<!-- lang:en -->
+A demo server.
+<!-- lang:fr -->
+Un serveur de démonstration.
+<!-- /lang -->
+```
+
+Text outside a marked region (code, tables, links) is copied to both. `npx mcp-readme-fr --write` writes
+`README.fr.md`; `npx mcp-readme-fr --check` (put it in `npm test`) fails when the two diverge. A malformed marker is
+an error naming its line, and the generator never overwrites a hand-written `README.fr.md` (one without its banner).
+This repository keeps its own hand translation.
+
 ## Testing
 
 ```bash

package/mcp-server.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/mcp-boilerplate",
-  "version": "0.5.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.5.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)));
+}