@dxos/mcp-client 0.8.4-main.fcfe5033a5 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/mcp-client",
-  "version": "0.8.4-main.fcfe5033a5",
+  "version": "0.9.0",
   "description": "MCP client.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "info@dxos.org",
   "type": "module",
   "exports": {
@@ -23,13 +23,13 @@
     "src"
   ],
   "dependencies": {
-    "@effect/ai": "0.33.2",
+    "@effect/ai": "0.36.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "effect": "3.20.0",
-    "@dxos/ai": "0.8.4-main.fcfe5033a5",
-    "@dxos/effect": "0.8.4-main.fcfe5033a5",
-    "@dxos/log": "0.8.4-main.fcfe5033a5",
-    "@dxos/invariant": "0.8.4-main.fcfe5033a5"
+    "effect": "3.21.3",
+    "@dxos/effect": "0.9.0",
+    "@dxos/invariant": "0.9.0",
+    "@dxos/ai": "0.9.0",
+    "@dxos/log": "0.9.0"
   },
   "publishConfig": {
     "access": "public"

package/src/McpToolkit.test.ts

@@ -12,13 +12,13 @@ import * as Schema from 'effect/Schema';
 
 import { AiService, type OpaqueToolkit } from '@dxos/ai';
 import { TestAiService } from '@dxos/ai/testing';
-import { runAndForwardErrors } from '@dxos/effect';
+import { EffectEx } from '@dxos/effect';
 import { TestHelpers } from '@dxos/effect/testing';
 import { log } from '@dxos/log';
 
 import * as McpToolkit from './McpToolkit';
 
-const AiServiceLayer = AiService.model('@anthropic/claude-opus-4-6', { thinking: false }).pipe(
+const AiServiceLayer = AiService.model('ai.claude.model.claude-opus-4-6', { thinking: false }).pipe(
   Layer.provide(
     TestAiService({
       disableMemoization: true,
@@ -34,10 +34,10 @@ describe('connectWithFallback', () => {
       timeout: 30_000,
     },
     async () => {
-      const toolkit = await runAndForwardErrors(
+      const toolkit = await EffectEx.runAndForwardErrors(
         McpToolkit.make({
           url: 'https://mcp.linear.app/mcp',
-          kind: 'sse',
+          protocol: 'sse',
           apiKey: process.env.LINEAR_API_KEY,
         }),
       );
@@ -53,7 +53,7 @@ describe('Browser Automation', () => {
       function* (_) {
         const browserAutomationToolkit = yield* McpToolkit.make({
           url: 'https://playwright-mcp-example.dxos.workers.dev/sse',
-          kind: 'sse',
+          protocol: 'sse',
         });
 
         const chat = yield* Chat.empty;
@@ -78,10 +78,10 @@ describe('Browser Automation', () => {
       },
       Effect.provide(AiServiceLayer),
       TestHelpers.provideTestContext,
-      TestHelpers.taggedTest('llm'),
     ),
     {
       timeout: 120_000,
+      tags: ['llm'],
     },
   );
 
@@ -91,7 +91,7 @@ describe('Browser Automation', () => {
       function* (_) {
         const browserAutomationToolkit = yield* McpToolkit.make({
           url: 'https://playwright-mcp-example.dxos.workers.dev/sse',
-          kind: 'sse',
+          protocol: 'sse',
         });
 
         const chat = yield* Chat.empty;
@@ -139,10 +139,10 @@ describe('Browser Automation', () => {
       },
       Effect.provide(AiServiceLayer),
       TestHelpers.provideTestContext,
-      TestHelpers.taggedTest('llm'),
     ),
     {
       timeout: 120_000,
+      tags: ['llm'],
     },
   );
 });

package/src/McpToolkit.ts

@@ -7,33 +7,59 @@
 import * as Tool from '@effect/ai/Tool';
 import * as Toolkit from '@effect/ai/Toolkit';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+// SSEClientTransport is marked @deprecated in the SDK in favor of StreamableHTTP, but the
+// SDK itself notes that clients should keep supporting both while servers migrate.
+// `connectWithFallback` below tries the configured protocol first, then the other on 405.
+// eslint-disable-next-line @typescript-eslint/no-deprecated
 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';
 
-export interface McpToolkitOptions {
-  url: string;
-  kind: 'sse' | 'http';
-  apiKey?: string;
-}
+/**
+ * Typed failure raised when the MCP client cannot connect or list tools.
+ * Carries the underlying cause and the server URL for diagnostics.
+ */
+export class McpConnectionError extends Schema.TaggedError<McpConnectionError>('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 kind ('sse' for SSE, 'http' for Streamable HTTP).
+ * @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.
  */
 const CLIENT_INFO = { name: '@dxos/mcp-client', version: '0.8.3' };
 
-export const make = (options: McpToolkitOptions): Effect.Effect<OpaqueToolkit.OpaqueToolkit> =>
-  Effect.gen(function* () {
-    const client = yield* connectWithFallback(options);
+export interface McpToolkitOptions {
+  url: string;
+  protocol: 'sse' | 'http';
+  apiKey?: string;
+}
 
-    const { tools } = yield* Effect.promise(() => client.listTools());
+export const make = (options: McpToolkitOptions): Effect.Effect<OpaqueToolkit.OpaqueToolkit, McpConnectionError> =>
+  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;
     }
@@ -94,45 +120,82 @@ export const is405 = (error: unknown): boolean => {
  * 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.
  */
-const connectWithFallback = (options: McpToolkitOptions): Effect.Effect<Client> =>
+const connectWithFallback = (
+  options: McpToolkitOptions,
+): Effect.Effect<{ client: Client; protocol: McpToolkitOptions['protocol'] }, McpConnectionError> =>
   Effect.gen(function* () {
-    const fallbackKind = options.kind === 'sse' ? 'http' : 'sse';
-    const primary = yield* connectClient(options.url, options.kind, options.apiKey).pipe(Effect.either);
+    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 primary.right;
+      return { client: primary.right, protocol: options.protocol };
     }
     if (is405(primary.left)) {
-      return yield* connectClient(options.url, fallbackKind, options.apiKey).pipe(Effect.orDie);
+      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.die(primary.left);
+    return yield* Effect.fail(
+      new McpConnectionError({
+        url: options.url,
+        protocol: options.protocol,
+        message: `Failed to connect via ${options.protocol}: ${formatCause(primary.left)}`,
+      }),
+    );
   });
 
-const connectClient = (url: string, kind: McpToolkitOptions['kind'], apiKey?: string) =>
+const connectClient = (url: string, protocol: McpToolkitOptions['protocol'], apiKey?: string) =>
   Effect.tryPromise(() => {
     const client = new Client(CLIENT_INFO);
-    const transport = createTransport(url, kind, apiKey);
+    const transport = createTransport(url, protocol, apiKey);
     return client.connect(transport).then(() => client);
   });
 
 /**
- * Creates a transport for the given MCP server URL and kind.
+ * Renders a thrown value to a short string for inclusion in error messages.
+ * `Effect.tryPromise` wraps thrown errors in `UnknownException`; unwrap when present.
+ */
+const formatCause = (error: unknown): string => {
+  const inner = error != null && typeof error === 'object' && 'error' in error ? (error as any).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.
  */
 const createTransport = (
   url: string,
-  kind: McpToolkitOptions['kind'],
+  protocol: McpToolkitOptions['protocol'],
   apiKey?: string,
 ): SSEClientTransport | StreamableHTTPClientTransport => {
   const urlObj = new URL(url);
   const requestInit: RequestInit | undefined = apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : undefined;
-  switch (kind) {
+  switch (protocol) {
     case 'sse':
       return new SSEClientTransport(urlObj, { requestInit });
     case 'http':
       return new StreamableHTTPClientTransport(urlObj, { requestInit });
     default: {
-      const _exhaustive: never = kind;
-      return invariant(false, `Unsupported MCP transport kind: ${_exhaustive}`) as never;
+      const _exhaustive: never = protocol;
+      return invariant(false, `Unsupported MCP transport protocol: ${_exhaustive}`) as never;
     }
   }
 };