@miragon/mcp-toolkit-core 0.10.1

package/dist/tools/register-dashboard-tools.js

@@ -0,0 +1,149 @@
+import { object } from "mcp-use/server";
+import { z } from "zod";
+import { collectLayoutWidgets } from "../framework/view-builders.js";
+import { layoutSchema } from "../framework/layout-schemas.js";
+const stepRefSchema = z.object({
+    id: z.string(),
+    step: z.string(),
+    optional: z.boolean().optional(),
+});
+const saveSchema = z.object({
+    id: z
+        .string()
+        .optional()
+        .describe("Existing dashboard id to update. Omit to create a new record."),
+    name: z.string().describe("Human-readable dashboard name shown in lists."),
+    description: z.string().optional(),
+    keys: z.record(z.string(), z.unknown()).optional(),
+    steps: z.array(stepRefSchema).optional(),
+    layout: layoutSchema,
+    title: z.string().optional().describe("View title rendered above the widget grid."),
+});
+const idSchema = z.object({
+    id: z.string().describe("Dashboard id as returned by `save-dashboard` or `list-dashboards`."),
+});
+function extractUserId(ctx) {
+    const user = ctx?.auth?.user;
+    return typeof user?.userId === "string" ? user.userId : undefined;
+}
+/**
+ * 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 function registerDashboardTools(server, options) {
+    const { store, widgetRegistry } = options;
+    server.tool({
+        name: "save-dashboard",
+        title: "Save Dashboard",
+        description: "Persists a dashboard (render-view input bundle + name). Pass an existing `id` to update, omit to create. The builder UI's Save button invokes this tool.",
+        schema: saveSchema,
+    }, async (params, ctx) => {
+        // Warn (never reject) on unknown widget ids — usually a typo. A save is
+        // deliberately never blocked on a cosmetic layout mistake; the unknown
+        // ids surface in the text summary so the user can spot and fix it.
+        const unknownWidgets = widgetRegistry
+            ? [...new Set(collectLayoutWidgets(params.layout))].filter((id) => !widgetRegistry.get(id))
+            : [];
+        const record = await store.save({
+            id: params.id,
+            name: params.name,
+            description: params.description,
+            userId: extractUserId(ctx),
+            keys: params.keys,
+            steps: params.steps,
+            layout: params.layout,
+            title: params.title,
+        });
+        const summaryLines = [
+            `Saved dashboard "${record.name}" (${record.id}).`,
+            unknownWidgets.length > 0
+                ? `Warning: layout references widget ids not registered on this server: ${unknownWidgets.join(", ")}. They will not render — check for typos or register the widgets.`
+                : "",
+        ].filter(Boolean);
+        return {
+            content: [{ type: "text", text: summaryLines.join("\n") }],
+            structuredContent: {
+                id: record.id,
+                name: record.name,
+                createdAt: record.createdAt,
+                updatedAt: record.updatedAt,
+                ...(unknownWidgets.length > 0 ? { unknownWidgets } : {}),
+            },
+        };
+    });
+    server.tool({
+        name: "list-dashboards",
+        title: "List Dashboards",
+        description: "Returns the dashboards visible to the caller (scoped by userId when auth is enabled). Metadata only — fetch a full record via `load-dashboard`.",
+        annotations: { readOnlyHint: true },
+    }, async (_params, ctx) => {
+        const items = await store.list({ userId: extractUserId(ctx) });
+        return object({ items });
+    });
+    server.tool({
+        name: "load-dashboard",
+        title: "Load Dashboard",
+        description: "Returns the full dashboard bundle. The returned `{ keys, steps, layout, title }` fields can be handed straight to `render-view`.",
+        schema: idSchema,
+        annotations: { readOnlyHint: true },
+    }, async ({ id }, ctx) => {
+        const record = await store.get(id, { userId: extractUserId(ctx) });
+        if (!record) {
+            return {
+                content: [{ type: "text", text: `Dashboard "${id}" not found.` }],
+                isError: true,
+            };
+        }
+        // Validate the persisted layout before handing it back: a corrupted
+        // store file could otherwise feed a malformed layout straight into
+        // `render-view` (and the model). Surface a clear error instead of
+        // silently forwarding garbage.
+        const parsed = layoutSchema.safeParse(record.layout);
+        if (!parsed.success) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Dashboard "${id}" has an invalid layout and cannot be loaded: ${parsed.error.issues
+                            .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+                            .join("; ")}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return object(record);
+    });
+    server.tool({
+        name: "delete-dashboard",
+        title: "Delete Dashboard",
+        description: "Permanently removes a dashboard by id.",
+        schema: idSchema,
+    }, async ({ id }, ctx) => {
+        const deleted = await store.delete(id, { userId: extractUserId(ctx) });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: deleted ? `Deleted dashboard "${id}"` : `Dashboard "${id}" not found.`,
+                },
+            ],
+            structuredContent: { deleted },
+            isError: !deleted,
+        };
+    });
+}
+//# sourceMappingURL=register-dashboard-tools.js.map

package/dist/tools/register-dashboard-tools.js.map

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

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

@@ -0,0 +1,83 @@
+import { type MCPServer } from "mcp-use/server";
+import type { StepRegistry } from "../registry/step-registry.js";
+import type { WidgetRegistry } from "../registry/widget-registry.js";
+import type { AppConfig, AppPlugin } from "../types/index.js";
+/**
+ * CSP advertised on the widget resource, in the SEP-1865 camelCase shape
+ * (`_meta.ui.csp`). All entries are full origins (e.g. `https://server.example`).
+ * The Apps SDK tool-meta variant (`openai/widgetCSP`, snake_cased) is derived
+ * from the same value.
+ */
+export interface AppResourceCsp {
+    /** Origins allowed for fetch/XHR/WebSocket from inside the widget iframe. */
+    connectDomains?: string[];
+    /** Origins allowed for images, scripts, stylesheets, fonts. */
+    resourceDomains?: string[];
+    /** Allowed iframe origins. */
+    frameDomains?: string[];
+    /** Allowed `base-uri` origins. */
+    baseUriDomains?: string[];
+}
+export interface RegisterFrameworkToolsOptions {
+    stepRegistry: StepRegistry;
+    widgetRegistry: WidgetRegistry;
+    config: AppConfig;
+    appConfigs: Record<string, Record<string, unknown>>;
+    plugins: AppPlugin[];
+    /**
+     * The MCP UI resource URI that hosts the widget bundle (typically the
+     * compiled `mcp-app.html`). Referenced by `render-view` / `refresh-view`
+     * via the `_meta.ui.resourceUri` convention.
+     */
+    resourceUri: string;
+    /** Absolute path to the bundled `mcp-app.html` served behind `resourceUri`. */
+    htmlPath: string;
+    /**
+     * Tool name for the refresh hook the UI calls to re-run the pipeline.
+     * The `@miragon/mcp-toolkit-ui` default matches this — change both in
+     * sync if you override.
+     */
+    refreshToolName?: string;
+    /**
+     * Whether the in-iframe visual builder platform is enabled (i.e.
+     * `app.builder` is true and `get-builder-catalogue` is registered).
+     * Forwarded into every `render-view` / `refresh-view` payload as
+     * `structuredContent.builderAvailable` so the `McpAppView` shell only
+     * shows its Build affordance when the server can service it. Defaults to
+     * `false`.
+     */
+    builderAvailable?: boolean;
+    /**
+     * Public base URL the server advertises. Its origin is auto-injected into
+     * the resource CSP's connect/resource/baseUri domains — mirroring native
+     * mcp-use's server-origin enrichment — so widgets can reach the server
+     * origin without CSP violations. Without it (and without {@link csp}) the
+     * resource advertises no CSP, which ext-apps hosts treat as the secure
+     * "no network" default; fine for a fully inlined bundle.
+     */
+    baseUrl?: string;
+    /**
+     * Additional CSP origins advertised on the widget resource
+     * (`_meta.ui.csp`) and, snake_cased, on widget tools (`openai/widgetCSP`).
+     * Merged with the origin derived from {@link baseUrl}.
+     */
+    csp?: AppResourceCsp;
+}
+/**
+ * Merges the configured CSP with the server origin derived from `baseUrl`
+ * (injected into connect/resource/baseUri domains, deduplicated) — the same
+ * enrichment native mcp-use applies to its widget definitions. Returns
+ * `undefined` when there is nothing to advertise.
+ */
+export declare function buildAppResourceCsp(baseUrl: string | undefined, csp: AppResourceCsp | undefined): AppResourceCsp | undefined;
+/**
+ * Registers the framework-level MCP tools that make up a Miranum-style MCP
+ * app: the manifest tool, the `render-view` / `refresh-view` pair, the widget
+ * bundle resource, plus any widget-action tools each plugin contributes.
+ *
+ * Intended to be called from `createFrameworkApp`, but exposed directly so
+ * consumers that build their own server can still opt into the framework
+ * tools without the rest of the boot helper.
+ */
+export declare function registerFrameworkTools(server: MCPServer, options: RegisterFrameworkToolsOptions): void;
+//# sourceMappingURL=register-framework-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register-framework-tools.d.ts","sourceRoot":"","sources":["../../src/tools/register-framework-tools.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,KAAK,SAAS,EAA4B,MAAM,gBAAgB,CAAA;AAKhG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAG7D;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,kCAAkC;IAClC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,6BAA6B;IAC5C,YAAY,EAAE,YAAY,CAAA;IAC1B,cAAc,EAAE,cAAc,CAAA;IAC9B,MAAM,EAAE,SAAS,CAAA;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACnD,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,GAAG,CAAC,EAAE,cAAc,CAAA;CACrB;AA+CD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,GAAG,EAAE,cAAc,GAAG,SAAS,GAC9B,cAAc,GAAG,SAAS,CAgB5B;AAYD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,6BAA6B,GACrC,IAAI,CAyGN"}

package/dist/tools/register-framework-tools.js

@@ -0,0 +1,154 @@
+import fs from "node:fs/promises";
+import { createMcpAppsResource, RESOURCE_MIME_TYPE, text } from "mcp-use/server";
+import { z } from "zod";
+import { getFrameworkManifest } from "../framework/manifest.js";
+import { layoutInputSchema } from "../framework/layout-schemas.js";
+import { renderView } from "../framework/render-view.js";
+import { uiMeta } from "../types/meta.js";
+const stepRefSchema = z.object({
+    id: z.string().describe("Context key under which the step's result is stored, e.g. 'invoice'."),
+    step: z.string().describe("Registered step id, e.g. 'lexoffice:load-invoice'."),
+    optional: z.boolean().optional(),
+});
+const renderViewSchema = z.object({
+    keys: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Keys the widgets will receive, e.g. { 'lexoffice:invoiceId': '…' }."),
+    steps: z
+        .array(stepRefSchema)
+        .optional()
+        .describe("Optional pipeline steps to compute keys before rendering. Without steps only the passed-in keys are used."),
+    // `layoutInputSchema` (not `layoutSchema`): also accepts the layout as a
+    // JSON-encoded string — hosts confronted with the type-less `anyOf` this
+    // union emits sometimes stringify the parameter (see layout-schemas.ts).
+    layout: layoutInputSchema,
+    title: z.string().optional().describe("Optional view title."),
+});
+function extractUserId(ctx) {
+    const user = ctx?.auth?.user;
+    return typeof user?.userId === "string" ? user.userId : undefined;
+}
+function withOrigin(list, origin) {
+    if (!list)
+        return [origin];
+    return list.includes(origin) ? list : [...list, origin];
+}
+/**
+ * Merges the configured CSP with the server origin derived from `baseUrl`
+ * (injected into connect/resource/baseUri domains, deduplicated) — the same
+ * enrichment native mcp-use applies to its widget definitions. Returns
+ * `undefined` when there is nothing to advertise.
+ */
+export function buildAppResourceCsp(baseUrl, csp) {
+    let origin;
+    if (baseUrl) {
+        try {
+            origin = new URL(baseUrl).origin;
+        }
+        catch {
+            // Invalid baseUrl — skip origin injection rather than failing boot.
+        }
+    }
+    if (!origin)
+        return csp;
+    return {
+        ...csp,
+        connectDomains: withOrigin(csp?.connectDomains, origin),
+        resourceDomains: withOrigin(csp?.resourceDomains, origin),
+        baseUriDomains: withOrigin(csp?.baseUriDomains, origin),
+    };
+}
+/** Converts the camelCase resource CSP into the snake_cased `openai/widgetCSP` shape. */
+function toWidgetCspMeta(csp) {
+    const meta = {};
+    if (csp.connectDomains)
+        meta.connect_domains = csp.connectDomains;
+    if (csp.resourceDomains)
+        meta.resource_domains = csp.resourceDomains;
+    if (csp.frameDomains)
+        meta.frame_domains = csp.frameDomains;
+    if (csp.baseUriDomains)
+        meta.base_uri_domains = csp.baseUriDomains;
+    return meta;
+}
+/**
+ * Registers the framework-level MCP tools that make up a Miranum-style MCP
+ * app: the manifest tool, the `render-view` / `refresh-view` pair, the widget
+ * bundle resource, plus any widget-action tools each plugin contributes.
+ *
+ * Intended to be called from `createFrameworkApp`, but exposed directly so
+ * consumers that build their own server can still opt into the framework
+ * tools without the rest of the boot helper.
+ */
+export function registerFrameworkTools(server, options) {
+    const { stepRegistry, widgetRegistry, config, appConfigs, plugins, resourceUri, htmlPath, refreshToolName = "refresh-view", builderAvailable = false, baseUrl, csp, } = options;
+    const resourceCsp = buildAppResourceCsp(baseUrl, csp);
+    const widgetCSP = resourceCsp ? toWidgetCspMeta(resourceCsp) : undefined;
+    server.tool({
+        name: "get-framework-manifest",
+        description: "Returns all active apps, available pipeline steps, widgets, and their key contracts. Call this first to discover which step-ids and widget-ids exist — and which `props` each widget accepts (see each widget's `propsSchema`) — before building a view.",
+        annotations: { readOnlyHint: true },
+    }, 
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async () => {
+        const manifest = getFrameworkManifest(stepRegistry, widgetRegistry, config);
+        return text(JSON.stringify(manifest, null, 2));
+    });
+    const renderHandler = async (params, ctx) => {
+        return renderView({
+            input: {
+                keys: params.keys,
+                steps: params.steps,
+                layout: params.layout,
+                title: params.title,
+            },
+            stepRegistry,
+            appConfigs,
+            ctx: { userId: extractUserId(ctx) },
+            builderAvailable,
+        });
+    };
+    server.tool({
+        name: "render-view",
+        title: "Render View",
+        description: "Builds a UI from pipeline steps and widgets. IMPORTANT: call get-framework-manifest first to learn which step-ids and widget-ids are available — only use ids listed there. Each widget entry's optional `propsSchema` (JSON Schema) describes the per-instance `props` you can set on a layout cell to scope or configure that widget (e.g. one tab per `processDefinitionKey`).",
+        schema: renderViewSchema,
+        _meta: uiMeta({
+            resourceUri,
+            title: "Render View",
+            invoking: "Rendering view...",
+            invoked: "View rendered",
+            widgetDescription: "Interactive view composed of pipeline-driven widgets",
+            widgetCSP,
+        }),
+    }, renderHandler);
+    for (const plugin of plugins) {
+        plugin.registerWidgetTools?.(server, resourceUri, { widgetCSP });
+    }
+    server.tool({
+        name: refreshToolName,
+        title: "Refresh View",
+        description: "Re-runs the pipeline with the stored parameters.",
+        schema: renderViewSchema,
+        _meta: uiMeta({ resourceUri, appOnly: true }),
+    }, renderHandler);
+    // The resource `_meta.ui.csp` must appear on the LISTING (resources/list)
+    // and on the READ contents — ext-apps hosts read it from the contents when
+    // sandboxing the iframe. `createMcpAppsResource` produces exactly the shape
+    // native mcp-use emits (mimeType `text/html;profile=mcp-app` + `_meta.ui`).
+    const resourceMeta = resourceCsp ? { ui: { csp: resourceCsp } } : undefined;
+    server.resource({
+        name: "mcp-app-html",
+        uri: resourceUri,
+        mimeType: RESOURCE_MIME_TYPE,
+        ...(resourceMeta ? { _meta: resourceMeta } : {}),
+    }, async () => {
+        // Read lazily per request so dev servers pick up a rebuilt bundle
+        // without a restart (same behaviour as before).
+        const html = await fs.readFile(htmlPath, "utf-8");
+        const uiResource = createMcpAppsResource(resourceUri, html, resourceCsp ? { csp: resourceCsp } : undefined);
+        return { contents: [uiResource.resource] };
+    });
+}
+//# sourceMappingURL=register-framework-tools.js.map

package/dist/tools/register-framework-tools.js.map

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

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

@@ -0,0 +1,45 @@
+import { type MCPServer } from "mcp-use/server";
+import { z } from "zod";
+type ZodRawShape = Record<string, z.ZodTypeAny>;
+/**
+ * The validated args a handler receives. When an `inputSchema` shape is
+ * declared, this is inferred from it (`z.infer`), so handlers get precise types
+ * for free instead of a loose `Record<string, any>`. With no `inputSchema` it
+ * falls back to a permissive record, matching the pre-generic behaviour.
+ */
+export type ToolArgs<TShape extends ZodRawShape = ZodRawShape> = z.infer<z.ZodObject<TShape>>;
+export interface ToolConfig<TClient, TShape extends ZodRawShape = ZodRawShape> {
+    name: string;
+    description: string;
+    category?: string;
+    inputSchema?: TShape;
+    /**
+     * Zod schema describing the tool's structured output. Mirrored into the
+     * MCP `outputSchema` advertised to clients and used to populate
+     * `structuredContent` on each response.
+     *
+     * If you pass a `z.array(...)`, the schema is auto-wrapped to
+     * `z.object({ data: <array> })` because MCP requires `structuredContent`
+     * to be an object. The runtime wrapping happens automatically too — your
+     * handler can return either the bare array or `{ data: [...] }`.
+     */
+    outputSchema?: z.ZodTypeAny;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+    handler: (client: TClient, args: ToolArgs<TShape>) => Promise<unknown>;
+    formatResult?: (result: unknown, args: ToolArgs<TShape>) => string;
+}
+export interface RegisteredToolMeta {
+    name: string;
+    category?: string;
+}
+export declare function createToolRegistrar<TClient>(server: MCPServer, client: TClient): {
+    <TShape extends ZodRawShape = ZodRawShape>(config: ToolConfig<TClient, TShape>): void;
+    getRegisteredTools(): RegisteredToolMeta[];
+};
+export {};
+//# sourceMappingURL=register-tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register-tool.d.ts","sourceRoot":"","sources":["../../src/tools/register-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAuB,MAAM,gBAAgB,CAAA;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAA;AAK/C;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,CAAC,MAAM,SAAS,WAAW,GAAG,WAAW,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAA;AAE7F,MAAM,WAAW,UAAU,CAAC,OAAO,EAAE,MAAM,SAAS,WAAW,GAAG,WAAW;IAC3E,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,CAAC,CAAC,UAAU,CAAA;IAC3B,WAAW,CAAC,EAAE;QACZ,YAAY,CAAC,EAAE,OAAO,CAAA;QACtB,eAAe,CAAC,EAAE,OAAO,CAAA;QACzB,cAAc,CAAC,EAAE,OAAO,CAAA;QACxB,aAAa,CAAC,EAAE,OAAO,CAAA;KACxB,CAAA;IACD,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACtE,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,MAAM,CAAA;CACnE;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AA+BD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO;KAG3D,MAAM,SAAS,WAAW,wBAAwB,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC;;EAmDhG"}

package/dist/tools/register-tool.js

@@ -0,0 +1,82 @@
+import { array, object, text } from "mcp-use/server";
+import { z } from "zod";
+import { withToolErrors } from "./with-tool-errors.js";
+function wrapArraySchema(schema) {
+    if (!schema)
+        return undefined;
+    return schema instanceof z.ZodArray ? z.object({ data: schema }) : schema;
+}
+/**
+ * Coerces a handler result into the `structuredContent` object shape MCP
+ * requires, mirroring {@link wrapArraySchema}: bare arrays become `{ data }`,
+ * objects pass through.
+ *
+ * A declared `outputSchema` is a promise to the client that this tool emits an
+ * *object* `structuredContent`. If the handler instead returns a scalar,
+ * `null`, or `undefined`, the SDK would reject the response with an opaque
+ * protocol error ("has an output schema but no structured content" / "invalid
+ * structured content"). We turn that into a clear, house-style tool error
+ * instead — thrown here and caught by {@link withToolErrors}, which surfaces it
+ * as an `isError` result the SDK passes through without output-schema
+ * validation.
+ */
+function toStructuredContent(result, toolName) {
+    if (Array.isArray(result))
+        return { data: result };
+    if (result !== null && typeof result === "object")
+        return result;
+    const kind = result === null ? "null" : typeof result;
+    throw new Error(`Tool "${toolName}" declares an outputSchema but its handler returned a ${kind} value; ` +
+        `structured output must be an object or array.`);
+}
+export function createToolRegistrar(server, client) {
+    const registeredTools = [];
+    function register(config) {
+        registeredTools.push({ name: config.name, category: config.category });
+        server.tool({
+            name: config.name,
+            description: config.description,
+            schema: config.inputSchema ? z.object(config.inputSchema) : undefined,
+            outputSchema: wrapArraySchema(config.outputSchema),
+            annotations: config.annotations,
+        }, 
+        // The SDK validates args against the schema above, so the loose callback
+        // arg is safely the handler's precise `ToolArgs<TShape>`.
+        withToolErrors(async (looseArgs) => {
+            const args = looseArgs;
+            const result = await config.handler(client, args);
+            if (config.formatResult) {
+                const formatted = text(config.formatResult(result, args));
+                // When an outputSchema is declared the tool promised structured
+                // output, so mirror the raw result into structuredContent alongside
+                // the human-readable text instead of dropping it. Without an
+                // outputSchema the formatResult path stays text-only as before.
+                if (config.outputSchema) {
+                    return { ...formatted, structuredContent: toStructuredContent(result, config.name) };
+                }
+                return formatted;
+            }
+            if (Array.isArray(result)) {
+                return array(result);
+            }
+            if (result !== null && typeof result === "object") {
+                return object(result);
+            }
+            // A declared outputSchema requires an object `structuredContent`; a
+            // scalar/null/undefined result would make the SDK reject the response
+            // with an opaque protocol error. Surface a clear tool error instead
+            // (see toStructuredContent). Without an outputSchema, the text-only
+            // fallbacks below are valid.
+            if (config.outputSchema) {
+                return object(toStructuredContent(result, config.name));
+            }
+            if (result !== null && result !== undefined) {
+                return text(JSON.stringify(result, null, 2));
+            }
+            return text("Success (no content returned)");
+        }));
+    }
+    register.getRegisteredTools = () => registeredTools;
+    return register;
+}
+//# sourceMappingURL=register-tool.js.map

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

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

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

@@ -0,0 +1,51 @@
+import { type MCPServer, type ToolAnnotations } from "mcp-use/server";
+import { z } from "zod";
+import { type WidgetToolMetaDefaults } from "../types/meta.js";
+import type { ToolArgs } from "./register-tool.js";
+type ZodRawShape = Record<string, z.ZodTypeAny>;
+interface WidgetToolResult {
+    text: string;
+    structuredContent: Record<string, unknown>;
+}
+/**
+ * Tool visibility per SEP-1865 (`_meta.ui.visibility`). `"app"` hides the tool
+ * from the LLM tool surface while keeping it callable from a widget; `"model"`
+ * exposes it to the LLM. Pass an array to advertise both surfaces.
+ */
+export type WidgetToolVisibility = "app" | "model" | ("app" | "model")[];
+export interface WidgetToolConfig<TClient, TShape extends ZodRawShape = ZodRawShape> {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema?: TShape;
+    /** MCP tool annotations (e.g. `readOnlyHint`) advertised to the host. */
+    annotations?: ToolAnnotations;
+    /**
+     * SEP-1865 visibility. Defaults to `"app"` (the historical behaviour — widget
+     * tools are app-only). Use `"model"` to expose the tool to the LLM; in that
+     * case the `_meta.ui` carries only `{ resourceUri }` and no `visibility`.
+     */
+    visibility?: WidgetToolVisibility;
+    /**
+     * Extra `_meta` entries merged flat into the emitted `_meta`, alongside the
+     * `ui` block this registrar builds. The `ui` key is reserved for the
+     * registrar; collisions are overwritten by the registrar's `ui`.
+     */
+    meta?: Record<string, unknown>;
+    /**
+     * Host status line while the tool call runs
+     * (`openai/toolInvocation/invoking`). Defaults to `Loading <title>...`.
+     * Only emitted on model-visible widget tools.
+     */
+    invoking?: string;
+    /**
+     * Host status line once the tool call finished
+     * (`openai/toolInvocation/invoked`). Defaults to `<title> ready`.
+     * Only emitted on model-visible widget tools.
+     */
+    invoked?: string;
+    handler: (client: TClient, params: ToolArgs<TShape>) => Promise<WidgetToolResult>;
+}
+export declare function createWidgetToolRegistrar<TClient>(server: MCPServer, client: TClient, resourceUri: string, metaDefaults?: WidgetToolMetaDefaults): <TShape extends ZodRawShape = ZodRawShape>(config: WidgetToolConfig<TClient, TShape>) => void;
+export {};
+//# sourceMappingURL=register-widget-tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register-widget-tool.d.ts","sourceRoot":"","sources":["../../src/tools/register-widget-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAU,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AAEtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAElD,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAA;AAK/C,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC3C;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,OAAO,GAAG,CAAC,KAAK,GAAG,OAAO,CAAC,EAAE,CAAA;AAExE,MAAM,WAAW,gBAAgB,CAAC,OAAO,EAAE,MAAM,SAAS,WAAW,GAAG,WAAW;IACjF,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,eAAe,CAAA;IAC7B;;;;OAIG;IACH,UAAU,CAAC,EAAE,oBAAoB,CAAA;IACjC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAA;CAClF;AAYD,wBAAgB,yBAAyB,CAAC,OAAO,EAC/C,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,OAAO,EACf,WAAW,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,sBAAsB,IAEZ,MAAM,SAAS,WAAW,GAAG,WAAW,EAC/D,QAAQ,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,UAsC5C"}