@vantageos/mcp-boilerplate 0.1.1 → 0.2.0

package/dist/oauth/clientRegistry.js

@@ -0,0 +1,203 @@
+/**
+ * OAuth client registry: how `/authorize` and `/token` learn who a `client_id` is.
+ *
+ * Two sources, tried by the SHAPE of the client_id:
+ *  - a URL-shaped client_id is a Client ID Metadata Document (CIMD): fetched over https,
+ *    SSRF-guarded (public addresses only, no redirects, size and time capped), and accepted
+ *    only when the document names exactly that URL;
+ *  - anything else is a Dynamic Client Registration (DCR) id looked up in the registry.
+ *
+ * Only PUBLIC clients (PKCE, no client secret) exist here: MCP clients are public clients,
+ * so the server issues and stores no client secret at all.
+ */
+import { lookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+export function createInMemoryClientRegistry(maxClients = 10_000) {
+    const clients = new Map();
+    return {
+        async get(clientId) {
+            return clients.get(clientId) ?? null;
+        },
+        async register(client) {
+            if (clients.size >= maxClients) {
+                throw new Error("client registry is full");
+            }
+            clients.set(client.clientId, client);
+        },
+    };
+}
+/** True for an https URL, or an http URL on a loopback host (native-app redirects). */
+export function isAllowedRedirectUri(raw) {
+    if (typeof raw !== "string")
+        return false;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (url.hash)
+        return false;
+    if (url.protocol === "https:")
+        return true;
+    return (url.protocol === "http:" &&
+        (url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]"));
+}
+// ---------------------------------------------------------------------------
+// SSRF guard for the CIMD fetch
+// ---------------------------------------------------------------------------
+/**
+ * Non-public ranges: the union required by mcp-server-standard.md S-10 (cloud metadata,
+ * 127/8, 0/8, ::1, RFC 1918, link-local, unique-local, multicast) plus the extra ranges this
+ * guard has always refused (CGNAT, IETF protocol block, benchmarking, reserved >= 240).
+ * Address parsing and range matching belong to `node:net` BlockList: this module writes no
+ * address parser and compares the PARSER'S view of the address, never the raw string.
+ */
+const BLOCKED_V4 = [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10], // CGNAT
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16], // link-local, includes 169.254.169.254 cloud metadata
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["224.0.0.0", 4], // multicast
+    ["240.0.0.0", 4], // reserved, includes the broadcast address
+];
+const BLOCKED_V6 = [
+    ["::", 96], // unspecified, loopback and every IPv4-compatible address (::a.b.c.d)
+    ["fc00::", 7], // unique local
+    ["fe80::", 10], // link-local
+    ["ff00::", 8], // multicast
+    ["64:ff9b:1::", 48], // local-use NAT64 (RFC 8215)
+];
+/** The v4 prefix `addr/len` written as a prefix under an IPv6 embedding of 96 leading bits. */
+function embedV4(v4, len, prefix6) {
+    const [a, b, c, d] = v4.split(".").map(Number);
+    const hi = ((a << 8) | b).toString(16);
+    const lo = ((c << 8) | d).toString(16);
+    return [`${prefix6}${hi}:${lo}`, 96 + len];
+}
+const blockList = new BlockList();
+for (const [addr, len] of BLOCKED_V4) {
+    blockList.addSubnet(addr, len, "ipv4");
+    // IPv4-mapped (::ffff:a.b.c.d, any textual form) and NAT64 (64:ff9b::a.b.c.d): the embedded
+    // v4 address is held to the same list.
+    for (const prefix6 of ["::ffff:", "64:ff9b::"]) {
+        const [sub, bits] = embedV4(addr, len, prefix6);
+        blockList.addSubnet(sub, bits, "ipv6");
+    }
+}
+for (const [addr, len] of BLOCKED_V6)
+    blockList.addSubnet(addr, len, "ipv6");
+/** True only for a globally routable address. Fail-closed: anything unrecognised is refused. */
+export function isPublicAddress(ip) {
+    if (typeof ip !== "string" || ip.includes("%"))
+        return false; // zone ids are never public
+    const version = isIP(ip);
+    if (version !== 4 && version !== 6)
+        return false;
+    try {
+        return !blockList.check(ip, version === 4 ? "ipv4" : "ipv6");
+    }
+    catch {
+        return false;
+    }
+}
+export async function defaultResolveHost(host) {
+    const records = await lookup(host, { all: true });
+    return records.map((r) => r.address);
+}
+/**
+ * Reads a response body as UTF-8 text, buffering at most `maxBytes`. The stream is cancelled
+ * the moment the cap is crossed, so an oversized body is never held in memory. Null = too big
+ * (or no body).
+ */
+async function readCappedText(res, maxBytes) {
+    if (!res.body)
+        return null;
+    const reader = res.body.getReader();
+    const chunks = [];
+    let received = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        received += value.byteLength;
+        if (received > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            return null;
+        }
+        chunks.push(value);
+    }
+    return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+}
+/** True when a client_id is URL-shaped, i.e. a CIMD identifier (valid or not). */
+export function isUrlShapedClientId(clientId) {
+    return /^https?:\/\//i.test(clientId);
+}
+/**
+ * Fetches and validates a Client ID Metadata Document. Returns null for ANY failure — an
+ * unreachable, oversized, malformed, private-addressed or self-contradicting document is an
+ * unknown client, never a partial one.
+ *
+ * Limitation (documented in docs/oauth-stores.md): the address check resolves the host and
+ * the fetch resolves it again, so a DNS-rebinding window exists. A hostile-network deployment
+ * injects a `fetchImpl` that pins the validated address (for example an undici dispatcher).
+ */
+export async function resolveCimdClient(clientId, options = {}) {
+    const { fetchImpl = fetch, resolveHost = defaultResolveHost } = options;
+    const maxBytes = options.maxBytes ?? 16 * 1024;
+    const timeoutMs = options.timeoutMs ?? 5000;
+    let url;
+    try {
+        url = new URL(clientId);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" || url.username || url.password || url.hash)
+        return null;
+    if (url.pathname === "/" || url.pathname === "")
+        return null; // the spec requires a path
+    if (url.href !== clientId)
+        return null; // client_id is compared as a string; no normalisation
+    try {
+        const host = url.hostname.replace(/^\[|\]$/g, "");
+        const addresses = isIP(host) ? [host] : await resolveHost(host);
+        if (addresses.length === 0 || !addresses.every(isPublicAddress))
+            return null;
+        const res = await fetchImpl(url, {
+            redirect: "error",
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        const text = await readCappedText(res, maxBytes);
+        if (text === null)
+            return null;
+        const doc = JSON.parse(text);
+        if (doc.client_id !== clientId)
+            return null;
+        const method = doc.token_endpoint_auth_method;
+        if (method !== undefined && method !== "none")
+            return null; // public clients only
+        const uris = doc.redirect_uris;
+        if (!Array.isArray(uris) || uris.length === 0 || uris.length > 20)
+            return null;
+        if (!uris.every(isAllowedRedirectUri))
+            return null;
+        return {
+            clientId,
+            redirectUris: uris,
+            ...(typeof doc.client_name === "string" ? { clientName: doc.client_name.slice(0, 200) } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/oauth/codeStore.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Authorization-code store: an INTERFACE (cloud-identity's `AuthorizationCodeStore`) with an
+ * in-memory adapter for tests and single-process development. The durable-adapter contract
+ * (atomic consume, TTL, digest-only storage) is documented in docs/oauth-stores.md.
+ *
+ * The in-memory adapter is NOT for a multi-instance deployment: codes live in one process,
+ * so a second instance cannot redeem a code issued by the first.
+ */
+import type { AuthorizationCodeRecord, AuthorizationCodeStore, ConsumeCodeResult } from "@vantageos/cloud-identity";
+export type { AuthorizationCodeRecord, AuthorizationCodeStore, ConsumeCodeResult };
+export declare function createInMemoryCodeStore(): AuthorizationCodeStore;

package/dist/oauth/codeStore.js

@@ -0,0 +1,28 @@
+/**
+ * Authorization-code store: an INTERFACE (cloud-identity's `AuthorizationCodeStore`) with an
+ * in-memory adapter for tests and single-process development. The durable-adapter contract
+ * (atomic consume, TTL, digest-only storage) is documented in docs/oauth-stores.md.
+ *
+ * The in-memory adapter is NOT for a multi-instance deployment: codes live in one process,
+ * so a second instance cannot redeem a code issued by the first.
+ */
+export function createInMemoryCodeStore() {
+    const live = new Map();
+    const used = new Set();
+    return {
+        async put(record) {
+            live.set(record.codeHash, record);
+        },
+        // Atomic by construction: this body has no await between the read and the delete, and
+        // JavaScript runs it to completion, so two concurrent consumes cannot both see "ok".
+        async consume(codeHash) {
+            const record = live.get(codeHash);
+            if (record) {
+                live.delete(codeHash);
+                used.add(codeHash);
+                return { status: "ok", record };
+            }
+            return used.has(codeHash) ? { status: "already-used" } : { status: "unknown" };
+        },
+    };
+}

package/dist/oauth/picker.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Server-rendered organisation picker and consent page (FR/EN by `Accept-Language`). It posts
+ * `state`, `orgId`, `approved` and the hidden `consentToken` to POST /authorize/org. The
+ * consentToken IS the CSRF protection of that POST: a cross-site form cannot know it, and
+ * cloud-identity's `resumeAuthorize` refuses `approved` without it. Do not drop it.
+ */
+import type { OrgPickerModel } from "@vantageos/cloud-identity";
+import { type McpLocale } from "../i18n.js";
+/** CSP for the picker page: no scripts, no external assets, one hashed inline style. */
+export declare function pickerContentSecurityPolicy(): Promise<string>;
+export declare function renderOrgPicker(model: OrgPickerModel, locale: McpLocale): string;

package/dist/oauth/picker.js

@@ -0,0 +1,67 @@
+/**
+ * Server-rendered organisation picker and consent page (FR/EN by `Accept-Language`). It posts
+ * `state`, `orgId`, `approved` and the hidden `consentToken` to POST /authorize/org. The
+ * consentToken IS the CSRF protection of that POST: a cross-site form cannot know it, and
+ * cloud-identity's `resumeAuthorize` refuses `approved` without it. Do not drop it.
+ */
+import { t } from "../i18n.js";
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+const PICKER_STYLE = "body{font-family:system-ui,sans-serif;max-width:32rem;margin:3rem auto;padding:0 1rem;line-height:1.5}" +
+    "fieldset{border:1px solid #888;padding:1rem}label{display:block;margin:.5rem 0}" +
+    "button{font:inherit;padding:.5rem 1rem;margin-right:.5rem}";
+/** CSP for the picker page: no scripts, no external assets, one hashed inline style. */
+export async function pickerContentSecurityPolicy() {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(PICKER_STYLE));
+    const hash = btoa(String.fromCharCode(...new Uint8Array(digest)));
+    return [
+        "default-src 'none'",
+        `style-src 'sha256-${hash}'`,
+        "base-uri 'none'",
+        "frame-ancestors 'none'",
+    ].join("; ");
+}
+export function renderOrgPicker(model, locale) {
+    const clientName = model.client.clientName ?? model.client.clientId;
+    const only = model.organizations.length === 1;
+    const orgs = model.organizations
+        .map((o, i) => `<label><input type="radio" name="orgId" value="${escapeHtml(o.id)}" required${only && i === 0 ? " checked" : ""}> ${escapeHtml(o.name)} <small>(${escapeHtml(o.role)})</small></label>`)
+        .join("\n");
+    const title = escapeHtml(t(locale, "oauth.pickerTitle").replace("{client}", clientName));
+    const intro = escapeHtml(t(locale, "oauth.pickerIntro").replaceAll("{client}", clientName));
+    return `<!doctype html>
+<html lang="${locale}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="no-referrer">
+<title>${title}</title>
+<style>${PICKER_STYLE}</style>
+</head>
+<body>
+<main>
+<h1>${title}</h1>
+<p>${intro}</p>
+<form method="post" action="/authorize/org">
+<input type="hidden" name="state" value="${escapeHtml(model.state)}">
+<input type="hidden" name="consentToken" value="${escapeHtml(model.consentToken ?? "")}">
+<fieldset>
+<legend>${escapeHtml(t(locale, "oauth.pickerOrganisation"))}</legend>
+${orgs}
+</fieldset>
+<p>
+<button type="submit" name="approved" value="true">${escapeHtml(t(locale, "oauth.approve"))}</button>
+<button type="submit" name="approved" value="false" formnovalidate>${escapeHtml(t(locale, "oauth.deny"))}</button>
+</p>
+</form>
+</main>
+</body>
+</html>
+`;
+}

package/dist/oauth/settings.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Environment-derived configuration of the authorization server. FAIL-CLOSED: when any
+ * required value is absent (or malformed) the result is `{ ok: false, missing }`, naming the
+ * variables — never their values — and every authorization route answers 503. There is no
+ * auto-approve path and no default secret.
+ */
+import { type JWK } from "jose";
+export declare const OAUTH_ENV: {
+    readonly publicBaseUrl: "PUBLIC_BASE_URL";
+    readonly stateSecret: "AUTHORIZE_STATE_SECRET";
+    readonly clerkIssuer: "CLERK_DOMAIN";
+    readonly signInUrl: "AUTHORIZE_SIGN_IN_URL";
+    readonly callbackUrl: "AUTHORIZE_CALLBACK_URL";
+    readonly clerkSecretKey: "CLERK_SECRET_KEY";
+    readonly extraAuthorizedParties: "AUTHORIZE_AUTHORIZED_PARTIES";
+    readonly signingJwk: "MCP_OAUTH_SIGNING_JWK";
+};
+/** Scope granted when a client names none: MCP access plus the OIDC subject. */
+export declare const DEFAULT_SCOPE = "mcp:full openid";
+export declare const SUPPORTED_SCOPES: readonly ["mcp:full", "openid", "email"];
+export interface AuthorizeSettings {
+    baseUrl: string;
+    /** The protected resource identifier (RFC 8707) and the access-token audience. */
+    resource: string;
+    stateSecret: string;
+    clerkIssuer: string;
+    signInUrl: string;
+    callbackUrl: string;
+    authorizedParties: string[];
+    /** Private signing key (RS256). Its public half is published at /.well-known/jwks.json. */
+    signingJwk: JWK & {
+        kid: string;
+    };
+    hasClerkSecretKey: boolean;
+}
+export type AuthorizeSettingsResult = {
+    ok: true;
+    settings: AuthorizeSettings;
+} | {
+    ok: false;
+    missing: string[];
+};
+/**
+ * Reads the settings from `env`. `clerkCollaboratorsInjected` is true when the caller supplied
+ * its own Clerk Backend access (tests, or a deployment with another membership source): the
+ * secret key is then not required.
+ */
+export declare function readAuthorizeSettings(env: NodeJS.ProcessEnv, clerkCollaboratorsInjected?: boolean): Promise<AuthorizeSettingsResult>;

package/dist/oauth/settings.js

@@ -0,0 +1,100 @@
+/**
+ * Environment-derived configuration of the authorization server. FAIL-CLOSED: when any
+ * required value is absent (or malformed) the result is `{ ok: false, missing }`, naming the
+ * variables — never their values — and every authorization route answers 503. There is no
+ * auto-approve path and no default secret.
+ */
+import { calculateJwkThumbprint } from "jose";
+export const OAUTH_ENV = {
+    publicBaseUrl: "PUBLIC_BASE_URL",
+    stateSecret: "AUTHORIZE_STATE_SECRET",
+    clerkIssuer: "CLERK_DOMAIN",
+    signInUrl: "AUTHORIZE_SIGN_IN_URL",
+    callbackUrl: "AUTHORIZE_CALLBACK_URL",
+    clerkSecretKey: "CLERK_SECRET_KEY",
+    extraAuthorizedParties: "AUTHORIZE_AUTHORIZED_PARTIES",
+    signingJwk: "MCP_OAUTH_SIGNING_JWK",
+};
+/** Scope granted when a client names none: MCP access plus the OIDC subject. */
+export const DEFAULT_SCOPE = "mcp:full openid";
+export const SUPPORTED_SCOPES = ["mcp:full", "openid", "email"];
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return null;
+    }
+}
+async function parseSigningJwk(raw) {
+    try {
+        const jwk = JSON.parse(raw);
+        if (jwk.kty !== "RSA" || typeof jwk.d !== "string" || !jwk.n || !jwk.e)
+            return null;
+        // The key id is DERIVED from the key (RFC 7638 thumbprint) when the operator did not set one.
+        const kid = jwk.kid ?? (await calculateJwkThumbprint(jwk));
+        return { ...jwk, kid, alg: "RS256", use: "sig" };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads the settings from `env`. `clerkCollaboratorsInjected` is true when the caller supplied
+ * its own Clerk Backend access (tests, or a deployment with another membership source): the
+ * secret key is then not required.
+ */
+export async function readAuthorizeSettings(env, clerkCollaboratorsInjected = false) {
+    const missing = [];
+    const stateSecret = env[OAUTH_ENV.stateSecret] ?? "";
+    if (stateSecret.length < 32)
+        missing.push(OAUTH_ENV.stateSecret);
+    const clerkIssuer = (env[OAUTH_ENV.clerkIssuer] ?? "").replace(/\/+$/, "");
+    if (!originOf(clerkIssuer))
+        missing.push(OAUTH_ENV.clerkIssuer);
+    const signInUrl = env[OAUTH_ENV.signInUrl] ?? "";
+    if (!originOf(signInUrl))
+        missing.push(OAUTH_ENV.signInUrl);
+    const callbackUrl = env[OAUTH_ENV.callbackUrl] ?? "";
+    if (!originOf(callbackUrl))
+        missing.push(OAUTH_ENV.callbackUrl);
+    const baseUrl = (env[OAUTH_ENV.publicBaseUrl] ?? "").replace(/\/+$/, "");
+    if (!originOf(baseUrl))
+        missing.push(OAUTH_ENV.publicBaseUrl);
+    const hasClerkSecretKey = (env[OAUTH_ENV.clerkSecretKey] ?? "") !== "";
+    if (!hasClerkSecretKey && !clerkCollaboratorsInjected)
+        missing.push(OAUTH_ENV.clerkSecretKey);
+    const signingJwk = await parseSigningJwk(env[OAUTH_ENV.signingJwk] ?? "");
+    if (!signingJwk)
+        missing.push(OAUTH_ENV.signingJwk);
+    if (missing.length > 0 || !signingJwk)
+        return { ok: false, missing };
+    // A Clerk session token minted for ANOTHER application carries that application's origin as
+    // `azp`; only this deployment's own origins are accepted.
+    const parties = new Set();
+    for (const url of [signInUrl, callbackUrl, baseUrl]) {
+        const origin = originOf(url);
+        if (origin)
+            parties.add(origin);
+    }
+    for (const extra of (env[OAUTH_ENV.extraAuthorizedParties] ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)) {
+        parties.add(extra);
+    }
+    return {
+        ok: true,
+        settings: {
+            baseUrl,
+            resource: `${baseUrl}/mcp`,
+            stateSecret,
+            clerkIssuer,
+            signInUrl,
+            callbackUrl,
+            authorizedParties: [...parties],
+            signingJwk,
+            hasClerkSecretKey,
+        },
+    };
+}

package/dist/oauth/tokenIssuer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Access-token signing. cloud-identity decides WHAT claims a token carries (the verified
+ * claims bound to the redeemed code); this module only signs them, as an RS256 JWT, with the
+ * deployment's key. The resource server (@vantageos/cloud-identity `verifyMcpAccessToken`)
+ * verifies the result against the public half published at /.well-known/jwks.json.
+ */
+import type { AuthorizedTokenClaims } from "@vantageos/cloud-identity";
+import { type JWK } from "jose";
+export declare const ACCESS_TOKEN_TTL_SECONDS = 3600;
+export interface TokenIssuer {
+    kid: string;
+    /** Public half only; safe to publish. */
+    publicJwk: JWK;
+    jwks: {
+        keys: JWK[];
+    };
+    sign(claims: AuthorizedTokenClaims, issuer: string, nowMs: number): Promise<string>;
+    verify(token: string, issuer: string, audience: string): Promise<AuthorizedTokenClaims>;
+}
+export declare function createTokenIssuer(privateJwk: JWK & {
+    kid: string;
+}): Promise<TokenIssuer>;

package/dist/oauth/tokenIssuer.js

@@ -0,0 +1,61 @@
+/**
+ * Access-token signing. cloud-identity decides WHAT claims a token carries (the verified
+ * claims bound to the redeemed code); this module only signs them, as an RS256 JWT, with the
+ * deployment's key. The resource server (@vantageos/cloud-identity `verifyMcpAccessToken`)
+ * verifies the result against the public half published at /.well-known/jwks.json.
+ */
+import { SignJWT, createLocalJWKSet, importJWK, jwtVerify } from "jose";
+export const ACCESS_TOKEN_TTL_SECONDS = 3600;
+export async function createTokenIssuer(privateJwk) {
+    const key = await importJWK(privateJwk, "RS256");
+    // Public members only: kty/n/e + metadata. Every private member (d, p, q, dp, dq, qi) is left out.
+    const publicJwk = {
+        kty: "RSA",
+        n: privateJwk.n,
+        e: privateJwk.e,
+        kid: privateJwk.kid,
+        alg: "RS256",
+        use: "sig",
+    };
+    const jwks = { keys: [publicJwk] };
+    const verifyKey = createLocalJWKSet(jwks);
+    return {
+        kid: privateJwk.kid,
+        publicJwk,
+        jwks,
+        async sign(claims, issuer, nowMs) {
+            const iat = Math.floor(nowMs / 1000);
+            return new SignJWT({
+                org_id: claims.org_id,
+                org_slug: claims.org_slug,
+                org_role: claims.org_role,
+                client_id: claims.client_id,
+                scope: claims.scope,
+            })
+                .setProtectedHeader({ alg: "RS256", kid: privateJwk.kid, typ: "at+jwt" })
+                .setIssuer(issuer)
+                .setAudience(claims.aud)
+                .setSubject(claims.sub)
+                .setIssuedAt(iat)
+                .setExpirationTime(iat + ACCESS_TOKEN_TTL_SECONDS)
+                .setJti(crypto.randomUUID())
+                .sign(key);
+        },
+        async verify(token, issuer, audience) {
+            const { payload } = await jwtVerify(token, verifyKey, {
+                issuer,
+                audience,
+                algorithms: ["RS256"],
+            });
+            return {
+                sub: String(payload.sub),
+                org_id: String(payload.org_id),
+                org_slug: payload.org_slug ?? null,
+                org_role: String(payload.org_role),
+                aud: audience,
+                client_id: String(payload.client_id),
+                scope: String(payload.scope),
+            };
+        },
+    };
+}

package/dist/stdio.d.ts

@@ -1,8 +1,9 @@
 /**
- * Stdio transport (local/self-host mode, e.g. Claude Code / Cursor local
- * config). Trust model: the local process invoking stdio IS the caller —
- * no auth challenge on this transport. The server definition (tools) lives
- * once in mcpServerFactory.ts, shared with the HTTP transport — this file
- * only wires the official SDK stdio Transport onto that shared server.
+ * Stdio transport (local/self-host mode, e.g. Claude Code / Cursor local config). Trust
+ * model: the local process invoking stdio IS the caller — no auth challenge on this
+ * transport. The server definition lives once in mcpServerFactory.ts, shared with the HTTP
+ * transport. `serveStdio` owns the era decision: a 2026-07-28 client opens with
+ * `server/discover`, a 2025-era client with `initialize`, and one instance from the factory
+ * is pinned for the connection either way.
  */
-export declare function startStdioServer(): Promise<void>;
+export declare function startStdioServer(): void;

package/dist/stdio.js

@@ -1,26 +1,27 @@
 /**
- * Stdio transport (local/self-host mode, e.g. Claude Code / Cursor local
- * config). Trust model: the local process invoking stdio IS the caller —
- * no auth challenge on this transport. The server definition (tools) lives
- * once in mcpServerFactory.ts, shared with the HTTP transport — this file
- * only wires the official SDK stdio Transport onto that shared server.
+ * Stdio transport (local/self-host mode, e.g. Claude Code / Cursor local config). Trust
+ * model: the local process invoking stdio IS the caller — no auth challenge on this
+ * transport. The server definition lives once in mcpServerFactory.ts, shared with the HTTP
+ * transport. `serveStdio` owns the era decision: a 2026-07-28 client opens with
+ * `server/discover`, a 2025-era client with `initialize`, and one instance from the factory
+ * is pinned for the connection either way.
  */
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { createBoilerplateMcpServer } from "./mcpServerFactory.js";
-export async function startStdioServer() {
-    // `requireTenant` is otherwise only reachable from the OAuth-tier HTTP
-    // transport (see httpApp.ts). This env toggle exists solely so the eval
-    // suite (evals/evals.json "list-items-requires-tenant-refusal") can
-    // exercise the ALREADY-EXISTING `list_items` tenant-refusal branch in
-    // mcpServerFactory.ts through the real stdio transport, without adding a
-    // new code path. Unset by default — normal stdio usage is unaffected.
+export function startStdioServer() {
+    // `requireTenant` is otherwise only reachable from the OAuth-tier HTTP transport (see
+    // httpApp.ts). This env toggle exists solely so the eval suite (evals/evals.json
+    // "list-items-requires-tenant-refusal") can exercise the existing `list_items`
+    // tenant-refusal branch through the real stdio transport. Unset by default.
     const requireTenant = process.env.MCP_BOILERPLATE_REQUIRE_TENANT === "1";
-    const server = createBoilerplateMcpServer({ requireTenant });
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    process.stderr.write("[mcp-boilerplate] stdio server started — 1 tool available\n");
+    const uiDomain = process.env.MCP_UI_DOMAIN || undefined;
+    serveStdio(() => createBoilerplateMcpServer({ requireTenant, uiDomain }));
+    process.stderr.write("[mcp-boilerplate] stdio server started — 3 tools available\n");
 }
-startStdioServer().catch((err) => {
+try {
+    startStdioServer();
+}
+catch (err) {
     process.stderr.write(`[mcp-boilerplate] fatal: ${err instanceof Error ? err.message : String(err)}\n`);
     process.exit(1);
-});
+}