@vantageos/mcp-boilerplate 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to `@vantageos/mcp-boilerplate` are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-08-07
+
+Hardening pass on the published template — packaging and documentation
+hygiene, no behavioral changes to the server layers.
+
+### Added
+
+- Bilingual `README.fr.md` + `description_fr` in `package.json` (T1).
+- This `CHANGELOG.md`, shipped inside the npm package (T2).
+- Eval suite hardened to >=3 evals/tool, with an opt-in tenant toggle (T3).
+- Fleet `biome.json` shipped at source, normalized to 0 lint errors (from #2).
+
+### Changed
+
+- Template hygiene: `mosaic-card` vendored into the template instead of an
+  external dependency; alpha-only devDependency dropped (T4).
+
+## [0.1.0] - 2026-08-04
+
+Initial published release.
+
+### Added
+
+- Dual-transport MCP server bootstrap built exclusively on the official
+  `@modelcontextprotocol/sdk` transports: stdio (`StdioServerTransport`) and
+  stateless Streamable HTTP (`WebStandardStreamableHTTPServerTransport`).
+- `@vantageos/mcp-protocol-kit` wiring for shared result types.
+- OAuth 2.1 resource-server auth layer (`@vantageos/mcp-auth-kit`), with a
+  public no-auth tier alongside the authenticated tier.
+- Multi-tenant scoping layer with proven tenant isolation.
+- MCP Apps UI extension: `ui://` resource serving a bundled widget
+  (`src/ui/Widget.tsx`, Vite single-file build).
+- Bilingual i18n (FR/EN) via `@vantageos/mosaic-i18n`, covering tool
+  descriptions and the UI resource.
+- Evals harness (`evals/`) exercising the tool surface end-to-end.
+- Example `ping` tool proving the handshake on both transports.
+- 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

package/README.fr.md

@@ -0,0 +1,193 @@
+# @vantageos/mcp-boilerplate
+
+Un squelette de serveur MCP clonable : bootstrap double-transport (stdio +
+Streamable HTTP, sans état) construit exclusivement sur les transports
+officiels du [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk).
+Aucune route REST personnalisée ne se place jamais devant un appel d'outil.
+
+Ceci est une fondation, pas un produit fini : il embarque un outil d'exemple
+trivial (`ping`) dont le seul but est de prouver que la poignée de main MCP
+fonctionne sur les deux transports. Les couches ultérieures (types de résultat
+protocol-kit, authentification, scoping multi-tenant, extensions UI, i18n) se
+construisent au-dessus de ce bootstrap sans modifier le câblage du transport.
+
+## Structure
+
+```
+src/
+  mcpServerFactory.ts   # définition unique du serveur MCP, partagée par les deux transports
+  stdio.ts              # point d'entrée StdioServerTransport du SDK officiel
+  http.ts               # adaptateur Node http.Server autour de l'app Hono
+  httpApp.ts            # WebStandardStreamableHTTPServerTransport du SDK officiel (sans état)
+  auth.ts               # câblage OAuth 2.1 resource-server (@vantageos/mcp-auth-kit)
+  config.ts             # chargeurs AuthMode + AuthConfig dérivés de l'environnement
+  index.ts              # exports du package
+tests/
+  helpers/mcpRpc.ts      # helpers de requête JSON-RPC pour le transport HTTP
+  helpers/authFixtures.ts # fixtures de signature JWT RS256 réservées aux tests
+  httpHandshake.test.ts  # initialize -> tools/list -> tools/call sur Streamable HTTP
+  stdioHandshake.test.ts # même poignée de main sur un vrai process enfant stdio
+  oauth.test.ts          # les deux paliers d'authentification : gate oauth + palier public sans auth
+docs/
+  architecture.md        # posture du protocole : version au niveau outil vs au niveau transport
+```
+
+## Démarrage rapide
+
+```bash
+npm install
+npm run build
+
+# stdio (config client local, ex. Claude Code / Cursor) — jamais gardé,
+# le process local qui invoque stdio EST l'appelant.
+npm run start:stdio
+
+# Streamable HTTP (distant, sans état) — gate OAuth 2.1 par défaut :
+MCP_OAUTH_ISSUER=https://your-tenant.example.com \
+MCP_OAUTH_AUDIENCE=https://your-mcp-server.example.com \
+PORT=8787 npm run start:http
+
+# Streamable HTTP, palier "Public MCP" sans authentification (local/self-host, appelant de confiance) :
+AUTH_MODE=public PORT=8787 npm run start:http
+```
+
+## Paliers d'authentification
+
+Deux paliers, selon `mcp-standard.md` "Authentication & Authorization" :
+
+| `AUTH_MODE` | Comportement |
+|---|---|
+| `oauth` (par défaut) | Resource server OAuth 2.1 (`@vantageos/mcp-auth-kit`) : chaque appel HTTP `/mcp` exige un Bearer JWT RS256 valide, lié à l'audience/l'émetteur. Token manquant/invalide -> `401` + `WWW-Authenticate`. Les métadonnées RFC 9728 Protected Resource sont servies sur `/.well-known/oauth-protected-resource`. `/health` reste sans token. Nécessite `MCP_OAUTH_ISSUER` + `MCP_OAUTH_AUDIENCE`. |
+| `public` | Aucun gate sur le transport HTTP — pour un usage local/self-host où l'appelant est déjà de confiance. Reprend le modèle de confiance du transport stdio (stdio n'a jamais eu de gate). Aucun document `.well-known/oauth-protected-resource` n'est servi dans ce mode (il n'y a pas de serveur d'autorisation à décrire). |
+
+Le transport stdio (`stdio.ts`) n'est jamais gardé, dans aucun des deux modes
+— le process local qui l'invoque EST l'appelant, selon le modèle de confiance
+de `mcp-standard.md` pour les outils locaux/self-host.
+
+`buildHttpApp()` appelé sans argument revient par défaut au palier `public` —
+c'est ce que les tests du squelette de transport (`httpHandshake.test.ts`,
+`protocolKitWiring.test.ts`) exercent, donc ils n'ont besoin d'aucune
+configuration OAuth. Le point d'entrée de production (`http.ts`) résout
+toujours `AUTH_MODE` depuis l'environnement via `config.ts`, avec `oauth`
+comme valeur par défaut si non défini.
+
+## i18n côté serveur (messages d'erreur FR/EN)
+
+`src/i18n.ts` localise les messages d'erreur/validation MCP (rejet
+d'authentification, refus de tenant, validation d'entrée d'outil) selon le
+mandat bilingue de `mcp-standard.md` (§Bilingual) : le client envoie
+`X-MCP-Locale: fr` ou `X-MCP-Locale: en` (par défaut `en` si absent), et
+`src/httpApp.ts` + `src/mcpServerFactory.ts` acheminent le message
+correspondant via `t(locale, key)`.
+
+Les deux fichiers de ressources (`src/locales/{en,fr}.json`) suivent
+exactement la convention de ressource à espace de noms livrée par
+`@vantageos/mosaic-i18n@0.1.1`
+(`node_modules/@vantageos/mosaic-i18n/src/locales/{en,fr}.json`) : un objet
+plat `<Namespace>.<catégorie>.<clé>` -> chaîne, FR et EN maintenus clé pour
+clé en parfait alignement. `mosaic-i18n` lui-même est un package
+React/`react-i18next` et ne peut pas être appelé directement depuis un
+serveur JSON-RPC, donc son API d'exécution n'est pas importée ici — la forme
+de son fichier de ressources est réutilisée à la place, sous le namespace
+`Mcp` propre à ce boilerplate.
+
+## Tests
+
+```bash
+npm test
+```
+
+Exécute les deux transports contre les vrais chemins de code du SDK officiel :
+la suite HTTP pilote l'app Hono en mémoire ; la suite stdio lance le binaire
+`dist/stdio.js` compilé comme un vrai process enfant via `StdioClientTransport`.
+
+## Ajouter un outil
+
+Enregistrez-le une seule fois dans `src/mcpServerFactory.ts` — il devient
+alors disponible automatiquement sur les deux transports. Il n'y a aucune
+route REST séparée à ajouter.
+
+## Packaging & distribution
+
+Ce boilerplate est lui-même un package npm publiable/clonable. Deux
+artefacts portent son identité de distribution :
+
+- `package.json` — le package npm. `files` ne livre que l'arbre `dist/`
+  compilé (serveur compilé + `dist/locales/` + `dist/ui-bundle/widget.html`),
+  le `README.md`, la `LICENSE`, le manifeste de plugin, et la config client
+  d'exemple — jamais `src/`, les tests, ou l'outillage. `main`/`types`/`exports`
+  pointent vers `dist/index.js` ; le bin `mcp-boilerplate` pointe vers
+  `dist/stdio.js`. `publishConfig.access = public` est requis pour le scope
+  `@vantageos`.
+- `.claude-plugin/plugin.json` — le manifeste de catalogue Claude Code
+  marketplace / VantageRegistry, suivant la convention fleet des serveurs MCP
+  (miroir de `vantage-frameworks-mcp` / `vantage-agent-composer-mcp`) :
+  `name`, `version`, `description` bilingue + `description_fr`, `author`,
+  `license`, `homepage`, `category: "mcp-server"`, `bilingual: true`,
+  `keywords`.
+
+### Scaffold → build → publish
+
+```bash
+# 1. Scaffold : clonez ce repo (ou le tarball npm) comme squelette de votre serveur.
+git clone https://github.com/elpiarthera/vantage-mcp-boilerplate.git my-mcp
+cd my-mcp && npm install --legacy-peer-deps   # voir la note de skew peer-range dev ci-dessous
+
+# 2. Renommer : définissez "name"/"bin" dans package.json et "name" dans
+#    .claude-plugin/plugin.json pour votre serveur, puis ajoutez des outils dans src/mcpServerFactory.ts.
+
+# 3. Build + vérification depuis un arbre propre (ce que CI et prepublishOnly imposent) :
+rm -rf dist node_modules/.vite && npm run build && npm test && npm run evals
+
+# 4. Inspectez le tarball avant publication — confirmez que dist/ est bien livré et que rien ne fuit :
+npm pack --dry-run
+
+# 5. Publiez sur les deux canaux :
+npm publish                 # registre npm (prepublishOnly relance build+test+evals)
+#   Catalogue VantageRegistry : enregistrez .claude-plugin/plugin.json via
+#   le skill fleet create-plugin / generate-marketplace (upsert VR).
+```
+
+`prepublishOnly` relance `build → build:ui → test → evals` pour qu'un
+tarball cassé ou contenant uniquement `src` ne puisse jamais atteindre npm.
+Les canaux de distribution sont **npm** (le package exécutable) et le
+**catalogue VantageRegistry / Claude Code marketplace** (découverte, via
+`plugin.json`).
+
+## Couche UI MCP Apps
+
+`render_items_ui` affiche `EXAMPLE_ITEMS` comme un widget interactif via
+l'officiel `@modelcontextprotocol/ext-apps/server` (`registerAppTool` +
+`registerAppResource`), forme imbriquée GA `_meta.ui.resourceUri` (stable
+depuis le 2026-01-26) — jamais la clé plate dépréciée `_meta["ui/resourceUri"]`.
+Un repli markdown est toujours présent dans `content[0]`, même pour les
+clients qui ne négocient jamais l'extension `io.modelcontextprotocol/ui`.
+
+Le widget (`src/ui/`) réutilise une famille `MosaicCard` vendorisée
+(`src/ui/mosaic-card.tsx` — atomes présentationnels, aucune dépendance
+d'exécution) et est empaqueté en un seul fichier HTML autonome
+(`vite-plugin-singlefile`, `dist/ui-bundle/widget.html`, ~70 Ko gzippé,
+aucun fetch d'exécution externe). `npm run build:ui` produit ce bundle
+indépendamment de `npm run build` (tsc), sur un chemin de sortie sans
+collision (`dist/ui-bundle/` vs `dist/ui/` de tsc) — les deux étapes de
+build écrivent sur des arbres `dist/ui*` d'apparence similaire mais jamais
+sur le même répertoire, si bien que `emptyOutDir` côté vite ne peut jamais
+supprimer un module serveur compilé par tsc.
+
+**Hygiène du template** : les atomes `MosaicCard` sont vendorisés
+localement plutôt qu'importés depuis `@vantageos/mosaic-blocks`, un paquet
+interne sans version stable (non-alpha) publiée sur npm. Une
+devDependency de template épinglée sur un tag alpha mouvant casse au
+prochain bump alpha ; vendoriser les quatre primitives présentationnelles
+réellement utilisées par le widget élimine ce mode de défaillance.
+
+**Ordre de publication (exigence stricte)** : ce boilerplate dépend de
+`@vantageos/mcp-protocol-kit@^0.2.0`. Le câblage de `tools/list` utilise
+`buildToolsListResult` du kit, qui existe UNIQUEMENT à partir du kit 0.2.0+.
+En semver 0.x, `^0.2.0` n'accepte PAS le 0.1.x, donc un `npm install` frais
+depuis le registre résout la version du kit dont le code a réellement
+besoin. Par conséquent, **le kit `@vantageos/mcp-protocol-kit` 0.2.0 DOIT
+être publié sur npm AVANT que ce boilerplate puisse être installé ou publié
+depuis le registre.** C'est un ordre strict, non optionnel : publiez d'abord
+le kit, confirmez que 0.2.0 est en ligne sur le registre, puis publiez le
+boilerplate.

package/README.md

@@ -1,5 +1,7 @@
 # @vantageos/mcp-boilerplate
 
+SELLABLE AS: `mcp-boilerplate` — a clonable MCP server starter for the Claude Code marketplace / VantageRegistry catalogue, published as `@vantageos/mcp-boilerplate` on npm.
+
 A clonable MCP server skeleton: dual-transport bootstrap (stdio + Streamable
 HTTP, stateless) built exclusively on the official
 [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
@@ -155,8 +157,9 @@ official `@modelcontextprotocol/ext-apps/server` (`registerAppTool` +
 markdown fallback is always present in `content[0]`, even for clients that
 never negotiate the `io.modelcontextprotocol/ui` extension.
 
-The widget (`src/ui/`) reuses `@vantageos/mosaic-blocks`' `MosaicCard`
-family and is bundled to a single self-contained HTML file
+The widget (`src/ui/`) reuses a vendored `MosaicCard` family
+(`src/ui/mosaic-card.tsx` — style-only presentational atoms, no runtime
+dependency) and is bundled to a single self-contained HTML file
 (`vite-plugin-singlefile`, `dist/ui-bundle/widget.html`, ~70 KB gzipped, no
 external runtime fetch). `npm run build:ui` produces this bundle
 independently of `npm run build` (tsc), on a non-colliding output path
@@ -165,13 +168,12 @@ same-looking `dist/ui*` tree but never share a directory, so
 `emptyOutDir` on the vite side can never delete a tsc-compiled server
 module.
 
-**Known dev peer-range skew**: `@vantageos/mosaic-blocks@0.5.34-alpha`
-declares `peerOptional @vantageos/cloud-identity@^0.2`, while this
-boilerplate's own dependency is `^0.3.0` (via `@vantageos/mcp-auth-kit`).
-`npm install` currently needs `--legacy-peer-deps` to resolve. This is a
-dev-only peer-range mismatch (mosaic-blocks is a devDependency, used only
-to build the widget bundle) — the full test suite is green from a clean
-build under the `^0.3.0` runtime dependency, proving no runtime conflict.
+**Template hygiene**: the `MosaicCard` atoms are vendored locally rather
+than pulled from `@vantageos/mosaic-blocks`, an internal package with no
+stable (non-alpha) npm release. A fork-template devDependency pinned to a
+moving alpha tag breaks on the next alpha bump; vendoring the four
+presentational primitives the widget actually uses removes that failure
+mode entirely.
 
 **Publish ordering (hard requirement)**: this boilerplate depends on
 `@vantageos/mcp-protocol-kit@^0.2.0`. The `tools/list` wiring uses the kit's

package/dist/stdio.js

@@ -8,7 +8,14 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createBoilerplateMcpServer } from "./mcpServerFactory.js";
 export async function startStdioServer() {
-    const server = createBoilerplateMcpServer();
+    // `requireTenant` is otherwise only reachable from the OAuth-tier HTTP
+    // transport (see httpApp.ts). This env toggle exists solely so the eval
+    // suite (evals/evals.json "list-items-requires-tenant-refusal") can
+    // exercise the ALREADY-EXISTING `list_items` tenant-refusal branch in
+    // mcpServerFactory.ts through the real stdio transport, without adding a
+    // new code path. Unset by default — normal stdio usage is unaffected.
+    const requireTenant = process.env.MCP_BOILERPLATE_REQUIRE_TENANT === "1";
+    const server = createBoilerplateMcpServer({ requireTenant });
     const transport = new StdioServerTransport();
     await server.connect(transport);
     process.stderr.write("[mcp-boilerplate] stdio server started — 1 tool available\n");