@vantageos/mcp-boilerplate 0.1.2 → 0.2.1

package/dist/mcpServerFactory.js

@@ -1,199 +1,148 @@
 /**
- * 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 { registerAppResource, registerAppTool } from "@modelcontextprotocol/ext-apps/server";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ListToolsRequestSchema, RequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { buildToolsListResult, handleServerDiscover } from "@vantageos/mcp-protocol-kit";
+import { registerAppResource } from "@modelcontextprotocol/ext-apps/server";
+import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
-// The SDK's own request schemas (RequestSchema, ListToolsRequestSchema, ...)
-// are built with the zod/v4 API. Extending RequestSchema for the custom
-// server/discover method must use the same zod build, or `.extend()`
-// fails with "expected a Zod schema" (v3/v4 schema objects are not
-// interchangeable). Tool input shapes below keep using the default `zod`
-// (v3) import, which is what `registerTool`'s public API expects.
-import { z as zv4 } from "zod/v4";
 import { EXAMPLE_ITEMS } from "./exampleItems.js";
 import { t } from "./i18n.js";
 import { scopeRowsForTenant } from "./tenancy.js";
-import { ITEMS_UI_META, ITEMS_UI_RESOURCE_URI, buildRenderItemsUiResult, buildUiResource, } from "./ui/uiResource.js";
-const pingInputShape = {
-    message: z.string().optional().describe("Optional message echoed back verbatim"),
-};
-// Zod shape of the single `ping` tool, kept alongside the SDK registration
-// so `tools/list` can re-describe it through the kit's `buildListResult`
-// without reaching into the SDK's private registered-tools map.
-const PING_TOOL_DESCRIPTOR = {
-    name: "ping",
-    description: "Echoes the given message (or 'pong' if none given). Proves the MCP handshake end to end.",
-    inputSchema: {
-        type: "object",
-        properties: { message: { type: "string" } },
-    },
-};
-const listItemsInputShape = {};
-const LIST_ITEMS_TOOL_DESCRIPTOR = {
-    name: "list_items",
-    description: "Lists example items. On the OAuth tier, results are scoped to the caller's tenant " +
-        "(@vantageos/cloud-identity); on the public tier (no auth gate), results are unscoped.",
-    inputSchema: { type: "object", properties: {} },
+import { ITEMS_TOOL_META, ITEMS_UI_RESOURCE_URI, buildItemsUiResourceMeta, buildRenderItemsUiResult, buildUiResource, } from "./ui/uiResource.js";
+import { SERVER_NAME, SERVER_VERSION } from "./version.js";
+/** Oldest 2025-era protocol revision served; the legacy `initialize` handshake never offers older. */
+export const SUPPORTED_LEGACY_PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18"];
+/** The four behavioural annotations, explicit on every tool (all three tools are pure reads). */
+export const TOOL_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
 };
-// server/discover is not yet part of the installed SDK's request-schema
-// union (protocol 2026-07-28 is ahead of the SDK's negotiated versions —
-// see docs/architecture.md "Wire posture"), so its request shape is
-// declared locally and registered via the low-level `Server` instance.
-const ServerDiscoverRequestSchema = RequestSchema.extend({
-    method: zv4.literal("server/discover"),
+const itemSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    orgId: z.string(),
+    createdBy: z.string(),
+    namespace: z.string(),
 });
-function toolResult(payload) {
+const localeSchema = z.enum(["en", "fr"]);
+const pingInput = z.object({
+    message: z.string().optional().describe("Optional message echoed back verbatim"),
+});
+const pingOutput = z.object({ reply: z.string() });
+const listItemsInput = z.object({});
+const listItemsOutput = z.object({ items: z.array(itemSchema) });
+const renderInput = z.object({
+    locale: localeSchema
+        .optional()
+        .describe("Widget language; defaults to the caller's X-MCP-Locale"),
+});
+const renderOutput = z.object({ items: z.array(itemSchema), locale: localeSchema });
+/** A text block carrying the same JSON as `structuredContent`. */
+function structuredResult(payload) {
     return {
         content: [{ type: "text", text: JSON.stringify(payload) }],
+        structuredContent: payload,
     };
 }
+function refusal(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
 export function createBoilerplateMcpServer(deps = {}) {
     const locale = deps.locale ?? "en";
-    const server = new McpServer({ name: "mcp-boilerplate", version: "0.1.0" }, { capabilities: { tools: {} } });
-    server.registerTool(PING_TOOL_DESCRIPTOR.name, {
-        description: PING_TOOL_DESCRIPTOR.description,
-        inputSchema: pingInputShape,
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        capabilities: { tools: {}, resources: {} },
+        instructions: "Clonable MCP server boilerplate — see README.md",
+        supportedProtocolVersions: SUPPORTED_LEGACY_PROTOCOL_VERSIONS,
+        cacheHints: {
+            "tools/list": { ttlMs: 60_000, cacheScope: "public" },
+            "resources/list": { ttlMs: 60_000, cacheScope: "public" },
+            "resources/read": { ttlMs: 60_000, cacheScope: "public" },
+            "server/discover": { ttlMs: 300_000, cacheScope: "public" },
+        },
+    });
+    server.registerTool("ping", {
+        title: "Ping",
+        description: "Echoes the given message (or 'pong' if none given). Proves the MCP handshake end to end.",
+        inputSchema: pingInput,
+        outputSchema: pingOutput,
+        annotations: TOOL_ANNOTATIONS,
     }, async (args) => {
-        // Application-level input validation (beyond the Zod type shape):
-        // an overly long echo message is refused as an MCP tool-call error,
-        // localized per the caller's X-MCP-Locale.
+        // Application-level input validation beyond the Zod shape: an overly long echo message
+        // is refused as an MCP tool-call error, localized per the caller's X-MCP-Locale.
         if (args.message !== undefined && args.message.length > 200) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: t(locale, "validation.messageTooLong"),
-                    },
-                ],
-                isError: true,
-            };
+            return refusal(t(locale, "validation.messageTooLong"));
         }
-        return toolResult({ reply: args.message ?? "pong" });
+        return structuredResult({ reply: args.message ?? "pong" });
     });
-    server.registerTool(LIST_ITEMS_TOOL_DESCRIPTOR.name, {
-        description: LIST_ITEMS_TOOL_DESCRIPTOR.description,
-        inputSchema: listItemsInputShape,
+    const scopedItems = () => deps.tenant ? scopeRowsForTenant(deps.tenant.tenantId, EXAMPLE_ITEMS) : EXAMPLE_ITEMS;
+    server.registerTool("list_items", {
+        title: "List items",
+        description: "Lists example items. On the OAuth tier, results are scoped to the caller's organisation " +
+            "(@vantageos/cloud-identity); on the public tier (no auth gate), results are unscoped.",
+        inputSchema: listItemsInput,
+        outputSchema: listItemsOutput,
+        annotations: TOOL_ANNOTATIONS,
     }, async () => {
         if (deps.requireTenant && !deps.tenant) {
-            // Refuse explicitly — never fall through to an unscoped/master view
-            // just because the caller's token had no organization.
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: t(locale, "tenant.permissionDenied"),
-                    },
-                ],
-                isError: true,
-            };
+            // Refuse explicitly — never fall through to an unscoped/master view just because the
+            // caller's token had no organization.
+            return refusal(t(locale, "tenant.permissionDenied"));
         }
-        const items = deps.tenant
-            ? scopeRowsForTenant(deps.tenant.tenantId, EXAMPLE_ITEMS)
-            : EXAMPLE_ITEMS;
-        return toolResult({ items });
+        return structuredResult({ items: scopedItems() });
     });
-    // MCP Apps UI layer (io.modelcontextprotocol/ui, GA 2026-01-26): renders
-    // EXAMPLE_ITEMS as an interactive widget. `registerAppResource` +
-    // `registerAppTool` (official `@modelcontextprotocol/ext-apps/server`)
-    // write the GA nested `_meta.ui.resourceUri` form — never the deprecated
-    // flat `_meta["ui/resourceUri"]` key. The markdown fallback in
-    // `content[0]` is mandatory and always present, even for clients that
-    // never negotiate the extension (mcp-app-standard.md Critical Rule #1).
-    registerAppResource(server, "Items widget", ITEMS_UI_RESOURCE_URI, { description: "Interactive items list", mimeType: "text/html;profile=mcp-app" }, async () => ({
-        contents: [buildUiResource({ items: EXAMPLE_ITEMS, locale: "en" })],
+    // MCP Apps UI layer (io.modelcontextprotocol/ui, spec 2026-01-26). The tool is registered
+    // with `server.registerTool` and the GA nested `_meta.ui` form, NOT with ext-apps'
+    // `registerAppTool`: that helper back-fills the deprecated flat `_meta["ui/resourceUri"]`
+    // key, which mcp-app-standard A-6 forbids writing (tests/mcpAppsMeta.test.ts asserts its
+    // absence). The markdown fallback in the call result is mandatory even for clients that never
+    // negotiate the extension (A-1).
+    const resourceUiMeta = buildItemsUiResourceMeta(deps.uiDomain);
+    registerAppResource(server, "Items widget", ITEMS_UI_RESOURCE_URI, {
+        title: "Items widget",
+        description: "Interactive items list",
+        mimeType: "text/html;profile=mcp-app",
+        _meta: { ui: resourceUiMeta },
+    }, async () => ({
+        contents: [buildUiResource({ items: scopedItems(), locale, domain: deps.uiDomain })],
     }));
-    registerAppTool(server, "render_items_ui", {
+    server.registerTool("render_items_ui", {
+        title: "Render items",
         description: "Render the example items as an interactive widget. Use this whenever the user asks for a visual/rendered view of the items.",
-        inputSchema: {
-            locale: z.enum(["en", "fr"]).default("en"),
-        },
-        // `description_fr` (mcp-standard.md convention) lives alongside
-        // `ui` in `_meta` — `McpUiAppToolConfig._meta` carries an index
-        // signature for exactly this kind of ElPi Corp addition.
+        inputSchema: renderInput,
+        outputSchema: renderOutput,
+        annotations: TOOL_ANNOTATIONS,
+        // `description_fr` (mcp-standard.md convention) lives alongside `ui` in `_meta`.
         _meta: {
-            ui: ITEMS_UI_META,
+            ...ITEMS_TOOL_META,
             description_fr: "Affiche les éléments d'exemple sous forme de widget interactif. Utilise cet outil quand l'utilisateur demande une vue visuelle des éléments.",
         },
     }, async (args) => {
-        const items = deps.tenant
-            ? scopeRowsForTenant(deps.tenant.tenantId, EXAMPLE_ITEMS)
-            : EXAMPLE_ITEMS;
-        return buildRenderItemsUiResult(items, args.locale);
-    });
-    // Re-shape tools/list through the kit: resultType + CacheableResult on
-    // top of the standard `tools` array every MCP client expects. The kit's
-    // `buildToolsListResult` (0.2.0+) emits the `tools` key the official
-    // `ListToolsResultSchema` requires directly — no hand alias needed.
-    //
-    // DERIVATION (not a hand-typed descriptor list): the SDK's own McpServer
-    // already builds the `tools/list` response from its single source of
-    // truth — `this._registeredTools`, populated by every `registerTool`/
-    // `registerAppTool` call above — and installs that handler on
-    // `server.server` (the low-level `Server`) via `setToolRequestHandlers()`
-    // BEFORE this function runs. Re-invoking that already-installed handler,
-    // then re-shaping its `tools` array through the kit, means a 4th
-    // registered tool appears here automatically — nothing here enumerates
-    // tool names by hand, so a tool can never again be silently missing from
-    // discovery just because this list forgot to mention it.
-    const baseListToolsHandler = server.server._requestHandlers.get("tools/list");
-    if (!baseListToolsHandler) {
-        throw new Error("tools/list handler not found on the SDK's Server — McpServer.registerTool() " +
-            "installs it lazily on first registration; this indicates no tool was ever " +
-            "registered, which is a boilerplate wiring bug, not a runtime condition to " +
-            "silently work around.");
-    }
-    server.server.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
-        const { tools } = await baseListToolsHandler(request, extra);
-        return buildToolsListResult(tools, {
-            ttlMs: 60_000,
-            cacheScope: "public",
-        });
-    });
-    // server/discover via the kit's handleServerDiscover — DiscoverResult
-    // extends CacheableResult, so resultType/ttlMs/cacheScope are always set
-    // alongside supportedVersions/capabilities.
-    server.server.setRequestHandler(ServerDiscoverRequestSchema, async () => {
-        return handleServerDiscover({
-            supportedVersions: ["2026-07-28", "2025-11-25"],
-            capabilities: { tools: {} },
-            ttlMs: 300_000,
-            cacheScope: "public",
-            instructions: "Clonable MCP server boilerplate — see README.md",
-        });
+        if (deps.requireTenant && !deps.tenant) {
+            return refusal(t(locale, "tenant.permissionDenied"));
+        }
+        return buildRenderItemsUiResult(scopedItems(), args.locale ?? locale, deps.uiDomain);
     });
     return server;
 }

package/dist/oauth/authorizationServer.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Own OAuth 2.1 authorization server (ruling R1). A code is issued ONLY to a signed-in Clerk
+ * person who picked one of their own organisations and approved the request on the picker
+ * page (consent ON). Routes:
+ *
+ *   GET  /.well-known/oauth-authorization-server  (+ /.well-known/openid-configuration)
+ *   GET  /.well-known/jwks.json                   public signing keys
+ *   POST /register                                Dynamic Client Registration (public clients)
+ *   GET  /authorize                               start; CIMD or DCR client_id
+ *   GET  /authorize/callback                      return from Clerk sign-in
+ *   POST /authorize/org                           person + organisation picker submit
+ *   POST /token                                   authorization_code + PKCE S256
+ *   GET  /userinfo
+ *
+ * EVERY decision lives in @vantageos/cloud-identity (startAuthorize, resumeAuthorize,
+ * exchangeAuthorizationCode, buildDiscoveryDocument, buildUserInfo, oauthErrorFor). This
+ * module owns only what the package takes as parameters: environment, stores, the client
+ * lookup, the Clerk calls, the picker page, and the RS256 signature of the access token.
+ *
+ * FAIL-CLOSED: any missing configuration value answers 503 `temporarily_unavailable`.
+ * No refresh tokens are issued; access tokens live one hour.
+ */
+import { type AuthorizationCodeStore } from "@vantageos/cloud-identity";
+import type { Hono } from "hono";
+import type { AuthConfig } from "../auth.js";
+import { type ClerkCollaborators } from "./clerk.js";
+import { type CimdOptions, type ClientRegistry } from "./clientRegistry.js";
+export interface AuthorizationServerDeps {
+    /** Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Defaults to an in-memory store (single process only; see docs/oauth-stores.md). */
+    codeStore?: AuthorizationCodeStore;
+    /** Defaults to an in-memory registry (single process only; see docs/oauth-stores.md). */
+    clientRegistry?: ClientRegistry;
+    /** Defaults to Clerk's Backend REST API with CLERK_SECRET_KEY. */
+    clerk?: Partial<ClerkCollaborators>;
+    /** CIMD fetch + DNS seam. */
+    fetchImpl?: typeof fetch;
+    resolveHost?: CimdOptions["resolveHost"];
+    now?: () => number;
+}
+export type ResourceServerConfig = {
+    ok: true;
+    auth: AuthConfig;
+} | {
+    ok: false;
+    missing: string[];
+};
+type AnyHono = Hono<any>;
+export interface AuthorizationServer {
+    mount(app: AnyHono): void;
+    /** The resource-server (`/mcp` gate) configuration derived from the same settings. */
+    resourceServer(): Promise<ResourceServerConfig>;
+}
+export declare function createAuthorizationServer(deps?: AuthorizationServerDeps): AuthorizationServer;
+export {};