@vantageos/mcp-boilerplate 0.1.2 → 0.2.1

package/dist/tenancy.d.ts

@@ -1,8 +1,7 @@
 /**
- * Multi-tenant glue: takes the already-verified JWT payload produced by
- * auth.ts's OAuth 2.1 resource-server gate (BP-T3, reusing
- * @vantageos/mcp-auth-kit's `verifyMcpBearerRequest` unmodified) and hands
- * it to @vantageos/cloud-identity to resolve the caller's tenant and scope
+ * Multi-tenant glue: takes the verified session claims produced by
+ * auth.ts's OAuth 2.1 resource-server gate (@vantageos/cloud-identity's `verifyMcpAccessToken`,
+ * `session.claims`) and hands them to @vantageos/cloud-identity to resolve the caller's tenant and scope
  * rows. This module never re-verifies the token and never reimplements
  * cloud-identity's authorization logic — it only adapts shapes.
  *
@@ -11,7 +10,7 @@
  * entry path expects a full `TenantContext` ({ workspaceId, userId, roles })
  * — the shape cloud-identity's OWN workspace-membership layer produces
  * (`decodeUnverifiedBearer`), not a generic OAuth JWT. This boilerplate's
- * verified payload (a plain `jose` `JWTPayload`, Clerk-as-AS) carries no
+ * verified claims (a plain claims record, Clerk-as-AS) carries no
  * `workspaceId`/`roles` claims, so it is NOT a `TenantContext` and cannot
  * go through the "bearer" path without inventing fields cloud-identity
  * never asked for. It goes through the "session" path instead
@@ -21,29 +20,25 @@
  * organization, on either path) — this is a compatible substitution
  * documented at the one call site it affects, never a bypass of the guard.
  */
-import { type OAuthCtx, type ScopeFilterable } from "@vantageos/cloud-identity";
-import type { JWTPayload } from "jose";
 export interface ResolvedTenant {
     tenantId: string;
 }
 /**
- * Resolve the caller's tenant from the verified JWT payload. Refuses
+ * Resolve the caller's tenant from the verified session claims. Refuses
  * (throws) when the token carries no organization — never falls through to
  * an unscoped/master view. Callers MUST treat the thrown error as a refusal
  * (an explicit permission-denied response), never silently grant access.
  */
-export declare function resolveTenantFromJwtPayload(payload: JWTPayload): ResolvedTenant;
-/**
- * Minimal scope profile derived from the resolved tenant: the tenant id
- * doubles as both the row-ownership allow-list entry and the namespace
- * prefix, so a tool result is scoped to rows this tenant created (or that
- * live under its namespace) and nothing else. This is the boilerplate's
- * example convention — a real deployment may derive richer allow-lists.
- */
-export declare function scopeForTenant(tenantId: string): OAuthCtx;
+export declare function resolveTenantFromJwtPayload(payload: Readonly<Record<string, unknown>>): ResolvedTenant;
+/** A row that carries the STORED id of the organisation that owns it. */
+export interface TenantOwned {
+    orgId?: string | null;
+}
 /**
- * Filter rows by the caller's tenant, reusing cloud-identity's
- * `scopeFilterList` unmodified — this module never reimplements row
- * filtering.
+ * Filter rows by the caller's tenant with cloud-identity's `isRowInTenant`: a row is visible
+ * only when it is stamped with an organisation and that id strictly equals the caller's. An
+ * unstamped row is never visible. This replaces the deprecated `scopeFilterList`, which
+ * selected rows by a creator NAME (backend standard R-53 clause 1 forbids that); identifiers
+ * are compared byte for byte, a slug is never compared against an id.
  */
-export declare function scopeRowsForTenant<T extends ScopeFilterable>(tenantId: string, rows: T[]): T[];
+export declare function scopeRowsForTenant<T extends TenantOwned>(tenantId: string, rows: T[]): T[];

package/dist/tenancy.js

@@ -1,8 +1,7 @@
 /**
- * Multi-tenant glue: takes the already-verified JWT payload produced by
- * auth.ts's OAuth 2.1 resource-server gate (BP-T3, reusing
- * @vantageos/mcp-auth-kit's `verifyMcpBearerRequest` unmodified) and hands
- * it to @vantageos/cloud-identity to resolve the caller's tenant and scope
+ * Multi-tenant glue: takes the verified session claims produced by
+ * auth.ts's OAuth 2.1 resource-server gate (@vantageos/cloud-identity's `verifyMcpAccessToken`,
+ * `session.claims`) and hands them to @vantageos/cloud-identity to resolve the caller's tenant and scope
  * rows. This module never re-verifies the token and never reimplements
  * cloud-identity's authorization logic — it only adapts shapes.
  *
@@ -11,7 +10,7 @@
  * entry path expects a full `TenantContext` ({ workspaceId, userId, roles })
  * — the shape cloud-identity's OWN workspace-membership layer produces
  * (`decodeUnverifiedBearer`), not a generic OAuth JWT. This boilerplate's
- * verified payload (a plain `jose` `JWTPayload`, Clerk-as-AS) carries no
+ * verified claims (a plain claims record, Clerk-as-AS) carries no
  * `workspaceId`/`roles` claims, so it is NOT a `TenantContext` and cannot
  * go through the "bearer" path without inventing fields cloud-identity
  * never asked for. It goes through the "session" path instead
@@ -21,9 +20,9 @@
  * organization, on either path) — this is a compatible substitution
  * documented at the one call site it affects, never a bypass of the guard.
  */
-import { requireTenantId, scopeFilterList, } from "@vantageos/cloud-identity";
+import { isRowInTenant, requireTenantId } from "@vantageos/cloud-identity";
 /**
- * Resolve the caller's tenant from the verified JWT payload. Refuses
+ * Resolve the caller's tenant from the verified session claims. Refuses
  * (throws) when the token carries no organization — never falls through to
  * an unscoped/master view. Callers MUST treat the thrown error as a refusal
  * (an explicit permission-denied response), never silently grant access.
@@ -34,25 +33,12 @@ export function resolveTenantFromJwtPayload(payload) {
     return { tenantId };
 }
 /**
- * Minimal scope profile derived from the resolved tenant: the tenant id
- * doubles as both the row-ownership allow-list entry and the namespace
- * prefix, so a tool result is scoped to rows this tenant created (or that
- * live under its namespace) and nothing else. This is the boilerplate's
- * example convention — a real deployment may derive richer allow-lists.
- */
-export function scopeForTenant(tenantId) {
-    return {
-        fromAllowList: [tenantId],
-        namespaceReadPrefixes: [tenantId],
-        namespaceWritePrefixes: [tenantId],
-        scope: "tenant",
-    };
-}
-/**
- * Filter rows by the caller's tenant, reusing cloud-identity's
- * `scopeFilterList` unmodified — this module never reimplements row
- * filtering.
+ * Filter rows by the caller's tenant with cloud-identity's `isRowInTenant`: a row is visible
+ * only when it is stamped with an organisation and that id strictly equals the caller's. An
+ * unstamped row is never visible. This replaces the deprecated `scopeFilterList`, which
+ * selected rows by a creator NAME (backend standard R-53 clause 1 forbids that); identifiers
+ * are compared byte for byte, a slug is never compared against an id.
  */
 export function scopeRowsForTenant(tenantId, rows) {
-    return scopeFilterList(scopeForTenant(tenantId), rows);
+    return rows.filter((row) => isRowInTenant({ rowOrgId: row.orgId, callerOrgId: tenantId }));
 }

package/dist/ui/uiResource.d.ts

@@ -1,23 +1,47 @@
-import type { McpUiToolMeta } from "@modelcontextprotocol/ext-apps";
+import type { McpUiResourceMeta, McpUiToolMeta } from "@modelcontextprotocol/ext-apps";
 import type { ExampleItem } from "../exampleItems.js";
 export declare const ITEMS_UI_RESOURCE_URI = "ui://mcp-boilerplate/items-widget.html";
 /**
  * Reads the single-file bundle produced by `npm run build:ui`
- * (vite-plugin-singlefile). Thrown, never silently swallowed, if the
- * bundle is missing — a missing bundle is a build defect, not a runtime
- * fallback case.
+ * (vite-plugin-singlefile). Never silently swallowed: a missing bundle is a build defect, not
+ * a runtime fallback case. The error that reaches the MCP client names no filesystem path;
+ * the detail goes to stderr (server side) only.
  */
 export declare function readUiBundle(): string;
+/**
+ * Resource-level `_meta.ui` (MCP Apps spec 2026-01-26). The CSP is derived from what the
+ * widget (src/ui/Widget.tsx) actually does: it renders props it is given, makes no network
+ * request, loads no third-party asset and embeds no frame, so every domain list is EMPTY
+ * (the secure default stated in the spec) — not omitted, so the declaration is explicit and
+ * a fork that adds a network call has to edit a visible list. `domain` is host-dependent
+ * (the spec says consult each host), so it is set only when the deployment supplies one.
+ */
+export declare function buildItemsUiResourceMeta(domain?: string): McpUiResourceMeta;
 export declare function buildUiResource(props: {
     items: ExampleItem[];
     locale: "en" | "fr";
+    domain?: string;
 }): {
     uri: string;
     mimeType: string;
     text: string;
+    _meta: {
+        ui: McpUiResourceMeta;
+    };
 };
-/** GA nested `_meta.ui` value shared by the tool registration and the result. */
+/**
+ * Tool-level `_meta`: the GA nested `_meta.ui.resourceUri` is the PRIMARY link, with explicit
+ * visibility. The `openai/*` keys are ADDITIVE hints for ChatGPT (same URI as the template,
+ * plus status strings); a client that ignores them loses nothing, and the server never reads
+ * them. `openai/ui` entrypoints are deliberately not emitted (optional; see the README).
+ */
 export declare const ITEMS_UI_META: McpUiToolMeta;
+export declare const ITEMS_TOOL_META: {
+    readonly ui: McpUiToolMeta;
+    readonly "openai/outputTemplate": "ui://mcp-boilerplate/items-widget.html";
+    readonly "openai/toolInvocation/invoking": "Rendering items…";
+    readonly "openai/toolInvocation/invoked": "Items ready.";
+};
 export interface RenderItemsUiResult {
     [key: string]: unknown;
     content: Array<{
@@ -27,8 +51,17 @@ export interface RenderItemsUiResult {
         type: "resource";
         resource: ReturnType<typeof buildUiResource>;
     }>;
+    structuredContent: {
+        items: ExampleItem[];
+        locale: "en" | "fr";
+    };
     _meta: {
         ui: McpUiToolMeta;
     };
 }
-export declare function buildRenderItemsUiResult(items: ExampleItem[], locale: "en" | "fr"): RenderItemsUiResult;
+/**
+ * content[0] is the mandatory markdown fallback for hosts without MCP Apps (mcp-app-standard
+ * A-1: it stays first, as before); content[1] mirrors `structuredContent` as JSON text (clients
+ * that only read text still get the data); content[2] is the embedded ui:// resource.
+ */
+export declare function buildRenderItemsUiResult(items: ExampleItem[], locale: "en" | "fr", domain?: string): RenderItemsUiResult;

package/dist/ui/uiResource.js

@@ -11,13 +11,18 @@
  * shape written here.
  */
 import { readFileSync } from "node:fs";
-import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
 export const ITEMS_UI_RESOURCE_URI = "ui://mcp-boilerplate/items-widget.html";
 // dist/ui-bundle/ — NEVER dist/ui/ (that path is tsc's compiled-server
 // output for this very module; see vite.config.ts for the collision this
-// avoids).
-const BUNDLE_PATH = path.join(process.cwd(), "dist", "ui-bundle", "widget.html");
+// avoids). Resolved relative to THIS module, never to the working directory: an installed
+// package runs from any cwd. Compiled (dist/ui/uiResource.js) the bundle is `../ui-bundle`;
+// from source (src/ui/uiResource.ts, under vitest) it is the repository's built `dist/`.
+const BUNDLE_CANDIDATES = [
+    fileURLToPath(new URL("../ui-bundle/widget.html", import.meta.url)),
+    fileURLToPath(new URL("../../dist/ui-bundle/widget.html", import.meta.url)),
+];
 function renderMarkdownFallback(items, locale) {
     const title = locale === "fr" ? "Éléments" : "Items";
     if (items.length === 0) {
@@ -28,32 +33,76 @@ function renderMarkdownFallback(items, locale) {
 }
 /**
  * Reads the single-file bundle produced by `npm run build:ui`
- * (vite-plugin-singlefile). Thrown, never silently swallowed, if the
- * bundle is missing — a missing bundle is a build defect, not a runtime
- * fallback case.
+ * (vite-plugin-singlefile). Never silently swallowed: a missing bundle is a build defect, not
+ * a runtime fallback case. The error that reaches the MCP client names no filesystem path;
+ * the detail goes to stderr (server side) only.
  */
 export function readUiBundle() {
-    return readFileSync(BUNDLE_PATH, "utf-8");
+    let lastError;
+    for (const candidate of BUNDLE_CANDIDATES) {
+        try {
+            return readFileSync(candidate, "utf-8");
+        }
+        catch (err) {
+            lastError = err;
+        }
+    }
+    console.error(`[ui] UI bundle unreadable (tried ${BUNDLE_CANDIDATES.join(", ")}):`, lastError);
+    throw new Error("UI bundle unavailable on this server");
+}
+/**
+ * Resource-level `_meta.ui` (MCP Apps spec 2026-01-26). The CSP is derived from what the
+ * widget (src/ui/Widget.tsx) actually does: it renders props it is given, makes no network
+ * request, loads no third-party asset and embeds no frame, so every domain list is EMPTY
+ * (the secure default stated in the spec) — not omitted, so the declaration is explicit and
+ * a fork that adds a network call has to edit a visible list. `domain` is host-dependent
+ * (the spec says consult each host), so it is set only when the deployment supplies one.
+ */
+export function buildItemsUiResourceMeta(domain) {
+    return {
+        csp: { connectDomains: [], resourceDomains: [], frameDomains: [], baseUriDomains: [] },
+        ...(domain ? { domain } : {}),
+        prefersBorder: true,
+    };
 }
 export function buildUiResource(props) {
     return {
         uri: ITEMS_UI_RESOURCE_URI,
         mimeType: RESOURCE_MIME_TYPE,
         text: readUiBundle(),
+        _meta: { ui: buildItemsUiResourceMeta(props.domain) },
     };
 }
-/** GA nested `_meta.ui` value shared by the tool registration and the result. */
+/**
+ * Tool-level `_meta`: the GA nested `_meta.ui.resourceUri` is the PRIMARY link, with explicit
+ * visibility. The `openai/*` keys are ADDITIVE hints for ChatGPT (same URI as the template,
+ * plus status strings); a client that ignores them loses nothing, and the server never reads
+ * them. `openai/ui` entrypoints are deliberately not emitted (optional; see the README).
+ */
 export const ITEMS_UI_META = {
     resourceUri: ITEMS_UI_RESOURCE_URI,
+    visibility: ["model", "app"],
+};
+export const ITEMS_TOOL_META = {
+    ui: ITEMS_UI_META,
+    "openai/outputTemplate": ITEMS_UI_RESOURCE_URI,
+    "openai/toolInvocation/invoking": "Rendering items…",
+    "openai/toolInvocation/invoked": "Items ready.",
 };
-export function buildRenderItemsUiResult(items, locale) {
-    const fallbackMarkdown = renderMarkdownFallback(items, locale);
-    const resource = buildUiResource({ items, locale });
+/**
+ * content[0] is the mandatory markdown fallback for hosts without MCP Apps (mcp-app-standard
+ * A-1: it stays first, as before); content[1] mirrors `structuredContent` as JSON text (clients
+ * that only read text still get the data); content[2] is the embedded ui:// resource.
+ */
+export function buildRenderItemsUiResult(items, locale, domain) {
+    const structuredContent = { items, locale };
     return {
         content: [
-            { type: "text", text: fallbackMarkdown },
-            { type: "resource", resource },
+            { type: "text", text: renderMarkdownFallback(items, locale) },
+            { type: "text", text: JSON.stringify(structuredContent) },
+            { type: "resource", resource: buildUiResource({ items, locale, domain }) },
         ],
+        structuredContent,
         _meta: { ui: ITEMS_UI_META },
     };
 }

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const SERVER_NAME = "mcp-boilerplate";
+export declare const SERVER_VERSION: string;

package/dist/version.js

@@ -0,0 +1,8 @@
+/**
+ * The advertised server version is DERIVED from package.json (never a literal).
+ * `src/version.ts` and `dist/version.js` both sit one level under the package root,
+ * so the same relative URL resolves in source mode (vitest) and in the built output.
+ */
+import { readFileSync } from "node:fs";
+export const SERVER_NAME = "mcp-boilerplate";
+export const SERVER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;

package/docs/architecture.md

@@ -0,0 +1,82 @@
+# Architecture
+
+## Single server, two transports
+
+`src/mcpServerFactory.ts` builds one `McpServer` definition (tools registered
+once). `src/stdio.ts` and `src/httpApp.ts` each hand that factory to an official
+SDK v2 serving entry: `serveStdio` for local/self-host clients and
+`createMcpHandler` for remote clients over stateless Streamable HTTP. Neither
+transport exposes a custom REST route for tool calls; every tool invocation goes
+through the SDK's own JSON-RPC method dispatch (`tools/list`, `tools/call`).
+
+The HTTP transport builds a brand-new `McpServer` for every request through the
+handler's factory and discards it at the end of the request. Nothing survives
+past one request/response cycle, so the endpoint is horizontally
+load-balanceable and never leaks state between concurrent callers.
+
+## Wire posture
+
+The server speaks MCP protocol **2026-07-28** and still serves the 2025 era from
+the same factory, with no private SDK field and no hand-written request schema:
+
+- **2026-07-28**: the client opens with `server/discover`. The SDK builds the
+  discover result and stamps `resultType`, `ttlMs` and `cacheScope` on
+  `server/discover`, `tools/list` and `resources/*` from the `cacheHints` option
+  set in the factory.
+- **2025 era**: the client opens with `initialize`. On HTTP the SDK serves it
+  through its stateless legacy leg (`createMcpHandler` default `legacy:
+  "stateless"`); on stdio `serveStdio` pins one instance to the connection.
+  Legacy results never carry the cache fields.
+- **Floor 2025-06-18**: `supportedProtocolVersions` (a `ProtocolOptions` field of
+  `@modelcontextprotocol/server`) lists `2025-11-25` and `2025-06-18` only. An
+  `initialize` below the floor is counter-offered `2025-11-25`.
+- **Version**: `serverInfo.version` is read from `package.json`
+  (`src/version.ts`), never typed.
+
+`@vantageos/mcp-protocol-kit` is no longer a dependency: the SDK emits the
+result types the kit used to add. Tests assert both eras
+(`tests/protocol20260728.test.ts`, HTTP in-process and stdio on the built binary).
+
+## Authentication posture
+
+Three tiers (`AUTH_MODE`, README): `public` (no gate), `oauth` with this server as
+its own authorization server (default), and `oauth` against an external issuer
+(resource server only).
+
+In the default tier `src/oauth/` is the authorization server and
+`@vantageos/cloud-identity` is also the resource server in front of `/mcp`
+(`verifyMcpAccessToken`; an unreachable key set answers 503, never 401), so it is the
+only identity layer. The authorization decisions are delegated to it; this
+repository owns HTTP, the stores (interfaces, in-memory adapters, durable-adapter
+contract in `docs/oauth-stores.md`), the Clerk calls and the RS256 signature. The
+flow is: Clerk sign-in, organisation picker with consent, a code bound to the
+person and the chosen organisation, then `POST /token` (PKCE S256) mints a JWT
+whose `aud` is `<base>/mcp` and whose `org_id` is the chosen organisation.
+`tenancy.ts` reads that claim and `list_items` keeps the rows whose stored
+`orgId` equals it. Missing configuration answers 503 on every authorization route
+and on `/mcp`.
+
+## Evals layer
+
+`evals/evals.json` declares a case-set (handshake, `tools/list` coverage,
+`tools/call` happy paths, and the public-tier tenancy assertion) as data,
+never as hand-written test code. `evals/run.ts` is the minimal harness that
+drives one JSON-RPC op per case against an already-connected SDK `Client`
+and checks the declared assertion — it reuses the SDK's own `Client`, never
+a reinvented protocol layer.
+
+Two consumers, on purpose:
+
+- `evals/evals.test.ts` (`npm run evals`) spawns the real built
+  `dist/stdio.js` child (same pattern as `tests/stdioHandshake.test.ts`)
+  and runs every declared case against it end to end. Vitest's own
+  pass/fail reporting and non-zero exit on any failing case ARE the
+  harness's ratio + exit-code contract — no separate reporter is built.
+- `tests/evalsRunner.test.ts` (`npm test`) unit-tests `evals/run.ts`'s
+  assertion logic against an in-process fake client, including the RED
+  path (a deliberately broken case failing with a message naming both the
+  expected and observed values) and the fail-loud empty-case-set guard.
+
+`vitest.evals.config.ts` keeps the eval-case glob (`evals/**/*.test.ts`)
+separate from the default test glob (`tests/**/*.test.ts`), so the two
+ratios stay independently reproducible from a clean build.

package/docs/oauth-stores.md

@@ -0,0 +1,60 @@
+# Authorization-server stores and the durable-adapter contract
+
+The authorization server (`src/oauth/`) keeps two kinds of state behind small interfaces. The
+in-memory adapters ship for tests and single-process development; a production deployment with
+more than one instance (or one that restarts) MUST inject durable adapters through
+`AuthorizationServerDeps` (`buildHttpApp({ authMode: "oauth", authorizationServer: { codeStore, clientRegistry } })`).
+
+## `AuthorizationCodeStore` (cloud-identity type, `src/oauth/codeStore.ts`)
+
+```ts
+interface AuthorizationCodeStore {
+  put(record: AuthorizationCodeRecord): Promise<void>;
+  consume(codeHash: string): Promise<ConsumeCodeResult>; // ok | unknown | already-used
+}
+```
+
+A durable adapter MUST honour all of the following; cloud-identity relies on each:
+
+1. **Digest only.** `codeHash` is the digest of the code; the raw code is never stored.
+2. **Atomic consume.** Of two concurrent `consume` calls for the same digest exactly one returns
+   `{ status: "ok", record }`; the other returns `{ status: "already-used" }`. A read followed by
+   a write is not an implementation (use a single conditional update, `DELETE ... RETURNING`,
+   `GETDEL`, or a transaction).
+3. **Distinguish the two misses.** `unknown` (never seen, or expired and swept) is not
+   `already-used`: a replayed code is reported as `code-reused`, which lets the operator revoke
+   what the first redemption issued.
+4. **Expiry.** `record.expiresAt` (epoch ms) is enforced by cloud-identity at exchange time; the
+   store should also sweep expired rows (a TTL index) so the table stays bounded.
+5. **Failure is loud.** A store that cannot answer throws; cloud-identity turns that into a 503
+   refusal, never a grant.
+
+Access tokens are self-contained RS256 JWTs (one hour, no refresh token), so there is no token
+table. An operator who needs revocation before expiry adds a `jti` deny-list checked by the
+resource-server gate; that is outside this boilerplate.
+
+## `ClientRegistry` (`src/oauth/clientRegistry.ts`)
+
+```ts
+interface ClientRegistry {
+  get(clientId: string): Promise<RegisteredClient | null>;
+  register(client: RegisteredClient): Promise<void>;
+}
+```
+
+Holds Dynamic Client Registration (DCR) clients only. A URL-shaped `client_id` is a Client ID
+Metadata Document (CIMD) and is never stored: it is fetched, validated and used per request.
+
+A durable adapter MUST: store `redirectUris` exactly as registered (cloud-identity compares them
+by exact equality), return `revoked: true` for a revoked client instead of deleting it, and cap
+the number of rows (DCR is an unauthenticated endpoint; `/register` is also rate-limited per IP
+in-process).
+
+## CIMD fetch and DNS rebinding
+
+`resolveCimdClient` accepts an https URL with a path only, refuses any host that resolves to a
+non-public address (loopback, private, link-local, CGNAT, multicast, and the IPv4-mapped, IPv4-compatible and NAT64 spellings of those, in any textual form), follows no
+redirect, reads at most 16 KiB (streamed, the read is cancelled once the cap is crossed) and gives up after 5 s. It resolves the host and then `fetch`
+resolves it again, so a DNS-rebinding window exists. A deployment on a hostile network injects a
+`fetchImpl` that connects to the validated address (for example an undici dispatcher with a
+custom `lookup`).

package/examples/oauth.env.example

@@ -0,0 +1,25 @@
+# Own authorization server (OAuth tier, the default). Every value below is REQUIRED; a missing
+# one makes /authorize, /token, /register and /mcp answer 503 (fail-closed). No secret is
+# committed here — fill these from your secret manager.
+
+# Public origin of this server (no trailing slash). The protected resource is <PUBLIC_BASE_URL>/mcp.
+PUBLIC_BASE_URL=https://your-server.example.com
+
+# Clerk: the instance's frontend API URL (issuer of the person's session token).
+CLERK_DOMAIN=https://clerk.your-domain.example.com
+# Clerk sign-in page the person is sent to, and this server's /authorize/callback URL.
+AUTHORIZE_SIGN_IN_URL=https://accounts.your-domain.example.com/sign-in
+AUTHORIZE_CALLBACK_URL=https://your-server.example.com/authorize/callback
+# Clerk Backend API key (memberships + user lookup).
+CLERK_SECRET_KEY=
+
+# HMAC secret for the signed authorize state, at least 32 characters.
+AUTHORIZE_STATE_SECRET=
+
+# RS256 private JWK that signs access tokens: `node scripts/generate-signing-key.mjs`.
+MCP_OAUTH_SIGNING_JWK=
+
+# Optional: extra Clerk `azp` origins accepted for the session token (comma-separated).
+# AUTHORIZE_AUTHORIZED_PARTIES=
+# Optional: dedicated sandbox origin of the MCP Apps widget (host-dependent).
+# MCP_UI_DOMAIN=

package/mcp.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "mcp-boilerplate": {
+      "type": "streamable-http",
+      "url": "https://your-server.example.com/mcp",
+      "extensions": {
+        "com.openai": {
+          "auth": {
+            "type": "oauth",
+            "client": {
+              "mode": "cimd"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@vantageos/mcp-boilerplate",
-  "version": "0.1.2",
-  "description": "Clonable MCP server skeleton: dual-transport bootstrap (stdio + Streamable HTTP, stateless) on the official @modelcontextprotocol/sdk, ready to extend with protocol-kit, auth, tenant and UI layers.",
-  "description_fr": "Squelette de serveur MCP clonable : bootstrap double-transport (stdio + Streamable HTTP, sans état) sur le @modelcontextprotocol/sdk officiel, prêt à étendre avec les couches protocol-kit, authentification, tenant et UI.",
+  "version": "0.2.1",
+  "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",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -23,7 +23,15 @@
     "CHANGELOG.md",
     "LICENSE",
     ".claude-plugin/plugin.json",
-    "examples/claude-desktop.json"
+    ".mcp.json",
+    "plugin.json",
+    "mcp.json",
+    "skills",
+    "scripts/plugin-manifest.source.json",
+    "scripts/generate-signing-key.mjs",
+    "docs",
+    "examples/claude-desktop.json",
+    "examples/oauth.env.example"
   ],
   "publishConfig": {
     "access": "public"
@@ -48,32 +56,34 @@
     "start:stdio": "node dist/stdio.js",
     "evals": "npm run build && npm run build:ui && vitest run --config vitest.evals.config.ts",
     "prepublishOnly": "npm run build && npm run build:ui && npm test && npm run evals",
-    "lint": "biome check src evals tests",
-    "lint:fix": "biome check --write src evals tests"
+    "lint": "biome check src evals tests scripts",
+    "lint:fix": "biome check --write src evals tests scripts"
   },
   "keywords": [
     "mcp",
     "model-context-protocol",
     "boilerplate",
-    "starter"
+    "starter",
+    "oauth",
+    "mcp-apps",
+    "chatgpt"
   ],
   "license": "MIT",
   "engines": {
     "node": ">=20"
   },
   "dependencies": {
-    "@modelcontextprotocol/ext-apps": "^1.7.5",
-    "@modelcontextprotocol/sdk": "^1.13.0",
-    "@vantageos/cloud-identity": "^0.3.0",
-    "@vantageos/mcp-auth-kit": "^0.1.0",
-    "@vantageos/mcp-protocol-kit": "^0.2.0",
+    "@modelcontextprotocol/ext-apps": "^2.0.3",
+    "@modelcontextprotocol/server": "^2.3.1",
+    "@vantageos/cloud-identity": "^0.15.0",
     "@vantageos/mosaic-i18n": "^0.1.1",
     "hono": "^4.6.0",
     "jose": "^6.2.7",
-    "zod": "^3.23.8"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
+    "@modelcontextprotocol/client": "^2.3.1",
     "@types/node": "^20.14.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/plugin.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "vantage-mcp-boilerplate",
+  "version": "0.2.1",
+  "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"
+  },
+  "homepage": "https://github.com/elpiarthera/vantage-mcp-boilerplate#readme",
+  "repository": "https://github.com/elpiarthera/vantage-mcp-boilerplate",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "chatgpt",
+    "boilerplate",
+    "starter",
+    "template",
+    "stdio",
+    "streamable-http",
+    "oauth",
+    "multi-tenant",
+    "mcp-apps",
+    "i18n",
+    "vantage",
+    "elpi"
+  ],
+  "extensions": {
+    "com.openai": {
+      "onboardingSkill": "./skills/connect-mcp-server/SKILL.md",
+      "interface": {
+        "displayName": "VantageOS MCP Boilerplate",
+        "shortDescription": "Clonable MCP server template with OAuth 2.1, MCP Apps UI and FR/EN i18n.",
+        "longDescription": "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.",
+        "developerName": "ElPi Corp / Laurent Perello",
+        "websiteURL": "https://github.com/elpiarthera/vantage-mcp-boilerplate#readme",
+        "capabilities": [
+          "Read"
+        ]
+      }
+    }
+  }
+}