@vantageos/mcp-boilerplate 0.1.0

package/dist/i18n.js

@@ -0,0 +1,70 @@
+/**
+ * Thin server-side locale layer for MCP error/validation messages.
+ *
+ * REUSE: @vantageos/mosaic-i18n@0.1.1 is a React/react-i18next package
+ * (`peerDependencies: i18next, react-i18next`) — its runtime API targets a
+ * React component tree, not a JSON-RPC server, so it cannot be called
+ * directly from tool handlers here. What IS reused, verified firsthand in
+ * `node_modules/@vantageos/mosaic-i18n/src/locales/{en,fr}.json`, is its
+ * resource-file CONVENTION: a flat namespaced object
+ * (`<Component>.<category>.<key>` -> string), one file per locale, FR and
+ * EN kept in lockstep key-for-key. `src/locales/{en,fr}.json` in this
+ * boilerplate follows that exact shape under a single `Mcp` namespace
+ * (`Mcp.auth.*`, `Mcp.tenant.*`, `Mcp.validation.*`), so the two locale
+ * files could be merged into mosaic-i18n's own resource files verbatim if
+ * this boilerplate ever grows a React UI consumer of the same strings.
+ *
+ * Locale detection follows mcp-standard.md's `X-MCP-Locale` request header
+ * (§Bilingual, l.234): "fr" selects the French resource, anything else
+ * (including a missing header) defaults to English.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+// Loaded via fs + JSON.parse, not a JSON module import: Node's ESM loader
+// (the runtime the compiled dist/stdio.js and dist/http.js run under)
+// requires an explicit import attribute for a JSON module import, which the
+// project's current `tsconfig.json` `module` target does not emit. This
+// project's `resolveJsonModule` + a plain JSON import already work for
+// bundler-processed code (e.g. src/ui/Widget.tsx, inlined by Vite at build
+// time and never hitting Node's loader at all) but not for tsc's own Node
+// ESM output, so the two resources here are read as plain files instead.
+function loadLocaleResource(fileName) {
+    const path = fileURLToPath(new URL(`./locales/${fileName}`, import.meta.url));
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+const RESOURCES = {
+    en: loadLocaleResource("en.json"),
+    fr: loadLocaleResource("fr.json"),
+};
+/**
+ * Resolves the caller's locale from the `X-MCP-Locale` request header.
+ * Defaults to "en" for a missing header or any value other than "fr".
+ */
+export function detectLocale(headerValue) {
+    return headerValue?.toLowerCase() === "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"`.
+ * Falls back to the English string (never to the raw key) if the requested
+ * locale is somehow missing a key the English resource carries.
+ */
+export function t(locale, key) {
+    const path = key.split(".");
+    const fromLocale = readPath(RESOURCES[locale].Mcp, path);
+    if (typeof fromLocale === "string") {
+        return fromLocale;
+    }
+    const fromEnglish = readPath(RESOURCES.en.Mcp, path);
+    return typeof fromEnglish === "string" ? fromEnglish : key;
+}
+function readPath(root, path) {
+    let node = root;
+    for (const segment of path) {
+        if (typeof node !== "object" || node === null) {
+            return undefined;
+        }
+        node = node[segment];
+    }
+    return node;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createBoilerplateMcpServer } from "./mcpServerFactory.js";
+export { buildHttpApp } from "./httpApp.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createBoilerplateMcpServer } from "./mcpServerFactory.js";
+export { buildHttpApp } from "./httpApp.js";

package/dist/locales/en.json

@@ -0,0 +1,13 @@
+{
+  "Mcp": {
+    "auth": {
+      "unauthorized": "Unauthorized"
+    },
+    "tenant": {
+      "permissionDenied": "permission denied: no tenant resolved for this caller"
+    },
+    "validation": {
+      "messageTooLong": "message exceeds the maximum length of 200 characters"
+    }
+  }
+}

package/dist/locales/fr.json

@@ -0,0 +1,13 @@
+{
+  "Mcp": {
+    "auth": {
+      "unauthorized": "Non autorisé"
+    },
+    "tenant": {
+      "permissionDenied": "permission refusée : aucun tenant résolu pour cet appelant"
+    },
+    "validation": {
+      "messageTooLong": "le message dépasse la longueur maximale de 200 caractères"
+    }
+  }
+}

package/dist/mcpServerFactory.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ *
+ * 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, ...).
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type McpLocale } from "./i18n.js";
+import { type ResolvedTenant } from "./tenancy.js";
+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.
+     */
+    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.
+     */
+    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.
+     */
+    locale?: McpLocale;
+}
+export declare function createBoilerplateMcpServer(deps?: McpServerDeps): McpServer;

package/dist/mcpServerFactory.js

@@ -0,0 +1,180 @@
+/**
+ * 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.
+ *
+ * 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, ...).
+ *
+ * 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.
+ *
+ * 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.
+ */
+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 { 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: {} },
+};
+// 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"),
+});
+function toolResult(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+    };
+}
+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,
+    }, 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.
+        if (args.message !== undefined && args.message.length > 200) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: t(locale, "validation.messageTooLong"),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return toolResult({ reply: args.message ?? "pong" });
+    });
+    server.registerTool(LIST_ITEMS_TOOL_DESCRIPTOR.name, {
+        description: LIST_ITEMS_TOOL_DESCRIPTOR.description,
+        inputSchema: listItemsInputShape,
+    }, 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,
+            };
+        }
+        const items = deps.tenant
+            ? scopeRowsForTenant(deps.tenant.tenantId, EXAMPLE_ITEMS)
+            : EXAMPLE_ITEMS;
+        return toolResult({ items });
+    });
+    // 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" })],
+    }));
+    registerAppTool(server, "render_items_ui", {
+        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.
+        _meta: {
+            ui: ITEMS_UI_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.
+    server.server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return buildToolsListResult([PING_TOOL_DESCRIPTOR, LIST_ITEMS_TOOL_DESCRIPTOR], {
+            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",
+        });
+    });
+    return server;
+}

package/dist/stdio.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export declare function startStdioServer(): Promise<void>;

package/dist/stdio.js

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createBoilerplateMcpServer } from "./mcpServerFactory.js";
+export async function startStdioServer() {
+    const server = createBoilerplateMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("[mcp-boilerplate] stdio server started — 1 tool available\n");
+}
+startStdioServer().catch((err) => {
+    process.stderr.write(`[mcp-boilerplate] fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/tenancy.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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
+ * rows. This module never re-verifies the token and never reimplements
+ * cloud-identity's authorization logic — it only adapts shapes.
+ *
+ * API-shape note (first real consumer of `requireTenantId`, new in
+ * cloud-identity 0.3.0 with zero prior callers): the package's "bearer"
+ * 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
+ * `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
+ * (`identity: { orgId }`), which matches the JWT's `org_id` claim exactly
+ * as Clerk mints it. Both entry paths converge on the same
+ * refuse-on-absence contract (`requireTenantId` throws when there is no
+ * 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
+ * (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;
+/**
+ * Filter rows by the caller's tenant, reusing cloud-identity's
+ * `scopeFilterList` unmodified — this module never reimplements row
+ * filtering.
+ */
+export declare function scopeRowsForTenant<T extends ScopeFilterable>(tenantId: string, rows: T[]): T[];

package/dist/tenancy.js

@@ -0,0 +1,58 @@
+/**
+ * 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
+ * rows. This module never re-verifies the token and never reimplements
+ * cloud-identity's authorization logic — it only adapts shapes.
+ *
+ * API-shape note (first real consumer of `requireTenantId`, new in
+ * cloud-identity 0.3.0 with zero prior callers): the package's "bearer"
+ * 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
+ * `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
+ * (`identity: { orgId }`), which matches the JWT's `org_id` claim exactly
+ * as Clerk mints it. Both entry paths converge on the same
+ * refuse-on-absence contract (`requireTenantId` throws when there is no
+ * 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";
+/**
+ * Resolve the caller's tenant from the verified JWT payload. 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 function resolveTenantFromJwtPayload(payload) {
+    const orgId = typeof payload.org_id === "string" ? payload.org_id : undefined;
+    const tenantId = requireTenantId({ kind: "session", identity: { orgId } });
+    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.
+ */
+export function scopeRowsForTenant(tenantId, rows) {
+    return scopeFilterList(scopeForTenant(tenantId), rows);
+}

package/dist/ui/uiResource.d.ts

@@ -0,0 +1,34 @@
+import type { 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.
+ */
+export declare function readUiBundle(): string;
+export declare function buildUiResource(props: {
+    items: ExampleItem[];
+    locale: "en" | "fr";
+}): {
+    uri: string;
+    mimeType: string;
+    text: string;
+};
+/** GA nested `_meta.ui` value shared by the tool registration and the result. */
+export declare const ITEMS_UI_META: McpUiToolMeta;
+export interface RenderItemsUiResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: "text";
+        text: string;
+    } | {
+        type: "resource";
+        resource: ReturnType<typeof buildUiResource>;
+    }>;
+    _meta: {
+        ui: McpUiToolMeta;
+    };
+}
+export declare function buildRenderItemsUiResult(items: ExampleItem[], locale: "en" | "fr"): RenderItemsUiResult;

package/dist/ui/uiResource.js

@@ -0,0 +1,59 @@
+/**
+ * MCP Apps UI resource for the `render_items_ui` tool — GA `_meta.ui`
+ * nested form (`io.modelcontextprotocol/ui`, stable 2026-01-26), built via
+ * the official `@modelcontextprotocol/ext-apps/server` helpers.
+ *
+ * `RESOURCE_URI_META_KEY` (the deprecated flat `_meta["ui/resourceUri"]`
+ * key) is imported ONLY to assert its absence in tests — this module never
+ * writes it. It also never writes a bespoke `_meta` key (the shape found
+ * in `@vantageos/mcp-architect@1.1.0` and flagged non-conformant in the
+ * CRM's own audit) — `registerAppTool`'s `_meta.ui` field is the only
+ * shape written here.
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+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");
+function renderMarkdownFallback(items, locale) {
+    const title = locale === "fr" ? "Éléments" : "Items";
+    if (items.length === 0) {
+        return `## ${title}\n\n${locale === "fr" ? "Aucun élément." : "No items."}`;
+    }
+    const rows = items.map((item) => `- **${item.name}** (${item.namespace})`).join("\n");
+    return `## ${title}\n\n${rows}`;
+}
+/**
+ * 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.
+ */
+export function readUiBundle() {
+    return readFileSync(BUNDLE_PATH, "utf-8");
+}
+export function buildUiResource(props) {
+    return {
+        uri: ITEMS_UI_RESOURCE_URI,
+        mimeType: RESOURCE_MIME_TYPE,
+        text: readUiBundle(),
+    };
+}
+/** GA nested `_meta.ui` value shared by the tool registration and the result. */
+export const ITEMS_UI_META = {
+    resourceUri: ITEMS_UI_RESOURCE_URI,
+};
+export function buildRenderItemsUiResult(items, locale) {
+    const fallbackMarkdown = renderMarkdownFallback(items, locale);
+    const resource = buildUiResource({ items, locale });
+    return {
+        content: [
+            { type: "text", text: fallbackMarkdown },
+            { type: "resource", resource },
+        ],
+        _meta: { ui: ITEMS_UI_META },
+    };
+}