@copilotkit/mcp-apps-renderer 2.0.0-rc.20 → 2.0.0-rc.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/host.cjs ADDED
@@ -0,0 +1,246 @@
1
+
2
+ //#region src/host.ts
3
+ /** Message shown when the bridge package cannot be loaded. */
4
+ const MCP_APPS_RENDERER_MISSING_MESSAGE = "MCP Apps require '@copilotkit/mcp-apps-renderer' and its '@modelcontextprotocol/ext-apps' dependency. Reinstall your dependencies if this package is missing.";
5
+ /** Error text when an MCP App renders without an agent to fetch it through. */
6
+ const MCP_APPS_NO_AGENT_MESSAGE = "No agent available to fetch resource";
7
+ /** Tallest an MCP App iframe may grow, in pixels. */
8
+ const MCP_APP_MAX_HEIGHT = 5e3;
9
+ /** The height the iframe starts at before the widget reports its size. */
10
+ const INITIAL_HEIGHT_PX = 100;
11
+ /**
12
+ * Loads the bridge (`bindMcpApp`) lazily. The bridge pulls the MCP SDK and
13
+ * its zod schemas (~40-50 kB gzipped), so an app only pays for it when an MCP
14
+ * App renders. The `import()` itself stays in the frontend, where its bundler
15
+ * can split it out. A failed load rethrows with what to install, since a raw
16
+ * module-resolution error does not say.
17
+ *
18
+ * @param importRenderer - `() => import("@copilotkit/mcp-apps-renderer")`.
19
+ */
20
+ function loadMcpAppsRenderer(importRenderer) {
21
+ return importRenderer().catch((importErr) => {
22
+ throw new Error(MCP_APPS_RENDERER_MISSING_MESSAGE, { cause: importErr });
23
+ });
24
+ }
25
+ function identityOf(content) {
26
+ if (!content) return "";
27
+ return JSON.stringify([
28
+ content.resourceUri,
29
+ content.serverHash,
30
+ content.serverId
31
+ ]);
32
+ }
33
+ const INITIAL_STATE = {
34
+ loading: true,
35
+ error: null,
36
+ contentError: null,
37
+ size: {},
38
+ prefersBorder: false
39
+ };
40
+ /**
41
+ * Hosts one MCP App: creates the sandbox iframe in a container, binds the
42
+ * MCP session to it, sizes it as the widget reports, and keeps the state a
43
+ * frontend renders. It binds again (new iframe, new session) only when the
44
+ * container, agent, message id or widget identity (resource URI, server)
45
+ * changes; new tool input or results feed the existing session.
46
+ *
47
+ * @example
48
+ * ```ts
49
+ * const app = new ɵMcpAppHost({ host: core });
50
+ * app.subscribe(() => render(app.getState()));
51
+ * app.setContent(content);
52
+ * app.setAgent(agent);
53
+ * app.setMessageId(message.id);
54
+ * app.setContainer(element); // on mount
55
+ * app.destroy(); // on unmount
56
+ * ```
57
+ */
58
+ var McpAppHost = class {
59
+ #options;
60
+ #listeners = /* @__PURE__ */ new Set();
61
+ #container = null;
62
+ #content;
63
+ #agent;
64
+ #messageId;
65
+ #bindKey = "";
66
+ #iframe = null;
67
+ #session = null;
68
+ /** Bumped on every bind and on destroy; stale async work checks it. */
69
+ #generation = 0;
70
+ #state = INITIAL_STATE;
71
+ constructor(options) {
72
+ this.getState = () => this.#state;
73
+ this.subscribe = (listener) => {
74
+ this.#listeners.add(listener);
75
+ return () => {
76
+ this.#listeners.delete(listener);
77
+ };
78
+ };
79
+ this.#options = options;
80
+ }
81
+ /** Sets the element the iframe goes into. `null` removes it. */
82
+ setContainer(container) {
83
+ this.#container = container;
84
+ this.#rebindIfNeeded();
85
+ }
86
+ /** Sets the latest activity content. */
87
+ setContent(content) {
88
+ this.#content = content;
89
+ if (!this.#rebindIfNeeded()) this.#session?.syncContent(content);
90
+ }
91
+ /** Sets the agent the widget's requests go through. */
92
+ setAgent(agent) {
93
+ this.#agent = agent;
94
+ this.#rebindIfNeeded();
95
+ }
96
+ /** Sets the id of the activity message, so the session follows the store. */
97
+ setMessageId(messageId) {
98
+ this.#messageId = messageId;
99
+ this.#rebindIfNeeded();
100
+ }
101
+ /** Tears the session down and removes the iframe. A later setter binds again. */
102
+ destroy() {
103
+ this.#unbind();
104
+ this.#bindKey = "";
105
+ }
106
+ #rebindIfNeeded() {
107
+ const key = JSON.stringify([
108
+ identityOf(this.#content),
109
+ this.#messageId ?? null,
110
+ this.#container !== null,
111
+ this.#agent !== void 0
112
+ ]);
113
+ const agentChanged = this.#session !== null && this.#boundAgent !== this.#agent;
114
+ const containerChanged = this.#boundContainer !== this.#container;
115
+ if (key === this.#bindKey && !agentChanged && !containerChanged) return false;
116
+ this.#bindKey = key;
117
+ this.#bind();
118
+ return true;
119
+ }
120
+ #boundAgent;
121
+ #boundContainer = null;
122
+ #bind() {
123
+ this.#unbind();
124
+ const container = this.#container;
125
+ const content = this.#content;
126
+ const agent = this.#agent;
127
+ this.#boundAgent = agent;
128
+ this.#boundContainer = container;
129
+ if (!content || !container) return;
130
+ if (!agent) {
131
+ this.#setState({
132
+ ...INITIAL_STATE,
133
+ loading: false,
134
+ error: MCP_APPS_NO_AGENT_MESSAGE
135
+ });
136
+ return;
137
+ }
138
+ const generation = this.#generation;
139
+ const isCurrent = () => generation === this.#generation;
140
+ this.#setState(INITIAL_STATE);
141
+ const iframe = document.createElement("iframe");
142
+ for (const [name, value] of Object.entries(this.#options.iframeAttributes ?? {})) iframe.setAttribute(name, value);
143
+ iframe.style.width = "100%";
144
+ iframe.style.height = `${String(INITIAL_HEIGHT_PX)}px`;
145
+ iframe.style.border = "none";
146
+ iframe.style.backgroundColor = "transparent";
147
+ iframe.style.display = "block";
148
+ container.appendChild(iframe);
149
+ this.#iframe = iframe;
150
+ const scoped = this.#options.scopeToWidget === true;
151
+ const fail = (err) => {
152
+ if (!isCurrent()) return;
153
+ this.#setState({
154
+ ...this.#state,
155
+ loading: false,
156
+ error: err.message
157
+ });
158
+ if (scoped) {
159
+ this.#session?.teardown();
160
+ this.#session = null;
161
+ iframe.removeAttribute("srcdoc");
162
+ iframe.removeAttribute("data-mcp-app-initialized");
163
+ }
164
+ };
165
+ loadMcpAppsRenderer(this.#options.importRenderer).then((mod) => {
166
+ if (!isCurrent()) return;
167
+ const session = mod.bindMcpApp({
168
+ iframe,
169
+ getContent: () => this.#content ?? content,
170
+ getAgent: () => this.#agent,
171
+ host: this.#options.host,
172
+ messageId: this.#messageId,
173
+ options: this.#options.sessionOptions,
174
+ cancelFollowUpsOnTeardown: scoped,
175
+ requireExactResourceUri: scoped,
176
+ cancelRunningWaitOnTeardown: scoped,
177
+ hooks: {
178
+ onResource: (resource) => {
179
+ if (!isCurrent()) return;
180
+ this.#setState({
181
+ ...this.#state,
182
+ loading: false,
183
+ prefersBorder: resource._meta?.ui?.prefersBorder === true
184
+ });
185
+ },
186
+ onInitialized: () => {
187
+ if (isCurrent()) iframe.setAttribute("data-mcp-app-initialized", "true");
188
+ },
189
+ onSizeChanged: (size) => {
190
+ if (isCurrent()) this.#applySize(iframe, size);
191
+ },
192
+ onContentError: (err) => {
193
+ if (!isCurrent()) return;
194
+ this.#setState({
195
+ ...this.#state,
196
+ contentError: err?.message ?? null
197
+ });
198
+ },
199
+ onError: fail,
200
+ ...scoped ? { onFollowUpError: fail } : {}
201
+ }
202
+ });
203
+ this.#session = session;
204
+ session.syncContent(this.#content ?? content);
205
+ }).catch((err) => {
206
+ console.error("[MCPAppsRenderer] Setup error:", err);
207
+ fail(err instanceof Error ? err : new Error(String(err)));
208
+ });
209
+ }
210
+ #applySize(iframe, size) {
211
+ const next = {};
212
+ if (typeof size.width === "number" && Number.isFinite(size.width)) {
213
+ next.width = size.width;
214
+ iframe.style.minWidth = `min(${String(size.width)}px, 100%)`;
215
+ iframe.style.width = "100%";
216
+ }
217
+ const height = size.height;
218
+ if (typeof height === "number" && Number.isFinite(height) && height > 0) {
219
+ next.height = Math.ceil(Math.min(height, MCP_APP_MAX_HEIGHT));
220
+ iframe.style.height = `${String(next.height)}px`;
221
+ }
222
+ this.#setState({
223
+ ...this.#state,
224
+ size: next
225
+ });
226
+ }
227
+ #unbind() {
228
+ this.#generation += 1;
229
+ this.#session?.teardown();
230
+ this.#session = null;
231
+ this.#iframe?.remove();
232
+ this.#iframe = null;
233
+ }
234
+ #setState(state) {
235
+ this.#state = state;
236
+ for (const listener of this.#listeners) listener();
237
+ }
238
+ };
239
+
240
+ //#endregion
241
+ exports.MCP_APPS_NO_AGENT_MESSAGE = MCP_APPS_NO_AGENT_MESSAGE;
242
+ exports.MCP_APPS_RENDERER_MISSING_MESSAGE = MCP_APPS_RENDERER_MISSING_MESSAGE;
243
+ exports.MCP_APP_MAX_HEIGHT = MCP_APP_MAX_HEIGHT;
244
+ exports.McpAppHost = McpAppHost;
245
+ exports.loadMcpAppsRenderer = loadMcpAppsRenderer;
246
+ //# sourceMappingURL=host.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"host.cjs","names":["#options","#listeners","#state","#container","#rebindIfNeeded","#content","#session","#agent","#messageId","#unbind","#bindKey","#boundAgent","#boundContainer","#bind","#setState","#generation","#iframe","#applySize"],"sources":["../src/host.ts"],"sourcesContent":["// The framework-neutral host shell around `bindMcpApp`: the iframe, its size,\n// and the loading / error / content-error state every frontend renders. It is\n// bridge-free (the bridge loads lazily through `loadMcpAppsRenderer`), so\n// frontends can import it statically from the `/activity` entry.\nimport type { AbstractAgent } from \"@ag-ui/client\";\nimport type { MCPAppsActivityContent } from \"./content-schema\";\nimport type { ɵMcpFollowUpHost } from \"./follow-up\";\nimport type {\n BindMcpAppOptions,\n FetchedResource,\n McpAppSession,\n McpAppSessionOptions,\n} from \"./session\";\n\n/** The part of the bridge module the host uses, loaded on demand. */\nexport interface McpAppsRendererModule {\n bindMcpApp(options: BindMcpAppOptions): McpAppSession;\n}\n\n/** Message shown when the bridge package cannot be loaded. */\nexport const MCP_APPS_RENDERER_MISSING_MESSAGE =\n \"MCP Apps require '@copilotkit/mcp-apps-renderer' and its \" +\n \"'@modelcontextprotocol/ext-apps' dependency. Reinstall your \" +\n \"dependencies if this package is missing.\";\n\n/** Error text when an MCP App renders without an agent to fetch it through. */\nexport const MCP_APPS_NO_AGENT_MESSAGE = \"No agent available to fetch resource\";\n\n/** Tallest an MCP App iframe may grow, in pixels. */\nexport const MCP_APP_MAX_HEIGHT = 5000;\n\n/** The height the iframe starts at before the widget reports its size. */\nconst INITIAL_HEIGHT_PX = 100;\n\n/** Imports the bridge module; frontends pass `() => import(\"@copilotkit/mcp-apps-renderer\")`. */\nexport type McpAppsRendererImporter = () => Promise<McpAppsRendererModule>;\n\n/**\n * Loads the bridge (`bindMcpApp`) lazily. The bridge pulls the MCP SDK and\n * its zod schemas (~40-50 kB gzipped), so an app only pays for it when an MCP\n * App renders. The `import()` itself stays in the frontend, where its bundler\n * can split it out. A failed load rethrows with what to install, since a raw\n * module-resolution error does not say.\n *\n * @param importRenderer - `() => import(\"@copilotkit/mcp-apps-renderer\")`.\n */\nexport function loadMcpAppsRenderer(importRenderer: McpAppsRendererImporter) {\n return importRenderer().catch((importErr: unknown) => {\n throw new Error(MCP_APPS_RENDERER_MISSING_MESSAGE, { cause: importErr });\n });\n}\n\n/** What a frontend renders around the MCP App iframe. */\nexport interface McpAppHostState {\n loading: boolean;\n /** Fatal setup failure; shown until the host binds again. */\n error: string | null;\n /** Recoverable: the latest content was rejected and not forwarded. */\n contentError: string | null;\n /** The size the widget reported. */\n size: { width?: number; height?: number };\n /** The resource asked the host for a border and background. */\n prefersBorder: boolean;\n}\n\nexport interface McpAppHostOptions {\n /** The CopilotKit core, for `ui/message` follow-up runs. */\n host: ɵMcpFollowUpHost;\n /** Session options (host info, timeouts, `allowSameOriginFallback`). */\n sessionOptions?: McpAppSessionOptions;\n /**\n * Scope the session to the widget (Angular's contract): teardown cancels\n * its queued follow-up and releases running waits, the fetched resource URI\n * must match exactly, and a failed follow-up or setup error tears the\n * session down, blanks the iframe and shows the error.\n */\n scopeToWidget?: boolean;\n /** Attributes set on the iframe, such as a `data-testid` or `title`. */\n iframeAttributes?: Record<string, string>;\n /** `() => import(\"@copilotkit/mcp-apps-renderer\")`; see {@link loadMcpAppsRenderer}. */\n importRenderer: McpAppsRendererImporter;\n}\n\nfunction identityOf(content: MCPAppsActivityContent | undefined) {\n if (!content) return \"\";\n return JSON.stringify([\n content.resourceUri,\n content.serverHash,\n content.serverId,\n ]);\n}\n\nconst INITIAL_STATE: McpAppHostState = {\n loading: true,\n error: null,\n contentError: null,\n size: {},\n prefersBorder: false,\n};\n\n/**\n * Hosts one MCP App: creates the sandbox iframe in a container, binds the\n * MCP session to it, sizes it as the widget reports, and keeps the state a\n * frontend renders. It binds again (new iframe, new session) only when the\n * container, agent, message id or widget identity (resource URI, server)\n * changes; new tool input or results feed the existing session.\n *\n * @example\n * ```ts\n * const app = new ɵMcpAppHost({ host: core });\n * app.subscribe(() => render(app.getState()));\n * app.setContent(content);\n * app.setAgent(agent);\n * app.setMessageId(message.id);\n * app.setContainer(element); // on mount\n * app.destroy(); // on unmount\n * ```\n */\nexport class McpAppHost {\n readonly #options: McpAppHostOptions;\n readonly #listeners = new Set<() => void>();\n #container: HTMLElement | null = null;\n #content: MCPAppsActivityContent | undefined;\n #agent: AbstractAgent | undefined;\n #messageId: string | undefined;\n #bindKey = \"\";\n #iframe: HTMLIFrameElement | null = null;\n #session: McpAppSession | null = null;\n /** Bumped on every bind and on destroy; stale async work checks it. */\n #generation = 0;\n #state: McpAppHostState = INITIAL_STATE;\n\n constructor(options: McpAppHostOptions) {\n this.#options = options;\n }\n\n /** The current state. The same object until something changes. */\n getState = () => this.#state;\n\n /** Calls `listener` when the state changes. Returns the unsubscribe function. */\n subscribe = (listener: () => void) => {\n this.#listeners.add(listener);\n return () => {\n this.#listeners.delete(listener);\n };\n };\n\n /** Sets the element the iframe goes into. `null` removes it. */\n setContainer(container: HTMLElement | null) {\n this.#container = container;\n this.#rebindIfNeeded();\n }\n\n /** Sets the latest activity content. */\n setContent(content: MCPAppsActivityContent) {\n this.#content = content;\n if (!this.#rebindIfNeeded()) this.#session?.syncContent(content);\n }\n\n /** Sets the agent the widget's requests go through. */\n setAgent(agent: AbstractAgent | undefined) {\n this.#agent = agent;\n this.#rebindIfNeeded();\n }\n\n /** Sets the id of the activity message, so the session follows the store. */\n setMessageId(messageId: string | undefined) {\n this.#messageId = messageId;\n this.#rebindIfNeeded();\n }\n\n /** Tears the session down and removes the iframe. A later setter binds again. */\n destroy() {\n this.#unbind();\n this.#bindKey = \"\";\n }\n\n #rebindIfNeeded() {\n const key = JSON.stringify([\n identityOf(this.#content),\n this.#messageId ?? null,\n this.#container !== null,\n this.#agent !== undefined,\n ]);\n const agentChanged =\n this.#session !== null && this.#boundAgent !== this.#agent;\n const containerChanged = this.#boundContainer !== this.#container;\n if (key === this.#bindKey && !agentChanged && !containerChanged) {\n return false;\n }\n this.#bindKey = key;\n this.#bind();\n return true;\n }\n\n #boundAgent: AbstractAgent | undefined;\n #boundContainer: HTMLElement | null = null;\n\n #bind() {\n this.#unbind();\n const container = this.#container;\n const content = this.#content;\n const agent = this.#agent;\n this.#boundAgent = agent;\n this.#boundContainer = container;\n if (!content || !container) return;\n if (!agent) {\n this.#setState({\n ...INITIAL_STATE,\n loading: false,\n error: MCP_APPS_NO_AGENT_MESSAGE,\n });\n return;\n }\n\n const generation = this.#generation;\n const isCurrent = () => generation === this.#generation;\n this.#setState(INITIAL_STATE);\n\n const iframe = document.createElement(\"iframe\");\n for (const [name, value] of Object.entries(\n this.#options.iframeAttributes ?? {},\n )) {\n iframe.setAttribute(name, value);\n }\n iframe.style.width = \"100%\";\n iframe.style.height = `${String(INITIAL_HEIGHT_PX)}px`;\n iframe.style.border = \"none\";\n iframe.style.backgroundColor = \"transparent\";\n iframe.style.display = \"block\";\n container.appendChild(iframe);\n this.#iframe = iframe;\n\n const scoped = this.#options.scopeToWidget === true;\n const fail = (err: Error) => {\n if (!isCurrent()) return;\n this.#setState({ ...this.#state, loading: false, error: err.message });\n if (scoped) {\n // Blank the widget, so a failed app does not stay interactive.\n this.#session?.teardown();\n this.#session = null;\n iframe.removeAttribute(\"srcdoc\");\n iframe.removeAttribute(\"data-mcp-app-initialized\");\n }\n };\n loadMcpAppsRenderer(this.#options.importRenderer)\n .then((mod) => {\n if (!isCurrent()) return;\n const session = mod.bindMcpApp({\n iframe,\n getContent: () => this.#content ?? content,\n getAgent: () => this.#agent,\n host: this.#options.host,\n messageId: this.#messageId,\n options: this.#options.sessionOptions,\n cancelFollowUpsOnTeardown: scoped,\n requireExactResourceUri: scoped,\n cancelRunningWaitOnTeardown: scoped,\n hooks: {\n onResource: (resource: FetchedResource) => {\n if (!isCurrent()) return;\n this.#setState({\n ...this.#state,\n loading: false,\n prefersBorder: resource._meta?.ui?.prefersBorder === true,\n });\n },\n onInitialized: () => {\n if (isCurrent()) {\n iframe.setAttribute(\"data-mcp-app-initialized\", \"true\");\n }\n },\n onSizeChanged: (size) => {\n if (isCurrent()) this.#applySize(iframe, size);\n },\n onContentError: (err) => {\n if (!isCurrent()) return;\n this.#setState({\n ...this.#state,\n contentError: err?.message ?? null,\n });\n },\n onError: fail,\n ...(scoped ? { onFollowUpError: fail } : {}),\n },\n });\n this.#session = session;\n // Seed the content: an activity rendered from an external message\n // list is not in the agent's store, so nothing else would send it.\n session.syncContent(this.#content ?? content);\n })\n .catch((err: unknown) => {\n console.error(\"[MCPAppsRenderer] Setup error:\", err);\n fail(err instanceof Error ? err : new Error(String(err)));\n });\n }\n\n #applySize(\n iframe: HTMLIFrameElement,\n size: { width?: number; height?: number },\n ) {\n const next: McpAppHostState[\"size\"] = {};\n if (typeof size.width === \"number\" && Number.isFinite(size.width)) {\n next.width = size.width;\n // Allow expansion but cap at the container width.\n iframe.style.minWidth = `min(${String(size.width)}px, 100%)`;\n iframe.style.width = \"100%\";\n }\n const height = size.height;\n if (typeof height === \"number\" && Number.isFinite(height) && height > 0) {\n next.height = Math.ceil(Math.min(height, MCP_APP_MAX_HEIGHT));\n iframe.style.height = `${String(next.height)}px`;\n }\n this.#setState({ ...this.#state, size: next });\n }\n\n #unbind() {\n this.#generation += 1;\n this.#session?.teardown();\n this.#session = null;\n this.#iframe?.remove();\n this.#iframe = null;\n }\n\n #setState(state: McpAppHostState) {\n this.#state = state;\n for (const listener of this.#listeners) listener();\n }\n}\n"],"mappings":"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"}
@@ -0,0 +1,99 @@
1
+ import { MCPAppsActivityContent } from "./content-schema.cjs";
2
+ import { ɵMcpFollowUpHost } from "./follow-up.cjs";
3
+ import { BindMcpAppOptions, McpAppSession, McpAppSessionOptions } from "./session.cjs";
4
+ import { AbstractAgent } from "@ag-ui/client";
5
+
6
+ //#region src/host.d.ts
7
+ /** The part of the bridge module the host uses, loaded on demand. */
8
+ interface McpAppsRendererModule {
9
+ bindMcpApp(options: BindMcpAppOptions): McpAppSession;
10
+ }
11
+ /** Message shown when the bridge package cannot be loaded. */
12
+ declare const MCP_APPS_RENDERER_MISSING_MESSAGE: string;
13
+ /** Error text when an MCP App renders without an agent to fetch it through. */
14
+ declare const MCP_APPS_NO_AGENT_MESSAGE = "No agent available to fetch resource";
15
+ /** Tallest an MCP App iframe may grow, in pixels. */
16
+ declare const MCP_APP_MAX_HEIGHT = 5000;
17
+ /** Imports the bridge module; frontends pass `() => import("@copilotkit/mcp-apps-renderer")`. */
18
+ type McpAppsRendererImporter = () => Promise<McpAppsRendererModule>;
19
+ /**
20
+ * Loads the bridge (`bindMcpApp`) lazily. The bridge pulls the MCP SDK and
21
+ * its zod schemas (~40-50 kB gzipped), so an app only pays for it when an MCP
22
+ * App renders. The `import()` itself stays in the frontend, where its bundler
23
+ * can split it out. A failed load rethrows with what to install, since a raw
24
+ * module-resolution error does not say.
25
+ *
26
+ * @param importRenderer - `() => import("@copilotkit/mcp-apps-renderer")`.
27
+ */
28
+ declare function loadMcpAppsRenderer(importRenderer: McpAppsRendererImporter): Promise<McpAppsRendererModule>;
29
+ /** What a frontend renders around the MCP App iframe. */
30
+ interface McpAppHostState {
31
+ loading: boolean;
32
+ /** Fatal setup failure; shown until the host binds again. */
33
+ error: string | null;
34
+ /** Recoverable: the latest content was rejected and not forwarded. */
35
+ contentError: string | null;
36
+ /** The size the widget reported. */
37
+ size: {
38
+ width?: number;
39
+ height?: number;
40
+ };
41
+ /** The resource asked the host for a border and background. */
42
+ prefersBorder: boolean;
43
+ }
44
+ interface McpAppHostOptions {
45
+ /** The CopilotKit core, for `ui/message` follow-up runs. */
46
+ host: ɵMcpFollowUpHost;
47
+ /** Session options (host info, timeouts, `allowSameOriginFallback`). */
48
+ sessionOptions?: McpAppSessionOptions;
49
+ /**
50
+ * Scope the session to the widget (Angular's contract): teardown cancels
51
+ * its queued follow-up and releases running waits, the fetched resource URI
52
+ * must match exactly, and a failed follow-up or setup error tears the
53
+ * session down, blanks the iframe and shows the error.
54
+ */
55
+ scopeToWidget?: boolean;
56
+ /** Attributes set on the iframe, such as a `data-testid` or `title`. */
57
+ iframeAttributes?: Record<string, string>;
58
+ /** `() => import("@copilotkit/mcp-apps-renderer")`; see {@link loadMcpAppsRenderer}. */
59
+ importRenderer: McpAppsRendererImporter;
60
+ }
61
+ /**
62
+ * Hosts one MCP App: creates the sandbox iframe in a container, binds the
63
+ * MCP session to it, sizes it as the widget reports, and keeps the state a
64
+ * frontend renders. It binds again (new iframe, new session) only when the
65
+ * container, agent, message id or widget identity (resource URI, server)
66
+ * changes; new tool input or results feed the existing session.
67
+ *
68
+ * @example
69
+ * ```ts
70
+ * const app = new ɵMcpAppHost({ host: core });
71
+ * app.subscribe(() => render(app.getState()));
72
+ * app.setContent(content);
73
+ * app.setAgent(agent);
74
+ * app.setMessageId(message.id);
75
+ * app.setContainer(element); // on mount
76
+ * app.destroy(); // on unmount
77
+ * ```
78
+ */
79
+ declare class McpAppHost {
80
+ #private;
81
+ constructor(options: McpAppHostOptions);
82
+ /** The current state. The same object until something changes. */
83
+ getState: () => McpAppHostState;
84
+ /** Calls `listener` when the state changes. Returns the unsubscribe function. */
85
+ subscribe: (listener: () => void) => () => void;
86
+ /** Sets the element the iframe goes into. `null` removes it. */
87
+ setContainer(container: HTMLElement | null): void;
88
+ /** Sets the latest activity content. */
89
+ setContent(content: MCPAppsActivityContent): void;
90
+ /** Sets the agent the widget's requests go through. */
91
+ setAgent(agent: AbstractAgent | undefined): void;
92
+ /** Sets the id of the activity message, so the session follows the store. */
93
+ setMessageId(messageId: string | undefined): void;
94
+ /** Tears the session down and removes the iframe. A later setter binds again. */
95
+ destroy(): void;
96
+ }
97
+ //#endregion
98
+ export { MCP_APPS_NO_AGENT_MESSAGE, MCP_APPS_RENDERER_MISSING_MESSAGE, MCP_APP_MAX_HEIGHT, McpAppHost, McpAppHostOptions, McpAppHostState, McpAppsRendererImporter, loadMcpAppsRenderer };
99
+ //# sourceMappingURL=host.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"host.d.cts","names":[],"sources":["../src/host.ts"],"mappings":";;;;;;;UAeiB,qBAAA;EACf,UAAA,CAAW,OAAA,EAAS,iBAAA,GAAoB,aAAA;AAAA;;cAI7B,iCAAA;;cAMA,yBAAA;;cAGA,kBAAA;;KAMD,uBAAA,SAAgC,OAAA,CAAQ,qBAAA;AAfpD;;;;;AAMA;;;;AANA,iBA0BgB,mBAAA,CAAoB,cAAA,EAAgB,uBAAA,GAAuB,OAAA,CAAA,qBAAA;AAjB3E;AAAA,UAwBiB,eAAA;EACf,OAAA;EAzB6B;EA2B7B,KAAA;EArBU;EAuBV,YAAA;;EAEA,IAAA;IAAQ,KAAA;IAAgB,MAAA;EAAA;;EAExB,aAAA;AAAA;AAAA,UAGe,iBAAA;EAnB0D;EAqBzE,IAAA,EAAM,gBAAA;EArB4C;EAuBlD,cAAA,GAAiB,oBAAA;EAvBwD;;;;AAO3E;;EAuBE,aAAA;EAvB8B;EAyB9B,gBAAA,GAAmB,MAAA;EAtBnB;EAwBA,cAAA,EAAgB,uBAAA;AAAA;;;;;;AAflB;;;;;;;;;;;;;cAqDa,UAAA;EAAA;cAcC,OAAA,EAAS,iBAAA;EApDrB;EAyDA,QAAA,QAAQ,eAAA;EAzD+B;EA4DvC,SAAA,GAAa,QAAA;EAtBF;EA8BX,YAAA,CAAa,SAAA,EAAW,WAAA;;EAMxB,UAAA,CAAW,OAAA,EAAS,sBAAA;EAjBZ;EAuBR,QAAA,CAAS,KAAA,EAAO,aAAA;EANI;EAYpB,YAAA,CAAa,SAAA;EANgB;EAY7B,OAAA,CAAA;AAAA"}
@@ -0,0 +1,99 @@
1
+ import { MCPAppsActivityContent } from "./content-schema.mjs";
2
+ import { ɵMcpFollowUpHost } from "./follow-up.mjs";
3
+ import { BindMcpAppOptions, McpAppSession, McpAppSessionOptions } from "./session.mjs";
4
+ import { AbstractAgent } from "@ag-ui/client";
5
+
6
+ //#region src/host.d.ts
7
+ /** The part of the bridge module the host uses, loaded on demand. */
8
+ interface McpAppsRendererModule {
9
+ bindMcpApp(options: BindMcpAppOptions): McpAppSession;
10
+ }
11
+ /** Message shown when the bridge package cannot be loaded. */
12
+ declare const MCP_APPS_RENDERER_MISSING_MESSAGE: string;
13
+ /** Error text when an MCP App renders without an agent to fetch it through. */
14
+ declare const MCP_APPS_NO_AGENT_MESSAGE = "No agent available to fetch resource";
15
+ /** Tallest an MCP App iframe may grow, in pixels. */
16
+ declare const MCP_APP_MAX_HEIGHT = 5000;
17
+ /** Imports the bridge module; frontends pass `() => import("@copilotkit/mcp-apps-renderer")`. */
18
+ type McpAppsRendererImporter = () => Promise<McpAppsRendererModule>;
19
+ /**
20
+ * Loads the bridge (`bindMcpApp`) lazily. The bridge pulls the MCP SDK and
21
+ * its zod schemas (~40-50 kB gzipped), so an app only pays for it when an MCP
22
+ * App renders. The `import()` itself stays in the frontend, where its bundler
23
+ * can split it out. A failed load rethrows with what to install, since a raw
24
+ * module-resolution error does not say.
25
+ *
26
+ * @param importRenderer - `() => import("@copilotkit/mcp-apps-renderer")`.
27
+ */
28
+ declare function loadMcpAppsRenderer(importRenderer: McpAppsRendererImporter): Promise<McpAppsRendererModule>;
29
+ /** What a frontend renders around the MCP App iframe. */
30
+ interface McpAppHostState {
31
+ loading: boolean;
32
+ /** Fatal setup failure; shown until the host binds again. */
33
+ error: string | null;
34
+ /** Recoverable: the latest content was rejected and not forwarded. */
35
+ contentError: string | null;
36
+ /** The size the widget reported. */
37
+ size: {
38
+ width?: number;
39
+ height?: number;
40
+ };
41
+ /** The resource asked the host for a border and background. */
42
+ prefersBorder: boolean;
43
+ }
44
+ interface McpAppHostOptions {
45
+ /** The CopilotKit core, for `ui/message` follow-up runs. */
46
+ host: ɵMcpFollowUpHost;
47
+ /** Session options (host info, timeouts, `allowSameOriginFallback`). */
48
+ sessionOptions?: McpAppSessionOptions;
49
+ /**
50
+ * Scope the session to the widget (Angular's contract): teardown cancels
51
+ * its queued follow-up and releases running waits, the fetched resource URI
52
+ * must match exactly, and a failed follow-up or setup error tears the
53
+ * session down, blanks the iframe and shows the error.
54
+ */
55
+ scopeToWidget?: boolean;
56
+ /** Attributes set on the iframe, such as a `data-testid` or `title`. */
57
+ iframeAttributes?: Record<string, string>;
58
+ /** `() => import("@copilotkit/mcp-apps-renderer")`; see {@link loadMcpAppsRenderer}. */
59
+ importRenderer: McpAppsRendererImporter;
60
+ }
61
+ /**
62
+ * Hosts one MCP App: creates the sandbox iframe in a container, binds the
63
+ * MCP session to it, sizes it as the widget reports, and keeps the state a
64
+ * frontend renders. It binds again (new iframe, new session) only when the
65
+ * container, agent, message id or widget identity (resource URI, server)
66
+ * changes; new tool input or results feed the existing session.
67
+ *
68
+ * @example
69
+ * ```ts
70
+ * const app = new ɵMcpAppHost({ host: core });
71
+ * app.subscribe(() => render(app.getState()));
72
+ * app.setContent(content);
73
+ * app.setAgent(agent);
74
+ * app.setMessageId(message.id);
75
+ * app.setContainer(element); // on mount
76
+ * app.destroy(); // on unmount
77
+ * ```
78
+ */
79
+ declare class McpAppHost {
80
+ #private;
81
+ constructor(options: McpAppHostOptions);
82
+ /** The current state. The same object until something changes. */
83
+ getState: () => McpAppHostState;
84
+ /** Calls `listener` when the state changes. Returns the unsubscribe function. */
85
+ subscribe: (listener: () => void) => () => void;
86
+ /** Sets the element the iframe goes into. `null` removes it. */
87
+ setContainer(container: HTMLElement | null): void;
88
+ /** Sets the latest activity content. */
89
+ setContent(content: MCPAppsActivityContent): void;
90
+ /** Sets the agent the widget's requests go through. */
91
+ setAgent(agent: AbstractAgent | undefined): void;
92
+ /** Sets the id of the activity message, so the session follows the store. */
93
+ setMessageId(messageId: string | undefined): void;
94
+ /** Tears the session down and removes the iframe. A later setter binds again. */
95
+ destroy(): void;
96
+ }
97
+ //#endregion
98
+ export { MCP_APPS_NO_AGENT_MESSAGE, MCP_APPS_RENDERER_MISSING_MESSAGE, MCP_APP_MAX_HEIGHT, McpAppHost, McpAppHostOptions, McpAppHostState, McpAppsRendererImporter, loadMcpAppsRenderer };
99
+ //# sourceMappingURL=host.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"host.d.mts","names":[],"sources":["../src/host.ts"],"mappings":";;;;;;;UAeiB,qBAAA;EACf,UAAA,CAAW,OAAA,EAAS,iBAAA,GAAoB,aAAA;AAAA;;cAI7B,iCAAA;;cAMA,yBAAA;;cAGA,kBAAA;;KAMD,uBAAA,SAAgC,OAAA,CAAQ,qBAAA;AAfpD;;;;;AAMA;;;;AANA,iBA0BgB,mBAAA,CAAoB,cAAA,EAAgB,uBAAA,GAAuB,OAAA,CAAA,qBAAA;AAjB3E;AAAA,UAwBiB,eAAA;EACf,OAAA;EAzB6B;EA2B7B,KAAA;EArBU;EAuBV,YAAA;;EAEA,IAAA;IAAQ,KAAA;IAAgB,MAAA;EAAA;;EAExB,aAAA;AAAA;AAAA,UAGe,iBAAA;EAnB0D;EAqBzE,IAAA,EAAM,gBAAA;EArB4C;EAuBlD,cAAA,GAAiB,oBAAA;EAvBwD;;;;AAO3E;;EAuBE,aAAA;EAvB8B;EAyB9B,gBAAA,GAAmB,MAAA;EAtBnB;EAwBA,cAAA,EAAgB,uBAAA;AAAA;;;;;;AAflB;;;;;;;;;;;;;cAqDa,UAAA;EAAA;cAcC,OAAA,EAAS,iBAAA;EApDrB;EAyDA,QAAA,QAAQ,eAAA;EAzD+B;EA4DvC,SAAA,GAAa,QAAA;EAtBF;EA8BX,YAAA,CAAa,SAAA,EAAW,WAAA;;EAMxB,UAAA,CAAW,OAAA,EAAS,sBAAA;EAjBZ;EAuBR,QAAA,CAAS,KAAA,EAAO,aAAA;EANI;EAYpB,YAAA,CAAa,SAAA;EANgB;EAY7B,OAAA,CAAA;AAAA"}