@miragon/mcp-toolkit-core 0.10.1

package/dist/tools/backend-registry.js

@@ -0,0 +1,154 @@
+import { getRequestContext } from "mcp-use/server";
+/**
+ * Default backend-selection TTL: how long a session's sticky pick survives
+ * without being re-set. `mcp-use` exposes no session-close hook to plugins, so
+ * without eviction the per-session selection map would grow with every MCP
+ * session that ever selected a backend. 24h comfortably outlives any real
+ * session.
+ */
+export const DEFAULT_BACKEND_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Reads the active MCP session id for the in-flight tool call.
+ *
+ * `mcp-use` ships an internal session-id helper but it's not part of the
+ * public `mcp-use/server` surface — we read the `Mcp-Session-Id` header off
+ * the Hono request context that `mcp-use` propagates via AsyncLocalStorage to
+ * every tool handler. Returns `undefined` for the stdio transport or when no
+ * session header was negotiated (single-backend config keeps working anyway
+ * because resolution falls back to the lone default).
+ */
+function defaultGetSessionId() {
+    const ctx = getRequestContext();
+    if (!ctx)
+        return undefined;
+    return ctx.req.header("Mcp-Session-Id") ?? ctx.req.header("mcp-session-id") ?? undefined;
+}
+/**
+ * Thrown when a tool is invoked but no backend has been selected for the
+ * current MCP session and the registry holds more than one backend.
+ *
+ * The message lists the available ids because the error path commonly only
+ * serialises `code` + `message` (the structured `availableIds` field may not
+ * reach the model) — naming them saves the model a discovery roundtrip before
+ * it can pick one and select it.
+ */
+export class BackendNotSelectedError extends Error {
+    code = "BACKEND_NOT_SELECTED";
+    availableIds;
+    constructor(availableIds, label) {
+        super(`No ${label} selected for this session. Available ${label}s: ${availableIds.join(", ")}. ` +
+            `Select one for this session first.`);
+        this.name = "BackendNotSelectedError";
+        this.availableIds = availableIds;
+    }
+}
+/** Thrown when an override or sticky selection names a backend that isn't registered. */
+export class UnknownBackendError extends Error {
+    code = "UNKNOWN_BACKEND";
+    requestedId;
+    availableIds;
+    constructor(requestedId, availableIds, label) {
+        super(`Unknown ${label} id "${requestedId}". Available: ${availableIds.join(", ")}.`);
+        this.name = "UnknownBackendError";
+        this.requestedId = requestedId;
+        this.availableIds = availableIds;
+    }
+}
+/**
+ * Builds a {@link BackendRegistry} from a non-empty list of backend entries.
+ * Throws if `entries` is empty or contains duplicate ids — both are
+ * programmer errors that should fail at boot rather than at the first tool
+ * call.
+ */
+export function createBackendRegistry(entries, opts = {}) {
+    if (entries.length === 0) {
+        throw new Error("createBackendRegistry requires at least one backend entry");
+    }
+    const byId = new Map();
+    for (const entry of entries) {
+        if (byId.has(entry.id)) {
+            throw new Error(`createBackendRegistry: duplicate backend id "${entry.id}"`);
+        }
+        byId.set(entry.id, entry);
+    }
+    const label = opts.label ?? "backend";
+    const ttlMs = opts.sessionTtlMs ?? DEFAULT_BACKEND_SESSION_TTL_MS;
+    const getSessionId = opts.getSessionId ?? defaultGetSessionId;
+    const now = opts.now ?? Date.now;
+    const sessionSelections = new Map();
+    const availableIds = () => [...byId.keys()];
+    const isExpired = (entry) => now() - entry.selectedAt > ttlMs;
+    const sweepExpired = () => {
+        for (const [sid, entry] of sessionSelections) {
+            if (isExpired(entry))
+                sessionSelections.delete(sid);
+        }
+    };
+    const stickySelection = () => {
+        const sid = getSessionId();
+        if (!sid)
+            return undefined;
+        const entry = sessionSelections.get(sid);
+        if (!entry)
+            return undefined;
+        if (isExpired(entry)) {
+            sessionSelections.delete(sid);
+            return undefined;
+        }
+        return entry.id;
+    };
+    const get = (id) => {
+        const entry = byId.get(id);
+        if (!entry)
+            throw new UnknownBackendError(id, availableIds(), label);
+        return { id: entry.id, client: entry.client, meta: entry.meta };
+    };
+    return {
+        resolve(override) {
+            if (override)
+                return get(override);
+            const sticky = stickySelection();
+            if (sticky)
+                return get(sticky);
+            if (byId.size === 1) {
+                const [only] = byId.values();
+                return { id: only.id, client: only.client, meta: only.meta };
+            }
+            throw new BackendNotSelectedError(availableIds(), label);
+        },
+        select(id) {
+            if (!byId.has(id))
+                throw new UnknownBackendError(id, availableIds(), label);
+            const sid = getSessionId();
+            if (!sid) {
+                throw new Error(`No active MCP session — cannot store a ${label} selection`);
+            }
+            sweepExpired();
+            sessionSelections.set(sid, { id, selectedAt: now() });
+        },
+        clear(sessionId) {
+            sessionSelections.delete(sessionId);
+        },
+        list() {
+            return [...byId.values()].map((entry) => ({ id: entry.id, meta: entry.meta }));
+        },
+        getSelected() {
+            return stickySelection();
+        },
+    };
+}
+/**
+ * Lifts a handler written against a single resolved backend into one that
+ * resolves the backend from `registry` (override > sticky > single default)
+ * before delegating. The override is read from `args[paramName]`, so a tool
+ * adds backend selection by spreading an optional `{ [paramName]: z.string() }`
+ * into its input schema and wrapping its handler in `withBackend(...)`.
+ */
+export function withBackend(registry, paramName, fn) {
+    return (args) => {
+        const override = args[paramName];
+        const backend = registry.resolve(typeof override === "string" ? override : undefined);
+        return fn(backend, args);
+    };
+}
+//# sourceMappingURL=backend-registry.js.map

package/dist/tools/backend-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-registry.js","sourceRoot":"","sources":["../../src/tools/backend-registry.ts"],"names":[],"mappings":"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"}

package/dist/tools/create-framework-app.d.ts

@@ -0,0 +1,147 @@
+import { type McpServerInstance, type OAuthProvider, type ServerConfig } from "mcp-use/server";
+import { type DashboardStore } from "../framework/dashboard-store.js";
+import type { AppConfig, AppPlugin } from "../types/index.js";
+import { type AppResourceCsp } from "./register-framework-tools.js";
+export interface CreateFrameworkAppOptionsBase {
+    name: string;
+    version?: string;
+    /**
+     * Human-readable description of what the server does. Shown on mcp-use's
+     * built-in landing page (a browser `GET` on the MCP endpoint) and in
+     * `serverInfo`-adjacent surfaces.
+     */
+    description?: string;
+    /** Public base URL the server advertises (resource URIs, oauth callbacks). */
+    baseUrl?: string;
+    host?: string;
+    /**
+     * Pass-through of the remaining mcp-use {@link ServerConfig} handed to the
+     * `MCPServer` constructor. The main use case is wiring session/stream
+     * backends — e.g. Redis-backed `sessionStore` / `streamManager` so several
+     * server instances can share sessions — but any mcp-use server option
+     * (`stateless`, `cors`, `sessionIdleTimeoutMs`, `instructions`, …) works
+     * without the toolkit having to mirror it. The six toolkit-owned keys
+     * (`name`, `version`, `description`, `host`, `baseUrl`, `oauth`) are
+     * excluded via `Omit` because they are first-class options on this
+     * interface already; `oauth` additionally stays out because it selects the
+     * `MCPServer<true | false>` constructor overload.
+     */
+    serverOptions?: Omit<ServerConfig, "name" | "version" | "description" | "host" | "baseUrl" | "oauth">;
+    plugins: AppPlugin[];
+    middleware?: {
+        /** When set, every RPC must come from a token with this organization_id. */
+        orgGate?: string;
+        /** role → allowed module prefixes. Empty / missing → no restriction. */
+        roleFilter?: Record<string, string[]>;
+        /**
+         * When `true`, a `tools/call` whose tool name can't be resolved is *denied*
+         * rather than allowed through the {@link roleFilter} guard. Defaults to
+         * `false` for backward compatibility, but production deployments that rely
+         * on `roleFilter` for access control should set this to `true` so an
+         * unresolved name never slips past the module guard. Only meaningful
+         * alongside `roleFilter`.
+         */
+        roleFilterFailClosed?: boolean;
+    };
+    app: {
+        /**
+         * MCP UI resource URI that hosts the widget bundle. Optional — when
+         * omitted it is derived as `ui://<name>/mcp-app.<hash>.html`, content-
+         * hashing the file at {@link htmlPath} so each build yields a distinct,
+         * cache-busting URI (see `deriveAppResourceUri`). Pass an explicit value
+         * only to pin the URI.
+         */
+        resourceUri?: string;
+        /** Absolute path to the bundled `mcp-app.html` served under `resourceUri`. */
+        htmlPath: string;
+        /** Override the refresh tool name (default: `refresh-view`). */
+        refreshToolName?: string;
+        /**
+         * Additional CSP origins advertised on the widget resource
+         * (`_meta.ui.csp`) and widget tools (`openai/widgetCSP`). The origin of
+         * {@link CreateFrameworkAppOptionsBase.baseUrl} is always merged in, so
+         * most deployments never need this — set it only when widgets fetch from
+         * origins other than the server itself (e.g. a CDN).
+         */
+        csp?: AppResourceCsp;
+        /**
+         * Opt-in switch for the visual in-iframe builder platform and dashboard
+         * persistence. **Defaults to `false` (lean by default).**
+         *
+         * Widget rendering always works regardless of this flag:
+         * `get-framework-manifest`, `render-view`, and `refresh-view` (plus the
+         * `mcp-app.html` resource) are registered unconditionally — that is the
+         * core surface every MCP server gets.
+         *
+         * Setting `builder: true` additionally registers:
+         *   - `get-builder-catalogue` — the app-only data source the in-iframe
+         *     LayoutBuilder calls to populate its palette / key catalogue, and
+         *   - `save-dashboard` / `list-dashboards` / `load-dashboard` /
+         *     `delete-dashboard` — dashboard CRUD persistence.
+         *
+         * These belong together: the visual builder reads the catalogue and saves
+         * its results as dashboards. Most lean MCP servers don't need either and
+         * should leave this off so the builder/dashboard tools never get forced
+         * onto their tool surface. The `McpAppView`'s Build/edit affordance hides
+         * itself when the catalogue tool isn't present, so the iframe UI degrades
+         * gracefully when `builder` is `false`.
+         */
+        builder?: boolean;
+        /**
+         * Override the catalogue tool name (default: `get-builder-catalogue`).
+         * The catalogue tool is app-only — it powers the in-iframe builder
+         * and never appears in the LLM's tool surface. Only relevant when
+         * {@link builder} is `true`; ignored otherwise.
+         */
+        catalogueToolName?: string;
+        /**
+         * Persistence backing for `save-dashboard` / `list-dashboards` /
+         * `load-dashboard` / `delete-dashboard`. Defaults to an in-memory store
+         * (process-local, lost on restart). Inject a filesystem or DB-backed
+         * store for real deployments. Only relevant when {@link builder} is
+         * `true` — with `builder` off the dashboard tools aren't registered, so
+         * this option has no effect.
+         */
+        dashboardStore?: DashboardStore;
+    };
+    /** Supplies the non-empty set of apps each plugin represents. */
+    appConfig?: AppConfig;
+}
+/**
+ * `createFrameworkApp` options when OAuth is enabled. The returned server is
+ * typed as `MCPServer<true>`, so tool callbacks receive a non-nullable
+ * `ctx.auth`.
+ */
+export interface CreateFrameworkAppOptionsWithOAuth extends CreateFrameworkAppOptionsBase {
+    oauth: OAuthProvider;
+}
+/**
+ * `createFrameworkApp` options with OAuth disabled. The returned server is
+ * typed as `MCPServer<false>`, so tool callbacks treat `ctx.auth` as
+ * nullable.
+ */
+export interface CreateFrameworkAppOptionsWithoutOAuth extends CreateFrameworkAppOptionsBase {
+    oauth?: undefined;
+}
+export type CreateFrameworkAppOptions = CreateFrameworkAppOptionsWithOAuth | CreateFrameworkAppOptionsWithoutOAuth;
+/**
+ * Orchestrates a full Miranum-style MCP server: MCPServer construction,
+ * org-gate + role-filter middleware, per-plugin tool registration, and the
+ * framework-level tool trio (`get-framework-manifest`, `render-view`,
+ * `refresh-view`) + mcp-app.html resource.
+ *
+ * The server is deliberately self-contained: it serves only the first-party
+ * plugins passed in. Aggregating several MCP servers into one surface is an
+ * external gateway's job (e.g. agentgateway), not this framework's.
+ *
+ * OAuth is opt-in: pass an `oauth` provider to enable OAuth-gated routes and
+ * get an `MCPServer<true>` back, or omit it to boot without OAuth and get an
+ * `MCPServer<false>`. `ctx.auth` is still optionally present at runtime in
+ * both modes; the generic just reflects what's guaranteed.
+ *
+ * Returns the booted server before `.listen()` — the caller decides the port
+ * and the moment the server starts accepting traffic.
+ */
+export declare function createFrameworkApp(options: CreateFrameworkAppOptionsWithOAuth): Promise<McpServerInstance<true>>;
+export declare function createFrameworkApp(options: CreateFrameworkAppOptionsWithoutOAuth): Promise<McpServerInstance<false>>;
+//# sourceMappingURL=create-framework-app.d.ts.map

package/dist/tools/create-framework-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-framework-app.d.ts","sourceRoot":"","sources":["../../src/tools/create-framework-app.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAA;AAMvB,OAAO,EAAgC,KAAK,cAAc,EAAE,MAAM,iCAAiC,CAAA;AACnG,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAM3F,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,IAAI,CAClB,YAAY,EACZ,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAClE,CAAA;IACD,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,UAAU,CAAC,EAAE;QACX,4EAA4E;QAC5E,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,wEAAwE;QACxE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;QACrC;;;;;;;WAOG;QACH,oBAAoB,CAAC,EAAE,OAAO,CAAA;KAC/B,CAAA;IACD,GAAG,EAAE;QACH;;;;;;WAMG;QACH,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,8EAA8E;QAC9E,QAAQ,EAAE,MAAM,CAAA;QAChB,gEAAgE;QAChE,eAAe,CAAC,EAAE,MAAM,CAAA;QACxB;;;;;;WAMG;QACH,GAAG,CAAC,EAAE,cAAc,CAAA;QACpB;;;;;;;;;;;;;;;;;;;;;WAqBG;QACH,OAAO,CAAC,EAAE,OAAO,CAAA;QACjB;;;;;WAKG;QACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;QAC1B;;;;;;;WAOG;QACH,cAAc,CAAC,EAAE,cAAc,CAAA;KAChC,CAAA;IACD,iEAAiE;IACjE,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,kCAAmC,SAAQ,6BAA6B;IACvF,KAAK,EAAE,aAAa,CAAA;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,qCAAsC,SAAQ,6BAA6B;IAC1F,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAED,MAAM,MAAM,yBAAyB,GACnC,kCAAkC,GAAG,qCAAqC,CAAA;AAE5E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,kCAAkC,GAC1C,OAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAA;AACnC,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,qCAAqC,GAC7C,OAAO,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAA"}

package/dist/tools/create-framework-app.js

@@ -0,0 +1,111 @@
+import { MCPServer, } from "mcp-use/server";
+import { loadApps } from "../registry/app-loader.js";
+import { StepRegistry } from "../registry/step-registry.js";
+import { WidgetRegistry } from "../registry/widget-registry.js";
+import { createOrgGateMiddleware } from "../middleware/org-gate.js";
+import { createRoleFilterMiddleware } from "../middleware/role-filter.js";
+import { createInMemoryDashboardStore } from "../framework/dashboard-store.js";
+import { registerFrameworkTools } from "./register-framework-tools.js";
+import { registerCatalogueTool } from "./register-catalogue-tool.js";
+import { registerDashboardTools } from "./register-dashboard-tools.js";
+import { installToolCallNameCapture } from "./tool-call-name.js";
+import { deriveAppResourceUri } from "./app-resource-uri.js";
+// Async without an internal await today: the boot path became fully
+// synchronous when upstream discovery was removed, but the Promise return
+// stays — consumers `await` it, and future boot steps may be async again.
+// eslint-disable-next-line @typescript-eslint/require-await
+export async function createFrameworkApp(options) {
+    const baseConfig = {
+        name: options.name,
+        version: options.version ?? "0.1.0",
+        description: options.description,
+        host: options.host ?? "localhost",
+        baseUrl: options.baseUrl,
+    };
+    // `serverOptions` is statically disjoint from `baseConfig` (its type Omits
+    // every toolkit-owned key); the spread order is defense-in-depth so the
+    // toolkit's first-class options always win at runtime.
+    const server = options.oauth
+        ? new MCPServer({ ...options.serverOptions, ...baseConfig, oauth: options.oauth })
+        : new MCPServer({ ...options.serverOptions, ...baseConfig });
+    const orgGateId = options.middleware?.orgGate;
+    if (orgGateId) {
+        server.use("mcp:*", createOrgGateMiddleware(orgGateId));
+    }
+    // Capture the `tools/call` tool name from the JSON-RPC envelope at the HTTP
+    // layer. mcp-use 1.28 populates `mcp:tools/call` middleware's `ctx.params`
+    // with the tool *arguments*, not `{ name, arguments }`, so the role filter
+    // can't read the name from there. The resolver is request-scoped via
+    // `getRequestContext()` and is safe to install unconditionally.
+    const resolveToolName = installToolCallNameCapture(server);
+    const roleFilter = options.middleware?.roleFilter;
+    if (roleFilter && Object.keys(roleFilter).length > 0) {
+        const { toolsList, toolsCall } = createRoleFilterMiddleware(roleFilter, {
+            resolveToolName,
+            // Batch-aware: a JSON-RPC batch envelope can carry several tools/call
+            // requests; the guard must check all of them, not just the first.
+            resolveToolNames: resolveToolName.all,
+            failClosed: options.middleware?.roleFilterFailClosed ?? false,
+        });
+        server.use("mcp:tools/list", toolsList);
+        server.use("mcp:tools/call", toolsCall);
+    }
+    const stepRegistry = new StepRegistry();
+    const widgetRegistry = new WidgetRegistry();
+    // Plugin step/widget ids are author-controlled, so a collision is a real
+    // bug and must fail loud (hard throw).
+    const allPlugins = options.plugins;
+    loadApps(allPlugins.map((p) => p.definition), stepRegistry, widgetRegistry);
+    for (const plugin of allPlugins) {
+        plugin.registerTools?.(server);
+    }
+    // Per-app step configuration: each plugin's `appConfig` keyed by app name.
+    // A plugin may inject closures here (e.g. a typed `callTool`) — the pipeline
+    // executor pre-binds the per-request user context on any `callTool` it finds
+    // (see `pipeline-executor.ts:bindAppConfig`).
+    const appConfigs = Object.fromEntries(allPlugins.map((p) => [p.definition.name, p.appConfig ?? {}]));
+    const appConfig = options.appConfig ?? {
+        activeApps: allPlugins.map((p) => ({ app: p.definition.name, config: {} })),
+        pipelines: {},
+    };
+    // Derive a content-hashed resource URI when one isn't pinned, so each build
+    // busts the host's widget-bundle cache (a fixed URI would keep serving a
+    // stale bundle across restarts). `deriveAppResourceUri` warns and falls back
+    // to a stable dev URI when the bundle file is missing.
+    const resourceUri = options.app.resourceUri ??
+        deriveAppResourceUri({ appName: options.name, htmlPath: options.app.htmlPath });
+    registerFrameworkTools(server, {
+        stepRegistry,
+        widgetRegistry,
+        config: appConfig,
+        appConfigs,
+        plugins: allPlugins,
+        resourceUri,
+        htmlPath: options.app.htmlPath,
+        refreshToolName: options.app.refreshToolName,
+        // Advertise builder availability in the view payload so the iframe shell
+        // shows its Build affordance only when the catalogue/dashboard tools below
+        // are actually registered.
+        builderAvailable: options.app.builder ?? false,
+        // Feeds the widget-resource CSP (`_meta.ui.csp` + `openai/widgetCSP`):
+        // the baseUrl origin is auto-injected next to any explicit `app.csp`.
+        baseUrl: options.baseUrl,
+        csp: options.app.csp,
+    });
+    // The visual builder platform is opt-in: the catalogue (its data source)
+    // and the dashboard CRUD tools (its persistence) are registered together
+    // only when `app.builder` is true. Lean servers leave it off so render-view
+    // / the widget core stay the entire surface. See the `app.builder` TSDoc.
+    if (options.app.builder) {
+        registerCatalogueTool(server, {
+            stepRegistry,
+            widgetRegistry,
+            appConfigs,
+            toolName: options.app.catalogueToolName,
+        });
+        const dashboardStore = options.app.dashboardStore ?? createInMemoryDashboardStore();
+        registerDashboardTools(server, { store: dashboardStore, widgetRegistry });
+    }
+    return server;
+}
+//# sourceMappingURL=create-framework-app.js.map

package/dist/tools/create-framework-app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-framework-app.js","sourceRoot":"","sources":["../../src/tools/create-framework-app.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -0,0 +1,22 @@
+export { createToolRegistrar } from "./register-tool.js";
+export type { ToolConfig, RegisteredToolMeta } from "./register-tool.js";
+export { createWidgetToolRegistrar } from "./register-widget-tool.js";
+export type { WidgetToolConfig, WidgetToolVisibility } from "./register-widget-tool.js";
+export { withToolErrors } from "./with-tool-errors.js";
+export { registerFrameworkTools, buildAppResourceCsp } from "./register-framework-tools.js";
+export type { RegisterFrameworkToolsOptions, AppResourceCsp } from "./register-framework-tools.js";
+export { registerCatalogueTool } from "./register-catalogue-tool.js";
+export type { RegisterCatalogueToolOptions } from "./register-catalogue-tool.js";
+export { registerDashboardTools } from "./register-dashboard-tools.js";
+export type { RegisterDashboardToolsOptions } from "./register-dashboard-tools.js";
+export { createFrameworkApp } from "./create-framework-app.js";
+export type { CreateFrameworkAppOptions } from "./create-framework-app.js";
+export { deriveAppResourceUri } from "./app-resource-uri.js";
+export type { DeriveAppResourceUriInput } from "./app-resource-uri.js";
+export { createBackendRegistry, withBackend, BackendNotSelectedError, UnknownBackendError, DEFAULT_BACKEND_SESSION_TTL_MS, } from "./backend-registry.js";
+export type { BackendRegistry, BackendEntry, ResolvedBackend, CreateBackendRegistryOptions, } from "./backend-registry.js";
+export { installToolCallNameCapture, extractToolCallName, extractToolCallNames, } from "./tool-call-name.js";
+export type { ToolNameResolver, ToolNameCapture } from "./tool-call-name.js";
+export { createInMemoryDashboardStore, createFileSystemDashboardStore, DashboardOwnershipError, resolveSavedRecord, parseDashboardRecord, DASHBOARD_SCHEMA_VERSION, } from "../framework/dashboard-store.js";
+export type { DashboardStore, DashboardRecord, DashboardSaveInput, DashboardSummary, DashboardListFilter, FileSystemDashboardStoreOptions, } from "../framework/dashboard-store.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAA;AACrE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAA;AAC3F,YAAY,EAAE,6BAA6B,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAClG,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AACpE,YAAY,EAAE,4BAA4B,EAAE,MAAM,8BAA8B,CAAA;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAA;AACtE,YAAY,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAA;AAClF,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,YAAY,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAA;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAC5D,YAAY,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAA;AACtE,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,uBAAuB,EACvB,mBAAmB,EACnB,8BAA8B,GAC/B,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EACV,eAAe,EACf,YAAY,EACZ,eAAe,EACf,4BAA4B,GAC7B,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAK5E,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,EAC9B,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,iCAAiC,CAAA;AACxC,YAAY,EACV,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,+BAA+B,GAChC,MAAM,iCAAiC,CAAA"}

package/dist/tools/index.js

@@ -0,0 +1,15 @@
+export { createToolRegistrar } from "./register-tool.js";
+export { createWidgetToolRegistrar } from "./register-widget-tool.js";
+export { withToolErrors } from "./with-tool-errors.js";
+export { registerFrameworkTools, buildAppResourceCsp } from "./register-framework-tools.js";
+export { registerCatalogueTool } from "./register-catalogue-tool.js";
+export { registerDashboardTools } from "./register-dashboard-tools.js";
+export { createFrameworkApp } from "./create-framework-app.js";
+export { deriveAppResourceUri } from "./app-resource-uri.js";
+export { createBackendRegistry, withBackend, BackendNotSelectedError, UnknownBackendError, DEFAULT_BACKEND_SESSION_TTL_MS, } from "./backend-registry.js";
+export { installToolCallNameCapture, extractToolCallName, extractToolCallNames, } from "./tool-call-name.js";
+// Dashboard-store implementations are server-side (the filesystem impl
+// imports `node:fs`). Consumers wire them through `createFrameworkApp`'s
+// `app.dashboardStore`.
+export { createInMemoryDashboardStore, createFileSystemDashboardStore, DashboardOwnershipError, resolveSavedRecord, parseDashboardRecord, DASHBOARD_SCHEMA_VERSION, } from "../framework/dashboard-store.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAExD,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAA;AAErE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAA;AAE3F,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AAEpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAA;AAEtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAE9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAE5D,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,uBAAuB,EACvB,mBAAmB,EACnB,8BAA8B,GAC/B,MAAM,uBAAuB,CAAA;AAO9B,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,qBAAqB,CAAA;AAG5B,uEAAuE;AACvE,yEAAyE;AACzE,wBAAwB;AACxB,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,EAC9B,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,iCAAiC,CAAA"}

package/dist/tools/register-catalogue-tool.d.ts

@@ -0,0 +1,22 @@
+import { type MCPServer } from "mcp-use/server";
+import type { StepRegistry } from "../registry/step-registry.js";
+import type { WidgetRegistry } from "../registry/widget-registry.js";
+export interface RegisterCatalogueToolOptions {
+    stepRegistry: StepRegistry;
+    widgetRegistry: WidgetRegistry;
+    appConfigs: Record<string, Record<string, unknown>>;
+    /** Override the tool name (default: `get-builder-catalogue`). */
+    toolName?: string;
+}
+/**
+ * Registers `get-builder-catalogue` — the in-iframe builder's data
+ * source. App-only (`visibility: ["app"]`), so it never appears in the
+ * LLM's `tools/list`. The LayoutBuilder calls it on mount and on each
+ * keys/steps edit; the LLM uses `render-view` for its own work.
+ *
+ * Registered by `createFrameworkApp` only when `app.builder` is `true` —
+ * the visual builder platform is opt-in (lean by default). When the builder
+ * is off this tool is absent and the `McpAppView` hides its Build affordance.
+ */
+export declare function registerCatalogueTool(server: MCPServer, options: RegisterCatalogueToolOptions): void;
+//# sourceMappingURL=register-catalogue-tool.d.ts.map

package/dist/tools/register-catalogue-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-catalogue-tool.d.ts","sourceRoot":"","sources":["../../src/tools/register-catalogue-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAG/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AAGpE,MAAM,WAAW,4BAA4B;IAC3C,YAAY,EAAE,YAAY,CAAA;IAC1B,cAAc,EAAE,cAAc,CAAA;IAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACnD,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,4BAA4B,GACpC,IAAI,CAsBN"}

package/dist/tools/register-catalogue-tool.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { getBuilderCatalogue } from "../framework/catalogue.js";
+import { APP_ONLY_META } from "../types/meta.js";
+const stepRefSchema = z.object({
+    id: z.string(),
+    step: z.string(),
+    optional: z.boolean().optional(),
+});
+const catalogueSchema = z.object({
+    keys: z.record(z.string(), z.unknown()).optional(),
+    steps: z.array(stepRefSchema).optional(),
+});
+function extractUserId(ctx) {
+    const user = ctx?.auth?.user;
+    return typeof user?.userId === "string" ? user.userId : undefined;
+}
+/**
+ * Registers `get-builder-catalogue` — the in-iframe builder's data
+ * source. App-only (`visibility: ["app"]`), so it never appears in the
+ * LLM's `tools/list`. The LayoutBuilder calls it on mount and on each
+ * keys/steps edit; the LLM uses `render-view` for its own work.
+ *
+ * Registered by `createFrameworkApp` only when `app.builder` is `true` —
+ * the visual builder platform is opt-in (lean by default). When the builder
+ * is off this tool is absent and the `McpAppView` hides its Build affordance.
+ */
+export function registerCatalogueTool(server, options) {
+    const { stepRegistry, widgetRegistry, appConfigs, toolName = "get-builder-catalogue" } = options;
+    server.tool({
+        name: toolName,
+        title: "Get Builder Catalogue",
+        description: "App-only. Returns the live pipeline context plus the reachable / unreachable widgets, available steps and key catalogue for the current keys + steps. Used by the in-iframe LayoutBuilder.",
+        schema: catalogueSchema,
+        _meta: APP_ONLY_META,
+    }, async (params, ctx) => {
+        return getBuilderCatalogue({
+            input: { keys: params.keys, steps: params.steps },
+            stepRegistry,
+            widgetRegistry,
+            appConfigs,
+            ctx: { userId: extractUserId(ctx) },
+        });
+    });
+}
+//# sourceMappingURL=register-catalogue-tool.js.map

package/dist/tools/register-catalogue-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-catalogue-tool.js","sourceRoot":"","sources":["../../src/tools/register-catalogue-tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAG/D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAUhD,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAA;AAEF,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IAClD,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE;CACzC,CAAC,CAAA;AAEF,SAAS,aAAa,CAAC,GAAY;IACjC,MAAM,IAAI,GAAI,GAA8D,EAAE,IAAI,EAAE,IAAI,CAAA;IACxF,OAAO,OAAO,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;AACnE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAiB,EACjB,OAAqC;IAErC,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,GAAG,uBAAuB,EAAE,GAAG,OAAO,CAAA;IAEhG,MAAM,CAAC,IAAI,CACT;QACE,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EACT,4LAA4L;QAC9L,MAAM,EAAE,eAAe;QACvB,KAAK,EAAE,aAAa;KACrB,EACD,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE;QACpB,OAAO,mBAAmB,CAAC;YACzB,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE;YACjD,YAAY;YACZ,cAAc;YACd,UAAU;YACV,GAAG,EAAE,EAAE,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE;SACpC,CAAC,CAAA;IACJ,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/tools/register-dashboard-tools.d.ts

@@ -0,0 +1,32 @@
+import { type MCPServer } from "mcp-use/server";
+import type { DashboardStore } from "../framework/dashboard-store.js";
+import type { WidgetRegistry } from "../registry/widget-registry.js";
+export interface RegisterDashboardToolsOptions {
+    store: DashboardStore;
+    /**
+     * Optional widget registry used by `save-dashboard` to warn (never reject)
+     * when a layout references widget ids the server doesn't know about —
+     * usually a typo, surfaced as a non-fatal warning so a save is never
+     * blocked on a cosmetic mistake. Omit to skip the check entirely.
+     */
+    widgetRegistry?: WidgetRegistry;
+}
+/**
+ * Registers `save-dashboard`, `list-dashboards`, `load-dashboard`, and
+ * `delete-dashboard`. The tools are thin CRUD wrappers around the injected
+ * `DashboardStore`; auth scoping is applied here (never in the store) via
+ * the standard `ctx.auth.user.userId` extraction.
+ *
+ * `load-dashboard` returns the full record as JSON in `content[0].text`
+ * (mirrored into `structuredContent`) so the model itself receives the
+ * bundle — `structuredContent` alone is "not added to model context" per
+ * MCP. The `{ keys, steps, layout, title }` fields can be piped straight
+ * into `render-view` to re-render the saved dashboard.
+ *
+ * Registered by `createFrameworkApp` only when `app.builder` is `true` —
+ * dashboard persistence is part of the opt-in visual builder platform
+ * (lean by default). With the builder off, none of these tools exist and
+ * the `app.dashboardStore` option has no effect.
+ */
+export declare function registerDashboardTools(server: MCPServer, options: RegisterDashboardToolsOptions): void;
+//# sourceMappingURL=register-dashboard-tools.d.ts.map

package/dist/tools/register-dashboard-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-dashboard-tools.d.ts","sourceRoot":"","sources":["../../src/tools/register-dashboard-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAU,MAAM,gBAAgB,CAAA;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AAGrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AAEpE,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE,cAAc,CAAA;IACrB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,cAAc,CAAA;CAChC;AA8BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,6BAA6B,GACrC,IAAI,CA0HN"}