@tylertech/forge-ai 0.15.2 → 0.15.3-dev.1

package/dist/tools/ai-mcp-app/mcp-app-bridge.mjs

@@ -0,0 +1,293 @@
+const PROTOCOL_VERSION = "2026-01-26";
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const SERVER_ERROR = -32e3;
+const DISPLAY_MODES = ["inline", "fullscreen", "pip"];
+class JsonRpcError extends Error {
+  constructor(config) {
+    super(config.message);
+    this.code = config.code;
+  }
+}
+function invalidParams(message) {
+  return new JsonRpcError({ code: INVALID_PARAMS, message });
+}
+function methodNotFound(method) {
+  return new JsonRpcError({ code: METHOD_NOT_FOUND, message: `Method not found: ${method}` });
+}
+function asParams(params) {
+  if (params === void 0 || params === null) {
+    return {};
+  }
+  if (typeof params !== "object" || Array.isArray(params)) {
+    throw invalidParams("params must be an object");
+  }
+  return params;
+}
+function asJsonRpc(data) {
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  const payload = data;
+  return payload.jsonrpc === "2.0" ? payload : null;
+}
+function asDisplayModes(value) {
+  return Array.isArray(value) ? DISPLAY_MODES.filter((mode) => value.includes(mode)) : [];
+}
+class McpAppBridge {
+  #hostInfo;
+  #capabilities = {};
+  #phase = "idle";
+  #sandboxWindow = null;
+  #sandboxOrigin = "";
+  #hostContext = { theme: "light" };
+  /** The host context the View last received (in the `ui/initialize` result or a change notification). */
+  #deliveredHostContext = null;
+  #appDisplayModes = [];
+  #nextId = 1;
+  #pending = /* @__PURE__ */ new Map();
+  #resolveProxyReady;
+  #initialized = null;
+  #resolveInitialized;
+  constructor(hostInfo) {
+    this.#hostInfo = hostInfo;
+  }
+  connect(config) {
+    if (this.#phase !== "idle") {
+      throw new Error("Bridge has already been connected; create a new bridge per widget.");
+    }
+    this.#phase = "connecting";
+    this.#capabilities = config.hostCapabilities;
+    this.#hostContext = config.hostContext;
+    this.#sandboxWindow = config.sandboxWindow;
+    this.#sandboxOrigin = config.sandboxOrigin;
+    window.addEventListener("message", this.#handleMessage);
+    const proxyReady = new Promise((resolve) => {
+      this.#resolveProxyReady = resolve;
+    });
+    this.#initialized = new Promise((resolve) => {
+      this.#resolveInitialized = resolve;
+    }).then(() => {
+      this.#phase = "ready";
+      this.#flushHostContext();
+    });
+    return proxyReady.then(
+      () => this.#sendNotification("ui/notifications/sandbox-resource-ready", {
+        html: config.html,
+        permissions: config.permissions,
+        sandbox: config.sandbox
+      })
+    ).then(() => this.#initialized);
+  }
+  sendToolInputPartial(args) {
+    this.#sendNotification("ui/notifications/tool-input-partial", { arguments: args });
+  }
+  sendToolInput(args) {
+    this.#sendNotification("ui/notifications/tool-input", { arguments: args });
+  }
+  sendToolResult(result) {
+    this.#sendNotification("ui/notifications/tool-result", result);
+  }
+  sendToolCancelled(reason) {
+    this.#sendNotification("ui/notifications/tool-cancelled", { reason: reason ?? "cancelled" });
+  }
+  sendHostContextChange(hostContext) {
+    this.#hostContext = hostContext;
+    if (this.#phase === "ready") {
+      this.#flushHostContext();
+    }
+  }
+  /**
+   * Send `ui/resource-teardown` and dispose immediately; the host doesn't wait for the ack,
+   * so the iframe is removed right away. A View that never initialized isn't messaged.
+   */
+  sendTeardown() {
+    if (this.#phase === "ready") {
+      this.#sendRequest("ui/resource-teardown", {}).catch(() => void 0);
+    }
+    this.#dispose();
+  }
+  #flushHostContext() {
+    if (this.#hostContext === this.#deliveredHostContext) {
+      return;
+    }
+    this.#deliveredHostContext = this.#hostContext;
+    this.#sendNotification("ui/notifications/host-context-changed", this.#hostContext);
+  }
+  /** Release the `message` listener + reject any in-flight requests. Idempotent. */
+  #dispose() {
+    this.#phase = "disposed";
+    window.removeEventListener("message", this.#handleMessage);
+    for (const pending of this.#pending.values()) {
+      pending.reject(new Error("Bridge disposed"));
+    }
+    this.#pending.clear();
+    this.#sandboxWindow = null;
+  }
+  #handleMessage = (event) => {
+    if (event.source !== this.#sandboxWindow || event.origin !== this.#sandboxOrigin) {
+      return;
+    }
+    const payload = asJsonRpc(event.data);
+    if (!payload || typeof payload.method !== "string") {
+      if (payload && payload.id !== void 0) {
+        this.#handleResponse(payload);
+      } else if (payload) {
+        console.warn("[forge-ai-mcp-app] Ignoring malformed JSON-RPC message", event.data);
+      }
+      return;
+    }
+    if (payload.id !== void 0) {
+      void this.#handleRequest(payload.method, payload.params, payload.id);
+    } else {
+      this.#handleNotification(payload.method, payload.params);
+    }
+  };
+  #handleResponse(payload) {
+    const id = payload.id;
+    const pending = this.#pending.get(id);
+    if (!pending) {
+      return;
+    }
+    this.#pending.delete(id);
+    if (payload.error) {
+      pending.reject(new Error(payload.error.message));
+    } else {
+      pending.resolve(payload.result);
+    }
+  }
+  async #handleRequest(method, params, id) {
+    try {
+      const result = await this.#dispatchRequest(method, params);
+      this.#post({ jsonrpc: "2.0", id, result: result ?? {} });
+    } catch (error) {
+      this.#post({
+        jsonrpc: "2.0",
+        id,
+        error: {
+          code: error instanceof JsonRpcError ? error.code : SERVER_ERROR,
+          message: error instanceof Error ? error.message : "Request failed"
+        }
+      });
+    }
+  }
+  /** Unknown or unadvertised methods (`tools/list`, `sampling/createMessage`, `ui/download-file`, …) reject with -32601. */
+  async #dispatchRequest(method, params) {
+    const p = asParams(params);
+    switch (method) {
+      case "ui/initialize": {
+        const appCapabilities = p.appCapabilities ?? {};
+        this.#appDisplayModes = asDisplayModes(appCapabilities.availableDisplayModes);
+        this.#deliveredHostContext = this.#hostContext;
+        return {
+          protocolVersion: PROTOCOL_VERSION,
+          hostInfo: this.#hostInfo,
+          hostCapabilities: this.#capabilities,
+          hostContext: this.#hostContext
+        };
+      }
+      case "ui/open-link":
+        if (typeof p.url !== "string") {
+          throw invalidParams("ui/open-link requires a string url");
+        }
+        return await this.onopenlink?.({ url: p.url }) ?? { isError: true };
+      case "ui/message":
+        if (!Array.isArray(p.content)) {
+          throw invalidParams("ui/message requires a content array");
+        }
+        return await this.onmessage?.({ content: p.content, role: "user" }) ?? { isError: true };
+      case "ui/update-model-context":
+        await this.onupdatemodelcontext?.({
+          content: Array.isArray(p.content) ? p.content : void 0,
+          structuredContent: p.structuredContent
+        });
+        return {};
+      case "ui/request-display-mode": {
+        const current = this.#hostContext.displayMode ?? "inline";
+        const [mode] = asDisplayModes([p.mode]);
+        if (!mode || !this.onrequestdisplaymode) {
+          return { mode: current };
+        }
+        return this.onrequestdisplaymode({ mode, appDisplayModes: this.#appDisplayModes });
+      }
+      case "ui/resource-teardown":
+      case "ping":
+        return {};
+      case "tools/call":
+        if (!this.oncalltool || !this.#capabilities.serverTools) {
+          throw methodNotFound(method);
+        }
+        this.#assertReady(method);
+        if (typeof p.name !== "string" || !p.name) {
+          throw invalidParams("tools/call requires a tool name");
+        }
+        return this.oncalltool({ name: p.name, arguments: asParams(p.arguments) });
+      case "resources/read":
+        if (!this.onreadresource) {
+          throw methodNotFound(method);
+        }
+        this.#assertReady(method);
+        if (typeof p.uri !== "string" || !p.uri) {
+          throw invalidParams("resources/read requires a uri");
+        }
+        return this.onreadresource({ uri: p.uri });
+      default:
+        throw methodNotFound(method);
+    }
+  }
+  /** Server-bound requests reach the adapter only after the View completes the handshake. */
+  #assertReady(method) {
+    if (this.#phase !== "ready") {
+      throw new JsonRpcError({
+        code: SERVER_ERROR,
+        message: `${method} is not allowed before ui/notifications/initialized`
+      });
+    }
+  }
+  #handleNotification(method, params) {
+    const p = params && typeof params === "object" ? params : {};
+    switch (method) {
+      case "ui/notifications/sandbox-proxy-ready":
+        this.#resolveProxyReady?.();
+        return;
+      case "ui/notifications/initialized":
+        this.#resolveInitialized?.();
+        return;
+      case "ui/notifications/size-changed":
+        this.onsizechange?.({
+          width: typeof p.width === "number" ? p.width : void 0,
+          height: typeof p.height === "number" ? p.height : 0
+        });
+        return;
+      case "notifications/message":
+        this.onloggingmessage?.({
+          level: typeof p.level === "string" ? p.level : "info",
+          logger: typeof p.logger === "string" ? p.logger : void 0,
+          data: p.data
+        });
+        return;
+      case "ui/notifications/request-teardown":
+        this.onrequestteardown?.();
+        return;
+      default:
+        console.warn(`[forge-ai-mcp-app] Unhandled notification method: ${method}`);
+        return;
+    }
+  }
+  #sendNotification(method, params) {
+    this.#post({ jsonrpc: "2.0", method, params });
+  }
+  #sendRequest(method, params) {
+    const id = this.#nextId++;
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      this.#post({ jsonrpc: "2.0", id, method, params });
+    });
+  }
+  #post(data) {
+    this.#sandboxWindow?.postMessage(data, this.#sandboxOrigin);
+  }
+}
+export {
+  McpAppBridge
+};

package/dist/tools/ai-mcp-app/mcp-app-context.d.ts

@@ -0,0 +1,46 @@
+import { McpAppHostCapabilities, McpAppHostContext, McpModelContextUpdateParams, McpResourceReadParams, McpToolCallParams } from '../../ai-chatbot';
+import { McpAppRequestResult } from './mcp-app-bridge-types.js';
+/** A mounted widget, registered so the host can tear it down before removing it. */
+export interface McpAppViewRegistration {
+    toolCallId: string;
+    teardown(): void;
+}
+/**
+ * Host surface an `<forge-ai-mcp-app>` consumes to service widget→host calls and to read
+ * the current host context. Provided by the chatbot base component (Step 4) and updated
+ * in place; consumers use `@consume({ subscribe: true })` and re-render when it changes.
+ *
+ * The library never owns an MCP `Client` — `callTool`/`readResource`/`updateModelContext`
+ * delegate to the adapter's `callMcpTool`/`readMcpResource`/`updateMcpModelContext`.
+ * Every call carries the widget's `toolCallId`.
+ */
+export interface McpAppHost {
+    callTool(params: McpToolCallParams): Promise<unknown>;
+    readResource(params: McpResourceReadParams): Promise<unknown>;
+    updateModelContext(params: McpModelContextUpdateParams): Promise<void>;
+    /**
+     * Place a widget's `ui/message` text in the prompt for the user to send. Resolves
+     * `{ isError: true }` when there is no text or no prompt.
+     */
+    draftMessage(params: {
+        toolCallId: string;
+        content: unknown[];
+    }): Promise<McpAppRequestResult>;
+    /** Tear down one widget through the host's normal per-widget teardown path. */
+    teardownView(params: {
+        toolCallId: string;
+    }): void;
+    /** Register a mounted widget; returns the unregister callback. */
+    registerView(view: McpAppViewRegistration): () => void;
+    hostContext: McpAppHostContext;
+    /** Cross-origin sandbox proxy URL. Absent → the element renders an error artifact. */
+    sandboxUrl?: string;
+    /**
+     * Advertised to the widget in `McpUiInitializeResult`, derived from what the host and
+     * adapter implement. The element adds `sandbox` (the enforced csp/permissions) per widget.
+     */
+    hostCapabilities: McpAppHostCapabilities;
+}
+export declare const mcpAppHostContext: {
+    __context__: McpAppHost;
+};

package/dist/tools/ai-mcp-app/mcp-app-context.mjs

@@ -0,0 +1,5 @@
+import { createContext } from "@lit/context";
+const mcpAppHostContext = createContext(/* @__PURE__ */ Symbol("forge-mcp-app-host"));
+export {
+  mcpAppHostContext
+};

package/dist/tools/ai-steps/ai-steps-definition.d.ts

@@ -0,0 +1,2 @@
+import { ToolDefinition } from '../../ai-chatbot';
+export declare const displayStepsTool: ToolDefinition;

package/dist/tools/ai-steps/ai-steps-definition.mjs

@@ -0,0 +1,51 @@
+import "../../ai-chatbot/ai-chatbot-base.mjs";
+import "../../ai-chatbot/ai-chatbot.mjs";
+import "../../ai-chatbot/ai-chatbot-tool-call.mjs";
+import "@ag-ui/client";
+import "uuid";
+import "../../utils/markdown.mjs";
+import { createToolRenderer } from "../../ai-chatbot/create-tool-renderer.mjs";
+import "../../ai-chatbot/tool-canvas.mjs";
+const displayStepsTool = {
+  name: "displaySteps",
+  displayName: "Display Steps",
+  description: "Surface the sequence of steps you took while working on a request as a compact, expandable timeline. Call this when your answer involved multiple discrete actions — searching, filtering, joining, calculating — and showing that work helps the user trust the result. Provide the steps in the order they happened.",
+  parameters: {
+    type: "object",
+    properties: {
+      steps: {
+        type: "array",
+        description: "The steps taken, in the order they happened.",
+        items: {
+          type: "object",
+          properties: {
+            label: {
+              type: "string",
+              description: 'Short past-tense description of the step, e.g. "Searched the orders table" or "Filtered by `crime_category`". This is the row title, so keep it to a few words. Inline markdown is supported — use `backticks` for identifiers such as columns, tables or query fragments, **bold** for a figure or outcome worth emphasizing, and *italics* or ~~strikethrough~~ where they help. Emphasize sparingly; a row where everything is bold reads the same as one where nothing is.'
+            },
+            detail: {
+              type: "string",
+              description: 'Optional elaboration shown beneath the label, e.g. the filter applied or the number of records matched. Supports the same inline markdown as "label". Omit for steps that need no explanation.'
+            },
+            status: {
+              type: "string",
+              enum: ["pending", "running", "complete"],
+              description: 'Outcome of the step. Defaults to "complete" when omitted.'
+            }
+          },
+          required: ["label"]
+        }
+      }
+    },
+    required: ["steps"]
+  },
+  // Steps are a progress affordance, so the timeline needs to appear while arguments are still
+  // streaming rather than only once the call settles.
+  renderOnStart: true,
+  renderer: createToolRenderer({
+    elementTag: "forge-ai-tool-steps"
+  })
+};
+export {
+  displayStepsTool
+};

package/dist/tools/ai-steps/ai-steps.d.ts

@@ -0,0 +1,28 @@
+import { LitElement, TemplateResult, CSSResult } from 'lit';
+import { IToolRenderer, ToolCall } from '../../ai-chatbot';
+import { AiStep } from '../../ai-steps';
+declare global {
+    interface HTMLElementTagNameMap {
+        'forge-ai-tool-steps': StepsToolElement;
+    }
+}
+interface StepsData {
+    steps: AiStep[];
+}
+/**
+ * Steps component tool renderer. Maps a `displaySteps` tool call onto the presentational
+ * `forge-ai-steps` primitive, so the primitive stays unaware of tool calls.
+ *
+ * @tag forge-ai-tool-steps
+ * @internal
+ */
+export declare class StepsToolElement extends LitElement implements IToolRenderer<StepsData> {
+    #private;
+    static styles: CSSResult;
+    /**
+     * Tool call data containing the agent-provided steps.
+     */
+    toolCall: ToolCall<StepsData>;
+    render(): TemplateResult;
+}
+export {};

package/dist/tools/ai-steps/ai-steps.mjs

@@ -0,0 +1,49 @@
+import { unsafeCSS, LitElement, html } from "lit";
+import { property, customElement } from "lit/decorators.js";
+import "../../ai-steps/ai-steps.mjs";
+import styles from "./ai-steps.scss.mjs";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var _StepsToolElement_instances, steps_get, running_get;
+let StepsToolElement = class extends LitElement {
+  constructor() {
+    super(...arguments);
+    __privateAdd(this, _StepsToolElement_instances);
+  }
+  render() {
+    return html`<forge-ai-steps .steps=${__privateGet(this, _StepsToolElement_instances, steps_get)} ?running=${__privateGet(this, _StepsToolElement_instances, running_get)}></forge-ai-steps>`;
+  }
+};
+_StepsToolElement_instances = /* @__PURE__ */ new WeakSet();
+steps_get = function() {
+  const steps = this.toolCall?.args?.steps;
+  return Array.isArray(steps) ? steps.filter((step) => !!step?.label) : [];
+};
+running_get = function() {
+  const status = this.toolCall?.status;
+  return status !== "complete" && status !== "error" && status !== "cancelled";
+};
+StepsToolElement.styles = unsafeCSS(styles);
+__decorateClass([
+  property({ attribute: false })
+], StepsToolElement.prototype, "toolCall", 2);
+StepsToolElement = __decorateClass([
+  customElement("forge-ai-tool-steps")
+], StepsToolElement);
+export {
+  StepsToolElement
+};

package/dist/tools/ai-steps/ai-steps.scss.mjs

@@ -0,0 +1,4 @@
+const styles = ":host {\n  display: block;\n}";
+export {
+  styles as default
+};

package/dist/tools/ai-steps/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ai-steps-definition.js';
+export * from './ai-steps.js';

package/dist/tools/ai-steps/index.mjs

@@ -0,0 +1,6 @@
+import { displayStepsTool } from "./ai-steps-definition.mjs";
+import { StepsToolElement } from "./ai-steps.mjs";
+export {
+  StepsToolElement,
+  displayStepsTool
+};

package/dist/tools/index.d.ts

@@ -1,2 +1,3 @@
 export * from './ai-data-table';
 export * from './ai-paginator';
+export * from './ai-steps';

package/dist/tools/index.mjs

@@ -1,8 +1,12 @@
 import { displayDataTableTool } from "./ai-data-table/ai-data-table-definition.mjs";
 import { DataTableToolElement } from "./ai-data-table/ai-data-table.mjs";
 import { AiPaginator } from "./ai-paginator/ai-paginator.mjs";
+import { displayStepsTool } from "./ai-steps/ai-steps-definition.mjs";
+import { StepsToolElement } from "./ai-steps/ai-steps.mjs";
 export {
   AiPaginator,
   DataTableToolElement,
-  displayDataTableTool
+  StepsToolElement,
+  displayDataTableTool,
+  displayStepsTool
 };

package/dist/utils/inert-outside.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Marks everything outside `element` inert, as a modal would, without moving it in the DOM.
+ * `inert` on an ancestor would disable `element` too (even in the top layer), so this marks
+ * the siblings at each level up through shadow roots instead. Returns a restore function that
+ * clears only the elements this call made inert.
+ */
+export declare function inertOutside(element: Element): () => void;

package/dist/utils/inert-outside.mjs

@@ -0,0 +1,28 @@
+function flatLevel(element) {
+  if (element.assignedSlot) {
+    return { siblings: element.assignedSlot.assignedElements(), parent: element.assignedSlot };
+  }
+  if (element.parentElement) {
+    return { siblings: [...element.parentElement.children], parent: element.parentElement };
+  }
+  const root = element.getRootNode();
+  return root instanceof ShadowRoot ? { siblings: [...root.children], parent: root.host } : { siblings: [], parent: null };
+}
+function inertOutside(element) {
+  const marked = [];
+  let current = element;
+  while (current) {
+    const { siblings, parent } = flatLevel(current);
+    for (const sibling of siblings) {
+      if (sibling !== current && sibling instanceof HTMLElement && !sibling.inert) {
+        sibling.inert = true;
+        marked.push(sibling);
+      }
+    }
+    current = parent;
+  }
+  return () => marked.forEach((sibling) => sibling.inert = false);
+}
+export {
+  inertOutside
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tylertech/forge-ai",
-  "version": "0.15.2",
+  "version": "0.15.3-dev.1",
   "description": "A library of Tyler Forge™ AI chat interface web components.",
   "license": "Apache-2.0",
   "author": "Tyler Technologies, Inc.",
@@ -52,6 +52,8 @@
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "0.11.0",
     "@esm-bundle/chai": "4.3.4-fix.0",
+    "@modelcontextprotocol/ext-apps": "^1.7.5",
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "@open-wc/testing": "4.0.0",
     "@storybook/addon-a11y": "9.1.20",
     "@storybook/addon-docs": "9.1.20",
@@ -111,6 +113,7 @@
     "preview": "vite preview",
     "prestorybook": "pnpm run cem",
     "storybook": "storybook dev -p 6016",
+    "sandbox": "node sandbox/server.mjs",
     "prebuild:storybook": "pnpm run cem",
     "build:storybook": "storybook build",
     "lint": "pnpm run lint:lit-analyzer && pnpm run lint:eslint && pnpm run lint:stylelint",