xmcp 0.6.5 → 0.6.7

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 (78) hide show
  1. package/README.md +32 -0
  2. package/dist/cli.js +58 -40
  3. package/dist/compiler/config/index.d.ts +106 -47
  4. package/dist/compiler/config/schemas/template.d.ts +40 -0
  5. package/dist/compiler/config/schemas/transport/http.d.ts +82 -82
  6. package/dist/compiler/config/schemas/transport/stdio.d.ts +5 -0
  7. package/dist/index.d.ts +4 -2
  8. package/dist/index.js +5 -5
  9. package/dist/runtime/adapter-express.js +40 -23
  10. package/dist/runtime/adapter-nestjs.js +40 -23
  11. package/dist/runtime/adapter-nextjs.js +39 -22
  12. package/dist/runtime/contexts/http-request-context.d.ts +3 -1
  13. package/dist/runtime/headers.js +1 -1
  14. package/dist/runtime/http.js +48 -31
  15. package/dist/runtime/stdio.js +19 -13
  16. package/dist/runtime/utils/elicitation.d.ts +4 -0
  17. package/dist/runtime/utils/ext-apps-registry.d.ts +132 -0
  18. package/dist/runtime/utils/path-to-tool-name.d.ts +20 -0
  19. package/dist/runtime/utils/prompt-loader.d.ts +11 -0
  20. package/dist/runtime/utils/prompts.d.ts +8 -0
  21. package/dist/runtime/utils/react/generate-html.d.ts +1 -0
  22. package/dist/runtime/utils/react/index.d.ts +4 -0
  23. package/dist/runtime/utils/resource-loader.d.ts +11 -0
  24. package/dist/runtime/utils/resources.d.ts +4 -0
  25. package/dist/runtime/utils/server.d.ts +35 -0
  26. package/dist/runtime/utils/tool-loader.d.ts +11 -0
  27. package/dist/runtime/utils/tools.d.ts +11 -0
  28. package/dist/runtime/utils/transformers/prompt.d.ts +32 -0
  29. package/dist/runtime/utils/transformers/resource.d.ts +26 -0
  30. package/dist/runtime/utils/transformers/tool.d.ts +30 -0
  31. package/dist/runtime/utils/ui/flatten-meta.d.ts +6 -0
  32. package/dist/runtime/utils/ui/split-meta.d.ts +17 -0
  33. package/dist/runtime/utils/utils/resource-uri-composer.d.ts +60 -0
  34. package/dist/runtime/utils/validators/index.d.ts +13 -0
  35. package/dist/types/client-info.d.ts +12 -0
  36. package/dist/types/tool.d.ts +70 -14
  37. package/dist/utils/context.d.ts +1 -1
  38. package/package.json +9 -1
  39. package/src/client/index.ts +4 -1
  40. package/src/compiler/config/__tests__/config.test.ts +36 -0
  41. package/src/compiler/config/injection.ts +63 -1
  42. package/src/compiler/config/schemas/template.ts +17 -0
  43. package/src/compiler/config/schemas/transport/stdio.ts +1 -0
  44. package/src/compiler/generate-tools-code.ts +24 -6
  45. package/src/compiler/get-bundler-config/get-injected-variables.ts +3 -0
  46. package/src/compiler/get-bundler-config/plugins/index.ts +0 -1
  47. package/src/compiler/index.ts +123 -30
  48. package/src/compiler/start-http-server.ts +11 -4
  49. package/src/compiler/watcher-recovery.ts +72 -0
  50. package/src/index.ts +9 -1
  51. package/src/runtime/adapters/express/index.ts +45 -47
  52. package/src/runtime/adapters/nestjs/xmcp.service.ts +4 -3
  53. package/src/runtime/adapters/nextjs/handler/node-to-web-adapter.ts +40 -6
  54. package/src/runtime/adapters/nextjs/handler/request-converter.ts +20 -0
  55. package/src/runtime/adapters/nextjs/handler/server-lifecycle.ts +8 -5
  56. package/src/runtime/adapters/nextjs/index.ts +41 -25
  57. package/src/runtime/contexts/http-request-context.ts +2 -0
  58. package/src/runtime/headers.ts +37 -2
  59. package/src/runtime/platforms/cloudflare/cors.ts +0 -1
  60. package/src/runtime/platforms/cloudflare/worker.ts +46 -44
  61. package/src/runtime/transports/http/index.ts +0 -4
  62. package/src/runtime/transports/http/stateless-streamable-http.ts +131 -233
  63. package/src/runtime/transports/stdio/index.ts +18 -1
  64. package/src/runtime/utils/__tests__/client-info.test.ts +80 -0
  65. package/src/runtime/utils/__tests__/tool-extra.test.ts +110 -0
  66. package/src/runtime/utils/client-info.ts +71 -0
  67. package/src/runtime/utils/elicitation.ts +396 -0
  68. package/src/runtime/utils/prompt-loader.ts +151 -0
  69. package/src/runtime/utils/resource-loader.ts +151 -0
  70. package/src/runtime/utils/resources.ts +0 -8
  71. package/src/runtime/utils/server.ts +30 -42
  72. package/src/runtime/utils/tool-loader.ts +149 -0
  73. package/src/runtime/utils/tools.ts +31 -9
  74. package/src/runtime/utils/transformers/tool.ts +149 -10
  75. package/src/types/client-info.ts +12 -0
  76. package/src/types/injected.d.ts +62 -0
  77. package/src/types/tool.ts +100 -17
  78. package/src/utils/context.ts +2 -2
@@ -0,0 +1,4 @@
1
+ import type { ElicitRequest, ElicitResult, ToolExtraArguments, ToolRequestOptions } from "@/types/tool";
2
+ type ElicitRequestSender = Pick<ToolExtraArguments, "sendRequest">;
3
+ export declare function elicitFromTool(extra: ElicitRequestSender, request: ElicitRequest, options?: ToolRequestOptions): Promise<ElicitResult>;
4
+ export {};
@@ -0,0 +1,132 @@
1
+ import { UserToolHandler } from "./transformers/tool";
2
+ interface UIResourceMeta {
3
+ /**
4
+ * Content Security Policy configuration
5
+ *
6
+ * Servers declare which external origins their UI needs to access.
7
+ * Hosts use this to enforce appropriate CSP headers.
8
+ */
9
+ csp?: {
10
+ /**
11
+ * Origins for network requests
12
+ *
13
+ * - Empty or omitted = no external connections (secure default)
14
+ * - Maps to CSP `connect-src` directive
15
+ *
16
+ * @example
17
+ * ["https://api.weather.com", "wss://realtime.service.com"]
18
+ */
19
+ connectDomains?: string[];
20
+ /**
21
+ * Origins for static resources (images, scripts, stylesheets, fonts)
22
+ *
23
+ * - Empty or omitted = no external resources (secure default)
24
+ * - Wildcard subdomains supported: `https://*.example.com`
25
+ * - Maps to CSP `img-src`, `script-src`, `style-src`, `font-src` directives
26
+ *
27
+ * @example
28
+ * ["https://cdn.jsdelivr.net", "https://*.cloudflare.com"]
29
+ */
30
+ resourceDomains?: string[];
31
+ };
32
+ /**
33
+ * Dedicated origin for widget
34
+ *
35
+ * Optional domain for the widget's sandbox origin. Useful when widgets need
36
+ * dedicated origins for API key allowlists or cross-origin isolation.
37
+ *
38
+ * If omitted, Host uses default sandbox origin.
39
+ *
40
+ * @example
41
+ * "https://weather-widget.example.com"
42
+ */
43
+ domain?: string;
44
+ /**
45
+ * Visual boundary preference
46
+ *
47
+ * Boolean indicating the UI prefers a visible border. Useful for widgets
48
+ * that might blend with host background.
49
+ *
50
+ * - `true`: Request visible border (host decides styling)
51
+ * - `false` or omitted: No preference
52
+ */
53
+ prefersBorder?: boolean;
54
+ }
55
+ interface UIResource {
56
+ /**
57
+ * Unique identifier for the UI resource
58
+ *
59
+ * MUST use the `ui://` URI scheme to distinguish UI resources from other
60
+ * MCP resource types.
61
+ *
62
+ * @example
63
+ * "ui://weather-dashboard"
64
+ */
65
+ uri: string;
66
+ /**
67
+ * Human-readable display name for the UI resource
68
+ *
69
+ * Used for listing and identifying the resource in host interfaces.
70
+ *
71
+ * @example
72
+ * "Weather Dashboard"
73
+ */
74
+ name: string;
75
+ /**
76
+ * Optional description of the UI resource's purpose and functionality
77
+ *
78
+ * Provides context about what the UI does and when to use it.
79
+ *
80
+ * @example
81
+ * "Interactive weather visualization with real-time updates"
82
+ */
83
+ description?: string;
84
+ /**
85
+ * MIME type of the UI content
86
+ *
87
+ * SHOULD be `text/html;profile=mcp-app` for HTML-based UIs in the initial MVP.
88
+ * Other content types are reserved for future extensions.
89
+ *
90
+ * @example
91
+ * "text/html;profile=mcp-app"
92
+ */
93
+ mimeType: "text/html;profile=mcp-app";
94
+ /**
95
+ * Resource metadata for security and rendering configuration
96
+ *
97
+ * Includes Content Security Policy configuration, dedicated domain settings,
98
+ * and visual preferences.
99
+ */
100
+ _meta?: {
101
+ ui?: UIResourceMeta;
102
+ };
103
+ /**
104
+ * Path to the tool file (for React bundling)
105
+ */
106
+ toolPath?: string;
107
+ /**
108
+ * Tool handler function
109
+ */
110
+ handler: UserToolHandler;
111
+ }
112
+ declare class UIResourceRegistry {
113
+ private resources;
114
+ /**
115
+ * Add a resource to the registry
116
+ */
117
+ add(toolName: string, resource: UIResource): void;
118
+ /**
119
+ * Get all registered resources
120
+ */
121
+ getAll(): Map<string, UIResource>;
122
+ /**
123
+ * Clear all resources (useful for testing or reinitialization)
124
+ */
125
+ clear(): void;
126
+ /**
127
+ * Check if a resource exists
128
+ */
129
+ has(toolName: string): boolean;
130
+ }
131
+ export declare const uIResourceRegistry: UIResourceRegistry;
132
+ export {};
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Web-compatible pathToToolName using djb2 hash.
3
+ * Used for Cloudflare Workers where node:crypto is not available.
4
+ */
5
+ export declare function pathToToolNameDjb2(path: string): string;
6
+ /**
7
+ * Node.js pathToToolName using MD5 hash.
8
+ * Used for backwards compatibility with existing Node.js deployments.
9
+ *
10
+ * Note: For Cloudflare builds, crypto is resolved to an empty module
11
+ * via bundler fallback config. This is safe because pathToToolNameDjb2
12
+ * is used instead in Cloudflare Workers.
13
+ */
14
+ export declare function pathToToolNameMd5(path: string): string;
15
+ /**
16
+ * Default export for backwards compatibility.
17
+ * In Cloudflare Workers, use pathToToolNameDjb2 directly.
18
+ * In Node.js, this uses MD5 for backwards compatibility.
19
+ */
20
+ export declare const pathToToolName: typeof pathToToolNameMd5;
@@ -0,0 +1,11 @@
1
+ import type { PromptFile } from "./server";
2
+ type PromptLoadIssue = {
3
+ path: string;
4
+ message: string;
5
+ };
6
+ export declare function loadPromptModules(loaders: Record<string, () => Promise<unknown>>): Promise<{
7
+ promptModules: Map<string, PromptFile>;
8
+ skippedPrompts: PromptLoadIssue[];
9
+ }>;
10
+ export declare const reportPromptLoadIssues: (skippedPrompts: PromptLoadIssue[]) => void;
11
+ export {};
@@ -0,0 +1,8 @@
1
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
2
+ import { ZodOptional, ZodType, ZodTypeDef } from "zod/v3";
3
+ import { PromptFile } from "./server";
4
+ export type PromptArgsRawShape = {
5
+ [k: string]: ZodType<string, ZodTypeDef, string> | ZodOptional<ZodType<string, ZodTypeDef, string>>;
6
+ };
7
+ /** Loads prompts and injects them into the server */
8
+ export declare function addPromptsToServer(server: McpServer, promptModules: Map<string, PromptFile>): McpServer;
@@ -0,0 +1 @@
1
+ export declare function generateUIHTML(componentCode: string, css: string | undefined): string;
@@ -0,0 +1,4 @@
1
+ /**
2
+ * Check if a file path is a React component (.tsx file)
3
+ */
4
+ export declare function isReactFile(filePath: string): boolean;
@@ -0,0 +1,11 @@
1
+ import type { ResourceFile } from "./server";
2
+ type ResourceLoadIssue = {
3
+ path: string;
4
+ message: string;
5
+ };
6
+ export declare function loadResourceModules(loaders: Record<string, () => Promise<unknown>>): Promise<{
7
+ resourceModules: Map<string, ResourceFile>;
8
+ skippedResources: ResourceLoadIssue[];
9
+ }>;
10
+ export declare const reportResourceLoadIssues: (skippedResources: ResourceLoadIssue[]) => void;
11
+ export {};
@@ -0,0 +1,4 @@
1
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
2
+ import { ResourceFile } from "./server";
3
+ /** Loads resources and injects them into the server */
4
+ export declare function addResourcesToServer(server: McpServer, resourcesModules: Map<string, ResourceFile>): McpServer;
@@ -0,0 +1,35 @@
1
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
2
+ import { Implementation } from "@modelcontextprotocol/sdk/types";
3
+ import { PromptArgsRawShape } from "./prompts";
4
+ import { ToolMetadata } from "@/types/tool";
5
+ import { PromptMetadata } from "@/types/prompt";
6
+ import { UserToolHandler } from "./transformers/tool";
7
+ import { UserPromptHandler } from "./transformers/prompt";
8
+ import { UserResourceHandler } from "./transformers/resource";
9
+ import { ZodRawShape } from "zod/v3";
10
+ import { ResourceMetadata } from "@/types/resource";
11
+ export type ToolFile = {
12
+ metadata: ToolMetadata;
13
+ schema: ZodRawShape;
14
+ outputSchema?: ZodRawShape;
15
+ default: UserToolHandler;
16
+ };
17
+ export type PromptFile = {
18
+ metadata: PromptMetadata;
19
+ schema: PromptArgsRawShape;
20
+ default: UserPromptHandler;
21
+ };
22
+ export type ResourceFile = {
23
+ metadata: ResourceMetadata;
24
+ schema: ZodRawShape;
25
+ default: UserResourceHandler;
26
+ };
27
+ export declare const injectedTools: Record<string, () => Promise<ToolFile>>;
28
+ export declare const injectedPrompts: Record<string, () => Promise<PromptFile>>;
29
+ export declare const injectedResources: Record<string, () => Promise<ResourceFile>>;
30
+ export declare const INJECTED_CONFIG: Implementation;
31
+ export declare function configureServer(server: McpServer, toolModules: Map<string, ToolFile>, promptModules: Map<string, PromptFile>, resourceModules: Map<string, ResourceFile>): Promise<McpServer>;
32
+ export declare function loadTools(): Promise<Map<string, ToolFile>>;
33
+ export declare function loadPrompts(): Promise<Map<string, PromptFile>>;
34
+ export declare function loadResources(): Promise<Map<string, ResourceFile>>;
35
+ export declare function createServer(): Promise<McpServer>;
@@ -0,0 +1,11 @@
1
+ import type { ToolFile } from "./server";
2
+ type ToolLoadIssue = {
3
+ path: string;
4
+ message: string;
5
+ };
6
+ export declare function loadToolModules(loaders: Record<string, () => Promise<unknown>>): Promise<{
7
+ toolModules: Map<string, ToolFile>;
8
+ skippedTools: ToolLoadIssue[];
9
+ }>;
10
+ export declare const reportToolLoadIssues: (skippedTools: ToolLoadIssue[]) => void;
11
+ export {};
@@ -0,0 +1,11 @@
1
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
2
+ import { ZodRawShape } from "zod/v3";
3
+ import { ToolFile } from "./server";
4
+ import { ToolMetadata } from "@/types/tool";
5
+ /** Validates if a value is a valid Zod schema object */
6
+ export declare function isZodRawShape(value: unknown): value is ZodRawShape;
7
+ export declare function pathToName(path: string): string;
8
+ /** Ensures toolConfig has its own annotations object with a title */
9
+ export declare function ensureAnnotations(toolConfig: Pick<ToolMetadata, "name" | "annotations">): void;
10
+ /** Loads tools and injects them into the server */
11
+ export declare function addToolsToServer(server: McpServer, toolModules: Map<string, ToolFile>): McpServer;
@@ -0,0 +1,32 @@
1
+ import { GetPromptResult, ServerRequest, ServerNotification } from "@modelcontextprotocol/sdk/types";
2
+ import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol";
3
+ import { PromptArgsRawShape } from "../prompts";
4
+ /**
5
+ * Type for content that users can return from prompt handlers
6
+ */
7
+ export type PromptContent = GetPromptResult["messages"][number]["content"];
8
+ /**
9
+ * Type for the original prompt handler that users write
10
+ * The extra parameter is optional for backward compatibility
11
+ * Users can only return content objects, strings, or numbers - not full message arrays
12
+ */
13
+ export type UserPromptHandler = (args: PromptArgsRawShape, extra?: RequestHandlerExtra<ServerRequest, ServerNotification>) => PromptContent | string | number | Promise<PromptContent | string | number>;
14
+ /**
15
+ * Type for the transformed handler that the MCP server expects
16
+ */
17
+ export type McpPromptHandler = (args: PromptArgsRawShape, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => GetPromptResult | Promise<GetPromptResult>;
18
+ /**
19
+ * Transforms a user's prompt handler into an MCP-compatible handler.
20
+ *
21
+ * This function:
22
+ * 1. Passes through both args and extra parameters to the user's handler
23
+ * 2. Transforms string/number/content responses into a single message GetPromptResult format
24
+ * 3. Always creates exactly one message with the specified role
25
+ * 4. Validates that the response is valid and throws a descriptive error if not
26
+ *
27
+ * @param handler - The user's prompt handler function
28
+ * @param role - The role to assign to the message ("user" or "assistant")
29
+ * @returns A transformed handler compatible with McpServer.registerPrompt
30
+ * @throws Error if the handler returns an invalid response type
31
+ */
32
+ export declare function transformPromptHandler(handler: UserPromptHandler, role?: "user" | "assistant"): McpPromptHandler;
@@ -0,0 +1,26 @@
1
+ import { ReadResourceResult, ServerRequest, ServerNotification } from "@modelcontextprotocol/sdk/types";
2
+ import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol";
3
+ import { ZodRawShape } from "zod/v3";
4
+ /**
5
+ * Type for the original resource handler that users write
6
+ */
7
+ export type UserResourceHandler = (args: ZodRawShape, extra?: RequestHandlerExtra<ServerRequest, ServerNotification>) => ReadResourceResult | string | Promise<ReadResourceResult | string>;
8
+ /**
9
+ * Type for the transformed handler that the MCP server expects (direct resources)
10
+ */
11
+ export type McpResourceHandler = (uri: URL, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => ReadResourceResult | Promise<ReadResourceResult>;
12
+ /**
13
+ * Transforms a user's resource handler into an MCP-compatible handler.
14
+ *
15
+ * This function:
16
+ * 1. Extracts parameters from the URI based on the resource file path
17
+ * 2. Passes the parameters to the user's handler
18
+ * 3. Transforms string responses into the required ReadResourceResult format
19
+ * 4. Ensures the URI is included in the response content
20
+ *
21
+ * @param handler - The user's resource handler function
22
+ * @param filePath - The resource file path (used to extract URI template and parameters)
23
+ * @returns A transformed handler compatible with McpServer.registerResource
24
+ * @throws Error if the handler returns an invalid response type
25
+ */
26
+ export declare function transformResourceHandler(handler: UserResourceHandler, filePath: string, schema?: ZodRawShape): McpResourceHandler;
@@ -0,0 +1,30 @@
1
+ import { CallToolResult, ServerRequest, ServerNotification } from "@modelcontextprotocol/sdk/types";
2
+ import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol";
3
+ import { ZodRawShape } from "zod/v3";
4
+ import type { ToolExtraArguments } from "@/types/tool";
5
+ /**
6
+ * Type for the original tool handler that users write
7
+ */
8
+ export type UserToolResponse = CallToolResult | string | number | Record<string, unknown>;
9
+ export type UserToolHandler = (args: ZodRawShape, extra: ToolExtraArguments) => UserToolResponse | Promise<UserToolResponse>;
10
+ /**
11
+ * Type for the transformed handler that the MCP server expects
12
+ */
13
+ export type McpToolHandler = (args: ZodRawShape, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => CallToolResult | Promise<CallToolResult>;
14
+ /**
15
+ * Transforms a user's tool handler into an MCP-compatible handler.
16
+ *
17
+ * This function:
18
+ * 1. Passes through both args and extra parameters to the user's handler
19
+ * 2. Transforms string/number responses into the required CallToolResult format
20
+ * 3. Allows returning `content`, `structuredContent`, or both
21
+ * 4. Allows returning only `_meta` (without `content`) when it contains widget metadata
22
+ * 5. Auto-wraps HTML strings with widget metadata if provided
23
+ * 6. Validates that the response is a proper CallToolResult and throws a descriptive error if not
24
+ *
25
+ * @param handler - The user's tool handler function
26
+ * @param meta - Optional metadata to attach to responses (for MCP app widgets)
27
+ * @returns A transformed handler compatible with McpServer.registerTool
28
+ * @throws Error if the handler returns an invalid response type
29
+ */
30
+ export declare function transformToolHandler(handler: UserToolHandler, meta?: Record<string, any>, outputSchema?: ZodRawShape, toolName?: string): McpToolHandler;
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Flattens nested metadata object into a flat structure with "/" delimited keys.
3
+ */
4
+ export declare function flattenMeta(meta: Record<string, any>): Record<string, any>;
5
+ /** Checks if metadata contains UI-specific keys.*/
6
+ export declare function hasUIMeta(meta?: Record<string, any>): boolean;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Splits UI metadata into tool-specific and resource-specific properties.
3
+ */
4
+ export interface SplitMetadata {
5
+ toolMeta: Record<string, any>;
6
+ resourceMeta: Record<string, any>;
7
+ }
8
+ /**
9
+ * Splits nested UI metadata into tool and resource metadata.
10
+ * Keeps metadata in nested format (no flattening).
11
+ *
12
+ * @param meta - The metadata object (nested format with 'ui' key)
13
+ * @returns Object containing toolMeta and resourceMeta in nested format
14
+ */
15
+ export declare function splitUIMetaNested(meta: Record<string, any>): SplitMetadata;
16
+ export declare function isToolMetaKeyNested(key: string): boolean;
17
+ export declare function isResourceMetaKeyNested(key: string): boolean;
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Utilities for composing URIs from resource file paths following the convention:
3
+ * - (scheme) folders become URI schemes
4
+ * - [param] folders become dynamic parameters
5
+ * - static folders become literal path segments
6
+ * - file names become endpoints
7
+ */
8
+ export type ResourceType = "direct" | "template";
9
+ export interface ResourceInfo {
10
+ /** The original file path */
11
+ filePath: string;
12
+ /** The composed URI template */
13
+ uriTemplate: string;
14
+ /** The URI scheme extracted from (scheme) folder */
15
+ scheme: string;
16
+ /** Dynamic parameters extracted from [param] folders */
17
+ parameters: string[];
18
+ /** Static path segments */
19
+ pathSegments: string[];
20
+ /** Whether this is a direct resource or template resource */
21
+ type: ResourceType;
22
+ }
23
+ /**
24
+ * Compose a URI template from a resource file path
25
+ *
26
+ * @param filePath - The file path relative to resources folder
27
+ * @returns ResourceInfo with composed URI and metadata
28
+ *
29
+ * @example
30
+ * // Static resource
31
+ * composeUriFromPath('(config)/app.ts')
32
+ * // Returns: { uriTemplate: 'config://app', parameters: [], ... }
33
+ *
34
+ * // Dynamic parameter as file
35
+ * composeUriFromPath('(users)/[id].ts')
36
+ * // Returns: { uriTemplate: 'users://{id}', parameters: ['id'], ... }
37
+ *
38
+ * // Dynamic parameter as folder with index
39
+ * composeUriFromPath('(users)/[id]/index.ts')
40
+ * // Returns: { uriTemplate: 'users://{id}', parameters: ['id'], ... }
41
+ *
42
+ * // Complex nested
43
+ * composeUriFromPath('(github)/repos/[owner]/[repo]/index.ts')
44
+ * // Returns: { uriTemplate: 'github://repos/{owner}/{repo}', parameters: ['owner', 'repo'], ... }
45
+ */
46
+ export declare function composeUriFromPath(filePath: string): ResourceInfo | null;
47
+ /**
48
+ * Get all resource URIs from a set of file paths
49
+ */
50
+ export declare function getResourceUris(resourcePaths: Set<string>, basePath: string): ResourceInfo[];
51
+ /** separate resources by type for different handling when injecting into the server */
52
+ export declare function categorizeResources(resourceInfos: ResourceInfo[]): {
53
+ directResources: ResourceInfo[];
54
+ templateResources: ResourceInfo[];
55
+ };
56
+ /** validate resource URI against MCP standards */
57
+ export declare function validateResourceUri(resourceInfo: ResourceInfo): {
58
+ valid: boolean;
59
+ errors: string[];
60
+ };
@@ -0,0 +1,13 @@
1
+ export type ContentValidator = (content: any) => {
2
+ valid: boolean;
3
+ error?: string;
4
+ };
5
+ export declare const contentValidators: Record<string, ContentValidator>;
6
+ /**
7
+ * Validates content and returns a detailed error message if invalid
8
+ * applies for both tools and prompts
9
+ */
10
+ export declare function validateContent(content: unknown): {
11
+ valid: boolean;
12
+ error?: string;
13
+ };
@@ -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
+ }
@@ -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
  export interface ToolAnnotations {
5
7
  /** Human-readable title for the tool */
6
8
  title?: string;
@@ -28,7 +30,70 @@ export interface ToolMetadata {
28
30
  };
29
31
  }
30
32
  type CompatibleZodType = z.ZodTypeAny | ZodTypeV4<unknown>;
33
+ type InferCompatibleZodType<T extends CompatibleZodType> = T extends z.ZodTypeAny ? z.infer<T> : T extends ZodTypeV4<unknown> ? inferV4<T> : never;
31
34
  export type ToolSchema = Record<string, CompatibleZodType>;
35
+ export type ToolOutputSchema = Record<string, CompatibleZodType>;
36
+ export type ElicitResult = McpElicitResult;
37
+ export interface ToolRequestOptions {
38
+ /** Progress notification callback */
39
+ onprogress?: (progress: any) => void;
40
+ /** Abort signal for cancelling the request */
41
+ signal?: AbortSignal;
42
+ /** Request timeout in milliseconds */
43
+ timeout?: number;
44
+ /** Whether receiving progress notifications resets the timeout */
45
+ resetTimeoutOnProgress?: boolean;
46
+ /** Maximum total time to wait for a response */
47
+ maxTotalTimeout?: number;
48
+ /** Additional transport-specific options */
49
+ [key: string]: unknown;
50
+ }
51
+ type ElicitStringFormat = "date" | "uri" | "email" | "date-time";
52
+ interface ElicitFieldBase {
53
+ title?: string;
54
+ description?: string;
55
+ }
56
+ export interface ElicitStringField extends ElicitFieldBase {
57
+ type: "string";
58
+ minLength?: number;
59
+ maxLength?: number;
60
+ format?: ElicitStringFormat;
61
+ default?: string;
62
+ }
63
+ export interface ElicitEnumField extends ElicitFieldBase {
64
+ type: "string";
65
+ enum: string[];
66
+ enumNames?: string[];
67
+ default?: string;
68
+ }
69
+ export interface ElicitBooleanField extends ElicitFieldBase {
70
+ type: "boolean";
71
+ default?: boolean;
72
+ }
73
+ export interface ElicitNumberField extends ElicitFieldBase {
74
+ type: "number" | "integer";
75
+ minimum?: number;
76
+ maximum?: number;
77
+ default?: number;
78
+ }
79
+ export type ElicitFormField = ElicitStringField | ElicitEnumField | ElicitBooleanField | ElicitNumberField;
80
+ export interface ElicitFormSchema {
81
+ type: "object";
82
+ properties: Record<string, ElicitFormField>;
83
+ required?: string[];
84
+ }
85
+ export interface ElicitFormRequest {
86
+ mode?: "form";
87
+ message: string;
88
+ requestedSchema: ElicitFormSchema;
89
+ }
90
+ export interface ElicitUrlRequest {
91
+ mode: "url";
92
+ message: string;
93
+ url: string;
94
+ elicitationId: string;
95
+ }
96
+ export type ElicitRequest = ElicitFormRequest | ElicitUrlRequest;
32
97
  /**
33
98
  * Extra arguments passed to MCP tool functions.
34
99
  */
@@ -64,23 +129,14 @@ export interface ToolExtraArguments {
64
129
  /** The headers of the request */
65
130
  headers: Record<string, string | string[] | undefined>;
66
131
  };
132
+ /** MCP client metadata from initialize.params.clientInfo, when available */
133
+ clientInfo?: McpClientInfo;
67
134
  /** Sends a notification that relates to the current request being handled */
68
135
  sendNotification: (notification: any) => Promise<void>;
69
136
  /** Sends a request that relates to the current request being handled */
70
- sendRequest: <U extends z.ZodType<object>>(request: any, resultSchema: U, options?: {
71
- /** Progress notification callback */
72
- onprogress?: (progress: any) => void;
73
- /** Abort signal for cancelling the request */
74
- signal?: AbortSignal;
75
- /** Request timeout in milliseconds */
76
- timeout?: number;
77
- /** Whether receiving progress notifications resets the timeout */
78
- resetTimeoutOnProgress?: boolean;
79
- /** Maximum total time to wait for a response */
80
- maxTotalTimeout?: number;
81
- /** Additional transport-specific options */
82
- [key: string]: unknown;
83
- }) => Promise<z.infer<U>>;
137
+ sendRequest: <U extends CompatibleZodType>(request: any, resultSchema: U, options?: ToolRequestOptions) => Promise<InferCompatibleZodType<U>>;
138
+ /** Requests user input from the connected client */
139
+ elicit: (request: ElicitRequest, options?: ToolRequestOptions) => Promise<ElicitResult>;
84
140
  }
85
141
  export type InferSchema<T extends Record<string, unknown>> = {
86
142
  [K in keyof T]: T[K] extends z.ZodTypeAny ? z.infer<T[K]> : T[K] extends ZodTypeV4<unknown> ? inferV4<T[K]> : never;
@@ -3,7 +3,7 @@ type GetContext<T extends DefaultContext> = () => T;
3
3
  type SetContext<T extends DefaultContext> = (data: Partial<T>) => void;
4
4
  export interface Context<T extends DefaultContext> {
5
5
  /** Run a callback with a specific context. */
6
- provider: (initialValue: T, callback: () => void) => void;
6
+ provider: <R>(initialValue: T, callback: () => R) => R;
7
7
  /** Get the context. */
8
8
  getContext: GetContext<T>;
9
9
  /** Partially update the context. */
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "xmcp",
3
3
  "description": "The MCP framework",
4
- "version": "0.6.5",
4
+ "version": "0.6.7",
5
5
  "author": {
6
6
  "name": "xmcp",
7
7
  "email": "support@xmcp.dev",
@@ -43,6 +43,11 @@
43
43
  "require": "./dist/index.js",
44
44
  "default": "./dist/index.js"
45
45
  },
46
+ "./headers": {
47
+ "types": "./dist/runtime/headers.d.ts",
48
+ "require": "./dist/runtime/headers.js",
49
+ "default": "./dist/runtime/headers.js"
50
+ },
46
51
  "./cloudflare": {
47
52
  "types": "./dist/cloudflare.d.ts",
48
53
  "require": "./dist/cloudflare.js",
@@ -52,6 +57,9 @@
52
57
  },
53
58
  "typesVersions": {
54
59
  "*": {
60
+ "headers": [
61
+ "dist/runtime/headers.d.ts"
62
+ ],
55
63
  "cloudflare": [
56
64
  "dist/cloudflare.d.ts"
57
65
  ]
@@ -26,7 +26,10 @@ export const CLIENT_IDENTITY = {
26
26
  const CLIENT_CAPABILITIES = {
27
27
  capabilities: {
28
28
  sampling: {},
29
- elicitation: {},
29
+ elicitation: {
30
+ form: {},
31
+ url: {},
32
+ },
30
33
  roots: { listChanged: true },
31
34
  },
32
35
  } as const;