@vantageos/mcp-boilerplate 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "vantage-mcp-boilerplate",
+  "version": "0.1.0",
+  "description": "Clonable dual-transport MCP server template (stdio + Streamable HTTP, stateless) on the official @modelcontextprotocol/sdk, with protocol-kit result types, OAuth 2.1 auth + public tier, multi-tenant JWT scoping, MCP Apps UI extension, server-side FR/EN i18n, and a declarative eval harness. Scaffold, extend, publish.",
+  "description_fr": "Template de serveur MCP clonable a double transport (stdio + Streamable HTTP, stateless) sur le @modelcontextprotocol/sdk officiel, avec types de resultats protocol-kit, auth OAuth 2.1 + tier public, scoping multi-tenant par JWT, extension UI MCP Apps, i18n FR/EN cote serveur, et un harnais d'evaluations declaratif. Scaffolder, etendre, publier.",
+  "author": "ElPi Corp / Laurent Perello",
+  "license": "MIT",
+  "homepage": "https://github.com/elpiarthera/vantage-mcp-boilerplate",
+  "category": "mcp-server",
+  "bilingual": true,
+  "keywords": ["mcp", "claude-code", "boilerplate", "starter", "template", "stdio", "streamable-http", "oauth", "multi-tenant", "i18n", "vantage", "elpi"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ElPi Corp / Laurent Perello
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# @vantageos/mcp-boilerplate
+
+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)
+transports. No custom REST routes ever stand in front of a tool call.
+
+This is a foundation, not a finished product: it ships one trivial example
+tool (`ping`) whose only purpose is to prove the MCP handshake works on both
+transports. Later layers (protocol-kit result types, auth, multi-tenant
+scoping, UI extensions, i18n) build on top of this bootstrap without
+changing the transport wiring.
+
+## Structure
+
+```
+src/
+  mcpServerFactory.ts   # single MCP server definition, shared by both transports
+  stdio.ts              # official SDK StdioServerTransport entrypoint
+  http.ts               # Node http.Server adapter around the Hono app
+  httpApp.ts            # official SDK WebStandardStreamableHTTPServerTransport (stateless)
+  auth.ts               # OAuth 2.1 resource-server wiring (@vantageos/mcp-auth-kit)
+  config.ts             # env-derived AuthMode + AuthConfig loaders
+  index.ts              # package exports
+tests/
+  helpers/mcpRpc.ts      # JSON-RPC request helpers for the HTTP transport
+  helpers/authFixtures.ts # test-only RS256 JWT signing fixtures
+  httpHandshake.test.ts  # initialize -> tools/list -> tools/call over Streamable HTTP
+  stdioHandshake.test.ts # same handshake over a real spawned stdio child process
+  oauth.test.ts          # both auth tiers: oauth gate + public no-auth tier
+docs/
+  architecture.md        # wire posture: tool-level vs wire-level protocol version
+```
+
+## Quick start
+
+```bash
+npm install
+npm run build
+
+# stdio (local client config, e.g. Claude Code / Cursor) — never gated,
+# the local process invoking stdio IS the caller.
+npm run start:stdio
+
+# Streamable HTTP (remote, stateless) — OAuth 2.1 gate by default:
+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, no-auth "Public MCP" tier (local/self-host, trusted caller):
+AUTH_MODE=public PORT=8787 npm run start:http
+```
+
+## Authentication tiers
+
+Two tiers, per `mcp-standard.md` "Authentication & Authorization":
+
+| `AUTH_MODE` | Behavior |
+|---|---|
+| `oauth` (default) | OAuth 2.1 resource server (`@vantageos/mcp-auth-kit`): every `/mcp` HTTP call requires a valid RS256 Bearer JWT, audience/issuer-bound. Missing/invalid token -> `401` + `WWW-Authenticate`. RFC 9728 Protected Resource Metadata served at `/.well-known/oauth-protected-resource`. `/health` stays token-free. Requires `MCP_OAUTH_ISSUER` + `MCP_OAUTH_AUDIENCE`. |
+| `public` | No gate at all on the HTTP transport — for local/self-host use where the caller is already trusted. Mirrors the stdio transport's trust model (stdio never had a gate). No `.well-known/oauth-protected-resource` document is served in this mode (there is no authorization server to describe). |
+
+The stdio transport (`stdio.ts`) is never gated in either mode — the local
+process invoking it IS the caller, per `mcp-standard.md`'s trust model for
+local/self-host tools.
+
+`buildHttpApp()` called with no arguments defaults to the `public` tier — this
+is what the transport-skeleton tests (`httpHandshake.test.ts`,
+`protocolKitWiring.test.ts`) exercise, so they need no OAuth configuration.
+The production entrypoint (`http.ts`) always resolves `AUTH_MODE` from the
+environment via `config.ts`, defaulting to `oauth` when unset.
+
+## Server-side i18n (FR/EN error messages)
+
+`src/i18n.ts` localizes MCP error/validation messages (auth rejection, tenant
+refusal, tool input-validation) per `mcp-standard.md`'s bilingual mandate
+(§Bilingual): the client sends `X-MCP-Locale: fr` or `X-MCP-Locale: en`
+(default `en` when absent), and `src/httpApp.ts` + `src/mcpServerFactory.ts`
+route the corresponding message through `t(locale, key)`.
+
+The two resource files (`src/locales/{en,fr}.json`) follow the exact
+namespaced-resource convention shipped by `@vantageos/mosaic-i18n@0.1.1`
+(`node_modules/@vantageos/mosaic-i18n/src/locales/{en,fr}.json`): a flat
+`<Namespace>.<category>.<key>` -> string object, FR and EN kept key-for-key
+in lockstep. `mosaic-i18n` itself is a React/`react-i18next` package and
+cannot be called directly from a JSON-RPC server, so its runtime API is not
+imported here — its resource-file shape is reused instead, under this
+boilerplate's own `Mcp` namespace.
+
+## Testing
+
+```bash
+npm test
+```
+
+Runs both transports against the real official-SDK code paths: the HTTP
+suite drives the Hono app in-process; the stdio suite spawns the built
+`dist/stdio.js` binary as a real child process via `StdioClientTransport`.
+
+## Adding a tool
+
+Register it once in `src/mcpServerFactory.ts` — it is then available on
+both transports automatically. There is no separate REST route to add.
+
+## Packaging & distribution
+
+This boilerplate is itself a publishable/clonable npm package. Two artifacts
+carry its distribution identity:
+
+- `package.json` — the npm package. `files` ships only the built `dist/` tree
+  (compiled server + `dist/locales/` + `dist/ui-bundle/widget.html`), the
+  `README.md`, the `LICENSE`, the plugin manifest, and the example client
+  config — never `src/`, tests, or tooling. `main`/`types`/`exports` point at
+  `dist/index.js`; the `mcp-boilerplate` bin points at `dist/stdio.js`.
+  `publishConfig.access = public` is required for the `@vantageos` scope.
+- `.claude-plugin/plugin.json` — the Claude Code marketplace / VantageRegistry
+  catalogue manifest, following the fleet MCP-server convention (mirrors
+  `vantage-frameworks-mcp` / `vantage-agent-composer-mcp`): `name`, `version`,
+  bilingual `description` + `description_fr`, `author`, `license`, `homepage`,
+  `category: "mcp-server"`, `bilingual: true`, `keywords`.
+
+### Scaffold → build → publish
+
+```bash
+# 1. Scaffold: clone this repo (or the npm tarball) as your server's skeleton.
+git clone https://github.com/elpiarthera/vantage-mcp-boilerplate.git my-mcp
+cd my-mcp && npm install --legacy-peer-deps   # see dev peer-range note above
+
+# 2. Rename: set package.json "name"/"bin" and .claude-plugin/plugin.json
+#    "name" to your server, then add tools in src/mcpServerFactory.ts.
+
+# 3. Build + verify from a clean tree (what CI and prepublishOnly enforce):
+rm -rf dist node_modules/.vite && npm run build && npm test && npm run evals
+
+# 4. Inspect the tarball before publishing — confirm dist/ ships and nothing leaks:
+npm pack --dry-run
+
+# 5. Publish to the two channels:
+npm publish                 # npm registry (prepublishOnly re-runs build+test+evals)
+#   VantageRegistry catalogue: register .claude-plugin/plugin.json via
+#   the fleet create-plugin / generate-marketplace skill (VR upsert).
+```
+
+`prepublishOnly` re-runs `build → build:ui → test → evals` so a broken or
+src-only tarball can never reach npm. The distribution channels are **npm**
+(the runnable package) and the **VantageRegistry / Claude Code marketplace
+catalogue** (discovery, via `plugin.json`).
+
+## MCP Apps UI layer
+
+`render_items_ui` renders `EXAMPLE_ITEMS` as an interactive widget via the
+official `@modelcontextprotocol/ext-apps/server` (`registerAppTool` +
+`registerAppResource`), GA `_meta.ui.resourceUri` nested form (stable
+2026-01-26) — never the deprecated flat `_meta["ui/resourceUri"]` key. A
+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
+(`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
+(`dist/ui-bundle/` vs tsc's `dist/ui/`) — the two build steps write to the
+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.
+
+**Publish ordering (hard requirement)**: this boilerplate depends on
+`@vantageos/mcp-protocol-kit@^0.2.0`. The `tools/list` wiring uses the kit's
+`buildToolsListResult`, which exists ONLY in kit 0.2.0+. In 0.x semver `^0.2.0`
+does NOT accept 0.1.x, so a fresh `npm install` from the registry resolves the
+kit build the code actually needs. Therefore **kit `@vantageos/mcp-protocol-kit`
+0.2.0 MUST be published to npm BEFORE this boilerplate can be installed or
+published from the registry.** This is a strict ordering, not optional: publish
+the kit first, confirm 0.2.0 is live at the registry, then the boilerplate.

package/dist/auth.d.ts

@@ -0,0 +1,27 @@
+/**
+ * OAuth 2.1 resource-server wiring for this MCP server's HTTP transport.
+ *
+ * Reuses @vantageos/mcp-auth-kit's `verifyMcpBearerRequest` facade
+ * unmodified — this module never hand-rolls JWT verification. It only
+ * supplies configuration (issuer, audience, JWKS resolver, resource
+ * metadata URL) and adapts the facade's result to a plain
+ * accept/reject decision for the HTTP transport.
+ *
+ * This is the "OAuth 2.1" tier of the two auth tiers this boilerplate
+ * supports (see config.ts `AuthMode`). The other tier — "public" — never
+ * touches this module at all: the HTTP gate is skipped entirely, and the
+ * stdio transport (stdio.ts) never had a gate to begin with (local process
+ * trust model, per mcp-standard.md).
+ */
+import { type McpResourceServerResult } from "@vantageos/mcp-auth-kit";
+import type { JWTVerifyGetKey } from "jose";
+export interface AuthConfig {
+    realm: string;
+    resourceMetadataUrl: string;
+    jwks: JWTVerifyGetKey;
+    issuer: string;
+    audience: string;
+    authorizationServers: string[];
+}
+export declare function authenticateRequest(authHeader: string | undefined, config: AuthConfig): Promise<McpResourceServerResult>;
+export declare function protectedResourceMetadataDocument(config: AuthConfig): import("@vantageos/mcp-auth-kit").ProtectedResourceMetadataDocument;

package/dist/auth.js

@@ -0,0 +1,31 @@
+/**
+ * OAuth 2.1 resource-server wiring for this MCP server's HTTP transport.
+ *
+ * Reuses @vantageos/mcp-auth-kit's `verifyMcpBearerRequest` facade
+ * unmodified — this module never hand-rolls JWT verification. It only
+ * supplies configuration (issuer, audience, JWKS resolver, resource
+ * metadata URL) and adapts the facade's result to a plain
+ * accept/reject decision for the HTTP transport.
+ *
+ * This is the "OAuth 2.1" tier of the two auth tiers this boilerplate
+ * supports (see config.ts `AuthMode`). The other tier — "public" — never
+ * touches this module at all: the HTTP gate is skipped entirely, and the
+ * stdio transport (stdio.ts) never had a gate to begin with (local process
+ * trust model, per mcp-standard.md).
+ */
+import { buildProtectedResourceMetadata, verifyMcpBearerRequest, } from "@vantageos/mcp-auth-kit";
+export async function authenticateRequest(authHeader, config) {
+    return verifyMcpBearerRequest(authHeader, {
+        realm: config.realm,
+        resourceMetadataUrl: config.resourceMetadataUrl,
+        jwks: config.jwks,
+        issuer: config.issuer,
+        audience: config.audience,
+    });
+}
+export function protectedResourceMetadataDocument(config) {
+    return buildProtectedResourceMetadata({
+        resource: config.resourceMetadataUrl.replace(/\/\.well-known\/.*/, ""),
+        authorizationServers: config.authorizationServers,
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Environment-derived configuration for the two auth tiers this
+ * boilerplate ships (mcp-standard.md "Authentication & Authorization"):
+ *
+ *  - "oauth"  (default): OAuth 2.1 resource server on the HTTP transport —
+ *    every /mcp call requires a valid RS256 JWT, audience/issuer-bound.
+ *  - "public": no gate at all on the HTTP transport — for local/self-host
+ *    use where the caller is already trusted (mirrors the stdio transport's
+ *    trust model, which never had a gate). Chosen explicitly, never a
+ *    silent fallback from a missing env var.
+ *
+ * No hardcoded business values — every deployment-specific identity (base
+ * URL, issuer, audience) comes from the environment, never a literal in
+ * code.
+ */
+import { type JWTVerifyGetKey, createLocalJWKSet } from "jose";
+import type { AuthConfig } from "./auth.js";
+export type AuthMode = "oauth" | "public";
+export declare function loadAuthMode(env?: NodeJS.ProcessEnv): AuthMode;
+export declare function loadAuthConfig(env?: NodeJS.ProcessEnv, jwksOverride?: JWTVerifyGetKey): AuthConfig;
+export { createLocalJWKSet };

package/dist/config.js

@@ -0,0 +1,43 @@
+/**
+ * Environment-derived configuration for the two auth tiers this
+ * boilerplate ships (mcp-standard.md "Authentication & Authorization"):
+ *
+ *  - "oauth"  (default): OAuth 2.1 resource server on the HTTP transport —
+ *    every /mcp call requires a valid RS256 JWT, audience/issuer-bound.
+ *  - "public": no gate at all on the HTTP transport — for local/self-host
+ *    use where the caller is already trusted (mirrors the stdio transport's
+ *    trust model, which never had a gate). Chosen explicitly, never a
+ *    silent fallback from a missing env var.
+ *
+ * No hardcoded business values — every deployment-specific identity (base
+ * URL, issuer, audience) comes from the environment, never a literal in
+ * code.
+ */
+import { createLocalJWKSet, createRemoteJWKSet } from "jose";
+export function loadAuthMode(env = process.env) {
+    const raw = (env.AUTH_MODE ?? "oauth").toLowerCase();
+    if (raw !== "oauth" && raw !== "public") {
+        throw new Error(`AUTH_MODE must be "oauth" or "public", got "${raw}". Set AUTH_MODE=public for the no-auth local/self-host tier, or leave unset for the OAuth 2.1 default.`);
+    }
+    return raw;
+}
+export function loadAuthConfig(env = process.env, jwksOverride) {
+    const issuer = env.MCP_OAUTH_ISSUER;
+    const audience = env.MCP_OAUTH_AUDIENCE;
+    const publicBaseUrl = env.PUBLIC_BASE_URL ?? "http://localhost:8787";
+    if (!issuer || !audience) {
+        throw new Error("MCP_OAUTH_ISSUER and MCP_OAUTH_AUDIENCE are required to run the HTTP transport in " +
+            "oauth mode (OAuth 2.1 resource-server requirement — mcp-standard.md Critical Rule #14). " +
+            "Set AUTH_MODE=public instead to run the no-auth local/self-host tier.");
+    }
+    const jwks = jwksOverride ?? createRemoteJWKSet(new URL(`${issuer}/.well-known/jwks.json`));
+    return {
+        realm: "mcp",
+        resourceMetadataUrl: `${publicBaseUrl}/.well-known/oauth-protected-resource`,
+        jwks,
+        issuer,
+        audience,
+        authorizationServers: [issuer],
+    };
+}
+export { createLocalJWKSet };

package/dist/exampleItems.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Seed data for the `list_items` multi-tenant example tool. `createdBy` and
+ * `namespace` follow the tenant-id convention documented in tenancy.ts
+ * (`scopeForTenant`) — each row is owned by, and namespaced under, exactly
+ * one tenant.
+ */
+export interface ExampleItem {
+    id: string;
+    name: string;
+    createdBy: string;
+    namespace: string;
+}
+export declare const EXAMPLE_ITEMS: ExampleItem[];

package/dist/exampleItems.js

@@ -0,0 +1,20 @@
+export const EXAMPLE_ITEMS = [
+    {
+        id: "item-1",
+        name: "Tenant A widget",
+        createdBy: "org_a",
+        namespace: "org_a",
+    },
+    {
+        id: "item-2",
+        name: "Tenant A gadget",
+        createdBy: "org_a",
+        namespace: "org_a",
+    },
+    {
+        id: "item-3",
+        name: "Tenant B widget",
+        createdBy: "org_b",
+        namespace: "org_b",
+    },
+];

package/dist/http.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/http.js

@@ -0,0 +1,28 @@
+import { loadAuthConfig, loadAuthMode } from "./config.js";
+import { buildHttpApp } from "./httpApp.js";
+const authMode = loadAuthMode();
+const app = buildHttpApp(authMode === "oauth" ? { authMode, auth: loadAuthConfig() } : { authMode });
+const port = Number(process.env.PORT ?? 8787);
+// Hono's fetch handler adapted onto Node's http server (no extra framework
+// dependency beyond hono + node:http).
+const { createServer } = await import("node:http");
+createServer(async (req, res) => {
+    const url = `http://${req.headers.host ?? "localhost"}${req.url}`;
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    const body = req.method === "GET" || req.method === "HEAD" ? undefined : Buffer.concat(chunks);
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (typeof value === "string")
+            headers.set(key, value);
+    }
+    const request = new Request(url, { method: req.method, headers, body });
+    const response = await app.fetch(request);
+    res.statusCode = response.status;
+    response.headers.forEach((value, key) => res.setHeader(key, value));
+    const buf = Buffer.from(await response.arrayBuffer());
+    res.end(buf);
+}).listen(port, () => {
+    console.log(`mcp-boilerplate HTTP transport listening on :${port} (authMode: ${authMode})`);
+});

package/dist/httpApp.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Hono HTTP app: stateless MCP transport for the boilerplate skeleton.
+ *
+ * The MCP wire protocol itself is served via the official
+ * `@modelcontextprotocol/sdk` `WebStandardStreamableHTTPServerTransport`
+ * (stateless mode: `sessionIdGenerator: undefined`) — a standard MCP client
+ * (Claude Code, ChatGPT, Cursor) speaks JSON-RPC over this endpoint exactly
+ * as it would over any other MCP HTTP server. No ad-hoc REST routes stand
+ * in front of tool calls.
+ *
+ * True statelessness: a FRESH `McpServer` + a FRESH stateless transport are
+ * created for every single POST to /mcp, connected, used to handle exactly
+ * one request, and never retained. Nothing survives past the request/
+ * response cycle, so the endpoint is horizontally load-balanceable and two
+ * concurrent requests never share any in-memory object.
+ *
+ * `server/discover` is NOT a separate REST route: it is a JSON-RPC method
+ * on this same `/mcp` endpoint (registered on the low-level `Server` in
+ * mcpServerFactory.ts via `@vantageos/mcp-protocol-kit`'s
+ * `handleServerDiscover`), exactly like `tools/list` and `tools/call` —
+ * a standard MCP client dispatches all three the same way.
+ *
+ * Auth tiers (mcp-standard.md "Authentication & Authorization"):
+ *
+ *  - `authMode: "oauth"` — OAuth 2.1 resource server via
+ *    @vantageos/mcp-auth-kit. Every /mcp call requires a valid Bearer JWT
+ *    (RS256, audience/issuer-bound); the RFC 9728 Protected Resource
+ *    Metadata document is served at `/.well-known/oauth-protected-resource`;
+ *    `/health` stays token-free. Requires an `AuthConfig` (deps.auth) — see
+ *    config.ts `loadAuthConfig()`.
+ *  - `authMode: "public"` — no gate at all. For local/self-host use where
+ *    the caller is already trusted, mirroring the stdio transport's trust
+ *    model (stdio.ts never had a gate to begin with). This is the DEFAULT
+ *    when `buildHttpApp()` is called with no deps, so the transport-only
+ *    tests (httpHandshake.test.ts, protocolKitWiring.test.ts) exercise the
+ *    skeleton without needing OAuth configuration.
+ */
+import { Hono } from "hono";
+import { type AuthConfig } from "./auth.js";
+import type { AuthMode } from "./config.js";
+import { type ResolvedTenant } from "./tenancy.js";
+export interface AppDeps {
+    authMode?: AuthMode;
+    auth?: AuthConfig;
+}
+type Variables = {
+    tenant?: ResolvedTenant;
+};
+export declare function buildHttpApp(deps?: AppDeps): Hono<{
+    Variables: Variables;
+}>;
+export {};

package/dist/httpApp.js

@@ -0,0 +1,113 @@
+/**
+ * Hono HTTP app: stateless MCP transport for the boilerplate skeleton.
+ *
+ * The MCP wire protocol itself is served via the official
+ * `@modelcontextprotocol/sdk` `WebStandardStreamableHTTPServerTransport`
+ * (stateless mode: `sessionIdGenerator: undefined`) — a standard MCP client
+ * (Claude Code, ChatGPT, Cursor) speaks JSON-RPC over this endpoint exactly
+ * as it would over any other MCP HTTP server. No ad-hoc REST routes stand
+ * in front of tool calls.
+ *
+ * True statelessness: a FRESH `McpServer` + a FRESH stateless transport are
+ * created for every single POST to /mcp, connected, used to handle exactly
+ * one request, and never retained. Nothing survives past the request/
+ * response cycle, so the endpoint is horizontally load-balanceable and two
+ * concurrent requests never share any in-memory object.
+ *
+ * `server/discover` is NOT a separate REST route: it is a JSON-RPC method
+ * on this same `/mcp` endpoint (registered on the low-level `Server` in
+ * mcpServerFactory.ts via `@vantageos/mcp-protocol-kit`'s
+ * `handleServerDiscover`), exactly like `tools/list` and `tools/call` —
+ * a standard MCP client dispatches all three the same way.
+ *
+ * Auth tiers (mcp-standard.md "Authentication & Authorization"):
+ *
+ *  - `authMode: "oauth"` — OAuth 2.1 resource server via
+ *    @vantageos/mcp-auth-kit. Every /mcp call requires a valid Bearer JWT
+ *    (RS256, audience/issuer-bound); the RFC 9728 Protected Resource
+ *    Metadata document is served at `/.well-known/oauth-protected-resource`;
+ *    `/health` stays token-free. Requires an `AuthConfig` (deps.auth) — see
+ *    config.ts `loadAuthConfig()`.
+ *  - `authMode: "public"` — no gate at all. For local/self-host use where
+ *    the caller is already trusted, mirroring the stdio transport's trust
+ *    model (stdio.ts never had a gate to begin with). This is the DEFAULT
+ *    when `buildHttpApp()` is called with no deps, so the transport-only
+ *    tests (httpHandshake.test.ts, protocolKitWiring.test.ts) exercise the
+ *    skeleton without needing OAuth configuration.
+ */
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { Hono } from "hono";
+import { authenticateRequest, protectedResourceMetadataDocument } from "./auth.js";
+import { detectLocale, t } from "./i18n.js";
+import { createBoilerplateMcpServer } from "./mcpServerFactory.js";
+import { resolveTenantFromJwtPayload } from "./tenancy.js";
+const WELL_KNOWN_PATHS = ["/.well-known/oauth-protected-resource", "/health"];
+export function buildHttpApp(deps = {}) {
+    const app = new Hono();
+    const authMode = deps.authMode ?? "public";
+    app.get("/health", (c) => c.json({ status: "ok" }));
+    if (authMode === "oauth") {
+        if (!deps.auth) {
+            throw new Error("authMode 'oauth' requires an AuthConfig (deps.auth) — build one via " +
+                "config.ts loadAuthConfig(), or pass authMode: 'public' for the no-auth tier.");
+        }
+        const auth = deps.auth;
+        app.get("/.well-known/oauth-protected-resource", (c) => {
+            return c.json(protectedResourceMetadataDocument(auth));
+        });
+        // OAuth 2.1 resource-server gate — every route below this line requires
+        // a valid Bearer JWT, verified entirely by @vantageos/mcp-auth-kit.
+        app.use("*", async (c, next) => {
+            if (WELL_KNOWN_PATHS.includes(c.req.path)) {
+                await next();
+                return;
+            }
+            const authHeader = c.req.header("Authorization");
+            const result = await authenticateRequest(authHeader, auth);
+            if (!result.ok) {
+                const locale = detectLocale(c.req.header("X-MCP-Locale"));
+                c.header("WWW-Authenticate", result.headers["WWW-Authenticate"]);
+                return c.json({ error: t(locale, "auth.unauthorized") }, result.status);
+            }
+            // Tenant resolution (tenancy.ts) is attempted here but is NOT
+            // request-fatal: `initialize`/`tools/list` and any tenant-agnostic
+            // tool (e.g. `ping`) must keep working for a verified caller that has
+            // no organization on their token. Tenant-scoped tools (`list_items`)
+            // enforce the requirement themselves, at the tool-call level (see
+            // mcpServerFactory.ts) — a missing tenant there is refused as an MCP
+            // tool error, never silently treated as an unscoped/master caller.
+            try {
+                c.set("tenant", resolveTenantFromJwtPayload(result.payload));
+            }
+            catch {
+                // No organization on this token — tenant stays unset. Tenant-scoped
+                // tools refuse explicitly when they see no tenant under oauth mode.
+            }
+            await next();
+        });
+    }
+    // The one real MCP endpoint: standard JSON-RPC over Streamable HTTP,
+    // stateless mode. GET/POST/DELETE are all delegated to the SDK transport,
+    // which handles the protocol's method dispatch itself.
+    app.all("/mcp", async (c) => {
+        const tenant = authMode === "oauth" ? c.get("tenant") : undefined;
+        const locale = detectLocale(c.req.header("X-MCP-Locale"));
+        const server = createBoilerplateMcpServer({
+            tenant,
+            requireTenant: authMode === "oauth",
+            locale,
+        });
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            sessionIdGenerator: undefined, // stateless mode — no session ID anywhere
+            enableJsonResponse: true,
+        });
+        await server.connect(transport);
+        try {
+            return await transport.handleRequest(c.req.raw);
+        }
+        finally {
+            await transport.close();
+        }
+    });
+    return app;
+}

package/dist/i18n.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Thin server-side locale layer for MCP error/validation messages.
+ *
+ * REUSE: @vantageos/mosaic-i18n@0.1.1 is a React/react-i18next package
+ * (`peerDependencies: i18next, react-i18next`) — its runtime API targets a
+ * React component tree, not a JSON-RPC server, so it cannot be called
+ * directly from tool handlers here. What IS reused, verified firsthand in
+ * `node_modules/@vantageos/mosaic-i18n/src/locales/{en,fr}.json`, is its
+ * resource-file CONVENTION: a flat namespaced object
+ * (`<Component>.<category>.<key>` -> string), one file per locale, FR and
+ * EN kept in lockstep key-for-key. `src/locales/{en,fr}.json` in this
+ * boilerplate follows that exact shape under a single `Mcp` namespace
+ * (`Mcp.auth.*`, `Mcp.tenant.*`, `Mcp.validation.*`), so the two locale
+ * files could be merged into mosaic-i18n's own resource files verbatim if
+ * this boilerplate ever grows a React UI consumer of the same strings.
+ *
+ * Locale detection follows mcp-standard.md's `X-MCP-Locale` request header
+ * (§Bilingual, l.234): "fr" selects the French resource, anything else
+ * (including a missing header) defaults to English.
+ */
+export type McpLocale = "en" | "fr";
+/**
+ * Resolves the caller's locale from the `X-MCP-Locale` request header.
+ * Defaults to "en" for a missing header or any value other than "fr".
+ */
+export declare function detectLocale(headerValue: string | null | undefined): McpLocale;
+/**
+ * Looks up a translated MCP message. `key` is a dot path under the `Mcp`
+ * namespace, e.g. `"auth.unauthorized"` or `"tenant.permissionDenied"`.
+ * Falls back to the English string (never to the raw key) if the requested
+ * locale is somehow missing a key the English resource carries.
+ */
+export declare function t(locale: McpLocale, key: string): string;