xmcp 0.6.6 → 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.
- package/README.md +32 -0
- package/dist/cli.js +30 -32
- package/dist/compiler/config/index.d.ts +54 -54
- package/dist/compiler/config/schemas/transport/http.d.ts +82 -82
- package/dist/index.d.ts +4 -2
- package/dist/index.js +3 -3
- package/dist/runtime/adapter-express.js +39 -22
- package/dist/runtime/adapter-nestjs.js +39 -22
- package/dist/runtime/adapter-nextjs.js +38 -21
- package/dist/runtime/contexts/http-request-context.d.ts +3 -1
- package/dist/runtime/headers.js +1 -1
- package/dist/runtime/http.js +47 -30
- package/dist/runtime/stdio.js +17 -11
- package/dist/runtime/utils/elicitation.d.ts +4 -0
- package/dist/runtime/utils/ext-apps-registry.d.ts +132 -0
- package/dist/runtime/utils/path-to-tool-name.d.ts +20 -0
- package/dist/runtime/utils/prompt-loader.d.ts +11 -0
- package/dist/runtime/utils/prompts.d.ts +8 -0
- package/dist/runtime/utils/react/generate-html.d.ts +1 -0
- package/dist/runtime/utils/react/index.d.ts +4 -0
- package/dist/runtime/utils/resource-loader.d.ts +11 -0
- package/dist/runtime/utils/resources.d.ts +4 -0
- package/dist/runtime/utils/server.d.ts +35 -0
- package/dist/runtime/utils/tool-loader.d.ts +11 -0
- package/dist/runtime/utils/tools.d.ts +11 -0
- package/dist/runtime/utils/transformers/prompt.d.ts +32 -0
- package/dist/runtime/utils/transformers/resource.d.ts +26 -0
- package/dist/runtime/utils/transformers/tool.d.ts +30 -0
- package/dist/runtime/utils/ui/flatten-meta.d.ts +6 -0
- package/dist/runtime/utils/ui/split-meta.d.ts +17 -0
- package/dist/runtime/utils/utils/resource-uri-composer.d.ts +60 -0
- package/dist/runtime/utils/validators/index.d.ts +13 -0
- package/dist/types/client-info.d.ts +12 -0
- package/dist/types/tool.d.ts +69 -14
- package/dist/utils/context.d.ts +1 -1
- package/package.json +9 -1
- package/src/client/index.ts +4 -1
- package/src/compiler/generate-tools-code.ts +4 -6
- package/src/compiler/get-bundler-config/plugins/index.ts +0 -1
- package/src/compiler/index.ts +24 -7
- package/src/index.ts +8 -1
- package/src/runtime/adapters/express/index.ts +45 -47
- package/src/runtime/adapters/nestjs/xmcp.service.ts +4 -3
- package/src/runtime/adapters/nextjs/handler/node-to-web-adapter.ts +40 -6
- package/src/runtime/adapters/nextjs/handler/request-converter.ts +20 -0
- package/src/runtime/adapters/nextjs/handler/server-lifecycle.ts +8 -5
- package/src/runtime/adapters/nextjs/index.ts +41 -25
- package/src/runtime/contexts/http-request-context.ts +2 -0
- package/src/runtime/headers.ts +37 -2
- package/src/runtime/platforms/cloudflare/cors.ts +0 -1
- package/src/runtime/platforms/cloudflare/worker.ts +46 -44
- package/src/runtime/transports/http/index.ts +0 -4
- package/src/runtime/transports/http/stateless-streamable-http.ts +131 -233
- package/src/runtime/transports/stdio/index.ts +0 -2
- package/src/runtime/utils/__tests__/client-info.test.ts +80 -0
- package/src/runtime/utils/__tests__/tool-extra.test.ts +110 -0
- package/src/runtime/utils/client-info.ts +71 -0
- package/src/runtime/utils/elicitation.ts +396 -0
- package/src/runtime/utils/prompt-loader.ts +151 -0
- package/src/runtime/utils/resource-loader.ts +151 -0
- package/src/runtime/utils/resources.ts +0 -8
- package/src/runtime/utils/server.ts +28 -38
- package/src/runtime/utils/tool-loader.ts +149 -0
- package/src/runtime/utils/tools.ts +9 -6
- package/src/runtime/utils/transformers/tool.ts +26 -5
- package/src/types/client-info.ts +12 -0
- package/src/types/injected.d.ts +62 -0
- package/src/types/tool.ts +99 -17
- 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,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
|
+
}
|
package/dist/types/tool.d.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
|
export interface ToolAnnotations {
|
|
5
7
|
/** Human-readable title for the tool */
|
|
6
8
|
title?: string;
|
|
@@ -28,8 +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>;
|
|
32
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;
|
|
33
97
|
/**
|
|
34
98
|
* Extra arguments passed to MCP tool functions.
|
|
35
99
|
*/
|
|
@@ -65,23 +129,14 @@ export interface ToolExtraArguments {
|
|
|
65
129
|
/** The headers of the request */
|
|
66
130
|
headers: Record<string, string | string[] | undefined>;
|
|
67
131
|
};
|
|
132
|
+
/** MCP client metadata from initialize.params.clientInfo, when available */
|
|
133
|
+
clientInfo?: McpClientInfo;
|
|
68
134
|
/** Sends a notification that relates to the current request being handled */
|
|
69
135
|
sendNotification: (notification: any) => Promise<void>;
|
|
70
136
|
/** Sends a request that relates to the current request being handled */
|
|
71
|
-
sendRequest: <U extends
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
/** Abort signal for cancelling the request */
|
|
75
|
-
signal?: AbortSignal;
|
|
76
|
-
/** Request timeout in milliseconds */
|
|
77
|
-
timeout?: number;
|
|
78
|
-
/** Whether receiving progress notifications resets the timeout */
|
|
79
|
-
resetTimeoutOnProgress?: boolean;
|
|
80
|
-
/** Maximum total time to wait for a response */
|
|
81
|
-
maxTotalTimeout?: number;
|
|
82
|
-
/** Additional transport-specific options */
|
|
83
|
-
[key: string]: unknown;
|
|
84
|
-
}) => 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>;
|
|
85
140
|
}
|
|
86
141
|
export type InferSchema<T extends Record<string, unknown>> = {
|
|
87
142
|
[K in keyof T]: T[K] extends z.ZodTypeAny ? z.infer<T[K]> : T[K] extends ZodTypeV4<unknown> ? inferV4<T[K]> : never;
|
package/dist/utils/context.d.ts
CHANGED
|
@@ -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: () =>
|
|
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.
|
|
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
|
]
|
package/src/client/index.ts
CHANGED