xmcp 0.6.4 → 0.6.6
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/cli.js +45 -29
- package/dist/compiler/config/index.d.ts +59 -0
- package/dist/compiler/config/schemas/template.d.ts +40 -0
- package/dist/compiler/config/schemas/transport/stdio.d.ts +5 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +4 -4
- package/dist/runtime/adapter-express.js +15 -38
- package/dist/runtime/adapter-nestjs.js +17 -40
- package/dist/runtime/adapter-nextjs.js +16 -39
- package/dist/runtime/http.js +23 -46
- package/dist/runtime/stdio.js +16 -39
- package/dist/types/resource.d.ts +3 -3
- package/dist/types/tool.d.ts +4 -4
- package/dist/types/ui-meta.d.ts +22 -0
- package/package.json +2 -2
- package/src/compiler/client/component-compiler.ts +0 -4
- package/src/compiler/config/__tests__/config.test.ts +36 -0
- package/src/compiler/config/injection.ts +63 -1
- package/src/compiler/config/schemas/template.ts +17 -0
- package/src/compiler/config/schemas/transport/stdio.ts +1 -0
- package/src/compiler/generate-tools-code.ts +21 -1
- package/src/compiler/get-bundler-config/get-injected-variables.ts +3 -0
- package/src/compiler/index.ts +100 -24
- package/src/compiler/on-first-build.ts +34 -50
- package/src/compiler/start-http-server.ts +11 -4
- package/src/compiler/watcher-recovery.ts +72 -0
- package/src/index.ts +2 -1
- package/src/runtime/transports/stdio/index.ts +19 -0
- package/src/runtime/utils/react/generate-html.ts +0 -32
- package/src/runtime/utils/resources.ts +15 -15
- package/src/runtime/utils/server.ts +5 -8
- package/src/runtime/utils/tools.ts +55 -71
- package/src/runtime/utils/transformers/tool.ts +148 -30
- package/src/types/resource.ts +3 -3
- package/src/types/tool.ts +4 -4
- package/src/types/ui-meta.ts +26 -0
- package/dist/types/openai-meta.d.ts +0 -173
- package/src/runtime/utils/openai/flatten-meta.ts +0 -44
- package/src/runtime/utils/openai/split-meta.ts +0 -81
- package/src/runtime/utils/openai-resource-registry.ts +0 -58
- package/src/types/openai-meta.ts +0 -191
|
@@ -7,17 +7,52 @@ import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol";
|
|
|
7
7
|
import { ZodRawShape } from "zod/v3";
|
|
8
8
|
import { validateContent } from "../validators";
|
|
9
9
|
|
|
10
|
+
function validateAgainstOutputSchema(
|
|
11
|
+
data: Record<string, unknown>,
|
|
12
|
+
outputSchema: ZodRawShape,
|
|
13
|
+
toolName: string,
|
|
14
|
+
errorPrefix: string
|
|
15
|
+
): void {
|
|
16
|
+
if (data === null || typeof data !== "object" || Array.isArray(data)) {
|
|
17
|
+
throw new Error(
|
|
18
|
+
`Tool "${toolName}" ${errorPrefix}: expected a plain object.`
|
|
19
|
+
);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const outputKeys = new Set(Object.keys(outputSchema));
|
|
23
|
+
const extraKeys = Object.keys(data).filter((key) => !outputKeys.has(key));
|
|
24
|
+
if (extraKeys.length > 0) {
|
|
25
|
+
throw new Error(
|
|
26
|
+
`Tool "${toolName}" ${errorPrefix}: unrecognized key(s): ${extraKeys.join(", ")}`
|
|
27
|
+
);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
for (const [fieldName, fieldSchema] of Object.entries(outputSchema)) {
|
|
31
|
+
try {
|
|
32
|
+
fieldSchema.parse((data as any)[fieldName]);
|
|
33
|
+
} catch (error: any) {
|
|
34
|
+
throw new Error(
|
|
35
|
+
`Tool "${toolName}" ${errorPrefix}: ${error?.message ?? `invalid field "${fieldName}"`}`
|
|
36
|
+
);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
|
|
10
41
|
/**
|
|
11
42
|
* Type for the original tool handler that users write
|
|
12
43
|
*/
|
|
44
|
+
export type UserToolResponse =
|
|
45
|
+
| CallToolResult
|
|
46
|
+
| string
|
|
47
|
+
| number
|
|
48
|
+
| Record<string, unknown>;
|
|
49
|
+
|
|
13
50
|
export type UserToolHandler = (
|
|
14
51
|
args: ZodRawShape,
|
|
15
52
|
extra: RequestHandlerExtra<ServerRequest, ServerNotification>
|
|
16
53
|
) =>
|
|
17
|
-
|
|
|
18
|
-
|
|
|
19
|
-
| number
|
|
20
|
-
| Promise<CallToolResult | string | number>;
|
|
54
|
+
| UserToolResponse
|
|
55
|
+
| Promise<UserToolResponse>;
|
|
21
56
|
|
|
22
57
|
/**
|
|
23
58
|
* Type for the transformed handler that the MCP server expects
|
|
@@ -27,6 +62,14 @@ export type McpToolHandler = (
|
|
|
27
62
|
extra: RequestHandlerExtra<ServerRequest, ServerNotification>
|
|
28
63
|
) => CallToolResult | Promise<CallToolResult>;
|
|
29
64
|
|
|
65
|
+
function hasUIMeta(meta?: Record<string, any>): boolean {
|
|
66
|
+
return !!(
|
|
67
|
+
meta &&
|
|
68
|
+
typeof meta === "object" &&
|
|
69
|
+
Object.keys(meta).some((key) => key.startsWith("ui/"))
|
|
70
|
+
);
|
|
71
|
+
}
|
|
72
|
+
|
|
30
73
|
/**
|
|
31
74
|
* Transforms a user's tool handler into an MCP-compatible handler.
|
|
32
75
|
*
|
|
@@ -34,24 +77,26 @@ export type McpToolHandler = (
|
|
|
34
77
|
* 1. Passes through both args and extra parameters to the user's handler
|
|
35
78
|
* 2. Transforms string/number responses into the required CallToolResult format
|
|
36
79
|
* 3. Allows returning `content`, `structuredContent`, or both
|
|
37
|
-
* 4. Allows returning only `_meta` (without `content`) when it contains
|
|
38
|
-
* 5. Auto-wraps HTML strings with
|
|
80
|
+
* 4. Allows returning only `_meta` (without `content`) when it contains widget metadata
|
|
81
|
+
* 5. Auto-wraps HTML strings with widget metadata if provided
|
|
39
82
|
* 6. Validates that the response is a proper CallToolResult and throws a descriptive error if not
|
|
40
83
|
*
|
|
41
84
|
* @param handler - The user's tool handler function
|
|
42
|
-
* @param meta - Optional metadata to attach to responses (for
|
|
85
|
+
* @param meta - Optional metadata to attach to responses (for MCP app widgets)
|
|
43
86
|
* @returns A transformed handler compatible with McpServer.registerTool
|
|
44
87
|
* @throws Error if the handler returns an invalid response type
|
|
45
88
|
*/
|
|
46
89
|
export function transformToolHandler(
|
|
47
90
|
handler: UserToolHandler,
|
|
48
|
-
meta?: Record<string, any
|
|
91
|
+
meta?: Record<string, any>,
|
|
92
|
+
outputSchema?: ZodRawShape,
|
|
93
|
+
toolName = "unknown-tool"
|
|
49
94
|
): McpToolHandler {
|
|
50
95
|
return async (
|
|
51
96
|
args: ZodRawShape,
|
|
52
97
|
extra: RequestHandlerExtra<ServerRequest, ServerNotification>
|
|
53
98
|
): Promise<CallToolResult> => {
|
|
54
|
-
let response = handler(args, extra);
|
|
99
|
+
let response: any = handler(args, extra);
|
|
55
100
|
|
|
56
101
|
// only await if it's actually a promise
|
|
57
102
|
if (response instanceof Promise) {
|
|
@@ -59,14 +104,35 @@ export function transformToolHandler(
|
|
|
59
104
|
}
|
|
60
105
|
|
|
61
106
|
if (typeof response === "string" || typeof response === "number") {
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
107
|
+
if (outputSchema) {
|
|
108
|
+
const outputSchemaEntries = Object.entries(outputSchema);
|
|
109
|
+
if (outputSchemaEntries.length === 1) {
|
|
110
|
+
const [fieldName, fieldSchema] = outputSchemaEntries[0];
|
|
111
|
+
try {
|
|
112
|
+
fieldSchema.parse(response);
|
|
113
|
+
return {
|
|
114
|
+
content: [
|
|
115
|
+
{
|
|
116
|
+
type: "text",
|
|
117
|
+
text: typeof response === "number" ? `${response}` : response,
|
|
118
|
+
},
|
|
119
|
+
],
|
|
120
|
+
structuredContent: {
|
|
121
|
+
[fieldName]: response,
|
|
122
|
+
},
|
|
123
|
+
};
|
|
124
|
+
} catch {
|
|
125
|
+
// Backward compatible fallback: keep content-only when primitive
|
|
126
|
+
// output does not match outputSchema.
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
// Check if we have widget metadata to attach
|
|
132
|
+
const hasWidgetMeta = hasUIMeta(meta);
|
|
133
|
+
|
|
134
|
+
if (hasWidgetMeta) {
|
|
135
|
+
// For widget tools, return empty text content with metadata
|
|
70
136
|
// The actual HTML is served by the auto-generated resource
|
|
71
137
|
return {
|
|
72
138
|
content: [
|
|
@@ -93,7 +159,31 @@ export function transformToolHandler(
|
|
|
93
159
|
};
|
|
94
160
|
}
|
|
95
161
|
|
|
96
|
-
//
|
|
162
|
+
// With outputSchema declared, allow returning a plain object as shorthand
|
|
163
|
+
// for `{ structuredContent: ... }`.
|
|
164
|
+
if (
|
|
165
|
+
outputSchema &&
|
|
166
|
+
response &&
|
|
167
|
+
typeof response === "object" &&
|
|
168
|
+
!Array.isArray(response) &&
|
|
169
|
+
!("structuredContent" in response) &&
|
|
170
|
+
!("content" in response && Array.isArray((response as any).content)) &&
|
|
171
|
+
!("_meta" in response) &&
|
|
172
|
+
!("isError" in response)
|
|
173
|
+
) {
|
|
174
|
+
// Validate the response against outputSchema before wrapping.
|
|
175
|
+
validateAgainstOutputSchema(
|
|
176
|
+
response as Record<string, unknown>,
|
|
177
|
+
outputSchema,
|
|
178
|
+
toolName,
|
|
179
|
+
"returned data that does not match outputSchema"
|
|
180
|
+
);
|
|
181
|
+
response = {
|
|
182
|
+
structuredContent: response,
|
|
183
|
+
};
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
// Check if response has _meta but no content (special case for widget metadata)
|
|
97
187
|
if (
|
|
98
188
|
response &&
|
|
99
189
|
typeof response === "object" &&
|
|
@@ -103,12 +193,7 @@ export function transformToolHandler(
|
|
|
103
193
|
) {
|
|
104
194
|
const meta = (response as any)._meta;
|
|
105
195
|
|
|
106
|
-
|
|
107
|
-
if (
|
|
108
|
-
meta &&
|
|
109
|
-
typeof meta === "object" &&
|
|
110
|
-
Object.keys(meta).some((key) => key.startsWith("openai/"))
|
|
111
|
-
) {
|
|
196
|
+
if (hasUIMeta(meta)) {
|
|
112
197
|
// Transform to include empty text content with the _meta
|
|
113
198
|
return {
|
|
114
199
|
content: [
|
|
@@ -156,20 +241,21 @@ export function transformToolHandler(
|
|
|
156
241
|
` content: [{ type: "text", text: "fallback" }],\n` +
|
|
157
242
|
` structuredContent: { your: "data" }\n` +
|
|
158
243
|
`}\n\n` +
|
|
159
|
-
`Or for
|
|
244
|
+
`Or for widget metadata only:\n` +
|
|
160
245
|
`{\n` +
|
|
161
246
|
` _meta: {\n` +
|
|
162
|
-
` "
|
|
247
|
+
` "ui/...": ...\n` +
|
|
163
248
|
` }\n` +
|
|
164
249
|
`}`
|
|
165
250
|
);
|
|
166
251
|
}
|
|
167
252
|
|
|
168
|
-
// Check if response has at least one of: content
|
|
169
|
-
|
|
253
|
+
// Check if response has at least one of: content or structuredContent
|
|
254
|
+
let hasContent = "content" in response && Array.isArray(response.content);
|
|
170
255
|
const hasStructuredContent = "structuredContent" in response;
|
|
256
|
+
const isError = "isError" in response && (response as any).isError === true;
|
|
171
257
|
|
|
172
|
-
if (!hasContent && !hasStructuredContent) {
|
|
258
|
+
if (!hasContent && !hasStructuredContent && !isError) {
|
|
173
259
|
const responseValue = JSON.stringify(response, null, 2);
|
|
174
260
|
|
|
175
261
|
throw new Error(
|
|
@@ -196,6 +282,38 @@ export function transformToolHandler(
|
|
|
196
282
|
);
|
|
197
283
|
}
|
|
198
284
|
|
|
285
|
+
// Auto-generate fallback content for isError responses without content
|
|
286
|
+
if (isError && !hasContent && !hasStructuredContent) {
|
|
287
|
+
const { isError: _, ...rest } = response as Record<string, unknown>;
|
|
288
|
+
const errorText =
|
|
289
|
+
Object.keys(rest).length > 0
|
|
290
|
+
? `Tool execution failed: ${JSON.stringify(rest)}`
|
|
291
|
+
: "Tool execution failed";
|
|
292
|
+
response.content = [{ type: "text", text: errorText }];
|
|
293
|
+
hasContent = true;
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
// Validate structuredContent against outputSchema if present.
|
|
297
|
+
if (outputSchema && hasStructuredContent && !isError) {
|
|
298
|
+
validateAgainstOutputSchema(
|
|
299
|
+
(response as any).structuredContent as Record<string, unknown>,
|
|
300
|
+
outputSchema,
|
|
301
|
+
toolName,
|
|
302
|
+
"returned structuredContent that does not match outputSchema"
|
|
303
|
+
);
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
// Auto-generate text fallback for clients that only render content.
|
|
307
|
+
if (!hasContent && hasStructuredContent) {
|
|
308
|
+
response.content = [
|
|
309
|
+
{
|
|
310
|
+
type: "text",
|
|
311
|
+
text: JSON.stringify((response as any).structuredContent),
|
|
312
|
+
},
|
|
313
|
+
];
|
|
314
|
+
hasContent = true;
|
|
315
|
+
}
|
|
316
|
+
|
|
199
317
|
// validate each content item if content is present
|
|
200
318
|
if (hasContent) {
|
|
201
319
|
for (let i = 0; i < response.content.length; i++) {
|
|
@@ -243,6 +361,6 @@ export function transformToolHandler(
|
|
|
243
361
|
}
|
|
244
362
|
}
|
|
245
363
|
|
|
246
|
-
return response;
|
|
364
|
+
return response as CallToolResult;
|
|
247
365
|
};
|
|
248
366
|
}
|
package/src/types/resource.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { UIMetadata } from "./ui-meta";
|
|
2
2
|
|
|
3
3
|
export interface ResourceMetadata {
|
|
4
4
|
name: string;
|
|
@@ -6,9 +6,9 @@ export interface ResourceMetadata {
|
|
|
6
6
|
description?: string;
|
|
7
7
|
mimeType?: string;
|
|
8
8
|
size?: number;
|
|
9
|
-
/** Metadata for the resource.
|
|
9
|
+
/** Metadata for the resource. */
|
|
10
10
|
_meta?: {
|
|
11
|
-
|
|
11
|
+
ui?: UIMetadata;
|
|
12
12
|
[key: string]: unknown;
|
|
13
13
|
};
|
|
14
14
|
[key: string]: any;
|
package/src/types/tool.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { z } from "zod/v3";
|
|
2
2
|
import type { ZodType as ZodTypeV4, infer as inferV4 } from "zod";
|
|
3
|
-
import {
|
|
3
|
+
import { UIMetadata } from "./ui-meta";
|
|
4
4
|
|
|
5
5
|
export interface ToolAnnotations {
|
|
6
6
|
/** Human-readable title for the tool */
|
|
@@ -23,10 +23,9 @@ export interface ToolMetadata {
|
|
|
23
23
|
description: string;
|
|
24
24
|
/** Optional hints about tool behavior */
|
|
25
25
|
annotations?: ToolAnnotations;
|
|
26
|
-
/** Metadata for the tool.
|
|
26
|
+
/** Metadata for the tool. */
|
|
27
27
|
_meta?: {
|
|
28
|
-
|
|
29
|
-
ui?: OpenAIMetadata;
|
|
28
|
+
ui?: UIMetadata;
|
|
30
29
|
[key: string]: unknown;
|
|
31
30
|
};
|
|
32
31
|
}
|
|
@@ -34,6 +33,7 @@ export interface ToolMetadata {
|
|
|
34
33
|
type CompatibleZodType = z.ZodTypeAny | ZodTypeV4<unknown>;
|
|
35
34
|
|
|
36
35
|
export type ToolSchema = Record<string, CompatibleZodType>;
|
|
36
|
+
export type ToolOutputSchema = Record<string, CompatibleZodType>;
|
|
37
37
|
|
|
38
38
|
// The ToolExtraArguments type is equivalent to Parameters<ToolCallback<undefined>>[0] from @modelcontextprotocol/sdk but fully resolved to avoid external type dependencies.
|
|
39
39
|
/**
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
export interface UIMetadata {
|
|
2
|
+
/**
|
|
3
|
+
* URI template for the widget resource.
|
|
4
|
+
* Auto-generated as `ui://app/{toolName}.html` when omitted.
|
|
5
|
+
*/
|
|
6
|
+
resourceUri?: string;
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Content Security Policy configuration for widget resources.
|
|
10
|
+
*/
|
|
11
|
+
csp?: {
|
|
12
|
+
connectDomains?: string[];
|
|
13
|
+
resourceDomains?: string[];
|
|
14
|
+
};
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Optional dedicated origin for this widget.
|
|
18
|
+
*/
|
|
19
|
+
domain?: string;
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Visual hint indicating the widget prefers a border.
|
|
23
|
+
*/
|
|
24
|
+
prefersBorder?: boolean;
|
|
25
|
+
}
|
|
26
|
+
|
|
@@ -1,173 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* OpenAI tool invocation metadata
|
|
3
|
-
*/
|
|
4
|
-
export interface OpenAIToolInvocation {
|
|
5
|
-
/**
|
|
6
|
-
* Message displayed while the tool is executing
|
|
7
|
-
* @example "Hand-tossing a map..."
|
|
8
|
-
*/
|
|
9
|
-
invoking?: string;
|
|
10
|
-
/**
|
|
11
|
-
* Message displayed after the tool completes
|
|
12
|
-
* @example "Served a fresh map!"
|
|
13
|
-
*/
|
|
14
|
-
invoked?: string;
|
|
15
|
-
}
|
|
16
|
-
/**
|
|
17
|
-
* OpenAI metadata for MCP tools and resources.
|
|
18
|
-
*
|
|
19
|
-
* This interface defines metadata that can be specified in nested form in your tool/resource
|
|
20
|
-
* configuration. The framework will automatically flatten it and split it appropriately:
|
|
21
|
-
*
|
|
22
|
-
* - Tool-specific metadata will be applied to the tool
|
|
23
|
-
* - Resource-specific metadata will be applied to auto-generated resources
|
|
24
|
-
*
|
|
25
|
-
* @example
|
|
26
|
-
* ```typescript
|
|
27
|
-
* // In your tool definition:
|
|
28
|
-
* export const metadata = {
|
|
29
|
-
* name: "get_map",
|
|
30
|
-
* description: "Gets a map",
|
|
31
|
-
* _meta: {
|
|
32
|
-
* openai: {
|
|
33
|
-
* // Tool-specific: status messages during execution
|
|
34
|
-
* toolInvocation: {
|
|
35
|
-
* invoking: "Hand-tossing a map...",
|
|
36
|
-
* invoked: "Served a fresh map!"
|
|
37
|
-
* },
|
|
38
|
-
* // Tool-specific: enables widget-to-tool communication
|
|
39
|
-
* widgetAccessible: true,
|
|
40
|
-
*
|
|
41
|
-
* // Resource-specific: describes the widget
|
|
42
|
-
* widgetDescription: "Interactive map viewer",
|
|
43
|
-
* widgetPrefersBorder: true,
|
|
44
|
-
* widgetCSP: {
|
|
45
|
-
* connect_domains: ["https://api.mapbox.com"],
|
|
46
|
-
* resource_domains: ["https://cdn.mapbox.com"]
|
|
47
|
-
* }
|
|
48
|
-
* }
|
|
49
|
-
* }
|
|
50
|
-
* };
|
|
51
|
-
* ```
|
|
52
|
-
*/
|
|
53
|
-
export interface OpenAIMetadata {
|
|
54
|
-
/**
|
|
55
|
-
* Tool invocation status messages
|
|
56
|
-
* - `openai/toolInvocation/invoking` - Loading state text (≤64 chars)
|
|
57
|
-
* - `openai/toolInvocation/invoked` - Completion state text (≤64 chars)
|
|
58
|
-
*/
|
|
59
|
-
toolInvocation?: OpenAIToolInvocation;
|
|
60
|
-
/**
|
|
61
|
-
* Whether the widget is accessible in the UI (enables widget-to-tool communication)
|
|
62
|
-
* Maps to: `openai/widgetAccessible`
|
|
63
|
-
* @default true
|
|
64
|
-
*/
|
|
65
|
-
widgetAccessible?: boolean;
|
|
66
|
-
/**
|
|
67
|
-
* URI template for the widget resource for MCP Apps
|
|
68
|
-
* Maps to: `ui/resourceUri`
|
|
69
|
-
*
|
|
70
|
-
* Auto-generated as `ui://widget/{toolName}.html` if not provided.
|
|
71
|
-
*
|
|
72
|
-
* @example "ui://widget/my-tool.html"
|
|
73
|
-
*/
|
|
74
|
-
resourceUri?: string;
|
|
75
|
-
/**
|
|
76
|
-
* URI template for the widget resource
|
|
77
|
-
* Maps to: `openai/outputTemplate`
|
|
78
|
-
*
|
|
79
|
-
* Auto-generated as `ui://widget/{toolName}.html` if not provided.
|
|
80
|
-
*
|
|
81
|
-
* @example "ui://widget/my-tool.html"
|
|
82
|
-
*/
|
|
83
|
-
outputTemplate?: string;
|
|
84
|
-
/**
|
|
85
|
-
* Human-readable widget summary
|
|
86
|
-
* Maps to: `openai/widgetDescription`
|
|
87
|
-
*/
|
|
88
|
-
widgetDescription?: string;
|
|
89
|
-
/**
|
|
90
|
-
* UI rendering hint for border preference
|
|
91
|
-
* Maps to: `openai/widgetPrefersBorder`
|
|
92
|
-
*/
|
|
93
|
-
widgetPrefersBorder?: boolean;
|
|
94
|
-
/**
|
|
95
|
-
* Content Security Policy configuration
|
|
96
|
-
* Maps to: `openai/widgetCSP`
|
|
97
|
-
*
|
|
98
|
-
* Defines allowed domains for widget resources and connections.
|
|
99
|
-
* These arrays map to CSP directives:
|
|
100
|
-
* - `resource_domains` → script-src, img-src, font-src
|
|
101
|
-
* - `connect_domains` → connect-src
|
|
102
|
-
*
|
|
103
|
-
* Generated CSP:
|
|
104
|
-
* ```
|
|
105
|
-
* script-src 'self' ${resource_domains}
|
|
106
|
-
* img-src 'self' data: ${resource_domains}
|
|
107
|
-
* font-src 'self' ${resource_domains}
|
|
108
|
-
* connect-src 'self' ${connect_domains}
|
|
109
|
-
* ```
|
|
110
|
-
*
|
|
111
|
-
* @example
|
|
112
|
-
* ```typescript
|
|
113
|
-
* widgetCSP: {
|
|
114
|
-
* connect_domains: ["https://api.example.com"],
|
|
115
|
-
* resource_domains: ["https://cdn.example.com", "https://fonts.googleapis.com"]
|
|
116
|
-
* }
|
|
117
|
-
* ```
|
|
118
|
-
*/
|
|
119
|
-
widgetCSP?: {
|
|
120
|
-
/** URLs allowed for fetch, WebSocket, and other connections (connect-src) */
|
|
121
|
-
connect_domains?: string[];
|
|
122
|
-
/** URLs allowed for scripts, images, and fonts (script-src, img-src, font-src) */
|
|
123
|
-
resource_domains?: string[];
|
|
124
|
-
};
|
|
125
|
-
/**
|
|
126
|
-
* Content Security Policy configuration (mcp-apps-only)
|
|
127
|
-
*
|
|
128
|
-
* Servers declare which external origins their UI needs to access.
|
|
129
|
-
* Hosts use this to enforce appropriate CSP headers.
|
|
130
|
-
*/
|
|
131
|
-
csp?: {
|
|
132
|
-
/**
|
|
133
|
-
* Origins for network requests
|
|
134
|
-
*
|
|
135
|
-
* - Empty or omitted = no external connections (secure default)
|
|
136
|
-
* - Maps to CSP `connect-src` directive
|
|
137
|
-
*
|
|
138
|
-
* @example
|
|
139
|
-
* ["https://api.weather.com", "wss://realtime.service.com"]
|
|
140
|
-
*/
|
|
141
|
-
connectDomains?: string[];
|
|
142
|
-
/**
|
|
143
|
-
* Origins for static resources (images, scripts, stylesheets, fonts)
|
|
144
|
-
*
|
|
145
|
-
* - Empty or omitted = no external resources (secure default)
|
|
146
|
-
* - Wildcard subdomains supported: `https://*.example.com`
|
|
147
|
-
* - Maps to CSP `img-src`, `script-src`, `style-src`, `font-src` directives
|
|
148
|
-
*
|
|
149
|
-
* @example
|
|
150
|
-
* ["https://cdn.jsdelivr.net", "https://*.cloudflare.com"]
|
|
151
|
-
*/
|
|
152
|
-
resourceDomains?: string[];
|
|
153
|
-
};
|
|
154
|
-
/**
|
|
155
|
-
* Optional dedicated subdomain for widget
|
|
156
|
-
* Maps to: `openai/widgetDomain`
|
|
157
|
-
*/
|
|
158
|
-
widgetDomain?: string;
|
|
159
|
-
/**
|
|
160
|
-
* Widget state object
|
|
161
|
-
* Maps to: `openai/widgetState`
|
|
162
|
-
*/
|
|
163
|
-
widgetState?: UnknownObject;
|
|
164
|
-
/**
|
|
165
|
-
* Whether the result can produce a widget
|
|
166
|
-
* @default true
|
|
167
|
-
*/
|
|
168
|
-
resultCanProduceWidget?: boolean;
|
|
169
|
-
}
|
|
170
|
-
type UnknownObject = {
|
|
171
|
-
[x: string]: unknown;
|
|
172
|
-
};
|
|
173
|
-
export {};
|
|
@@ -1,44 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Flattens nested metadata object into a flat structure with "/" delimited keys.
|
|
3
|
-
*/
|
|
4
|
-
export function flattenMeta(meta: Record<string, any>): Record<string, any> {
|
|
5
|
-
const result: Record<string, any> = {};
|
|
6
|
-
|
|
7
|
-
function flatten(obj: any, prefix = ""): void {
|
|
8
|
-
if (!obj || typeof obj !== "object") {
|
|
9
|
-
return;
|
|
10
|
-
}
|
|
11
|
-
|
|
12
|
-
for (const [key, value] of Object.entries(obj)) {
|
|
13
|
-
const newKey = prefix ? `${prefix}/${key}` : key;
|
|
14
|
-
|
|
15
|
-
if (
|
|
16
|
-
value &&
|
|
17
|
-
typeof value === "object" &&
|
|
18
|
-
!Array.isArray(value) &&
|
|
19
|
-
!(value instanceof Date) &&
|
|
20
|
-
!(value instanceof RegExp)
|
|
21
|
-
) {
|
|
22
|
-
flatten(value, newKey);
|
|
23
|
-
} else {
|
|
24
|
-
result[newKey] = value;
|
|
25
|
-
}
|
|
26
|
-
}
|
|
27
|
-
}
|
|
28
|
-
|
|
29
|
-
flatten(meta);
|
|
30
|
-
return result;
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
/** Checks if metadata contains OpenAI-specific keys.*/
|
|
34
|
-
export function hasOpenAIMeta(meta?: Record<string, any>): boolean {
|
|
35
|
-
if (!meta || typeof meta !== "object") {
|
|
36
|
-
return false;
|
|
37
|
-
}
|
|
38
|
-
|
|
39
|
-
if ("openai" in meta && typeof meta.openai === "object") {
|
|
40
|
-
return true;
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
return Object.keys(meta).some((key) => key.startsWith("openai/"));
|
|
44
|
-
}
|
|
@@ -1,81 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Splits OpenAI metadata into tool-specific and resource-specific properties.
|
|
3
|
-
*/
|
|
4
|
-
|
|
5
|
-
export interface SplitMetadata {
|
|
6
|
-
toolMeta: Record<string, any>;
|
|
7
|
-
resourceMeta: Record<string, any>;
|
|
8
|
-
}
|
|
9
|
-
|
|
10
|
-
/**
|
|
11
|
-
* Tool-specific metadata keys in nested format
|
|
12
|
-
*/
|
|
13
|
-
const TOOL_META_KEYS_NESTED = [
|
|
14
|
-
"toolInvocation",
|
|
15
|
-
"widgetAccessible",
|
|
16
|
-
"outputTemplate",
|
|
17
|
-
];
|
|
18
|
-
|
|
19
|
-
/**
|
|
20
|
-
* Resource-specific metadata keys in nested format
|
|
21
|
-
*/
|
|
22
|
-
const RESOURCE_META_KEYS_NESTED = [
|
|
23
|
-
"widgetDescription",
|
|
24
|
-
"widgetPrefersBorder",
|
|
25
|
-
"widgetCSP",
|
|
26
|
-
"widgetDomain",
|
|
27
|
-
"widgetState",
|
|
28
|
-
];
|
|
29
|
-
|
|
30
|
-
/**
|
|
31
|
-
* Splits nested OpenAI metadata into tool and resource metadata.
|
|
32
|
-
* Keeps metadata in nested format (no flattening).
|
|
33
|
-
*
|
|
34
|
-
* @param meta - The metadata object (nested format with 'openai' key)
|
|
35
|
-
* @returns Object containing toolMeta and resourceMeta in nested format
|
|
36
|
-
*/
|
|
37
|
-
export function splitOpenAIMetaNested(
|
|
38
|
-
meta: Record<string, any>
|
|
39
|
-
): SplitMetadata {
|
|
40
|
-
const toolMeta: Record<string, any> = {};
|
|
41
|
-
const resourceMeta: Record<string, any> = {};
|
|
42
|
-
|
|
43
|
-
if (meta.openai && typeof meta.openai === "object") {
|
|
44
|
-
const openaiMeta = meta.openai;
|
|
45
|
-
const toolOpenAI: Record<string, any> = {};
|
|
46
|
-
const resourceOpenAI: Record<string, any> = {};
|
|
47
|
-
|
|
48
|
-
for (const [key, value] of Object.entries(openaiMeta)) {
|
|
49
|
-
if (TOOL_META_KEYS_NESTED.includes(key)) {
|
|
50
|
-
toolOpenAI[key] = value;
|
|
51
|
-
} else if (RESOURCE_META_KEYS_NESTED.includes(key)) {
|
|
52
|
-
resourceOpenAI[key] = value;
|
|
53
|
-
} else {
|
|
54
|
-
toolOpenAI[key] = value;
|
|
55
|
-
}
|
|
56
|
-
}
|
|
57
|
-
|
|
58
|
-
if (Object.keys(toolOpenAI).length > 0) {
|
|
59
|
-
toolMeta.openai = toolOpenAI;
|
|
60
|
-
}
|
|
61
|
-
if (Object.keys(resourceOpenAI).length > 0) {
|
|
62
|
-
resourceMeta.openai = resourceOpenAI;
|
|
63
|
-
}
|
|
64
|
-
}
|
|
65
|
-
|
|
66
|
-
for (const [key, value] of Object.entries(meta)) {
|
|
67
|
-
if (key !== "openai") {
|
|
68
|
-
toolMeta[key] = value;
|
|
69
|
-
}
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
return { toolMeta, resourceMeta };
|
|
73
|
-
}
|
|
74
|
-
|
|
75
|
-
export function isToolMetaKeyNested(key: string): boolean {
|
|
76
|
-
return TOOL_META_KEYS_NESTED.includes(key);
|
|
77
|
-
}
|
|
78
|
-
|
|
79
|
-
export function isResourceMetaKeyNested(key: string): boolean {
|
|
80
|
-
return RESOURCE_META_KEYS_NESTED.includes(key);
|
|
81
|
-
}
|
|
@@ -1,58 +0,0 @@
|
|
|
1
|
-
import { UserToolHandler } from "./transformers/tool";
|
|
2
|
-
|
|
3
|
-
/**
|
|
4
|
-
* Represents an auto-generated resource from an OpenAI tool
|
|
5
|
-
*/
|
|
6
|
-
export interface AutoGeneratedResource {
|
|
7
|
-
name: string;
|
|
8
|
-
uri: string;
|
|
9
|
-
handler: UserToolHandler;
|
|
10
|
-
/** Tool-specific metadata (e.g., toolInvocation, widgetAccessible) */
|
|
11
|
-
toolPath?: string; // Path to the tool file (for React bundling)
|
|
12
|
-
clientBundle?: string; // Pre-built client-side bundle for hydration
|
|
13
|
-
/** Resource-specific metadata (e.g., widgetDescription, widgetPrefersBorder) */
|
|
14
|
-
_meta: Record<string, any>;
|
|
15
|
-
mimeType: "text/html+skybridge";
|
|
16
|
-
}
|
|
17
|
-
|
|
18
|
-
/**
|
|
19
|
-
* Global registry for auto-generated OpenAI resources
|
|
20
|
-
* This allows tools to automatically create corresponding resources
|
|
21
|
-
* when they have OpenAI metadata
|
|
22
|
-
*/
|
|
23
|
-
class OpenAIResourceRegistry {
|
|
24
|
-
private resources = new Map<string, AutoGeneratedResource>();
|
|
25
|
-
|
|
26
|
-
/**
|
|
27
|
-
* Add a resource to the registry
|
|
28
|
-
*/
|
|
29
|
-
add(toolName: string, resource: AutoGeneratedResource): void {
|
|
30
|
-
this.resources.set(toolName, resource);
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
/**
|
|
34
|
-
* Get all registered resources
|
|
35
|
-
*/
|
|
36
|
-
getAll(): Map<string, AutoGeneratedResource> {
|
|
37
|
-
return this.resources;
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
/**
|
|
41
|
-
* Clear all resources (useful for testing or reinitialization)
|
|
42
|
-
*/
|
|
43
|
-
clear(): void {
|
|
44
|
-
this.resources.clear();
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
/**
|
|
48
|
-
* Check if a resource exists
|
|
49
|
-
*/
|
|
50
|
-
has(toolName: string): boolean {
|
|
51
|
-
return this.resources.has(toolName);
|
|
52
|
-
}
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
/**
|
|
56
|
-
* Singleton instance of the registry
|
|
57
|
-
*/
|
|
58
|
-
export const openAIResourceRegistry = new OpenAIResourceRegistry();
|