@vantageos/mcp-boilerplate 0.1.1 → 0.2.0

package/dist/httpApp.d.ts

@@ -1,47 +1,40 @@
 /**
- * Hono HTTP app: stateless MCP transport for the boilerplate skeleton.
+ * Hono HTTP app: the MCP endpoint plus, on the OAuth tier, this server's own authorization
+ * server (ruling R1).
  *
- * 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.
+ * The MCP wire protocol is served by the SDK v2 `createMcpHandler` — ONE handler serves both
+ * protocol eras on `/mcp`: a 2026-07-28 client opens with `server/discover`, a 2025-era client
+ * with `initialize` (served through the SDK's stateless legacy leg). 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.
+ * True statelessness: a FRESH `McpServer` is built for every request by the handler's factory
+ * and never retained, so the endpoint is horizontally load-balanceable.
  *
  * 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.
+ *  - `authMode: "oauth"` with `authorizationServer` — the default: this app is BOTH the OAuth
+ *    2.1 authorization server (src/oauth/, every decision delegated to @vantageos/cloud-identity)
+ *    and the resource server (@vantageos/cloud-identity resource-server). Every /mcp call needs a valid Bearer
+ *    JWT bound to `<base>/mcp` (RFC 8707) and to this issuer. Missing configuration answers
+ *    503 (fail-closed), never an open endpoint.
+ *  - `authMode: "oauth"` with `auth` — resource server only, for a deployment that keeps an
+ *    EXTERNAL issuer (config.ts `loadAuthConfig`).
+ *  - `authMode: "public"` — no gate at all, for local/self-host use where the caller is already
+ *    trusted (mirrors stdio's trust model). The DEFAULT when `buildHttpApp()` gets no deps.
  */
 import { Hono } from "hono";
 import { type AuthConfig } from "./auth.js";
 import type { AuthMode } from "./config.js";
+import { type AuthorizationServerDeps } from "./oauth/authorizationServer.js";
 import { type ResolvedTenant } from "./tenancy.js";
 export interface AppDeps {
     authMode?: AuthMode;
+    /** External-issuer resource-server configuration (no authorization server mounted). */
     auth?: AuthConfig;
+    /** Own authorization server (R1). Takes precedence over `auth`. */
+    authorizationServer?: AuthorizationServerDeps;
+    /** Dedicated sandbox origin for the MCP Apps widget (`_meta.ui.domain`). */
+    uiDomain?: string;
 }
 type Variables = {
     tenant?: ResolvedTenant;

package/dist/httpApp.js

@@ -1,113 +1,112 @@
 /**
- * Hono HTTP app: stateless MCP transport for the boilerplate skeleton.
+ * Hono HTTP app: the MCP endpoint plus, on the OAuth tier, this server's own authorization
+ * server (ruling R1).
  *
- * 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.
+ * The MCP wire protocol is served by the SDK v2 `createMcpHandler` — ONE handler serves both
+ * protocol eras on `/mcp`: a 2026-07-28 client opens with `server/discover`, a 2025-era client
+ * with `initialize` (served through the SDK's stateless legacy leg). 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.
+ * True statelessness: a FRESH `McpServer` is built for every request by the handler's factory
+ * and never retained, so the endpoint is horizontally load-balanceable.
  *
  * 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.
+ *  - `authMode: "oauth"` with `authorizationServer` — the default: this app is BOTH the OAuth
+ *    2.1 authorization server (src/oauth/, every decision delegated to @vantageos/cloud-identity)
+ *    and the resource server (@vantageos/cloud-identity resource-server). Every /mcp call needs a valid Bearer
+ *    JWT bound to `<base>/mcp` (RFC 8707) and to this issuer. Missing configuration answers
+ *    503 (fail-closed), never an open endpoint.
+ *  - `authMode: "oauth"` with `auth` — resource server only, for a deployment that keeps an
+ *    EXTERNAL issuer (config.ts `loadAuthConfig`).
+ *  - `authMode: "public"` — no gate at all, for local/self-host use where the caller is already
+ *    trusted (mirrors stdio's trust model). The DEFAULT when `buildHttpApp()` gets no deps.
  */
-import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { createMcpHandler } from "@modelcontextprotocol/server";
 import { Hono } from "hono";
 import { authenticateRequest, protectedResourceMetadataDocument } from "./auth.js";
 import { detectLocale, t } from "./i18n.js";
 import { createBoilerplateMcpServer } from "./mcpServerFactory.js";
+import { createAuthorizationServer, } from "./oauth/authorizationServer.js";
 import { resolveTenantFromJwtPayload } from "./tenancy.js";
-const WELL_KNOWN_PATHS = ["/.well-known/oauth-protected-resource", "/health"];
+const PRM_PATHS = [
+    "/.well-known/oauth-protected-resource",
+    "/.well-known/oauth-protected-resource/mcp",
+];
 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.");
+        // Resolves the resource-server configuration per request: the own-AS tier reads its
+        // environment lazily, so a missing value is a 503 on the request, not a crash at boot.
+        let resolve;
+        if (deps.authorizationServer) {
+            const as = createAuthorizationServer(deps.authorizationServer);
+            as.mount(app);
+            resolve = () => as.resourceServer();
         }
-        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;
+        else if (deps.auth) {
+            const auth = deps.auth;
+            resolve = async () => ({ ok: true, auth });
+        }
+        else {
+            throw new Error("authMode 'oauth' requires an AuthConfig (deps.auth, external issuer) or an " +
+                "authorizationServer (own issuer, the default) — see config.ts and src/http.ts, or pass " +
+                "authMode: 'public' for the no-auth tier.");
+        }
+        for (const path of PRM_PATHS) {
+            app.get(path, async (c) => {
+                const rs = await resolve();
+                if (!rs.ok)
+                    return c.json({ error: "temporarily_unavailable" }, 503);
+                return c.json(protectedResourceMetadataDocument(rs.auth));
+            });
+        }
+        // OAuth 2.1 resource-server gate — /mcp requires a valid Bearer JWT, verified entirely by
+        // @vantageos/cloud-identity (`verifyMcpAccessToken`).
+        app.use("/mcp", async (c, next) => {
+            const rs = await resolve();
+            if (!rs.ok) {
+                console.error(`[oauth] /mcp refused: missing configuration ${rs.missing.join(", ")}`);
+                return c.json({ error: "temporarily_unavailable" }, 503);
             }
-            const authHeader = c.req.header("Authorization");
-            const result = await authenticateRequest(authHeader, auth);
+            const result = await authenticateRequest(c.req.header("Authorization"), rs.auth);
             if (!result.ok) {
+                if (result.status === 503) {
+                    // Key set unreachable: an outage, never a bad credential — no challenge, no 401.
+                    console.error("[oauth] /mcp refused: signing keys unavailable");
+                    return c.json({ error: "temporarily_unavailable" }, 503);
+                }
                 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.
+            // 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 with no organization on their token. Tenant-scoped tools enforce
+            // the requirement themselves, at the tool-call level (see mcpServerFactory.ts) — a
+            // missing tenant there is refused as an MCP tool error, never treated as unscoped.
             try {
-                c.set("tenant", resolveTenantFromJwtPayload(result.payload));
+                c.set("tenant", resolveTenantFromJwtPayload(result.session.claims));
             }
             catch {
-                // No organization on this token — tenant stays unset. Tenant-scoped
-                // tools refuse explicitly when they see no tenant under oauth mode.
+                // No organization on this token — tenant stays unset.
             }
             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) => {
+    // The one real MCP endpoint, both protocol eras (see header comment).
+    app.all("/mcp", (c) => {
         const tenant = authMode === "oauth" ? c.get("tenant") : undefined;
         const locale = detectLocale(c.req.header("X-MCP-Locale"));
-        const server = createBoilerplateMcpServer({
+        const handler = createMcpHandler(() => 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();
-        }
+            uiDomain: deps.uiDomain,
+        }));
+        return handler.fetch(c.req.raw);
     });
     return app;
 }

package/dist/i18n.d.ts

@@ -24,6 +24,12 @@ export type McpLocale = "en" | "fr";
  * Defaults to "en" for a missing header or any value other than "fr".
  */
 export declare function detectLocale(headerValue: string | null | undefined): McpLocale;
+/**
+ * Resolves the locale of a browser navigation (the OAuth picker page) from `Accept-Language`,
+ * where no `X-MCP-Locale` header exists. The first listed language decides; "fr" selects
+ * French, anything else English.
+ */
+export declare function detectLocaleFromAcceptLanguage(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"`.

package/dist/i18n.js

@@ -43,6 +43,15 @@ const RESOURCES = {
 export function detectLocale(headerValue) {
     return headerValue?.toLowerCase() === "fr" ? "fr" : "en";
 }
+/**
+ * Resolves the locale of a browser navigation (the OAuth picker page) from `Accept-Language`,
+ * where no `X-MCP-Locale` header exists. The first listed language decides; "fr" selects
+ * French, anything else English.
+ */
+export function detectLocaleFromAcceptLanguage(headerValue) {
+    const first = headerValue?.split(",")[0]?.trim().toLowerCase() ?? "";
+    return first === "fr" || first.startsWith("fr-") || first.startsWith("fr;") ? "fr" : "en";
+}
 /**
  * Looks up a translated MCP message. `key` is a dot path under the `Mcp`
  * namespace, e.g. `"auth.unauthorized"` or `"tenant.permissionDenied"`.

package/dist/locales/en.json

@@ -8,6 +8,15 @@
     },
     "validation": {
       "messageTooLong": "message exceeds the maximum length of 200 characters"
+    },
+    "oauth": {
+      "pickerTitle": "Connect {client}",
+      "pickerIntro": "{client} asks to act on your behalf. Choose the organisation it may reach, then approve or deny.",
+      "pickerOrganisation": "Organisation",
+      "approve": "Approve",
+      "deny": "Deny",
+      "denied": "The request was denied; you can close this window.",
+      "unavailable": "Authorization is not configured on this server."
     }
   }
 }

package/dist/locales/fr.json

@@ -8,6 +8,15 @@
     },
     "validation": {
       "messageTooLong": "le message dépasse la longueur maximale de 200 caractères"
+    },
+    "oauth": {
+      "pickerTitle": "Connecter {client}",
+      "pickerIntro": "{client} demande à agir en votre nom. Choisissez l'organisation à laquelle il peut accéder, puis approuvez ou refusez.",
+      "pickerOrganisation": "Organisation",
+      "approve": "Approuver",
+      "deny": "Refuser",
+      "denied": "La demande a été refusée ; vous pouvez fermer cette fenêtre.",
+      "unavailable": "L'autorisation n'est pas configurée sur ce serveur."
     }
   }
 }

package/dist/mcpServerFactory.d.ts

@@ -1,60 +1,61 @@
 /**
- * Single MCP server definition shared by both transports (stdio and HTTP).
- * The example tool is registered here, once, on the SDK's `McpServer` —
- * never on ad-hoc REST routes. Each call to `createBoilerplateMcpServer`
- * builds a fresh server instance with no shared mutable state; the HTTP
- * transport creates one per request (see httpApp.ts), which is what makes
- * the Streamable HTTP stateless mode genuinely load-balanceable: nothing
- * survives past the single request/response cycle.
+ * Single MCP server definition shared by both transports. It is registered once, on the SDK
+ * v2 `McpServer`, and served by `createMcpHandler` (HTTP, src/httpApp.ts) and `serveStdio`
+ * (src/stdio.ts) — each owns the protocol-era decision, so ONE factory serves a 2026-07-28
+ * client (opens with `server/discover`) and a 2025-era client (opens with `initialize`).
+ * Each call builds a fresh instance with no shared mutable state; the HTTP transport builds
+ * one per request, which is what keeps the endpoint load-balanceable.
  *
- * This is a SKELETON: `ping` is the only tool, kept trivial on purpose to
- * prove the MCP handshake on both transports. Later layers replace or
- * extend it (auth-gated tools, tenant-scoped tools, ...).
+ * Wire posture:
+ *  - the 2025-era floor is 2025-06-18: `supportedProtocolVersions` lists only 2025-11-25 and
+ *    2025-06-18 (the SDK option on `ProtocolOptions`); older revisions are never counter-offered;
+ *  - `ttlMs` / `cacheScope` on 2026-07-28 results come from the SDK's `cacheHints` — no
+ *    handler override, no private-field access, no hand-written discover schema;
+ *  - the advertised version is `SERVER_VERSION`, derived from package.json.
  *
- * Protocol-kit wiring (`@vantageos/mcp-protocol-kit` 0.2.0+): `tools/list`
- * is re-shaped through `buildToolsListResult` so every response carries
- * `resultType: "complete"` + a CacheableResult (`ttlMs`/`cacheScope`) on top
- * of the `tools` key the official SDK's `ListToolsResultSchema` requires. The
- * kit emits that key directly now — no hand alias.
+ * Tool records (mcp-standard C-4, C-15): every tool declares `title`, the four behavioural
+ * annotations as explicit booleans, a typed input schema AND a typed output schema (Zod 4),
+ * and returns `structuredContent` plus a text block carrying the same JSON.
+ * tests/toolRecordComplete.test.ts walks `tools/list` and fails on any gap.
  *
- * IMPORTANT — tools/call posture: `ping`'s tool-call result is NOT run
- * through the cache builders. The official `CallToolResultSchema` is the
- * fixed `{ content, isError? }` shape with no room for extra top-level fields
- * without breaking client-side schema validation, so `resultType`/
- * `CacheableResult` never apply to a tool-call result. The kit's
- * `buildToolCallResult` (0.2.0+) is the conformant builder for that case; the
- * inline `toolResult` helper here predates it and stays for the skeleton's
- * trivial `{ content }` returns.
- *
- * `list_items` is the multi-tenant example tool (tenancy.ts): when a
- * resolved tenant is supplied (OAuth tier — see httpApp.ts), results are
- * scoped via `scopeRowsForTenant` (@vantageos/cloud-identity, reused
- * unmodified); when no tenant is supplied (public tier — no auth gate at
- * all, mirrors stdio's trust model), results are returned unscoped.
+ * `list_items` is the multi-tenant example (tenancy.ts): with a resolved tenant, rows are
+ * filtered by stored `orgId` (cloud-identity `isRowInTenant`); on the public tier there is no
+ * tenant gate at all, by design (it mirrors stdio's local-trust model).
  */
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 import { type McpLocale } from "./i18n.js";
 import { type ResolvedTenant } from "./tenancy.js";
+/** Oldest 2025-era protocol revision served; the legacy `initialize` handshake never offers older. */
+export declare const SUPPORTED_LEGACY_PROTOCOL_VERSIONS: string[];
+/** The four behavioural annotations, explicit on every tool (all three tools are pure reads). */
+export declare const TOOL_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+};
 export interface McpServerDeps {
     /**
-     * The caller's resolved tenant (tenancy.ts), when the OAuth tier verified
-     * a JWT carrying an organization. Undefined on the public tier (no gate)
-     * or when the verified token itself carries no organization.
+     * The caller's resolved tenant (tenancy.ts), when the OAuth tier verified a JWT carrying an
+     * organization. Undefined on the public tier (no gate) or when the verified token itself
+     * carries no organization.
      */
     tenant?: ResolvedTenant;
     /**
-     * True when this deployment's tenant-scoped tools MUST see a resolved
-     * tenant (the OAuth tier). A verified-but-org-less caller then gets an
-     * explicit MCP tool-call refusal from `list_items` rather than silently
-     * falling through to an unscoped/master view. False on the public tier,
-     * where there is no tenant gate at all by design.
+     * True when this deployment's tenant-scoped tools MUST see a resolved tenant (the OAuth
+     * tier). A verified-but-org-less caller then gets an explicit MCP tool-call refusal from
+     * `list_items` rather than silently falling through to an unscoped/master view.
      */
     requireTenant?: boolean;
     /**
-     * The caller's locale, resolved from the `X-MCP-Locale` request header
-     * (see i18n.ts + httpApp.ts). Defaults to "en" when not supplied — the
-     * stdio transport (no HTTP headers) always uses the default.
+     * The caller's locale, resolved from the `X-MCP-Locale` request header (see i18n.ts +
+     * httpApp.ts). Defaults to "en"; the stdio transport (no HTTP headers) uses the default.
      */
     locale?: McpLocale;
+    /**
+     * Dedicated sandbox origin for the MCP Apps widget (`_meta.ui.domain`). Host-dependent; set
+     * only when the deployment has one (MCP_UI_DOMAIN). Omitted from the resource when unset.
+     */
+    uiDomain?: string;
 }
 export declare function createBoilerplateMcpServer(deps?: McpServerDeps): McpServer;