@dxos/mcp-client 0.8.3 → 0.8.4-main.03d5cd7b56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/mcp-client",
-  "version": "0.8.3",
+  "version": "0.8.4-main.03d5cd7b56",
   "description": "MCP client.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -25,11 +25,11 @@
   "dependencies": {
     "@effect/ai": "0.33.2",
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "effect": "3.19.16",
-    "@dxos/ai": "0.8.3",
-    "@dxos/effect": "0.8.3",
-    "@dxos/invariant": "0.8.3",
-    "@dxos/log": "0.8.3"
+    "effect": "3.20.0",
+    "@dxos/invariant": "0.8.4-main.03d5cd7b56",
+    "@dxos/effect": "0.8.4-main.03d5cd7b56",
+    "@dxos/log": "0.8.4-main.03d5cd7b56",
+    "@dxos/ai": "0.8.4-main.03d5cd7b56"
   },
   "publishConfig": {
     "access": "public"

package/src/McpToolkit.test.ts

@@ -10,8 +10,9 @@ import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as Schema from 'effect/Schema';
 
-import { AiService, type GenericToolkit } from '@dxos/ai';
+import { AiService, type OpaqueToolkit } from '@dxos/ai';
 import { TestAiService } from '@dxos/ai/testing';
+import { runAndForwardErrors } from '@dxos/effect';
 import { TestHelpers } from '@dxos/effect/testing';
 import { log } from '@dxos/log';
 
@@ -25,6 +26,26 @@ const AiServiceLayer = AiService.model('@anthropic/claude-opus-4-6', { thinking:
   ),
 );
 
+describe('connectWithFallback', () => {
+  it(
+    'connects to Linear MCP (SSE kind falls back to HTTP)',
+    {
+      skip: !process.env.LINEAR_API_KEY,
+      timeout: 30_000,
+    },
+    async () => {
+      const toolkit = await runAndForwardErrors(
+        McpToolkit.make({
+          url: 'https://mcp.linear.app/mcp',
+          protocol: 'sse',
+          apiKey: process.env.LINEAR_API_KEY,
+        }),
+      );
+      log.info('connected', { tools: Object.keys(toolkit.toolkit.tools) });
+    },
+  );
+});
+
 describe('Browser Automation', () => {
   it.effect(
     'smoke',
@@ -32,12 +53,12 @@ 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;
         let prompt: Prompt.RawInput = 'Check that you are able to use the browser. Open https://example.com';
-        let output: LanguageModel.GenerateTextResponse<GenericToolkit.GenericTools>;
+        let output: LanguageModel.GenerateTextResponse<OpaqueToolkit.OpaqueTools>;
 
         do {
           output = yield* chat
@@ -57,9 +78,11 @@ describe('Browser Automation', () => {
       },
       Effect.provide(AiServiceLayer),
       TestHelpers.provideTestContext,
-      TestHelpers.taggedTest('llm'),
     ),
-    { timeout: 120_000 },
+    {
+      timeout: 120_000,
+      tags: ['llm'],
+    },
   );
 
   it.effect(
@@ -68,13 +91,13 @@ 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;
         let prompt: Prompt.RawInput =
           'Scrape effect blog at https://effect.website/blog and find the content of last 3 articles. Next prompt I will ask you generate structured representation.';
-        let output: LanguageModel.GenerateTextResponse<GenericToolkit.GenericTools>;
+        let output: LanguageModel.GenerateTextResponse<OpaqueToolkit.OpaqueTools>;
 
         do {
           output = yield* chat
@@ -116,8 +139,10 @@ describe('Browser Automation', () => {
       },
       Effect.provide(AiServiceLayer),
       TestHelpers.provideTestContext,
-      TestHelpers.taggedTest('llm'),
     ),
-    { timeout: 120_000 },
+    {
+      timeout: 120_000,
+      tags: ['llm'],
+    },
   );
 });

package/src/McpToolkit.ts

@@ -2,55 +2,75 @@
 // Copyright 2026 DXOS.org
 //
 
+// @import-as-namespace
+
 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 { GenericToolkit } from '@dxos/ai';
+import { OpaqueToolkit } from '@dxos/ai';
 import { invariant } from '@dxos/invariant';
 
-export interface McpToolkitOptions {
-  url: string;
-  kind: 'sse' | 'http';
-}
+/**
+ * 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 a GenericToolkit that connects to an MCP server and exposes its tools to the assistant.
+ * 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).
- * @returns A GenericToolkit containing all tools from the MCP server.
+ * @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.
  */
-export const make = (options: McpToolkitOptions): Effect.Effect<GenericToolkit.GenericToolkit> =>
-  Effect.gen(function* () {
-    const transport = createTransport(options.url, options.kind);
-    const client = new Client({ name: '@dxos/mcp-client', version: '0.8.3' });
-    yield* Effect.promise(() => client.connect(transport));
+const CLIENT_INFO = { name: '@dxos/mcp-client', version: '0.8.3' };
+
+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 GenericToolkit.empty;
+      return OpaqueToolkit.empty;
     }
 
     const effectTools = tools.map((mcpTool) => {
       const parameters: any = {};
       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,
-            }),
-          );
+          parameters[key] = Schema.Unknown.pipe(Schema.annotations({ jsonSchema: value }));
         } else {
-          parameters[key] = Schema.Unknown.pipe(
-            Schema.annotations({
-              jsonSchema: value,
-            }),
-          ).pipe(Schema.optional);
+          parameters[key] = Schema.Unknown.pipe(Schema.annotations({ jsonSchema: value })).pipe(Schema.optional);
         }
       }
 
@@ -84,25 +104,98 @@ export const make = (options: McpToolkitOptions): Effect.Effect<GenericToolkit.G
 
     const layer = toolkit.toLayer(handlers);
 
-    return GenericToolkit.make(toolkit, layer);
+    return OpaqueToolkit.make(toolkit, layer);
   }).pipe(Effect.withSpan('McpToolkit.make'));
 
 /**
- * Creates a transport for the given MCP server URL and kind.
+ * 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.
+ */
+export const is405 = (error: unknown): boolean => {
+  const cause = error != null && typeof error === 'object' && 'error' in error ? (error as any).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.
+ */
+const connectWithFallback = (
+  options: McpToolkitOptions,
+): Effect.Effect<{ client: Client; protocol: McpToolkitOptions['protocol'] }, McpConnectionError> =>
+  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)}`,
+      }),
+    );
+  });
+
+const connectClient = (url: string, protocol: McpToolkitOptions['protocol'], apiKey?: string) =>
+  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.
+ */
+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);
-  switch (kind) {
+  const requestInit: RequestInit | undefined = apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : undefined;
+  switch (protocol) {
     case 'sse':
-      return new SSEClientTransport(urlObj);
+      return new SSEClientTransport(urlObj, { requestInit });
     case 'http':
-      return new StreamableHTTPClientTransport(urlObj);
+      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;
     }
   }
 };
@@ -125,5 +218,6 @@ const formatToolResult = (result: Awaited<ReturnType<Client['callTool']>>): stri
       .map((part) => part.text)
       .join('\n');
   }
+
   return String(result);
 };

package/src/is405.test.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Cause from 'effect/Cause';
+import { describe, test } from 'vitest';
+
+import * as McpToolkit from './McpToolkit';
+
+describe('is405', () => {
+  test('matches raw Error with 405 in message', ({ expect }) => {
+    expect(McpToolkit.is405(new Error('SSE error: Non-200 status code (405)'))).toBe(true);
+  });
+
+  test('matches UnknownException wrapping a 405 Error', ({ expect }) => {
+    const wrapped = new Cause.UnknownException(new Error('SSE error: Non-200 status code (405)'));
+    expect(McpToolkit.is405(wrapped)).toBe(true);
+  });
+
+  test('does not match unrelated errors', ({ expect }) => {
+    expect(McpToolkit.is405(new Error('connection refused'))).toBe(false);
+  });
+
+  test('does not match UnknownException wrapping a non-405 Error', ({ expect }) => {
+    const wrapped = new Cause.UnknownException(new Error('connection refused'));
+    expect(McpToolkit.is405(wrapped)).toBe(false);
+  });
+
+  test('does not match null or undefined', ({ expect }) => {
+    expect(McpToolkit.is405(null)).toBe(false);
+    expect(McpToolkit.is405(undefined)).toBe(false);
+  });
+});