@dxos/mcp-client 0.10.0 → 0.11.1

package/dist/lib/index.mjs

@@ -0,0 +1,172 @@
+import * as Tool from "@effect/ai/Tool";
+import * as Toolkit from "@effect/ai/Toolkit";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { OpaqueToolkit } from "@dxos/ai";
+import { invariant } from "@dxos/invariant";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region src/McpToolkit.ts
+var McpToolkit_exports = /* @__PURE__ */ __exportAll({
+	McpConnectionError: () => McpConnectionError,
+	is405: () => is405,
+	make: () => make
+});
+var __dxlog_file = "/__w/dxos/dxos/packages/core/compute/mcp-client/src/McpToolkit.ts";
+/**
+* Typed failure raised when the MCP client cannot connect or list tools.
+* Carries the underlying cause and the server URL for diagnostics.
+*/
+var McpConnectionError = class extends Schema.TaggedError("McpConnectionError")("McpConnectionError", {
+	url: Schema.String,
+	protocol: Schema.Literal("sse", "http"),
+	message: Schema.String
+}) {};
+/**
+* Creates an OpaqueToolkit that connects to an MCP server and exposes its tools to the assistant.
+*
+* @param options MCP server URL and transport protocol ('http' for Streamable HTTP, 'sse' for SSE).
+* @returns An OpaqueToolkit containing all tools from the MCP server.
+*/
+var CLIENT_INFO = {
+	name: "@dxos/mcp-client",
+	version: "0.8.3"
+};
+var make = (options) => Effect.gen(function* () {
+	const { client, protocol } = yield* connectWithFallback(options);
+	const { tools } = yield* Effect.tryPromise({
+		try: () => client.listTools(),
+		catch: (cause) => new McpConnectionError({
+			url: options.url,
+			protocol,
+			message: `Failed to list MCP tools: ${formatCause(cause)}`
+		})
+	});
+	if (tools.length === 0) return OpaqueToolkit.empty;
+	const effectTools = tools.map((mcpTool) => {
+		const parameters = {};
+		for (const [key, value] of Object.entries(mcpTool.inputSchema.properties ?? {})) if (mcpTool.inputSchema.required?.includes(key)) parameters[key] = Schema.Unknown.pipe(Schema.annotations({ jsonSchema: value }));
+		else parameters[key] = Schema.Unknown.pipe(Schema.annotations({ jsonSchema: value })).pipe(Schema.optional);
+		return Tool.make(sanitizeToolName(mcpTool.name), {
+			description: mcpTool.description ?? `MCP tool: ${mcpTool.name}`,
+			parameters,
+			success: Schema.String,
+			failure: Schema.Never
+		});
+	});
+	const toolkit = Toolkit.make(...effectTools);
+	const handlers = Object.fromEntries(tools.map((mcpTool) => {
+		return [sanitizeToolName(mcpTool.name), Effect.fn(function* (args) {
+			return formatToolResult(yield* Effect.promise(() => client.callTool({
+				name: mcpTool.name,
+				arguments: args
+			})));
+		})];
+	}));
+	const layer = toolkit.toLayer(handlers);
+	return OpaqueToolkit.make(toolkit, layer);
+}).pipe(Effect.withSpan("McpToolkit.make"));
+/**
+* Returns true when the error (or its wrapped cause) contains a 405 status code.
+* `Effect.tryPromise` wraps thrown errors in `UnknownException`, so we unwrap first.
+*/
+var is405 = (error) => {
+	const cause = error != null && typeof error === "object" && "error" in error ? error.error : error;
+	return cause instanceof Error && cause.message.includes("405");
+};
+/**
+* Connects to an MCP server, falling back to the alternate transport on 405 errors.
+* Per the MCP spec, a 405 indicates the server uses the other transport protocol.
+* Returns the connected Client (a fresh instance is created for the fallback attempt).
+*
+* Failures are surfaced as typed `McpConnectionError` so callers can recover (e.g. drop
+* the misconfigured server) without breaking the surrounding effect.
+*/
+var connectWithFallback = (options) => Effect.gen(function* () {
+	const fallbackProtocol = options.protocol === "sse" ? "http" : "sse";
+	const primary = yield* connectClient(options.url, options.protocol, options.apiKey).pipe(Effect.either);
+	if (primary._tag === "Right") return {
+		client: primary.right,
+		protocol: options.protocol
+	};
+	if (is405(primary.left)) {
+		const fallback = yield* connectClient(options.url, fallbackProtocol, options.apiKey).pipe(Effect.either);
+		if (fallback._tag === "Right") return {
+			client: fallback.right,
+			protocol: fallbackProtocol
+		};
+		return yield* Effect.fail(new McpConnectionError({
+			url: options.url,
+			protocol: fallbackProtocol,
+			message: `Failed to connect via ${fallbackProtocol} after 405 fallback: ${formatCause(fallback.left)}`
+		}));
+	}
+	return yield* Effect.fail(new McpConnectionError({
+		url: options.url,
+		protocol: options.protocol,
+		message: `Failed to connect via ${options.protocol}: ${formatCause(primary.left)}`
+	}));
+});
+var connectClient = (url, protocol, apiKey) => Effect.tryPromise(() => {
+	const client = new Client(CLIENT_INFO);
+	const transport = createTransport(url, protocol, apiKey);
+	return client.connect(transport).then(() => client);
+});
+/**
+* Renders a thrown value to a short string for inclusion in error messages.
+* `Effect.tryPromise` wraps thrown errors in `UnknownException`; unwrap when present.
+*/
+var formatCause = (error) => {
+	const inner = error != null && typeof error === "object" && "error" in error ? error.error : error;
+	if (inner instanceof Error) return inner.message;
+	if (Cause.isCause(error)) return Cause.pretty(error);
+	return String(inner);
+};
+/**
+* Creates a transport for the given MCP server URL and protocol.
+*/
+var createTransport = (url, protocol, apiKey) => {
+	const urlObj = new URL(url);
+	const requestInit = apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : void 0;
+	switch (protocol) {
+		case "sse": return new SSEClientTransport(urlObj, { requestInit });
+		case "http": return new StreamableHTTPClientTransport(urlObj, { requestInit });
+		default: return invariant(false, `Unsupported MCP transport protocol: ${protocol}`, {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 198,
+			S: void 0,
+			A: ["false", "`Unsupported MCP transport protocol: ${_exhaustive}`"]
+		});
+	}
+};
+/**
+* Sanitizes MCP tool names for use as Effect tool names (replaces / with _).
+*/
+var sanitizeToolName = (name) => name.replace(/\//g, "_");
+/**
+* Formats MCP callTool result content for the assistant.
+*/
+var formatToolResult = (result) => {
+	if ("toolResult" in result && result.toolResult !== void 0) return JSON.stringify(result.toolResult);
+	if ("content" in result && Array.isArray(result.content)) return result.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+	return String(result);
+};
+//#endregion
+export { McpToolkit_exports as McpToolkit };
+
+//# sourceMappingURL=index.mjs.map

package/dist/lib/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/McpToolkit.ts"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\n// @import-as-namespace\n\nimport * as Tool from '@effect/ai/Tool';\nimport * as Toolkit from '@effect/ai/Toolkit';\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\n// SSEClientTransport is marked @deprecated in the SDK in favor of StreamableHTTP, but the\n// SDK itself notes that clients should keep supporting both while servers migrate.\n// `connectWithFallback` below tries the configured protocol first, then the other on 405.\n// eslint-disable-next-line @typescript-eslint/no-deprecated\nimport { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';\nimport * as Cause from 'effect/Cause';\nimport * as Effect from 'effect/Effect';\nimport * as Schema from 'effect/Schema';\n\nimport { OpaqueToolkit } from '@dxos/ai';\nimport { invariant } from '@dxos/invariant';\n\n/**\n * Typed failure raised when the MCP client cannot connect or list tools.\n * Carries the underlying cause and the server URL for diagnostics.\n */\nexport class McpConnectionError extends Schema.TaggedError<McpConnectionError>('McpConnectionError')(\n  'McpConnectionError',\n  {\n    url: Schema.String,\n    protocol: Schema.Literal('sse', 'http'),\n    message: Schema.String,\n  },\n) {}\n\n/**\n * Creates an OpaqueToolkit that connects to an MCP server and exposes its tools to the assistant.\n *\n * @param options MCP server URL and transport protocol ('http' for Streamable HTTP, 'sse' for SSE).\n * @returns An OpaqueToolkit containing all tools from the MCP server.\n */\nconst CLIENT_INFO = { name: '@dxos/mcp-client', version: '0.8.3' };\n\nexport interface McpToolkitOptions {\n  url: string;\n  protocol: 'sse' | 'http';\n  apiKey?: string;\n}\n\nexport const make = (options: McpToolkitOptions): Effect.Effect<OpaqueToolkit.OpaqueToolkit, McpConnectionError> =>\n  Effect.gen(function* () {\n    const { client, protocol } = yield* connectWithFallback(options);\n\n    const { tools } = yield* Effect.tryPromise({\n      try: () => client.listTools(),\n      catch: (cause) =>\n        new McpConnectionError({\n          url: options.url,\n          protocol,\n          message: `Failed to list MCP tools: ${formatCause(cause)}`,\n        }),\n    });\n    if (tools.length === 0) {\n      return OpaqueToolkit.empty;\n    }\n\n    const effectTools = tools.map((mcpTool) => {\n      const parameters: any = {};\n      for (const [key, value] of Object.entries(mcpTool.inputSchema.properties ?? {})) {\n        if (mcpTool.inputSchema.required?.includes(key)) {\n          parameters[key] = Schema.Unknown.pipe(Schema.annotations({ jsonSchema: value }));\n        } else {\n          parameters[key] = Schema.Unknown.pipe(Schema.annotations({ jsonSchema: value })).pipe(Schema.optional);\n        }\n      }\n\n      return Tool.make(sanitizeToolName(mcpTool.name), {\n        description: mcpTool.description ?? `MCP tool: ${mcpTool.name}`,\n        parameters,\n        success: Schema.String,\n        failure: Schema.Never,\n      });\n    });\n\n    const toolkit = Toolkit.make(...effectTools);\n\n    const handlers = Object.fromEntries(\n      tools.map((mcpTool) => {\n        const toolName = sanitizeToolName(mcpTool.name);\n        return [\n          toolName,\n          Effect.fn(function* (args: unknown) {\n            const result = yield* Effect.promise(() =>\n              client.callTool({\n                name: mcpTool.name,\n                arguments: args as any,\n              }),\n            );\n            return formatToolResult(result);\n          }),\n        ];\n      }),\n    ) as any;\n\n    const layer = toolkit.toLayer(handlers);\n\n    return OpaqueToolkit.make(toolkit, layer);\n  }).pipe(Effect.withSpan('McpToolkit.make'));\n\n/**\n * Returns true when the error (or its wrapped cause) contains a 405 status code.\n * `Effect.tryPromise` wraps thrown errors in `UnknownException`, so we unwrap first.\n */\nexport const is405 = (error: unknown): boolean => {\n  const cause = error != null && typeof error === 'object' && 'error' in error ? (error as any).error : error;\n  return cause instanceof Error && cause.message.includes('405');\n};\n\n/**\n * Connects to an MCP server, falling back to the alternate transport on 405 errors.\n * Per the MCP spec, a 405 indicates the server uses the other transport protocol.\n * Returns the connected Client (a fresh instance is created for the fallback attempt).\n *\n * Failures are surfaced as typed `McpConnectionError` so callers can recover (e.g. drop\n * the misconfigured server) without breaking the surrounding effect.\n */\nconst connectWithFallback = (\n  options: McpToolkitOptions,\n): Effect.Effect<{ client: Client; protocol: McpToolkitOptions['protocol'] }, McpConnectionError> =>\n  Effect.gen(function* () {\n    const fallbackProtocol = options.protocol === 'sse' ? 'http' : 'sse';\n    const primary = yield* connectClient(options.url, options.protocol, options.apiKey).pipe(Effect.either);\n    if (primary._tag === 'Right') {\n      return { client: primary.right, protocol: options.protocol };\n    }\n    if (is405(primary.left)) {\n      const fallback = yield* connectClient(options.url, fallbackProtocol, options.apiKey).pipe(Effect.either);\n      if (fallback._tag === 'Right') {\n        return { client: fallback.right, protocol: fallbackProtocol };\n      }\n      return yield* Effect.fail(\n        new McpConnectionError({\n          url: options.url,\n          protocol: fallbackProtocol,\n          message: `Failed to connect via ${fallbackProtocol} after 405 fallback: ${formatCause(fallback.left)}`,\n        }),\n      );\n    }\n    return yield* Effect.fail(\n      new McpConnectionError({\n        url: options.url,\n        protocol: options.protocol,\n        message: `Failed to connect via ${options.protocol}: ${formatCause(primary.left)}`,\n      }),\n    );\n  });\n\nconst connectClient = (url: string, protocol: McpToolkitOptions['protocol'], apiKey?: string) =>\n  Effect.tryPromise(() => {\n    const client = new Client(CLIENT_INFO);\n    const transport = createTransport(url, protocol, apiKey);\n    return client.connect(transport).then(() => client);\n  });\n\n/**\n * Renders a thrown value to a short string for inclusion in error messages.\n * `Effect.tryPromise` wraps thrown errors in `UnknownException`; unwrap when present.\n */\nconst formatCause = (error: unknown): string => {\n  const inner = error != null && typeof error === 'object' && 'error' in error ? (error as any).error : error;\n  if (inner instanceof Error) {\n    return inner.message;\n  }\n  if (Cause.isCause(error)) {\n    return Cause.pretty(error);\n  }\n\n  return String(inner);\n};\n\n/**\n * Creates a transport for the given MCP server URL and protocol.\n */\nconst createTransport = (\n  url: string,\n  protocol: McpToolkitOptions['protocol'],\n  apiKey?: string,\n): SSEClientTransport | StreamableHTTPClientTransport => {\n  const urlObj = new URL(url);\n  const requestInit: RequestInit | undefined = apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : undefined;\n  switch (protocol) {\n    case 'sse':\n      return new SSEClientTransport(urlObj, { requestInit });\n    case 'http':\n      return new StreamableHTTPClientTransport(urlObj, { requestInit });\n    default: {\n      const _exhaustive: never = protocol;\n      return invariant(false, `Unsupported MCP transport protocol: ${_exhaustive}`) as never;\n    }\n  }\n};\n\n/**\n * Sanitizes MCP tool names for use as Effect tool names (replaces / with _).\n */\nconst sanitizeToolName = (name: string): string => name.replace(/\\//g, '_');\n\n/**\n * Formats MCP callTool result content for the assistant.\n */\nconst formatToolResult = (result: Awaited<ReturnType<Client['callTool']>>): string => {\n  if ('toolResult' in result && result.toolResult !== undefined) {\n    return JSON.stringify(result.toolResult);\n  }\n  if ('content' in result && Array.isArray(result.content)) {\n    return result.content\n      .filter((part): part is { type: 'text'; text: string } => part.type === 'text')\n      .map((part) => part.text)\n      .join('\\n');\n  }\n\n  return String(result);\n};\n"],"mappings":"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"}