The best way to control Claude Code, Codex and more from any computer or phone

main
ts 455 lines 15.4 KB
Raw
1 import { describe, expect, it } from "vite-plus/test";
2
3 import { makeMcpAppHost, McpAppHostRefusal, type McpAppHostContext } from "./host.ts";
4
5 const app = {
6 attachmentId: "thread-1-app",
7 server: "weather",
8 tool: "get_weather",
9 resourceUri: "ui://weather/dashboard",
10 csp: { connectDomains: ["https://api.weather.test"] },
11 };
12
13 const context = (
14 theme: "light" | "dark" = "dark",
15 displayMode: "inline" | "fullscreen" = "inline",
16 ): McpAppHostContext => ({
17 theme,
18 styles: { variables: { "--color-background-primary": theme === "dark" ? "#000" : "#fff" } },
19 displayMode,
20 availableDisplayModes: ["inline", "fullscreen"],
21 containerDimensions: { width: 600, maxHeight: 2000 },
22 platform: "web",
23 });
24
25 const flush = () => new Promise<void>((resolve) => queueMicrotask(resolve)).then(() => undefined);
26
27 const initialize = (
28 host: ReturnType<typeof makeMcpAppHost>,
29 appCapabilities: Record<string, unknown> = {},
30 ) => {
31 host.receive({
32 jsonrpc: "2.0",
33 id: "init",
34 method: "ui/initialize",
35 params: { appCapabilities },
36 });
37 host.receive({ jsonrpc: "2.0", method: "ui/notifications/initialized" });
38 };
39
40 function setup(overrides: Partial<Parameters<typeof makeMcpAppHost>[0]> = {}) {
41 const sent: Array<Record<string, unknown>> = [];
42 let theme: "light" | "dark" = "dark";
43 let mode: "inline" | "fullscreen" = "inline";
44 const host = makeMcpAppHost({
45 app,
46 hostVersion: "1.0.0",
47 post: (message) => sent.push(message as Record<string, unknown>),
48 hostContext: () => context(theme, mode),
49 callTool: async (input) => ({ content: [{ type: "text", text: `called ${input.name}` }] }),
50 readResource: async () => ({ contents: [] }),
51 openLink: async () => undefined,
52 sendMessage: async () => undefined,
53 updateModelContext: async () => undefined,
54 requestDisplayMode: async (next) => {
55 mode = next === "fullscreen" ? "fullscreen" : "inline";
56 return mode;
57 },
58 downloadFile: async () => undefined,
59 onRequestTeardown: () => undefined,
60 onSizeChanged: () => undefined,
61 ...overrides,
62 });
63 return {
64 host,
65 sent,
66 setTheme: (next: "light" | "dark") => {
67 theme = next;
68 },
69 };
70 }
71
72 describe("makeMcpAppHost", () => {
73 it("initializes, then replays the tool input and result after initialized", () => {
74 const { host, sent } = setup();
75 host.setToolCall({
76 arguments: { city: "Oslo" },
77 result: { content: [{ type: "text", text: "Sunny" }] },
78 });
79 host.receive({
80 jsonrpc: "2.0",
81 id: 1,
82 method: "ui/initialize",
83 params: { protocolVersion: "2026-01-26", appInfo: { name: "a", version: "1" } },
84 });
85 expect(sent[0]).toMatchObject({
86 id: 1,
87 result: {
88 protocolVersion: "2026-01-26",
89 hostCapabilities: { serverTools: {}, sandbox: { csp: app.csp } },
90 hostContext: { theme: "dark", displayMode: "inline" },
91 },
92 });
93 expect(sent).toHaveLength(1);
94
95 host.receive({ jsonrpc: "2.0", method: "ui/notifications/initialized", params: {} });
96 expect(sent.slice(1)).toEqual([
97 {
98 jsonrpc: "2.0",
99 method: "ui/notifications/tool-input",
100 params: { arguments: { city: "Oslo" } },
101 },
102 {
103 jsonrpc: "2.0",
104 method: "ui/notifications/tool-result",
105 params: { content: [{ type: "text", text: "Sunny" }] },
106 },
107 ]);
108 });
109
110 it("drops null fields providers report, which the MCP Apps SDK rejects", async () => {
111 const { host, sent } = setup({
112 callTool: async () => ({ content: [], structuredContent: null, _meta: null }),
113 });
114 host.receive({ jsonrpc: "2.0", id: 1, method: "ui/initialize", params: {} });
115 host.receive({ jsonrpc: "2.0", method: "ui/notifications/initialized" });
116 host.setToolCall({
117 arguments: {},
118 result: {
119 content: [{ type: "text", text: "t" }],
120 structuredContent: { time: "t" },
121 _meta: null,
122 },
123 });
124 host.receive({ jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "get-time" } });
125 await flush();
126 expect(sent.find((m) => m.method === "ui/notifications/tool-result")?.params).toEqual({
127 content: [{ type: "text", text: "t" }],
128 structuredContent: { time: "t" },
129 });
130 expect(sent.find((m) => m.id === 2)?.result).toEqual({ content: [] });
131 });
132
133 it("delivers results whose stored image blocks lost their bytes, which the MCP Apps SDK rejects", async () => {
134 const { host, sent } = setup({
135 callTool: async () => ({
136 content: [
137 { type: "text", text: "rendered" },
138 { type: "image", mimeType: "image/png", sizeBytes: 300 },
139 { type: "image", mimeType: "image/png", data: "iVBORw0KGgo=" },
140 ],
141 structuredContent: { rendered: true },
142 }),
143 });
144 initialize(host);
145 host.setToolCall({
146 arguments: {},
147 result: {
148 content: [
149 { type: "text", text: "Chart ready" },
150 { type: "image", source: { type: "base64", media_type: "image/png", sizeBytes: 300 } },
151 { type: "text", text: "[Image: source: /tmp/chart.png]" },
152 ],
153 structuredContent: { chart: "sales" },
154 },
155 });
156 host.receive({ jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "render" } });
157 await flush();
158
159 const notified = sent.find((m) => m.method === "ui/notifications/tool-result")?.params as {
160 content: ReadonlyArray<unknown>;
161 structuredContent: unknown;
162 };
163 expect(notified.structuredContent).toEqual({ chart: "sales" });
164 expect(notified.content).toContainEqual({ type: "text", text: "Chart ready" });
165 expect(notified.content).not.toContainEqual(expect.objectContaining({ type: "image" }));
166
167 const answered = sent.find((m) => m.id === 2)?.result as {
168 content: ReadonlyArray<unknown>;
169 structuredContent: unknown;
170 };
171 expect(answered.structuredContent).toEqual({ rendered: true });
172 expect(answered.content).toEqual([
173 { type: "text", text: "rendered" },
174 { type: "image", mimeType: "image/png", data: "iVBORw0KGgo=" },
175 ]);
176 });
177
178 it("sends a later result for a call that had none, without repeating its input", () => {
179 const { host, sent } = setup();
180 initialize(host);
181 sent.length = 0;
182 host.setToolCall({ arguments: { city: "Oslo" }, result: undefined });
183 host.setToolCall({
184 arguments: { city: "Oslo" },
185 result: { content: [{ type: "text", text: "Sunny" }] },
186 });
187 host.setToolCall({
188 arguments: { city: "Bergen" },
189 result: { content: [{ type: "text", text: "Rain" }] },
190 });
191 expect(sent).toEqual([
192 {
193 jsonrpc: "2.0",
194 method: "ui/notifications/tool-input",
195 params: { arguments: { city: "Oslo" } },
196 },
197 {
198 jsonrpc: "2.0",
199 method: "ui/notifications/tool-result",
200 params: { content: [{ type: "text", text: "Sunny" }] },
201 },
202 ]);
203 });
204
205 it("accepts ui/message as one text block or the SDK's block array", async () => {
206 const messages: Array<string> = [];
207 const { host, sent } = setup({ sendMessage: async (text) => void messages.push(text) });
208 host.receive({
209 jsonrpc: "2.0",
210 id: 1,
211 method: "ui/message",
212 params: { role: "user", content: { type: "text", text: "one" } },
213 });
214 host.receive({
215 jsonrpc: "2.0",
216 id: 2,
217 method: "ui/message",
218 params: { role: "user", content: [{ type: "text", text: "two" }] },
219 });
220 host.receive({
221 jsonrpc: "2.0",
222 id: 3,
223 method: "ui/message",
224 params: { role: "user", content: [{ type: "image", data: "x" }] },
225 });
226 host.receive({
227 jsonrpc: "2.0",
228 id: 4,
229 method: "ui/message",
230 params: { role: "user", content: { type: "text", text: " " } },
231 });
232 await flush();
233 expect(messages).toEqual(["one", "two"]);
234 expect(sent.find((m) => m.id === 3)?.error).toMatchObject({ code: -32602 });
235 expect(sent.find((m) => m.id === 4)?.error).toMatchObject({ code: -32602 });
236 });
237
238 it("catches the app up on context that changed while it was initializing", () => {
239 const { host, sent, setTheme } = setup();
240 host.receive({ jsonrpc: "2.0", id: 1, method: "ui/initialize", params: {} });
241 setTheme("light");
242 host.receive({ jsonrpc: "2.0", method: "ui/notifications/initialized" });
243 expect(sent.at(-1)).toEqual({
244 jsonrpc: "2.0",
245 method: "ui/notifications/host-context-changed",
246 params: { theme: "light", styles: context("light").styles },
247 });
248 });
249
250 it("proxies tools/call and reports a refusal as a JSON-RPC error", async () => {
251 const received: unknown[] = [];
252 const { host, sent } = setup({
253 callTool: async (input) => {
254 if (input.name === "delete_everything")
255 throw new McpAppHostRefusal({ message: "Declined by the user." });
256 received.push(input.arguments);
257 return { content: [], structuredContent: { ok: true } };
258 },
259 });
260 host.receive({ jsonrpc: "2.0", id: 7, method: "tools/call", params: { name: "refresh" } });
261 host.receive({
262 jsonrpc: "2.0",
263 id: 8,
264 method: "tools/call",
265 params: { name: "delete_everything", arguments: {} },
266 });
267 // postMessage's structured clone keeps undefined properties, which JSON cannot carry.
268 host.receive({
269 jsonrpc: "2.0",
270 id: 9,
271 method: "tools/call",
272 params: {
273 name: "poll",
274 arguments: { since: undefined, nested: { a: undefined, b: 1 }, list: [1, undefined] },
275 },
276 });
277 await flush();
278 expect(received).toStrictEqual([{}, { nested: { b: 1 }, list: [1, null] }]);
279 expect(sent).toContainEqual({
280 jsonrpc: "2.0",
281 id: 7,
282 result: { content: [], structuredContent: { ok: true } },
283 });
284 expect(sent).toContainEqual({
285 jsonrpc: "2.0",
286 id: 8,
287 error: { code: -32000, message: "Declined by the user." },
288 });
289 });
290
291 it("rejects malformed requests and unsupported methods", () => {
292 const { host, sent } = setup();
293 host.receive({
294 jsonrpc: "2.0",
295 id: 1,
296 method: "ui/open-link",
297 params: { url: "javascript:x" },
298 });
299 host.receive({ jsonrpc: "2.0", id: 3, method: "sampling/createMessage", params: {} });
300 host.receive({ jsonrpc: "2.0", id: 4, method: "ui/message", params: { role: "assistant" } });
301 host.receive({
302 jsonrpc: "2.0",
303 id: 5,
304 method: "tools/call",
305 params: { name: "poll", arguments: { since: 1n } },
306 });
307 expect(sent.map((message) => (message.error as { code: number }).code)).toEqual([
308 -32602, -32601, -32602, -32602,
309 ]);
310 });
311
312 it("refuses requests past the in-flight limit and posts nothing after dispose", async () => {
313 let release: () => void = () => undefined;
314 const gate = new Promise<void>((resolve) => {
315 release = resolve;
316 });
317 const { host, sent } = setup({
318 callTool: async () => {
319 await gate;
320 return { content: [] };
321 },
322 });
323 for (let id = 0; id < 17; id++) {
324 host.receive({ jsonrpc: "2.0", id, method: "tools/call", params: { name: "slow" } });
325 }
326 expect(sent).toEqual([
327 { jsonrpc: "2.0", id: 16, error: { code: -32000, message: "Too many requests in flight." } },
328 ]);
329 host.dispose();
330 release();
331 await flush();
332 expect(sent).toHaveLength(1);
333 });
334
335 it("switches display mode only to one both sides offer, and tells the app", async () => {
336 const { host, sent } = setup();
337 initialize(host, { availableDisplayModes: ["inline", "fullscreen"] });
338 sent.length = 0;
339 host.receive({
340 jsonrpc: "2.0",
341 id: 1,
342 method: "ui/request-display-mode",
343 params: { mode: "pip" },
344 });
345 host.receive({
346 jsonrpc: "2.0",
347 id: 2,
348 method: "ui/request-display-mode",
349 params: { mode: "fullscreen" },
350 });
351 await flush();
352 host.updateHostContext();
353 expect(sent.find((m) => m.id === 1)?.result).toEqual({ mode: "inline" });
354 expect(sent.find((m) => m.id === 2)?.result).toEqual({ mode: "fullscreen" });
355 expect(sent.find((m) => m.method === "ui/notifications/host-context-changed")?.params).toEqual({
356 displayMode: "fullscreen",
357 });
358
359 const declined = setup();
360 initialize(declined.host, { availableDisplayModes: ["inline"] });
361 declined.host.receive({
362 jsonrpc: "2.0",
363 id: 3,
364 method: "ui/request-display-mode",
365 params: { mode: "fullscreen" },
366 });
367 await flush();
368 expect(declined.sent.find((m) => m.id === 3)?.result).toEqual({ mode: "inline" });
369 });
370
371 it("forwards model context and download requests, and declares both", async () => {
372 const contexts: Array<unknown> = [];
373 const downloads: Array<ReadonlyArray<{ readonly name: string }>> = [];
374 const { host, sent } = setup({
375 updateModelContext: async (update) => void contexts.push(update),
376 downloadFile: async (files) => {
377 downloads.push(files);
378 if (files.length > 1) throw new McpAppHostRefusal({ message: "Declined by the user." });
379 },
380 });
381 initialize(host);
382 const capabilities = (
383 sent[0]?.result as { hostCapabilities: Record<string, unknown> } | undefined
384 )?.hostCapabilities;
385 expect(capabilities?.updateModelContext).toEqual({ text: {}, structuredContent: {} });
386 expect(capabilities?.downloadFile).toEqual({});
387
388 host.receive({
389 jsonrpc: "2.0",
390 id: 1,
391 method: "ui/update-model-context",
392 params: {
393 content: [{ type: "text", text: "2 overdue" }],
394 structuredContent: { overdue: 2, since: undefined },
395 },
396 });
397 const longName = `${"a".repeat(199)}😀.csv`;
398 const embedded = {
399 type: "resource",
400 resource: { uri: "file:///report.csv", mimeType: "text/csv", text: "a,b" },
401 };
402 host.receive({
403 jsonrpc: "2.0",
404 id: 2,
405 method: "ui/download-file",
406 params: { contents: [embedded] },
407 });
408 host.receive({
409 jsonrpc: "2.0",
410 id: 3,
411 method: "ui/download-file",
412 params: {
413 contents: [embedded, { type: "resource_link", uri: "ui://todos/export", name: longName }],
414 },
415 });
416 host.receive({ jsonrpc: "2.0", id: 4, method: "ui/download-file", params: { contents: [{}] } });
417 await flush();
418 expect(contexts).toStrictEqual([
419 { content: [{ type: "text", text: "2 overdue" }], structuredContent: { overdue: 2 } },
420 ]);
421 expect(downloads[0]).toEqual([
422 {
423 _tag: "embedded",
424 name: "report.csv",
425 mimeType: "text/csv",
426 bytes: new TextEncoder().encode("a,b"),
427 },
428 ]);
429 const capped = downloads[1]?.[1]?.name ?? "";
430 expect(capped.length).toBeLessThanOrEqual(200);
431 expect(capped.isWellFormed()).toBe(true);
432 expect(sent.find((m) => m.id === 2)?.result).toEqual({});
433 expect(sent.find((m) => m.id === 3)?.result).toEqual({ isError: true });
434 expect(sent.find((m) => m.id === 4)?.error).toMatchObject({ code: -32602 });
435
436 const unnamedUris = [
437 "https://example.invalid/report.csv?version=2",
438 "https://example.invalid/report.csv#page=2",
439 "https://example.invalid/report.csv?next=/noise.json#page=3",
440 ];
441 for (const [index, uri] of unnamedUris.entries()) {
442 const id = `download-${index}`;
443 const downloadIndex = downloads.length;
444 host.receive({
445 jsonrpc: "2.0",
446 id,
447 method: "ui/download-file",
448 params: { contents: [{ ...embedded, resource: { ...embedded.resource, uri } }] },
449 });
450 await flush();
451 expect(downloads[downloadIndex]?.[0]).toMatchObject({ _tag: "embedded", name: "report.csv" });
452 expect(sent.find((m) => m.id === id)?.result).toEqual({});
453 }
454 });
455 });