xmcp 0.6.6 → 0.6.8

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.
Files changed (90) hide show
  1. package/README.md +32 -0
  2. package/dist/cli.js +55 -36
  3. package/dist/compiler/config/index.d.ts +61 -54
  4. package/dist/compiler/config/schemas/template.d.ts +5 -0
  5. package/dist/compiler/config/schemas/transport/http.d.ts +82 -82
  6. package/dist/host-bridge.d.ts +4 -0
  7. package/dist/host-bridge.js +1 -0
  8. package/dist/index.d.ts +8 -2
  9. package/dist/index.js +5 -5
  10. package/dist/runtime/adapter-express.js +45 -26
  11. package/dist/runtime/adapter-nestjs.js +45 -26
  12. package/dist/runtime/adapter-nextjs.js +44 -25
  13. package/dist/runtime/contexts/client-info-context.d.ts +8 -0
  14. package/dist/runtime/contexts/http-request-context.d.ts +3 -1
  15. package/dist/runtime/headers.js +1 -1
  16. package/dist/runtime/http.js +53 -34
  17. package/dist/runtime/stdio.js +32 -24
  18. package/dist/runtime/utils/elicitation.d.ts +4 -0
  19. package/dist/runtime/utils/ext-apps-registry.d.ts +132 -0
  20. package/dist/runtime/utils/mcp-app-protocol.d.ts +14 -0
  21. package/dist/runtime/utils/mcp-app-types.d.ts +103 -0
  22. package/dist/runtime/utils/mcp-host-bridge.d.ts +43 -0
  23. package/dist/runtime/utils/path-to-tool-name.d.ts +20 -0
  24. package/dist/runtime/utils/prompt-loader.d.ts +11 -0
  25. package/dist/runtime/utils/prompts.d.ts +8 -0
  26. package/dist/runtime/utils/react/generate-html.d.ts +1 -0
  27. package/dist/runtime/utils/react/index.d.ts +4 -0
  28. package/dist/runtime/utils/resource-loader.d.ts +11 -0
  29. package/dist/runtime/utils/resources.d.ts +4 -0
  30. package/dist/runtime/utils/server.d.ts +37 -0
  31. package/dist/runtime/utils/tool-loader.d.ts +11 -0
  32. package/dist/runtime/utils/tools.d.ts +11 -0
  33. package/dist/runtime/utils/transformers/prompt.d.ts +32 -0
  34. package/dist/runtime/utils/transformers/resource.d.ts +26 -0
  35. package/dist/runtime/utils/transformers/tool.d.ts +30 -0
  36. package/dist/runtime/utils/ui/flatten-meta.d.ts +6 -0
  37. package/dist/runtime/utils/ui/split-meta.d.ts +17 -0
  38. package/dist/runtime/utils/utils/resource-uri-composer.d.ts +60 -0
  39. package/dist/runtime/utils/validators/index.d.ts +13 -0
  40. package/dist/types/client-info.d.ts +12 -0
  41. package/dist/types/tool.d.ts +69 -14
  42. package/dist/types/ui-meta.d.ts +15 -0
  43. package/dist/utils/context.d.ts +1 -1
  44. package/package.json +20 -1
  45. package/src/client/index.ts +4 -1
  46. package/src/compiler/client/component-compiler.ts +26 -5
  47. package/src/compiler/config/injection.ts +1 -0
  48. package/src/compiler/config/schemas/template.ts +13 -0
  49. package/src/compiler/generate-tools-code.ts +4 -6
  50. package/src/compiler/get-bundler-config/index.ts +1 -0
  51. package/src/compiler/get-bundler-config/plugins/index.ts +0 -1
  52. package/src/compiler/index.ts +24 -7
  53. package/src/host-bridge.ts +36 -0
  54. package/src/index.ts +44 -1
  55. package/src/runtime/adapters/express/index.ts +45 -47
  56. package/src/runtime/adapters/nestjs/xmcp.service.ts +4 -3
  57. package/src/runtime/adapters/nextjs/handler/node-to-web-adapter.ts +40 -6
  58. package/src/runtime/adapters/nextjs/handler/request-converter.ts +20 -0
  59. package/src/runtime/adapters/nextjs/handler/server-lifecycle.ts +10 -6
  60. package/src/runtime/adapters/nextjs/index.ts +41 -25
  61. package/src/runtime/contexts/client-info-context.ts +16 -0
  62. package/src/runtime/contexts/http-request-context.ts +2 -0
  63. package/src/runtime/headers.ts +37 -2
  64. package/src/runtime/platforms/cloudflare/cors.ts +0 -1
  65. package/src/runtime/platforms/cloudflare/worker.ts +46 -44
  66. package/src/runtime/transports/http/index.ts +0 -4
  67. package/src/runtime/transports/http/stateless-streamable-http.ts +131 -233
  68. package/src/runtime/transports/stdio/index.ts +40 -9
  69. package/src/runtime/utils/__tests__/client-info.test.ts +99 -0
  70. package/src/runtime/utils/__tests__/tool-extra.test.ts +149 -0
  71. package/src/runtime/utils/client-info.ts +78 -0
  72. package/src/runtime/utils/elicitation.ts +396 -0
  73. package/src/runtime/utils/mcp-app-protocol.ts +16 -0
  74. package/src/runtime/utils/mcp-app-types.ts +113 -0
  75. package/src/runtime/utils/mcp-host-bridge.ts +473 -0
  76. package/src/runtime/utils/prompt-loader.ts +151 -0
  77. package/src/runtime/utils/react/generate-html.ts +12 -4
  78. package/src/runtime/utils/resource-loader.ts +151 -0
  79. package/src/runtime/utils/resources.ts +0 -8
  80. package/src/runtime/utils/server.ts +31 -40
  81. package/src/runtime/utils/tool-loader.ts +149 -0
  82. package/src/runtime/utils/tools.ts +9 -6
  83. package/src/runtime/utils/transformers/tool.ts +35 -5
  84. package/src/runtime/utils/ui/__tests__/split-meta.test.ts +42 -0
  85. package/src/runtime/utils/ui/split-meta.ts +4 -1
  86. package/src/types/client-info.ts +12 -0
  87. package/src/types/injected.d.ts +62 -0
  88. package/src/types/tool.ts +99 -17
  89. package/src/types/ui-meta.ts +17 -1
  90. package/src/utils/context.ts +2 -2
@@ -5,6 +5,10 @@ import {
5
5
  } from "@modelcontextprotocol/sdk/types";
6
6
  import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol";
7
7
  import { ZodRawShape } from "zod/v3";
8
+ import type { ToolExtraArguments } from "@/types/tool";
9
+ import { getHttpRequestContext } from "@/runtime/contexts/http-request-context";
10
+ import { getClientInfoContext } from "@/runtime/contexts/client-info-context";
11
+ import { elicitFromTool } from "../elicitation";
8
12
  import { validateContent } from "../validators";
9
13
 
10
14
  function validateAgainstOutputSchema(
@@ -49,10 +53,8 @@ export type UserToolResponse =
49
53
 
50
54
  export type UserToolHandler = (
51
55
  args: ZodRawShape,
52
- extra: RequestHandlerExtra<ServerRequest, ServerNotification>
53
- ) =>
54
- | UserToolResponse
55
- | Promise<UserToolResponse>;
56
+ extra: ToolExtraArguments
57
+ ) => UserToolResponse | Promise<UserToolResponse>;
56
58
 
57
59
  /**
58
60
  * Type for the transformed handler that the MCP server expects
@@ -70,6 +72,33 @@ function hasUIMeta(meta?: Record<string, any>): boolean {
70
72
  );
71
73
  }
72
74
 
75
+ function createToolExtraArguments(
76
+ extra: RequestHandlerExtra<ServerRequest, ServerNotification>
77
+ ): ToolExtraArguments {
78
+ let clientInfo = undefined;
79
+
80
+ try {
81
+ clientInfo = getHttpRequestContext().clientInfo;
82
+ } catch {
83
+ // no HTTP request context available (for example, stdio transport)
84
+ }
85
+
86
+ if (!clientInfo) {
87
+ try {
88
+ clientInfo = getClientInfoContext().clientInfo;
89
+ } catch {
90
+ // no client info context available
91
+ }
92
+ }
93
+
94
+ return {
95
+ ...(extra as ToolExtraArguments),
96
+ clientInfo,
97
+ elicit: (request, options) =>
98
+ elicitFromTool(extra as ToolExtraArguments, request, options),
99
+ };
100
+ }
101
+
73
102
  /**
74
103
  * Transforms a user's tool handler into an MCP-compatible handler.
75
104
  *
@@ -96,7 +125,8 @@ export function transformToolHandler(
96
125
  args: ZodRawShape,
97
126
  extra: RequestHandlerExtra<ServerRequest, ServerNotification>
98
127
  ): Promise<CallToolResult> => {
99
- let response: any = handler(args, extra);
128
+ const toolExtra = createToolExtraArguments(extra);
129
+ let response: any = handler(args, toolExtra);
100
130
 
101
131
  // only await if it's actually a promise
102
132
  if (response instanceof Promise) {
@@ -80,6 +80,22 @@ describe("splitUIMetaNested", () => {
80
80
  );
81
81
  }
82
82
  });
83
+
84
+ it("should split visibility to toolMeta", () => {
85
+ const meta = {
86
+ ui: {
87
+ visibility: ["model", "app"],
88
+ },
89
+ };
90
+ const result = splitUIMetaNested(meta);
91
+
92
+ assert.deepStrictEqual(result.toolMeta, {
93
+ ui: {
94
+ visibility: ["model", "app"],
95
+ },
96
+ });
97
+ assert.deepStrictEqual(result.resourceMeta, {});
98
+ });
83
99
  });
84
100
 
85
101
  describe("Resource Metadata Keys (CSP and Display)", () => {
@@ -121,6 +137,8 @@ describe("splitUIMetaNested", () => {
121
137
  csp: {
122
138
  connectDomains: ["https://api.weather.com"],
123
139
  resourceDomains: ["https://cdn.jsdelivr.net"],
140
+ frameDomains: ["https://widgets.example.com"],
141
+ baseUriDomains: ["https://assets.example.com"],
124
142
  },
125
143
  },
126
144
  };
@@ -132,6 +150,30 @@ describe("splitUIMetaNested", () => {
132
150
  csp: {
133
151
  connectDomains: ["https://api.weather.com"],
134
152
  resourceDomains: ["https://cdn.jsdelivr.net"],
153
+ frameDomains: ["https://widgets.example.com"],
154
+ baseUriDomains: ["https://assets.example.com"],
155
+ },
156
+ },
157
+ });
158
+ });
159
+
160
+ it("should split permissions to resourceMeta", () => {
161
+ const meta = {
162
+ ui: {
163
+ permissions: {
164
+ camera: {},
165
+ microphone: {},
166
+ },
167
+ },
168
+ };
169
+ const result = splitUIMetaNested(meta);
170
+
171
+ assert.deepStrictEqual(result.toolMeta, {});
172
+ assert.deepStrictEqual(result.resourceMeta, {
173
+ ui: {
174
+ permissions: {
175
+ camera: {},
176
+ microphone: {},
135
177
  },
136
178
  },
137
179
  });
@@ -10,7 +10,7 @@ export interface SplitMetadata {
10
10
  /**
11
11
  * Tool-specific metadata keys in nested format
12
12
  */
13
- const TOOL_META_KEYS_NESTED = ["ui/resourceUri"];
13
+ const TOOL_META_KEYS_NESTED = ["ui/resourceUri", "resourceUri", "visibility"];
14
14
 
15
15
  /**
16
16
  * Resource-specific metadata keys in nested format
@@ -19,8 +19,11 @@ const RESOURCE_META_KEYS_NESTED = [
19
19
  "prefersBorder",
20
20
  "domain",
21
21
  "csp",
22
+ "permissions",
22
23
  "connectDomains",
23
24
  "resourceDomains",
25
+ "frameDomains",
26
+ "baseUriDomains",
24
27
  ];
25
28
 
26
29
  /**
@@ -0,0 +1,12 @@
1
+ export interface McpClientInfo {
2
+ /** MCP client implementation name from initialize.params.clientInfo.name */
3
+ name: string;
4
+ /** MCP client implementation version from initialize.params.clientInfo.version */
5
+ version: string;
6
+ /** Optional human-friendly title from initialize.params.clientInfo.title */
7
+ title?: string;
8
+ /** Optional website URL from initialize.params.clientInfo.websiteUrl */
9
+ websiteUrl?: string;
10
+ /** Optional description from initialize.params.clientInfo.description */
11
+ description?: string;
12
+ }
@@ -0,0 +1,62 @@
1
+ // ─── ProvidePlugin (module exports wired from .xmcp/import-map.js) ────────────
2
+
3
+ declare const INJECTED_TOOLS: Record<
4
+ string,
5
+ () => Promise<import("../runtime/utils/server").ToolFile>
6
+ >;
7
+
8
+ declare const INJECTED_PROMPTS: Record<
9
+ string,
10
+ () => Promise<import("../runtime/utils/server").PromptFile>
11
+ >;
12
+
13
+ declare const INJECTED_RESOURCES: Record<
14
+ string,
15
+ () => Promise<import("../runtime/utils/server").ResourceFile>
16
+ >;
17
+
18
+ declare const INJECTED_MIDDLEWARE:
19
+ | (() => Promise<{
20
+ default?:
21
+ | import("./middleware").Middleware
22
+ | import("./middleware").Middleware[]
23
+ | import("./middleware").WebMiddleware
24
+ | import("./middleware").WebMiddleware[];
25
+ }>)
26
+ | undefined;
27
+
28
+ // ─── DefinePlugin — config objects ────────────────────────────────────────────
29
+
30
+ declare const HTTP_CONFIG: Omit<
31
+ NonNullable<import("../compiler/config").ResolvedHttpConfig>,
32
+ "cors"
33
+ >;
34
+
35
+ declare const HTTP_CORS_CONFIG: import("../compiler/config").CorsConfig;
36
+
37
+ declare const TEMPLATE_CONFIG: import("../compiler/config").TemplateConfig;
38
+
39
+ declare const STDIO_CONFIG: { debug: boolean; silent: boolean };
40
+
41
+ declare const SERVER_INFO: import("@modelcontextprotocol/sdk/types").Implementation;
42
+
43
+ // ─── DefinePlugin — individual CORS vars (legacy Express adapter) ──────────────
44
+
45
+ declare const HTTP_CORS_ORIGIN: string;
46
+ declare const HTTP_CORS_METHODS: string;
47
+ declare const HTTP_CORS_ALLOWED_HEADERS: string;
48
+ declare const HTTP_CORS_EXPOSED_HEADERS: string;
49
+ declare const HTTP_CORS_CREDENTIALS: boolean;
50
+ declare const HTTP_CORS_MAX_AGE: number;
51
+ declare const HTTP_DEBUG: boolean;
52
+ declare const HTTP_BODY_SIZE_LIMIT: string;
53
+
54
+ // ─── DefinePlugin — runtime flags ─────────────────────────────────────────────
55
+
56
+ declare const IS_CLOUDFLARE: boolean;
57
+
58
+ declare const INJECTED_CLIENT_BUNDLES:
59
+ | Record<string, { js: string; css?: string }>
60
+ | undefined;
61
+
62
+ declare const RUNTIME_FILES: Record<string, string>;
package/src/types/tool.ts CHANGED
@@ -1,6 +1,8 @@
1
1
  import { z } from "zod/v3";
2
2
  import type { ZodType as ZodTypeV4, infer as inferV4 } from "zod";
3
+ import type { ElicitResult as McpElicitResult } from "@modelcontextprotocol/sdk/types";
3
4
  import { UIMetadata } from "./ui-meta";
5
+ import type { McpClientInfo } from "./client-info";
4
6
 
5
7
  export interface ToolAnnotations {
6
8
  /** Human-readable title for the tool */
@@ -31,11 +33,95 @@ export interface ToolMetadata {
31
33
  }
32
34
 
33
35
  type CompatibleZodType = z.ZodTypeAny | ZodTypeV4<unknown>;
36
+ type InferCompatibleZodType<T extends CompatibleZodType> =
37
+ T extends z.ZodTypeAny
38
+ ? z.infer<T>
39
+ : T extends ZodTypeV4<unknown>
40
+ ? inferV4<T>
41
+ : never;
34
42
 
35
43
  export type ToolSchema = Record<string, CompatibleZodType>;
36
44
  export type ToolOutputSchema = Record<string, CompatibleZodType>;
45
+ export type ElicitResult = McpElicitResult;
46
+
47
+ export interface ToolRequestOptions {
48
+ /** Progress notification callback */
49
+ onprogress?: (progress: any) => void;
50
+ /** Abort signal for cancelling the request */
51
+ signal?: AbortSignal;
52
+ /** Request timeout in milliseconds */
53
+ timeout?: number;
54
+ /** Whether receiving progress notifications resets the timeout */
55
+ resetTimeoutOnProgress?: boolean;
56
+ /** Maximum total time to wait for a response */
57
+ maxTotalTimeout?: number;
58
+ /** Additional transport-specific options */
59
+ [key: string]: unknown;
60
+ }
61
+
62
+ type ElicitStringFormat = "date" | "uri" | "email" | "date-time";
63
+
64
+ interface ElicitFieldBase {
65
+ title?: string;
66
+ description?: string;
67
+ }
68
+
69
+ export interface ElicitStringField extends ElicitFieldBase {
70
+ type: "string";
71
+ minLength?: number;
72
+ maxLength?: number;
73
+ format?: ElicitStringFormat;
74
+ default?: string;
75
+ }
76
+
77
+ export interface ElicitEnumField extends ElicitFieldBase {
78
+ type: "string";
79
+ enum: string[];
80
+ enumNames?: string[];
81
+ default?: string;
82
+ }
83
+
84
+ export interface ElicitBooleanField extends ElicitFieldBase {
85
+ type: "boolean";
86
+ default?: boolean;
87
+ }
37
88
 
38
- // The ToolExtraArguments type is equivalent to Parameters<ToolCallback<undefined>>[0] from @modelcontextprotocol/sdk but fully resolved to avoid external type dependencies.
89
+ export interface ElicitNumberField extends ElicitFieldBase {
90
+ type: "number" | "integer";
91
+ minimum?: number;
92
+ maximum?: number;
93
+ default?: number;
94
+ }
95
+
96
+ export type ElicitFormField =
97
+ | ElicitStringField
98
+ | ElicitEnumField
99
+ | ElicitBooleanField
100
+ | ElicitNumberField;
101
+
102
+ export interface ElicitFormSchema {
103
+ type: "object";
104
+ properties: Record<string, ElicitFormField>;
105
+ required?: string[];
106
+ }
107
+
108
+ export interface ElicitFormRequest {
109
+ mode?: "form";
110
+ message: string;
111
+ requestedSchema: ElicitFormSchema;
112
+ }
113
+
114
+ export interface ElicitUrlRequest {
115
+ mode: "url";
116
+ message: string;
117
+ url: string;
118
+ elicitationId: string;
119
+ }
120
+
121
+ export type ElicitRequest = ElicitFormRequest | ElicitUrlRequest;
122
+
123
+ // The ToolExtraArguments type is based on Parameters<ToolCallback<undefined>>[0]
124
+ // from @modelcontextprotocol/sdk, with xmcp-specific extensions.
39
125
  /**
40
126
  * Extra arguments passed to MCP tool functions.
41
127
  */
@@ -77,28 +163,24 @@ export interface ToolExtraArguments {
77
163
  headers: Record<string, string | string[] | undefined>;
78
164
  };
79
165
 
166
+ /** MCP client metadata from initialize.params.clientInfo, when available */
167
+ clientInfo?: McpClientInfo;
168
+
80
169
  /** Sends a notification that relates to the current request being handled */
81
170
  sendNotification: (notification: any) => Promise<void>;
82
171
 
83
172
  /** Sends a request that relates to the current request being handled */
84
- sendRequest: <U extends z.ZodType<object>>(
173
+ sendRequest: <U extends CompatibleZodType>(
85
174
  request: any,
86
175
  resultSchema: U,
87
- options?: {
88
- /** Progress notification callback */
89
- onprogress?: (progress: any) => void;
90
- /** Abort signal for cancelling the request */
91
- signal?: AbortSignal;
92
- /** Request timeout in milliseconds */
93
- timeout?: number;
94
- /** Whether receiving progress notifications resets the timeout */
95
- resetTimeoutOnProgress?: boolean;
96
- /** Maximum total time to wait for a response */
97
- maxTotalTimeout?: number;
98
- /** Additional transport-specific options */
99
- [key: string]: unknown;
100
- }
101
- ) => Promise<z.infer<U>>;
176
+ options?: ToolRequestOptions
177
+ ) => Promise<InferCompatibleZodType<U>>;
178
+
179
+ /** Requests user input from the connected client */
180
+ elicit: (
181
+ request: ElicitRequest,
182
+ options?: ToolRequestOptions
183
+ ) => Promise<ElicitResult>;
102
184
  }
103
185
 
104
186
  export type InferSchema<T extends Record<string, unknown>> = {
@@ -5,12 +5,29 @@ export interface UIMetadata {
5
5
  */
6
6
  resourceUri?: string;
7
7
 
8
+ /**
9
+ * Visibility hint for how prominently hosts should surface the widget entry point.
10
+ */
11
+ visibility?: Array<"model" | "app">;
12
+
8
13
  /**
9
14
  * Content Security Policy configuration for widget resources.
10
15
  */
11
16
  csp?: {
12
17
  connectDomains?: string[];
13
18
  resourceDomains?: string[];
19
+ frameDomains?: string[];
20
+ baseUriDomains?: string[];
21
+ };
22
+
23
+ /**
24
+ * Browser permission hints requested by the widget iframe.
25
+ */
26
+ permissions?: {
27
+ camera?: Record<string, never>;
28
+ microphone?: Record<string, never>;
29
+ geolocation?: Record<string, never>;
30
+ clipboardWrite?: Record<string, never>;
14
31
  };
15
32
 
16
33
  /**
@@ -23,4 +40,3 @@ export interface UIMetadata {
23
40
  */
24
41
  prefersBorder?: boolean;
25
42
  }
26
-
@@ -8,7 +8,7 @@ type SetContext<T extends DefaultContext> = (data: Partial<T>) => void;
8
8
 
9
9
  export interface Context<T extends DefaultContext> {
10
10
  /** Run a callback with a specific context. */
11
- provider: (initialValue: T, callback: () => void) => void;
11
+ provider: <R>(initialValue: T, callback: () => R) => R;
12
12
  /** Get the context. */
13
13
  getContext: GetContext<T>;
14
14
  /** Partially update the context. */
@@ -88,7 +88,7 @@ export function createContext<T extends Object>({
88
88
  Object.assign(store, data);
89
89
  };
90
90
 
91
- const provider = (initialValue: T, callback: () => void) => {
91
+ const provider = <R>(initialValue: T, callback: () => R): R => {
92
92
  fallbackStoreWrapper.current = initialValue;
93
93
  return context.run(initialValue, callback);
94
94
  };