@vantageos/mcp-boilerplate 0.6.3 → 0.8.0

package/dist/stdio.js

@@ -18,12 +18,12 @@ export function startStdioServer() {
     // Refuses at start, naming the field, a manifest without a readable context ceiling (G6).
     loadServerManifest();
     const requireTenant = process.env.MCP_BOILERPLATE_REQUIRE_TENANT === "1";
-    const uiDomain = process.env.MCP_UI_DOMAIN || undefined;
     // No verified person on stdio, by design: there is no bearer and no verified session on this
     // transport, so `caller` is deliberately left unset and a tool wrapped with
     // `withVerifiedPerson` is refused as `no_verified_session` (src/verifiedPerson.ts). The local
     // process is trusted as the caller, never impersonated as a person.
-    serveStdio(() => createBoilerplateMcpServer({ requireTenant, uiDomain }));
+    // No served URL on stdio, so no Claude sandbox domain to derive (A-11): the widget declares none.
+    serveStdio(() => createBoilerplateMcpServer({ requireTenant }));
     process.stderr.write("[mcp-boilerplate] stdio server started — 2 tools available\n");
 }
 try {

package/dist/tenancy.d.ts

@@ -5,20 +5,10 @@
  * 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 claims (a plain claims record, Clerk-as-AS) carries no
- * `workspaceId`/`roles` claims, so it is NOT a `TenantContext` and cannot
- * go through the "bearer" path without inventing fields cloud-identity
- * never asked for. It goes through the "session" path instead
- * (`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.
+ * The organisation is read by cloud-identity's one claim reader (`requireTenantFromIdentity`: the same
+ * claim names and the same Clerk `org_` shape as `resolveTenantFromAccessToken`), never by this module.
+ * No claim, or a claim that is not an organisation id, refuses (throws); there is no fallback to a slug, a
+ * name or a default tenant.
  */
 export interface ResolvedTenant {
     tenantId: string;

package/dist/tenancy.js

@@ -5,22 +5,12 @@
  * 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 claims (a plain claims record, Clerk-as-AS) carries no
- * `workspaceId`/`roles` claims, so it is NOT a `TenantContext` and cannot
- * go through the "bearer" path without inventing fields cloud-identity
- * never asked for. It goes through the "session" path instead
- * (`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.
+ * The organisation is read by cloud-identity's one claim reader (`requireTenantFromIdentity`: the same
+ * claim names and the same Clerk `org_` shape as `resolveTenantFromAccessToken`), never by this module.
+ * No claim, or a claim that is not an organisation id, refuses (throws); there is no fallback to a slug, a
+ * name or a default tenant.
  */
-import { isRowInTenant, requireTenantId } from "@vantageos/cloud-identity";
+import { isRowInTenant, requireTenantFromIdentity } from "@vantageos/cloud-identity";
 /**
  * Resolve the caller's tenant from the verified session claims. Refuses
  * (throws) when the token carries no organization — never falls through to
@@ -28,9 +18,8 @@ import { isRowInTenant, requireTenantId } from "@vantageos/cloud-identity";
  * (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 };
+    // The organisation claim is read by the identity layer's one claim reader, never here (DLocalIdentity).
+    return { tenantId: requireTenantFromIdentity(payload, { door: "mcp" }) };
 }
 /**
  * Filter rows by the caller's tenant with cloud-identity's `isRowInTenant`: a row is visible

package/dist/toolRecord.d.ts

@@ -10,6 +10,8 @@ import type { ContextCeiling } from "./serverManifest.js";
  *   searchMechanism         C-10  how a list/search is served; `unindexed-scan` does not publish
  *   paginationCursor/Default/Max  C-11  declared here, applied by src/pagination.ts
  *   tokensEstimeContexte    C-13  the estimated context cost of the served tool
+ *   domain, mode            Agent tool roles rule 2: the business domain the tool belongs to, and `read` | `write`;
+ *                           what `decideToolRole` (@vantageos/cloud-identity) reads to allow or deny it per role
  *
  * The sets are closed UNIONS, so a value outside them is a compile error, and the verb decides
  * which other slots are required (a list/search tool cannot omit its mechanism or its pagination).
@@ -34,6 +36,11 @@ export type ToolVerb = "list" | "get" | "search" | "aggregate" | "create" | "upd
  * must declare it (`checkToolRecord`).
  */
 export type SearchMechanism = "indexed-range" | "indexed-bm25" | `indexed-vector(${string})` | "indexed-hybrid-rrf" | `upstream-delegated(${string})`;
+/**
+ * Agent tool roles rule 2 (mcp-server-standard "Agent tool roles"): exactly `read` or `write`. `read` must agree with
+ * `readOnlyHint: true`, `write` with `readOnlyHint: false` (C-15). Same union as cloud-identity's `ToolMode`.
+ */
+export type ToolMode = "read" | "write";
 /** The four behavioural annotations (C-15), explicit booleans on every tool. */
 interface BehaviourHints {
     readOnlyHint: boolean;
@@ -44,6 +51,10 @@ interface BehaviourHints {
 interface CommonSlots extends BehaviourHints {
     authRead: AuthTier;
     authWrite: AuthTier;
+    /** The business domain a role grants (rule 1); a non-empty name. */
+    domain: string;
+    /** read | write (rule 2); agrees with readOnlyHint. */
+    mode: ToolMode;
     /** Estimated context tokens of the served tool (C-13); tests/contextCeiling.test.ts checks it. */
     tokensEstimeContexte: number;
 }
@@ -75,8 +86,22 @@ export declare const PING_ANNOTATIONS: {
     readonly openWorldHint: false;
     readonly authRead: "public";
     readonly authWrite: "master";
+    readonly domain: "system";
+    readonly mode: "read";
     readonly verb: "pure";
-    readonly tokensEstimeContexte: 200;
+    readonly tokensEstimeContexte: 280;
+};
+export declare const WHOAMI_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+    readonly authRead: "public";
+    readonly authWrite: "master";
+    readonly domain: "identity";
+    readonly mode: "read";
+    readonly verb: "introspect";
+    readonly tokensEstimeContexte: 330;
 };
 export declare const LIST_ITEMS_ANNOTATIONS: {
     readonly readOnlyHint: true;
@@ -85,13 +110,15 @@ export declare const LIST_ITEMS_ANNOTATIONS: {
     readonly openWorldHint: false;
     readonly authRead: "org-member";
     readonly authWrite: "master";
+    readonly domain: "items";
+    readonly mode: "read";
     readonly verb: "list";
     readonly table: "items";
     readonly searchMechanism: "indexed-range";
     readonly paginationCursor: true;
     readonly paginationDefault: 20;
     readonly paginationMax: 100;
-    readonly tokensEstimeContexte: 640;
+    readonly tokensEstimeContexte: 690;
 };
 /** One tool's declared context cost, as `checkContextCeiling` reads it. */
 export interface ContextEstimate {
@@ -111,6 +138,12 @@ export declare function checkContextCeiling(estimates: readonly ContextEstimate[
  * refused. A tool that is not a list/search is not asked for a mechanism.
  */
 export declare function checkToolRecord(name: string, record: Record<string, unknown>): string[];
+/**
+ * Agent tool roles rule 2: every tool declares a non-empty `domain` and a `mode` of exactly `read` or `write`, and the
+ * mode agrees with `readOnlyHint` (read <-> true, write <-> false). A tool missing either, or with any other value, is
+ * served to no one: the start refuses, naming it.
+ */
+export declare function checkToolRole(name: string, record: Record<string, unknown>): string[];
 /** Thrown at start when a tool record or the ceiling is unsound. `problems` name every tool. */
 export declare class ToolRecordError extends Error {
     readonly problems: readonly string[];

package/dist/toolRecord.js

@@ -9,8 +9,24 @@ export const PING_ANNOTATIONS = {
     openWorldHint: false,
     authRead: "public",
     authWrite: "master",
+    domain: "system",
+    mode: "read",
     verb: "pure",
-    tokensEstimeContexte: 200,
+    tokensEstimeContexte: 280,
+};
+// The identity tool (C-33; agent tool roles rule 6): the caller's own identity and granted tools. It reveals nothing
+// beyond the caller's own standing, so it is `public` to read; it writes nothing.
+export const WHOAMI_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    authRead: "public",
+    authWrite: "master",
+    domain: "identity",
+    mode: "read",
+    verb: "introspect",
+    tokensEstimeContexte: 330,
 };
 export const LIST_ITEMS_ANNOTATIONS = {
     readOnlyHint: true,
@@ -19,13 +35,15 @@ export const LIST_ITEMS_ANNOTATIONS = {
     openWorldHint: false,
     authRead: "org-member",
     authWrite: "master",
+    domain: "items",
+    mode: "read",
     verb: "list",
     table: "items",
     searchMechanism: "indexed-range",
     paginationCursor: true,
     paginationDefault: 20,
     paginationMax: 100,
-    tokensEstimeContexte: 640,
+    tokensEstimeContexte: 690,
 };
 /** Every problem found, each naming the tool; empty when the ceiling holds. Never skips a tool. */
 export function checkContextCeiling(estimates, ceiling) {
@@ -66,6 +84,30 @@ function isIndexedMechanism(value) {
  * refused. A tool that is not a list/search is not asked for a mechanism.
  */
 export function checkToolRecord(name, record) {
+    return [...checkToolRole(name, record), ...checkMechanism(name, record)];
+}
+/**
+ * Agent tool roles rule 2: every tool declares a non-empty `domain` and a `mode` of exactly `read` or `write`, and the
+ * mode agrees with `readOnlyHint` (read <-> true, write <-> false). A tool missing either, or with any other value, is
+ * served to no one: the start refuses, naming it.
+ */
+export function checkToolRole(name, record) {
+    const problems = [];
+    const { domain, mode, readOnlyHint } = record;
+    if (typeof domain !== "string" || domain.trim() === "") {
+        problems.push(`${name}: declares no domain (agent tool roles rule 2)`);
+    }
+    if (mode !== "read" && mode !== "write") {
+        problems.push(mode === undefined
+            ? `${name}: declares no mode (agent tool roles rule 2: "read" or "write")`
+            : `${name}: mode ${JSON.stringify(mode)} is not "read" or "write"`);
+    }
+    else if ((mode === "read") !== (readOnlyHint === true)) {
+        problems.push(`${name}: mode "${mode}" disagrees with readOnlyHint ${String(readOnlyHint)} (read <-> true, write <-> false)`);
+    }
+    return problems;
+}
+function checkMechanism(name, record) {
     if (!LIST_VERBS.includes(record.verb))
         return [];
     const mechanism = record.searchMechanism;

package/dist/toolRoleGate.d.ts

@@ -0,0 +1,41 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import { type StandingScope, type ToolDeclaration, type ToolRoleLookup } from "@vantageos/cloud-identity";
+import { type McpLocale } from "./i18n.js";
+import { type CallerResolution, type VerifiedPerson } from "./verifiedPerson.js";
+/**
+ * The two enforcement points of agent tool roles (mcp-server-standard "Agent tool roles", rule 4), both calling the
+ * same decision of @vantageos/cloud-identity:
+ *   - tools/call is REFUSED: every registered handler is wrapped; a denied call returns a tool result with
+ *     `isError: true` and `structuredContent.error.code` = TOOL_ROLE_DENIED (or TOOL_ROLE_UNRESOLVED when the role could
+ *     not be read), and the handler does not run. Never a protocol error, never an empty success.
+ *   - tools/list is FILTERED: the SDK's own tools/list handler runs, then the denied tools are removed. The SDK's
+ *     `disable()` cannot be used: a disabled tool answers tools/call with a protocol error, which rule 4 forbids.
+ *
+ * The identity tool is outside the gate (rule 6: a caller with no role still gets `role: null` and an empty list,
+ * never an error); it is named in `exempt`, here and nowhere else.
+ */
+/** The per-request role context the server is built with. */
+export type ToolRolesContext = {
+    applicable: false;
+} | {
+    applicable: true;
+    lookup: ToolRoleLookup;
+    /** The caller's member scope, or null when the person was not resolved (every tool is then denied). */
+    caller: StandingScope | null;
+    /** The identity layer's resolution of the caller: an unresolved one is refused with its own code (callerRefusal). */
+    resolution: CallerResolution | undefined;
+    /** The display name of a role, for the identity tool. */
+    roleName: (roleId: string) => string | undefined;
+};
+/** The caller's member scope from the person the identity layer resolved, or null. Never built from a claim here. */
+export declare function callerScopeOf(person: VerifiedPerson | undefined): StandingScope | null;
+/**
+ * Wraps `server.registerTool` so every handler registered AFTER this call is gated, and returns the declarations seen
+ * (for the list filter and the identity tool). With roles not applicable, nothing is wrapped and nothing is filtered.
+ */
+export declare function installToolRoleGate(server: McpServer, roles: ToolRolesContext, locale: McpLocale, exempt: ReadonlySet<string>): {
+    declarations: ToolDeclaration[];
+    filterList: () => void;
+};
+/** The tools the caller is granted, by the same decision as the list (for the identity tool's `grantedTools`). */
+export declare function grantedToolNames(roles: ToolRolesContext, declarations: readonly ToolDeclaration[]): string[];

package/dist/toolRoleGate.js

@@ -0,0 +1,94 @@
+import { decideToolRole, filterGrantedTools, memberScopeFrom, } from "@vantageos/cloud-identity";
+import { t } from "./i18n.js";
+import { callerRefusal } from "./verifiedPerson.js";
+/** A scope `scopeStanding` reads as "refused": the decision denies with caller-not-resolved. */
+const UNRESOLVED_CALLER = { isMaster: false, fleetWide: false, refused: true };
+/** The caller's member scope from the person the identity layer resolved, or null. Never built from a claim here. */
+export function callerScopeOf(person) {
+    if (!person)
+        return null;
+    // The person is deep-readonly; the package reads the org row without mutating it, so a shallow copy of its arrays
+    // satisfies the mutable parameter type.
+    const org = {
+        id: person.org.id,
+        label: person.org.label,
+        allowedAgentIds: person.org.allowedAgentIds ? [...person.org.allowedAgentIds] : undefined,
+        scopes: [...person.org.scopes],
+    };
+    const r = memberScopeFrom(org, {
+        userId: person.subject,
+        orgRole: person.role,
+        orgId: person.org.id,
+    });
+    return r.ok ? r.scope : null;
+}
+function declarationOf(name, annotations) {
+    const a = (annotations ?? {});
+    return { toolId: name, domain: a.domain, mode: a.mode };
+}
+/**
+ * Wraps `server.registerTool` so every handler registered AFTER this call is gated, and returns the declarations seen
+ * (for the list filter and the identity tool). With roles not applicable, nothing is wrapped and nothing is filtered.
+ */
+export function installToolRoleGate(server, roles, locale, exempt) {
+    const declarations = [];
+    if (!roles.applicable)
+        return { declarations, filterList: () => { } };
+    const register = server.registerTool.bind(server);
+    server.registerTool = ((name, config, callback) => {
+        if (exempt.has(name))
+            return register(name, config, callback);
+        const declaration = declarationOf(name, config.annotations);
+        declarations.push(declaration);
+        const gated = async (...args) => {
+            const refused = callerRefusal(roles.resolution, locale);
+            if (refused)
+                return refused;
+            const decision = decideToolRole(roles.lookup, declaration, roles.caller ?? UNRESOLVED_CALLER, { door: name });
+            if (!decision.ok) {
+                const { code, reason } = decision.refusal;
+                const message = code === "TOOL_ROLE_UNRESOLVED"
+                    ? t(locale, "toolRoles.unresolved")
+                    : t(locale, "toolRoles.denied")
+                        .replace("{tool}", () => name)
+                        .replace("{reason}", () => reason);
+                return {
+                    content: [{ type: "text", text: message }],
+                    structuredContent: { error: { code, reason, message } },
+                    isError: true,
+                };
+            }
+            return callback(...args);
+        };
+        return register(name, config, gated);
+    });
+    const filterList = () => {
+        // The SDK keeps its handlers in a map; the tools/list entry is wrapped in place so the SDK's own listing (schemas,
+        // eras, pagination) runs unchanged and only its result is narrowed. A missing entry refuses the start: a server
+        // that cannot filter its list must not serve it unfiltered.
+        const handlers = server.server
+            ._requestHandlers;
+        const inner = handlers?.get("tools/list");
+        if (!handlers || typeof inner !== "function")
+            throw new Error("agent tool roles: the SDK's tools/list handler was not found; the list cannot be filtered");
+        handlers.set("tools/list", async (req, ctx) => {
+            // Only `tools` is narrowed: every other field of the SDK's page, `nextCursor` included, is carried unchanged, so
+            // pagination is the SDK's (and src/listCursor.ts's) exactly as without the gate.
+            const result = (await inner(req, ctx));
+            // Decided at list time, over every declaration seen so far: a tool registered after the gate was installed is
+            // listed by the same decision that gates its calls.
+            const granted = new Set(filterGrantedTools(roles.lookup, declarations, roles.caller ?? UNRESOLVED_CALLER).map((d) => d.toolId));
+            return {
+                ...result,
+                tools: (result.tools ?? []).filter((tool) => exempt.has(tool.name) || granted.has(tool.name)),
+            };
+        });
+    };
+    return { declarations, filterList };
+}
+/** The tools the caller is granted, by the same decision as the list (for the identity tool's `grantedTools`). */
+export function grantedToolNames(roles, declarations) {
+    if (!roles.applicable)
+        return [];
+    return filterGrantedTools(roles.lookup, declarations, roles.caller ?? UNRESOLVED_CALLER).map((d) => d.toolId);
+}

package/dist/toolRoles.d.ts

@@ -0,0 +1,57 @@
+import type { ToolRole, ToolRoleLookup } from "@vantageos/cloud-identity";
+/**
+ * Agent tool roles (mcp-server-standard "Agent tool roles"): which tools exist for the calling agent.
+ *
+ * The decision is @vantageos/cloud-identity's (`decideToolRole` / `filterGrantedTools`); this module only supplies its
+ * input, the role the caller holds, through ONE seam: a `RoleProvider`. The boilerplate ships a data-backed provider
+ * (roles in a JSON file named by `MCP_ROLES_FILE`, no business value in code); the Convex agent-roles component plugs
+ * into the same seam.
+ *
+ * Where roles apply (Pi's ruling on task k17103j933e6en0aqyws2v1twx8hc0s3):
+ *   - the OAuth tier: a provider is REQUIRED. No `MCP_ROLES_FILE`, an unreadable one or a malformed one stops the
+ *     server at start, naming the variable. An absent store never widens access.
+ *   - the public HTTP tier and stdio have no caller: roles are NOT APPLICABLE there, said at start and in the identity
+ *     tool (`rolesApplicable: false`), never a silent pass.
+ */
+/** The verified caller a provider reads its role from: what the identity layer resolved, never a claim read here. */
+export interface RoleCaller {
+    /** The verified subject (the person or agent behind the credential). */
+    subject: string;
+    /** The organisation's permanent ID, as resolved by the identity layer. */
+    orgClerkId: string;
+}
+/** The role store seam: the role the caller holds, or why there is none. A thrown error is read as unresolved. */
+export type RoleProvider = (caller: RoleCaller) => Promise<ToolRoleLookup>;
+/** A role as the roles file holds it: cloud-identity's `ToolRole` plus a display name for the identity tool. */
+export interface NamedToolRole extends ToolRole {
+    name: string;
+}
+/** The roles file: the roles, and the binding of each verified subject to exactly one role. */
+export interface RolesFile {
+    roles: NamedToolRole[];
+    agents: Record<string, string>;
+}
+/** Where roles apply, decided once at start. */
+export type ToolRolesConfig = {
+    applicable: true;
+    provider: RoleProvider;
+    roleName: (roleId: string) => string | undefined;
+} | {
+    applicable: false;
+};
+/** Thrown at start when the OAuth tier has no usable roles file. */
+export declare class ToolRolesConfigError extends Error {
+    constructor(message: string);
+}
+/** Every problem with a parsed roles file; empty when sound. A malformed file is refused whole, never half-used. */
+export declare function checkRolesFile(value: unknown): string[];
+/**
+ * The provider over a roles file already read and checked. A subject with no binding -> absent ("unassigned"); a
+ * binding to a role the file does not hold -> absent ("deleted"). Both deny, by the decision function.
+ */
+export declare function fileRoleProvider(file: RolesFile): RoleProvider;
+/**
+ * Where roles apply, read at start. OAuth: `MCP_ROLES_FILE` is required and must hold a sound roles file, else the
+ * start is refused naming the variable. Public HTTP and stdio: not applicable.
+ */
+export declare function loadToolRoles(authMode: "oauth" | "public" | "stdio", env?: NodeJS.ProcessEnv): ToolRolesConfig;

package/dist/toolRoles.js

@@ -0,0 +1,113 @@
+import { readFileSync } from "node:fs";
+import { tBoth } from "./i18n.js";
+const ROLES_FILE_VARIABLE = "MCP_ROLES_FILE";
+/** Thrown at start when the OAuth tier has no usable roles file. */
+export class ToolRolesConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ToolRolesConfigError";
+    }
+}
+const isStringList = (v) => Array.isArray(v) && v.every((x) => typeof x === "string" && x.length > 0);
+/** Every problem with a parsed roles file; empty when sound. A malformed file is refused whole, never half-used. */
+export function checkRolesFile(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return ["not a JSON object"];
+    const { roles, agents } = value;
+    const problems = [];
+    if (!Array.isArray(roles))
+        problems.push("`roles` is not a list");
+    if (!agents || typeof agents !== "object" || Array.isArray(agents))
+        problems.push("`agents` is not an object");
+    if (problems.length > 0)
+        return problems;
+    const ids = new Set();
+    roles.forEach((r, i) => {
+        const role = r;
+        const at = `roles[${i}]`;
+        if (!role || typeof role !== "object")
+            return void problems.push(`${at} is not an object`);
+        for (const key of ["roleId", "orgClerkId", "name"])
+            if (typeof role[key] !== "string" || role[key].trim() === "")
+                problems.push(`${at}.${key} is missing`);
+        if (typeof role.roleId === "string") {
+            if (ids.has(role.roleId))
+                problems.push(`${at}.roleId ${role.roleId} is declared twice`);
+            ids.add(role.roleId);
+        }
+        if (!Array.isArray(role.domains))
+            problems.push(`${at}.domains is not a list`);
+        else
+            role.domains.forEach((d, k) => {
+                if (typeof d?.domain !== "string" || d.domain.trim() === "")
+                    problems.push(`${at}.domains[${k}].domain is missing`);
+                if (typeof d?.read !== "boolean" || typeof d?.write !== "boolean")
+                    problems.push(`${at}.domains[${k}] needs boolean read and write`);
+            });
+        if (!isStringList(role.add ?? []))
+            problems.push(`${at}.add is not a list of tool names`);
+        if (!isStringList(role.remove ?? []))
+            problems.push(`${at}.remove is not a list of tool names`);
+    });
+    for (const [subject, roleId] of Object.entries(agents))
+        if (typeof roleId !== "string" || roleId === "")
+            problems.push(`agents["${subject}"] is not a role ID`);
+    return problems;
+}
+/**
+ * The provider over a roles file already read and checked. A subject with no binding -> absent ("unassigned"); a
+ * binding to a role the file does not hold -> absent ("deleted"). Both deny, by the decision function.
+ */
+export function fileRoleProvider(file) {
+    const byId = new Map(file.roles.map((r) => [r.roleId, r]));
+    return async ({ subject }) => {
+        const roleId = Object.hasOwn(file.agents, subject) ? file.agents[subject] : undefined;
+        if (roleId === undefined)
+            return { status: "absent", cause: "unassigned" };
+        const role = byId.get(roleId);
+        if (!role)
+            return { status: "absent", cause: "deleted" };
+        return {
+            status: "resolved",
+            role: {
+                roleId: role.roleId,
+                orgClerkId: role.orgClerkId,
+                domains: role.domains,
+                add: role.add ?? [],
+                remove: role.remove ?? [],
+            },
+        };
+    };
+}
+/**
+ * Where roles apply, read at start. OAuth: `MCP_ROLES_FILE` is required and must hold a sound roles file, else the
+ * start is refused naming the variable. Public HTTP and stdio: not applicable.
+ */
+export function loadToolRoles(authMode, env = process.env) {
+    if (authMode !== "oauth")
+        return { applicable: false };
+    const path = env[ROLES_FILE_VARIABLE]?.trim();
+    if (!path)
+        throw new ToolRolesConfigError(tBoth("toolRoles.configMissing", { variable: ROLES_FILE_VARIABLE }));
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new ToolRolesConfigError(tBoth("toolRoles.configInvalid", {
+            variable: ROLES_FILE_VARIABLE,
+            path,
+            problem: e.message,
+        }));
+    }
+    const problems = checkRolesFile(parsed);
+    if (problems.length > 0)
+        throw new ToolRolesConfigError(tBoth("toolRoles.configInvalid", {
+            variable: ROLES_FILE_VARIABLE,
+            path,
+            problem: problems.join("; "),
+        }));
+    const file = parsed;
+    const names = new Map(file.roles.map((r) => [r.roleId, r.name]));
+    return { applicable: true, provider: fileRoleProvider(file), roleName: (id) => names.get(id) };
+}

package/dist/ui/sandboxDomain.d.ts

@@ -0,0 +1,13 @@
+/** The suffix of every Claude MCP Apps sandbox origin. Half of the derivation, never a whole domain. */
+export declare const CLAUDE_SANDBOX_SUFFIX = ".claudemcpcontent.com";
+/**
+ * The sandbox domain Claude serves this server's widget from (mcp-app-standard A-11): the first 32 hexadecimal
+ * characters of SHA-256 of the served MCP URL, followed by `.claudemcpcontent.com`. Computed at start from the URL
+ * the server is reached at, never written as a literal: a typed domain is wrong as soon as the URL changes.
+ */
+export declare function claudeSandboxDomain(servedMcpUrl: string): string;
+/**
+ * The served MCP URL: `PUBLIC_BASE_URL` (the public origin, a path prefix allowed) joined to the `/mcp` endpoint.
+ * Unset, there is no served URL to derive from and the widget declares no domain (development).
+ */
+export declare function servedMcpUrl(env: NodeJS.ProcessEnv): string | undefined;

package/dist/ui/sandboxDomain.js

@@ -0,0 +1,23 @@
+import { createHash } from "node:crypto";
+/** The suffix of every Claude MCP Apps sandbox origin. Half of the derivation, never a whole domain. */
+export const CLAUDE_SANDBOX_SUFFIX = ".claudemcpcontent.com";
+/**
+ * The sandbox domain Claude serves this server's widget from (mcp-app-standard A-11): the first 32 hexadecimal
+ * characters of SHA-256 of the served MCP URL, followed by `.claudemcpcontent.com`. Computed at start from the URL
+ * the server is reached at, never written as a literal: a typed domain is wrong as soon as the URL changes.
+ */
+// allow-local-identity: hashes the PUBLIC served MCP URL to name a sandbox origin; no credential, no caller, no tenant
+export function claudeSandboxDomain(servedMcpUrl) {
+    const label = createHash("sha256").update(servedMcpUrl).digest("hex").slice(0, 32);
+    return `${label}${CLAUDE_SANDBOX_SUFFIX}`;
+}
+/**
+ * The served MCP URL: `PUBLIC_BASE_URL` (the public origin, a path prefix allowed) joined to the `/mcp` endpoint.
+ * Unset, there is no served URL to derive from and the widget declares no domain (development).
+ */
+export function servedMcpUrl(env) {
+    const base = env.PUBLIC_BASE_URL;
+    if (!base)
+        return undefined;
+    return new URL("mcp", base.endsWith("/") ? base : `${base}/`).href;
+}

package/dist/ui/uiResource.d.ts

@@ -21,6 +21,12 @@ export declare function buildItemsUiResourceMeta(domain?: string): McpUiResource
  * The widget template. It carries no row: the widget renders the `list_items` RESULT it is given,
  * so the template is the same for every caller and every page.
  */
+/**
+ * What the widget shows, for the host and the model, in both languages ("EN / FR"). Hosts read it
+ * under two keys: `_meta.ui.widgetDescription` and the ChatGPT hint `_meta["openai/widgetDescription"]`
+ * (Manufact's tool-resource-metadata-complete reads exactly these); the same text under both.
+ */
+export declare const WIDGET_DESCRIPTION: string;
 export declare function buildUiResource(props: {
     domain?: string;
 }): {
@@ -28,7 +34,14 @@ export declare function buildUiResource(props: {
     mimeType: string;
     text: string;
     _meta: {
-        ui: McpUiResourceMeta;
+        ui: {
+            widgetDescription: string;
+            csp?: import("@modelcontextprotocol/ext-apps").McpUiResourceCsp;
+            permissions?: import("@modelcontextprotocol/ext-apps").McpUiResourcePermissions;
+            domain?: string;
+            prefersBorder?: boolean;
+        };
+        "openai/widgetDescription": string;
     };
 };
 /**

package/dist/ui/uiResource.js

@@ -13,6 +13,7 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+import { tBoth } from "../i18n.js";
 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
@@ -69,12 +70,21 @@ export function buildItemsUiResourceMeta(domain) {
  * The widget template. It carries no row: the widget renders the `list_items` RESULT it is given,
  * so the template is the same for every caller and every page.
  */
+/**
+ * What the widget shows, for the host and the model, in both languages ("EN / FR"). Hosts read it
+ * under two keys: `_meta.ui.widgetDescription` and the ChatGPT hint `_meta["openai/widgetDescription"]`
+ * (Manufact's tool-resource-metadata-complete reads exactly these); the same text under both.
+ */
+export const WIDGET_DESCRIPTION = tBoth("widget.description");
 export function buildUiResource(props) {
     return {
         uri: ITEMS_UI_RESOURCE_URI,
         mimeType: RESOURCE_MIME_TYPE,
         text: readUiBundle(),
-        _meta: { ui: buildItemsUiResourceMeta(props.domain) },
+        _meta: {
+            ui: { ...buildItemsUiResourceMeta(props.domain), widgetDescription: WIDGET_DESCRIPTION },
+            "openai/widgetDescription": WIDGET_DESCRIPTION,
+        },
     };
 }
 /**