xmcp 0.6.4 → 0.6.5

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.
@@ -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();
@@ -1,191 +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
- /**
12
- * Message displayed after the tool completes
13
- * @example "Served a fresh map!"
14
- */
15
- invoked?: string;
16
- }
17
-
18
- /**
19
- * OpenAI metadata for MCP tools and resources.
20
- *
21
- * This interface defines metadata that can be specified in nested form in your tool/resource
22
- * configuration. The framework will automatically flatten it and split it appropriately:
23
- *
24
- * - Tool-specific metadata will be applied to the tool
25
- * - Resource-specific metadata will be applied to auto-generated resources
26
- *
27
- * @example
28
- * ```typescript
29
- * // In your tool definition:
30
- * export const metadata = {
31
- * name: "get_map",
32
- * description: "Gets a map",
33
- * _meta: {
34
- * openai: {
35
- * // Tool-specific: status messages during execution
36
- * toolInvocation: {
37
- * invoking: "Hand-tossing a map...",
38
- * invoked: "Served a fresh map!"
39
- * },
40
- * // Tool-specific: enables widget-to-tool communication
41
- * widgetAccessible: true,
42
- *
43
- * // Resource-specific: describes the widget
44
- * widgetDescription: "Interactive map viewer",
45
- * widgetPrefersBorder: true,
46
- * widgetCSP: {
47
- * connect_domains: ["https://api.mapbox.com"],
48
- * resource_domains: ["https://cdn.mapbox.com"]
49
- * }
50
- * }
51
- * }
52
- * };
53
- * ```
54
- */
55
- export interface OpenAIMetadata {
56
- // ==================== Tool-specific metadata ====================
57
-
58
- /**
59
- * Tool invocation status messages
60
- * - `openai/toolInvocation/invoking` - Loading state text (≤64 chars)
61
- * - `openai/toolInvocation/invoked` - Completion state text (≤64 chars)
62
- */
63
- toolInvocation?: OpenAIToolInvocation;
64
-
65
- /**
66
- * Whether the widget is accessible in the UI (enables widget-to-tool communication)
67
- * Maps to: `openai/widgetAccessible`
68
- * @default true
69
- */
70
- widgetAccessible?: boolean;
71
-
72
- /**
73
- * URI template for the widget resource for MCP Apps
74
- * Maps to: `ui/resourceUri`
75
- *
76
- * Auto-generated as `ui://widget/{toolName}.html` if not provided.
77
- *
78
- * @example "ui://widget/my-tool.html"
79
- */
80
- resourceUri?: string;
81
-
82
- /**
83
- * URI template for the widget resource
84
- * Maps to: `openai/outputTemplate`
85
- *
86
- * Auto-generated as `ui://widget/{toolName}.html` if not provided.
87
- *
88
- * @example "ui://widget/my-tool.html"
89
- */
90
- outputTemplate?: string;
91
-
92
- // ==================== Resource-specific metadata ====================
93
-
94
- /**
95
- * Human-readable widget summary
96
- * Maps to: `openai/widgetDescription`
97
- */
98
- widgetDescription?: string;
99
-
100
- /**
101
- * UI rendering hint for border preference
102
- * Maps to: `openai/widgetPrefersBorder`
103
- */
104
- widgetPrefersBorder?: boolean;
105
-
106
- /**
107
- * Content Security Policy configuration
108
- * Maps to: `openai/widgetCSP`
109
- *
110
- * Defines allowed domains for widget resources and connections.
111
- * These arrays map to CSP directives:
112
- * - `resource_domains` → script-src, img-src, font-src
113
- * - `connect_domains` → connect-src
114
- *
115
- * Generated CSP:
116
- * ```
117
- * script-src 'self' ${resource_domains}
118
- * img-src 'self' data: ${resource_domains}
119
- * font-src 'self' ${resource_domains}
120
- * connect-src 'self' ${connect_domains}
121
- * ```
122
- *
123
- * @example
124
- * ```typescript
125
- * widgetCSP: {
126
- * connect_domains: ["https://api.example.com"],
127
- * resource_domains: ["https://cdn.example.com", "https://fonts.googleapis.com"]
128
- * }
129
- * ```
130
- */
131
- widgetCSP?: {
132
- /** URLs allowed for fetch, WebSocket, and other connections (connect-src) */
133
- connect_domains?: string[];
134
- /** URLs allowed for scripts, images, and fonts (script-src, img-src, font-src) */
135
- resource_domains?: string[];
136
- };
137
-
138
- /**
139
- * Content Security Policy configuration (mcp-apps-only)
140
- *
141
- * Servers declare which external origins their UI needs to access.
142
- * Hosts use this to enforce appropriate CSP headers.
143
- */
144
- csp?: {
145
- /**
146
- * Origins for network requests
147
- *
148
- * - Empty or omitted = no external connections (secure default)
149
- * - Maps to CSP `connect-src` directive
150
- *
151
- * @example
152
- * ["https://api.weather.com", "wss://realtime.service.com"]
153
- */
154
- connectDomains?: string[];
155
- /**
156
- * Origins for static resources (images, scripts, stylesheets, fonts)
157
- *
158
- * - Empty or omitted = no external resources (secure default)
159
- * - Wildcard subdomains supported: `https://*.example.com`
160
- * - Maps to CSP `img-src`, `script-src`, `style-src`, `font-src` directives
161
- *
162
- * @example
163
- * ["https://cdn.jsdelivr.net", "https://*.cloudflare.com"]
164
- */
165
- resourceDomains?: string[];
166
- };
167
-
168
- /**
169
- * Optional dedicated subdomain for widget
170
- * Maps to: `openai/widgetDomain`
171
- */
172
- widgetDomain?: string;
173
-
174
- /**
175
- * Widget state object
176
- * Maps to: `openai/widgetState`
177
- */
178
- widgetState?: UnknownObject;
179
-
180
- // ==================== Shared/deprecated metadata ====================
181
-
182
- /**
183
- * Whether the result can produce a widget
184
- * @default true
185
- */
186
- resultCanProduceWidget?: boolean;
187
- }
188
-
189
- type UnknownObject = {
190
- [x: string]: unknown;
191
- };