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
@@ -0,0 +1,151 @@
1
+ import type { PromptFile } from "./server";
2
+
3
+ const EMPTY_PROMPT_FILE_MESSAGE = "File is empty.";
4
+ const MISSING_DEFAULT_EXPORT_MESSAGE =
5
+ "File does not export a default prompt handler.";
6
+ const INVALID_DEFAULT_EXPORT_MESSAGE =
7
+ "Default export must be a prompt handler function.";
8
+
9
+ type PromptLoadIssue = {
10
+ path: string;
11
+ message: string;
12
+ };
13
+
14
+ function createPromptLoadIssue(path: string): PromptLoadIssue {
15
+ return {
16
+ path,
17
+ message: EMPTY_PROMPT_FILE_MESSAGE,
18
+ };
19
+ }
20
+
21
+ function createInvalidPromptImplementationError(path: string): Error {
22
+ return new Error(
23
+ `[xmcp] Invalid prompt file: ${path}\n -> ${INVALID_DEFAULT_EXPORT_MESSAGE}`
24
+ );
25
+ }
26
+
27
+ function classifyPromptModule(
28
+ promptModule: unknown,
29
+ path: string
30
+ ): "empty" | "missing-default" | "valid" {
31
+ if (typeof promptModule !== "object" || promptModule === null) {
32
+ throw createInvalidPromptImplementationError(path);
33
+ }
34
+
35
+ const moduleRecord = promptModule as Record<string, unknown>;
36
+ const keys = Object.keys(moduleRecord);
37
+ const defaultExport = moduleRecord.default;
38
+ const nonInteropKeys = keys.filter((key) => key !== "__esModule");
39
+
40
+ if (
41
+ keys.length === 0 ||
42
+ (nonInteropKeys.length === 1 &&
43
+ nonInteropKeys[0] === "default" &&
44
+ typeof defaultExport === "object" &&
45
+ defaultExport !== null &&
46
+ Object.keys(defaultExport as Record<string, unknown>).length === 0)
47
+ ) {
48
+ return "empty";
49
+ }
50
+
51
+ if (!("default" in moduleRecord) || moduleRecord.default === undefined) {
52
+ return "missing-default";
53
+ }
54
+
55
+ if (typeof moduleRecord.default !== "function") {
56
+ throw createInvalidPromptImplementationError(path);
57
+ }
58
+
59
+ return "valid";
60
+ }
61
+
62
+ function toPromptFile(promptModule: unknown): PromptFile {
63
+ return promptModule as PromptFile;
64
+ }
65
+
66
+ export async function loadPromptModules(
67
+ loaders: Record<string, () => Promise<unknown>>
68
+ ) {
69
+ const promptModules = new Map<string, PromptFile>();
70
+ const skippedPrompts: PromptLoadIssue[] = [];
71
+
72
+ const results = await Promise.all(
73
+ Object.entries(loaders).map(async ([path, loadPrompt]) => {
74
+ const promptModule = await loadPrompt();
75
+ const classification = classifyPromptModule(promptModule, path);
76
+
77
+ if (classification === "empty") {
78
+ return {
79
+ skipped: true as const,
80
+ issue: createPromptLoadIssue(path),
81
+ };
82
+ }
83
+
84
+ if (classification === "missing-default") {
85
+ return {
86
+ skipped: true as const,
87
+ issue: {
88
+ path,
89
+ message: MISSING_DEFAULT_EXPORT_MESSAGE,
90
+ },
91
+ };
92
+ }
93
+
94
+ return {
95
+ skipped: false as const,
96
+ path,
97
+ promptModule: toPromptFile(promptModule),
98
+ };
99
+ })
100
+ );
101
+
102
+ for (const result of results) {
103
+ if (result.skipped) {
104
+ skippedPrompts.push(result.issue);
105
+ continue;
106
+ }
107
+
108
+ promptModules.set(result.path, result.promptModule);
109
+ }
110
+
111
+ return {
112
+ promptModules,
113
+ skippedPrompts,
114
+ };
115
+ }
116
+
117
+ function createPromptLoadIssueReporter(
118
+ logger: Pick<Console, "warn"> = console
119
+ ) {
120
+ let lastReportedSummaryKey = "";
121
+
122
+ return (skippedPrompts: PromptLoadIssue[]) => {
123
+ const summaryKey = skippedPrompts
124
+ .map(({ path, message }) => `${path}:${message}`)
125
+ .sort()
126
+ .join("|");
127
+
128
+ if (summaryKey === lastReportedSummaryKey) {
129
+ return;
130
+ }
131
+
132
+ lastReportedSummaryKey = summaryKey;
133
+
134
+ if (skippedPrompts.length === 0) {
135
+ return;
136
+ }
137
+
138
+ skippedPrompts.forEach(({ path, message }) => {
139
+ logger.warn(
140
+ `[xmcp] Failed to load prompt file: ${path}\n -> ${message}`
141
+ );
142
+ });
143
+
144
+ const count = skippedPrompts.length;
145
+ logger.warn(
146
+ `[xmcp] ${count} prompt${count === 1 ? "" : "s"} skipped due to empty files or missing default exports`
147
+ );
148
+ };
149
+ }
150
+
151
+ export const reportPromptLoadIssues = createPromptLoadIssueReporter();
@@ -1,3 +1,9 @@
1
+ import {
2
+ INITIALIZE_METHOD,
3
+ INITIALIZED_METHOD,
4
+ MCP_APPS_PROTOCOL_VERSION,
5
+ } from "../mcp-app-protocol";
6
+
1
7
  export function generateUIHTML(
2
8
  componentCode: string,
3
9
  css: string | undefined
@@ -16,11 +22,13 @@ export function generateUIHTML(
16
22
  window.parent.postMessage({
17
23
  jsonrpc: "2.0",
18
24
  id: nextId++,
19
- method: "ui/initialize",
25
+ method: ${JSON.stringify(INITIALIZE_METHOD)},
20
26
  params: {
21
- appCapabilities: {},
27
+ appCapabilities: {
28
+ availableDisplayModes: ["inline", "fullscreen", "pip"]
29
+ },
22
30
  appInfo: { name: "xmcp React Widget", version: "1.0.0" },
23
- protocolVersion: "2025-06-18"
31
+ protocolVersion: ${JSON.stringify(MCP_APPS_PROTOCOL_VERSION)}
24
32
  }
25
33
  }, "*");
26
34
 
@@ -33,7 +41,7 @@ export function generateUIHTML(
33
41
  if (data?.result?.hostContext && data?.id === 1) {
34
42
  window.parent.postMessage({
35
43
  jsonrpc: "2.0",
36
- method: "ui/notifications/initialized",
44
+ method: ${JSON.stringify(INITIALIZED_METHOD)},
37
45
  params: {}
38
46
  }, "*");
39
47
  }
@@ -0,0 +1,151 @@
1
+ import type { ResourceFile } from "./server";
2
+
3
+ const EMPTY_RESOURCE_FILE_MESSAGE = "File is empty.";
4
+ const MISSING_DEFAULT_EXPORT_MESSAGE =
5
+ "File does not export a default resource handler.";
6
+ const INVALID_DEFAULT_EXPORT_MESSAGE =
7
+ "Default export must be a resource handler function.";
8
+
9
+ type ResourceLoadIssue = {
10
+ path: string;
11
+ message: string;
12
+ };
13
+
14
+ function createResourceLoadIssue(path: string): ResourceLoadIssue {
15
+ return {
16
+ path,
17
+ message: EMPTY_RESOURCE_FILE_MESSAGE,
18
+ };
19
+ }
20
+
21
+ function createInvalidResourceImplementationError(path: string): Error {
22
+ return new Error(
23
+ `[xmcp] Invalid resource file: ${path}\n -> ${INVALID_DEFAULT_EXPORT_MESSAGE}`
24
+ );
25
+ }
26
+
27
+ function classifyResourceModule(
28
+ resourceModule: unknown,
29
+ path: string
30
+ ): "empty" | "missing-default" | "valid" {
31
+ if (typeof resourceModule !== "object" || resourceModule === null) {
32
+ throw createInvalidResourceImplementationError(path);
33
+ }
34
+
35
+ const moduleRecord = resourceModule as Record<string, unknown>;
36
+ const keys = Object.keys(moduleRecord);
37
+ const defaultExport = moduleRecord.default;
38
+ const nonInteropKeys = keys.filter((key) => key !== "__esModule");
39
+
40
+ if (
41
+ keys.length === 0 ||
42
+ (nonInteropKeys.length === 1 &&
43
+ nonInteropKeys[0] === "default" &&
44
+ typeof defaultExport === "object" &&
45
+ defaultExport !== null &&
46
+ Object.keys(defaultExport as Record<string, unknown>).length === 0)
47
+ ) {
48
+ return "empty";
49
+ }
50
+
51
+ if (!("default" in moduleRecord) || moduleRecord.default === undefined) {
52
+ return "missing-default";
53
+ }
54
+
55
+ if (typeof moduleRecord.default !== "function") {
56
+ throw createInvalidResourceImplementationError(path);
57
+ }
58
+
59
+ return "valid";
60
+ }
61
+
62
+ function toResourceFile(resourceModule: unknown): ResourceFile {
63
+ return resourceModule as ResourceFile;
64
+ }
65
+
66
+ export async function loadResourceModules(
67
+ loaders: Record<string, () => Promise<unknown>>
68
+ ) {
69
+ const resourceModules = new Map<string, ResourceFile>();
70
+ const skippedResources: ResourceLoadIssue[] = [];
71
+
72
+ const results = await Promise.all(
73
+ Object.entries(loaders).map(async ([path, loadResource]) => {
74
+ const resourceModule = await loadResource();
75
+ const classification = classifyResourceModule(resourceModule, path);
76
+
77
+ if (classification === "empty") {
78
+ return {
79
+ skipped: true as const,
80
+ issue: createResourceLoadIssue(path),
81
+ };
82
+ }
83
+
84
+ if (classification === "missing-default") {
85
+ return {
86
+ skipped: true as const,
87
+ issue: {
88
+ path,
89
+ message: MISSING_DEFAULT_EXPORT_MESSAGE,
90
+ },
91
+ };
92
+ }
93
+
94
+ return {
95
+ skipped: false as const,
96
+ path,
97
+ resourceModule: toResourceFile(resourceModule),
98
+ };
99
+ })
100
+ );
101
+
102
+ for (const result of results) {
103
+ if (result.skipped) {
104
+ skippedResources.push(result.issue);
105
+ continue;
106
+ }
107
+
108
+ resourceModules.set(result.path, result.resourceModule);
109
+ }
110
+
111
+ return {
112
+ resourceModules,
113
+ skippedResources,
114
+ };
115
+ }
116
+
117
+ function createResourceLoadIssueReporter(
118
+ logger: Pick<Console, "warn"> = console
119
+ ) {
120
+ let lastReportedSummaryKey = "";
121
+
122
+ return (skippedResources: ResourceLoadIssue[]) => {
123
+ const summaryKey = skippedResources
124
+ .map(({ path, message }) => `${path}:${message}`)
125
+ .sort()
126
+ .join("|");
127
+
128
+ if (summaryKey === lastReportedSummaryKey) {
129
+ return;
130
+ }
131
+
132
+ lastReportedSummaryKey = summaryKey;
133
+
134
+ if (skippedResources.length === 0) {
135
+ return;
136
+ }
137
+
138
+ skippedResources.forEach(({ path, message }) => {
139
+ logger.warn(
140
+ `[xmcp] Failed to load resource file: ${path}\n -> ${message}`
141
+ );
142
+ });
143
+
144
+ const count = skippedResources.length;
145
+ logger.warn(
146
+ `[xmcp] ${count} resource${count === 1 ? "" : "s"} skipped due to empty files or missing default exports`
147
+ );
148
+ };
149
+ }
150
+
151
+ export const reportResourceLoadIssues = createResourceLoadIssueReporter();
@@ -14,14 +14,6 @@ import { generateUIHTML } from "./react/generate-html";
14
14
  import { pathToToolNameMd5, pathToToolNameDjb2 } from "./path-to-tool-name";
15
15
  import { uIResourceRegistry } from "./ext-apps-registry";
16
16
 
17
- // Client bundles can be injected at compile time for Cloudflare Workers
18
- // This variable is defined by DefinePlugin at compile time
19
- declare const INJECTED_CLIENT_BUNDLES:
20
- | Record<string, { js: string; css?: string }>
21
- | undefined;
22
-
23
- declare const IS_CLOUDFLARE: boolean;
24
-
25
17
  /**
26
18
  * Get the appropriate pathToToolName function based on runtime environment.
27
19
  * - For Cloudflare (INJECTED_CLIENT_BUNDLES defined): Use djb2 hash
@@ -11,6 +11,12 @@ import { ZodRawShape } from "zod/v3";
11
11
  import { addResourcesToServer } from "./resources";
12
12
  import { ResourceMetadata } from "@/types/resource";
13
13
  import { uIResourceRegistry } from "./ext-apps-registry";
14
+ import { loadPromptModules, reportPromptLoadIssues } from "./prompt-loader";
15
+ import {
16
+ loadResourceModules,
17
+ reportResourceLoadIssues,
18
+ } from "./resource-loader";
19
+ import { loadToolModules, reportToolLoadIssues } from "./tool-loader";
14
20
 
15
21
  export type ToolFile = {
16
22
  metadata: ToolMetadata;
@@ -31,26 +37,22 @@ export type ResourceFile = {
31
37
  default: UserResourceHandler;
32
38
  };
33
39
 
34
- // @ts-expect-error: injected by compiler
35
40
  export const injectedTools = INJECTED_TOOLS as Record<
36
41
  string,
37
42
  () => Promise<ToolFile>
38
43
  >;
39
44
 
40
- // @ts-expect-error: injected by compiler
41
45
  export const injectedPrompts = INJECTED_PROMPTS as Record<
42
46
  string,
43
47
  () => Promise<PromptFile>
44
48
  >;
45
49
 
46
- // @ts-expect-error: injected by compiler
47
50
  export const injectedResources = INJECTED_RESOURCES as Record<
48
51
  string,
49
52
  () => Promise<ResourceFile>
50
53
  >;
51
54
 
52
- // @ts-expect-error: injected by compiler
53
- export const INJECTED_CONFIG = SERVER_INFO as Implementation;
55
+ export const INJECTED_CONFIG = SERVER_INFO as Implementation & { instructions?: string };
54
56
 
55
57
  /* Loads all modules and injects them into the server */
56
58
  // would be better as a class and use dependency injection perhaps
@@ -68,49 +70,38 @@ export async function configureServer(
68
70
  return server;
69
71
  }
70
72
 
71
- export function loadTools() {
72
- const toolModules = new Map<string, ToolFile>();
73
-
74
- const toolPromises = Object.keys(injectedTools).map((path) =>
75
- injectedTools[path]().then((toolModule) => {
76
- toolModules.set(path, toolModule);
77
- })
78
- );
79
-
80
- return [toolPromises, toolModules] as const;
73
+ export async function loadTools() {
74
+ const { toolModules, skippedTools } = await loadToolModules(injectedTools);
75
+ reportToolLoadIssues(skippedTools);
76
+ return toolModules;
81
77
  }
82
78
 
83
- export function loadPrompts() {
84
- const promptModules = new Map<string, PromptFile>();
85
-
86
- const promptPromises = Object.keys(injectedPrompts).map((path) =>
87
- injectedPrompts[path]().then((promptModule) => {
88
- promptModules.set(path, promptModule);
89
- })
79
+ export async function loadPrompts() {
80
+ const { promptModules, skippedPrompts } = await loadPromptModules(
81
+ injectedPrompts
90
82
  );
91
-
92
- return [promptPromises, promptModules] as const;
83
+ reportPromptLoadIssues(skippedPrompts);
84
+ return promptModules;
93
85
  }
94
86
 
95
- export function loadResources() {
96
- const resourceModules = new Map<string, ResourceFile>();
97
-
98
- const resourcePromises = Object.keys(injectedResources).map((path) =>
99
- injectedResources[path]().then((resourceModule) => {
100
- resourceModules.set(path, resourceModule);
101
- })
87
+ export async function loadResources() {
88
+ const { resourceModules, skippedResources } = await loadResourceModules(
89
+ injectedResources
102
90
  );
103
-
104
- return [resourcePromises, resourceModules] as const;
91
+ reportResourceLoadIssues(skippedResources);
92
+ return resourceModules;
105
93
  }
106
94
 
107
95
  export async function createServer() {
108
- const server = new McpServer(INJECTED_CONFIG);
109
- const [toolPromises, toolModules] = loadTools();
110
- const [promptPromises, promptModules] = loadPrompts();
111
- const [resourcePromises, resourceModules] = loadResources();
112
- await Promise.all(toolPromises);
113
- await Promise.all(promptPromises);
114
- await Promise.all(resourcePromises);
96
+ const { instructions, ...serverInfo } = INJECTED_CONFIG;
97
+ const server = new McpServer(serverInfo, { instructions });
98
+ const toolModulesPromise = loadTools();
99
+ const promptModulesPromise = loadPrompts();
100
+ const resourceModulesPromise = loadResources();
101
+ const [toolModules, promptModules, resourceModules] = await Promise.all([
102
+ toolModulesPromise,
103
+ promptModulesPromise,
104
+ resourceModulesPromise,
105
+ ]);
115
106
  return configureServer(server, toolModules, promptModules, resourceModules);
116
107
  }
@@ -0,0 +1,149 @@
1
+ import type { ToolFile } from "./server";
2
+
3
+ const EMPTY_TOOL_FILE_MESSAGE = "File is empty.";
4
+ const MISSING_DEFAULT_EXPORT_MESSAGE =
5
+ "File does not export a default tool handler.";
6
+ const INVALID_DEFAULT_EXPORT_MESSAGE =
7
+ "Default export must be a tool handler function.";
8
+
9
+ type ToolLoadIssue = {
10
+ path: string;
11
+ message: string;
12
+ };
13
+
14
+ function createToolLoadIssue(path: string): ToolLoadIssue {
15
+ return {
16
+ path,
17
+ message: EMPTY_TOOL_FILE_MESSAGE,
18
+ };
19
+ }
20
+
21
+ function createInvalidToolImplementationError(path: string): Error {
22
+ return new Error(
23
+ `[xmcp] Invalid tool file: ${path}\n -> ${INVALID_DEFAULT_EXPORT_MESSAGE}`
24
+ );
25
+ }
26
+
27
+ function classifyToolModule(
28
+ toolModule: unknown,
29
+ path: string
30
+ ): "empty" | "missing-default" | "valid" {
31
+ if (typeof toolModule !== "object" || toolModule === null) {
32
+ throw createInvalidToolImplementationError(path);
33
+ }
34
+
35
+ const moduleRecord = toolModule as Record<string, unknown>;
36
+ const keys = Object.keys(moduleRecord);
37
+ const defaultExport = moduleRecord.default;
38
+ const nonInteropKeys = keys.filter((key) => key !== "__esModule");
39
+
40
+ if (
41
+ keys.length === 0 ||
42
+ (nonInteropKeys.length === 1 &&
43
+ nonInteropKeys[0] === "default" &&
44
+ typeof defaultExport === "object" &&
45
+ defaultExport !== null &&
46
+ Object.keys(defaultExport as Record<string, unknown>).length === 0)
47
+ ) {
48
+ return "empty";
49
+ }
50
+
51
+ if (!("default" in moduleRecord) || moduleRecord.default === undefined) {
52
+ return "missing-default";
53
+ }
54
+
55
+ if (typeof moduleRecord.default !== "function") {
56
+ throw createInvalidToolImplementationError(path);
57
+ }
58
+
59
+ return "valid";
60
+ }
61
+
62
+ function toToolFile(toolModule: unknown): ToolFile {
63
+ return toolModule as ToolFile;
64
+ }
65
+
66
+ export async function loadToolModules(
67
+ loaders: Record<string, () => Promise<unknown>>
68
+ ) {
69
+ const toolModules = new Map<string, ToolFile>();
70
+ const skippedTools: ToolLoadIssue[] = [];
71
+
72
+ const results = await Promise.all(
73
+ Object.entries(loaders).map(async ([path, loadTool]) => {
74
+ const toolModule = await loadTool();
75
+ const classification = classifyToolModule(toolModule, path);
76
+
77
+ if (classification === "empty") {
78
+ return {
79
+ skipped: true as const,
80
+ issue: createToolLoadIssue(path),
81
+ };
82
+ }
83
+
84
+ if (classification === "missing-default") {
85
+ return {
86
+ skipped: true as const,
87
+ issue: {
88
+ path,
89
+ message: MISSING_DEFAULT_EXPORT_MESSAGE,
90
+ },
91
+ };
92
+ }
93
+
94
+ return {
95
+ skipped: false as const,
96
+ path,
97
+ toolModule: toToolFile(toolModule),
98
+ };
99
+ })
100
+ );
101
+
102
+ for (const result of results) {
103
+ if (result.skipped) {
104
+ skippedTools.push(result.issue);
105
+ continue;
106
+ }
107
+
108
+ toolModules.set(result.path, result.toolModule);
109
+ }
110
+
111
+ return {
112
+ toolModules,
113
+ skippedTools,
114
+ };
115
+ }
116
+
117
+ function createToolLoadIssueReporter(
118
+ logger: Pick<Console, "warn"> = console
119
+ ) {
120
+ let lastReportedSummaryKey = "";
121
+
122
+ return (skippedTools: ToolLoadIssue[]) => {
123
+ const summaryKey = skippedTools
124
+ .map(({ path, message }) => `${path}:${message}`)
125
+ .sort()
126
+ .join("|");
127
+
128
+ if (summaryKey === lastReportedSummaryKey) {
129
+ return;
130
+ }
131
+
132
+ lastReportedSummaryKey = summaryKey;
133
+
134
+ if (skippedTools.length === 0) {
135
+ return;
136
+ }
137
+
138
+ skippedTools.forEach(({ path, message }) => {
139
+ logger.warn(`[xmcp] Failed to load tool file: ${path}\n -> ${message}`);
140
+ });
141
+
142
+ const count = skippedTools.length;
143
+ logger.warn(
144
+ `[xmcp] ${count} tool${count === 1 ? "" : "s"} skipped due to empty files or missing default exports`
145
+ );
146
+ };
147
+ }
148
+
149
+ export const reportToolLoadIssues = createToolLoadIssueReporter();
@@ -30,6 +30,14 @@ export function pathToName(path: string): string {
30
30
  return fileName.replace(/\.[^/.]+$/, "");
31
31
  }
32
32
 
33
+ /** Ensures toolConfig has its own annotations object with a title */
34
+ export function ensureAnnotations(toolConfig: Pick<ToolMetadata, "name" | "annotations">): void {
35
+ toolConfig.annotations = { ...(toolConfig.annotations ?? {}) };
36
+ if (toolConfig.annotations.title === undefined) {
37
+ toolConfig.annotations.title = toolConfig.name;
38
+ }
39
+ }
40
+
33
41
  /** Loads tools and injects them into the server */
34
42
  export function addToolsToServer(
35
43
  server: McpServer,
@@ -79,12 +87,7 @@ export function addToolsToServer(
79
87
  }
80
88
 
81
89
  // Make sure tools has annotations with a title
82
- if (toolConfig.annotations === undefined) {
83
- toolConfig.annotations = {};
84
- }
85
- if (toolConfig.annotations.title === undefined) {
86
- toolConfig.annotations.title = toolConfig.name;
87
- }
90
+ ensureAnnotations(toolConfig);
88
91
 
89
92
  if (toolConfig._meta === undefined) {
90
93
  toolConfig._meta = {};