@mcp-b/transports 4.1.0-beta.20260702224704 → 5.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 mcp-b
+Copyright (c) 2025 mcp-b contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -20,7 +20,7 @@
 | **Secure by Default**        | Origin validation, CORS configuration, and Chrome's secure messaging APIs    |
 | **AI-Agent Ready**           | Built specifically for MCP, the standard protocol for AI tool integration    |
 | **TypeScript First**         | Full type safety with comprehensive type definitions                         |
-| **Zero Dependencies**        | Only requires `zod` for schema validation                                    |
+| **MCP SDK v2**               | Uses the split MCP server and core packages                                  |
 | **Works Everywhere**         | Chrome, Firefox, Edge, and any Chromium-based browser                        |
 
 ## Use Cases
@@ -34,7 +34,7 @@
 ## Installation
 
 ```bash
-npm install @mcp-b/transports
+npm install @mcp-b/transports @modelcontextprotocol/client @modelcontextprotocol/server zod
 ```
 
 ## Transport Types
@@ -49,7 +49,8 @@ Use `ExtensionClientTransport` and `ExtensionServerTransport` for communication
 
 ### Extension External Transports (Cross-Extension Communication)
 
-Use `ExtensionExternalClientTransport` and `ExtensionExternalServerTransport` for communication between different browser extensions, enabling one extension to access MCP servers hosted by another extension.
+Use `ExtensionClientTransport` and `ExtensionServerTransport` with an extension ID and
+`chrome.runtime.onConnectExternal` for communication between different browser extensions.
 
 ## Tab Transport Examples
 
@@ -59,7 +60,7 @@ Create an MCP server in your web page and expose it via `TabServerTransport`:
 
 ```typescript
 import { TabServerTransport } from '@mcp-b/transports';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 
 // Create MCP server with tools
@@ -74,11 +75,13 @@ const server = new McpServer(
 );
 
 // Register a tool
-server.tool(
+server.registerTool(
   'createTodo',
-  'Creates a new todo item for the current user',
   {
-    todoText: z.string().describe('The content of the todo item.'),
+    description: 'Creates a new todo item for the current user',
+    inputSchema: z.object({
+      todoText: z.string().describe('The content of the todo item.'),
+    }),
   },
   async (args) => {
     // Implementation here
@@ -106,24 +109,23 @@ Connect to the server from within the same page or from an extension content scr
 
 ```typescript
 import { TabClientTransport } from '@mcp-b/transports';
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { Client } from '@modelcontextprotocol/client';
 
 // Create transport with target origin
 const transport = new TabClientTransport({
   targetOrigin: window.location.origin,
 });
 
-// Discover available servers
-const availableServers = await transport.discover();
-if (availableServers.length > 0) {
-  console.log(`Found server: ${availableServers[0].implementation.name}`);
-}
-
 // Create and connect client
-const client = new Client({
-  name: 'ExtensionProxyClient',
-  version: '1.0.0',
-});
+const client = new Client(
+  {
+    name: 'ExtensionProxyClient',
+    version: '1.0.0',
+  },
+  {
+    versionNegotiation: { mode: 'auto' },
+  }
+);
 
 await client.connect(transport);
 
@@ -156,28 +158,23 @@ Create an MCP server inside an iframe that can be accessed by the parent page:
 
 ```typescript
 import { IframeChildTransport } from '@mcp-b/transports';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 
 // Create MCP server
-const server = new Server(
-  {
-    name: 'IframeApp',
-    version: '1.0.0',
-  },
-  {
-    capabilities: {
-      tools: {},
-    },
-  }
-);
+const server = new McpServer({
+  name: 'IframeApp',
+  version: '1.0.0',
+});
 
 // Register tools
-server.tool(
+server.registerTool(
   'getIframeData',
-  'Get data from the iframe application',
   {
-    key: z.string().describe('Data key to retrieve'),
+    description: 'Get data from the iframe application',
+    inputSchema: z.object({
+      key: z.string().describe('Data key to retrieve'),
+    }),
   },
   async (args) => {
     return {
@@ -206,7 +203,7 @@ Connect from the parent page to the iframe's MCP server:
 
 ```typescript
 import { IframeParentTransport } from '@mcp-b/transports';
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { Client } from '@modelcontextprotocol/client';
 
 // Get reference to iframe element
 const iframe = document.querySelector('iframe');
@@ -220,10 +217,15 @@ iframe.addEventListener('load', async () => {
   });
 
   // Create MCP client
-  const client = new Client({
-    name: 'ParentPage',
-    version: '1.0.0',
-  });
+  const client = new Client(
+    {
+      name: 'ParentPage',
+      version: '1.0.0',
+    },
+    {
+      versionNegotiation: { mode: 'auto' },
+    }
+  );
 
   // Connect and use
   await client.connect(transport);
@@ -247,13 +249,12 @@ iframe.addEventListener('load', async () => {
 - `iframe` (required): Reference to the HTMLIFrameElement
 - `targetOrigin` (required): Expected origin of the iframe (for security)
 - `channelId`: Override the default channel identifier (default: `mcp-iframe`)
-- `checkReadyRetryMs`: Interval to retry the ready handshake if iframe isn't ready yet (default: 250ms)
+- `checkReadyRetryMs`: Retry interval while `iframe.contentWindow` is unavailable (default: 250ms)
 
 #### IframeChildTransport Options
 
 - `allowedOrigins` (required): Whitelist of parent origins allowed to connect (for security)
 - `channelId`: Override the default channel identifier (default: `mcp-iframe`)
-- `serverReadyRetryMs`: Interval to retry broadcasting ready signal to parent (default: 250ms)
 
 ### Cross-Origin Support
 
@@ -262,7 +263,7 @@ Iframe transports are designed for cross-origin communication:
 - Parent and iframe can be on different domains
 - Origin validation is performed on both sides
 - Uses secure `postMessage` API
-- Retry mechanisms handle iframe loading timing issues
+- The parent retries its ready check until the iframe window is available
 
 ## Extension Transport Examples
 
@@ -272,18 +273,20 @@ The extension background script acts as a hub, aggregating tools from multiple t
 
 ```typescript
 import { ExtensionServerTransport } from '@mcp-b/transports';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/server';
 
 class McpHub {
-  private server: McpServer;
-
   constructor() {
-    this.server = new McpServer({
+    this.setupConnections();
+  }
+
+  private createServer() {
+    const server = new McpServer({
       name: 'Extension-Hub',
       version: '1.0.0',
     });
-
-    this.setupConnections();
+    // Register tools backed by the hub's shared application state here.
+    return server;
   }
 
   private setupConnections() {
@@ -297,29 +300,38 @@ class McpHub {
   }
 
   private async handleUiConnection(port: chrome.runtime.Port) {
+    const server = this.createServer();
     const transport = new ExtensionServerTransport(port);
-    await this.server.connect(transport);
+    await server.connect(transport);
   }
 }
 ```
 
+Each `McpServer` owns one protocol session, so every accepted port gets a fresh server. Keep the
+hub's shared application state outside the per-connection server.
+
 ### Content Script Bridge
 
 Content scripts act as a bridge between the page's MCP server and the extension:
 
 ```typescript
 import { TabClientTransport } from '@mcp-b/transports';
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { Client } from '@modelcontextprotocol/client';
 
 // Connect to the page's MCP server
 const transport = new TabClientTransport({
   targetOrigin: window.location.origin,
 });
 
-const client = new Client({
-  name: 'ExtensionProxyClient',
-  version: '1.0.0',
-});
+const client = new Client(
+  {
+    name: 'ExtensionProxyClient',
+    version: '1.0.0',
+  },
+  {
+    versionNegotiation: { mode: 'auto' },
+  }
+);
 
 // Connect to extension background
 const backgroundPort = chrome.runtime.connect({
@@ -359,7 +371,7 @@ Connect from the extension's sidebar or popup to use tools from all connected pa
 
 ```typescript
 import { ExtensionClientTransport } from '@mcp-b/transports';
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { Client } from '@modelcontextprotocol/client';
 
 // Create transport - connects to the extension's background script
 const transport = new ExtensionClientTransport({
@@ -367,10 +379,15 @@ const transport = new ExtensionClientTransport({
 });
 
 // Create MCP client
-const client = new Client({
-  name: 'Extension Sidepanel',
-  version: '1.0.0',
-});
+const client = new Client(
+  {
+    name: 'Extension Sidepanel',
+    version: '1.0.0',
+  },
+  {
+    versionNegotiation: { mode: 'auto' },
+  }
+);
 
 // Connect and use
 await client.connect(transport);
@@ -392,33 +409,41 @@ const result = await client.callTool({
 Create an MCP server in Extension 1 that can be accessed by other extensions:
 
 ```typescript
-import { ExtensionExternalServerTransport } from '@mcp-b/transports';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ExtensionServerTransport } from '@mcp-b/transports';
+import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 
-// Create MCP server with tools
-const server = new McpServer(
-  {
-    name: 'MyExtensionAPI',
-    version: '1.0.0',
-  },
-  {
-    instructions: 'Extension API for cross-extension communication',
-  }
-);
+function createServer() {
+  const server = new McpServer(
+    {
+      name: 'MyExtensionAPI',
+      version: '1.0.0',
+    },
+    {
+      instructions: 'Extension API for cross-extension communication',
+    }
+  );
 
-// Register tools
-server.tool('getBookmarks', 'Retrieves user bookmarks', {}, async () => {
-  const bookmarks = await chrome.bookmarks.getTree();
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify(bookmarks, null, 2),
-      },
-    ],
-  };
-});
+  server.registerTool(
+    'getBookmarks',
+    {
+      description: 'Retrieves user bookmarks',
+      inputSchema: z.object({}),
+    },
+    async () => {
+      const bookmarks = await chrome.bookmarks.getTree();
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(bookmarks, null, 2),
+          },
+        ],
+      };
+    }
+  );
+  return server;
+}
 
 // Set up external connection listener in background script
 chrome.runtime.onConnectExternal.addListener(async (port) => {
@@ -429,6 +454,7 @@ chrome.runtime.onConnectExternal.addListener(async (port) => {
       return;
     }
 
+    const server = createServer();
     const transport = new ExtensionServerTransport(port);
     await server.connect(transport);
   }
@@ -440,8 +466,8 @@ chrome.runtime.onConnectExternal.addListener(async (port) => {
 Connect from Extension 2 to use Extension 1's MCP server:
 
 ```typescript
-import { ExtensionExternalClientTransport } from '@mcp-b/transports';
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { ExtensionClientTransport } from '@mcp-b/transports';
+import { Client } from '@modelcontextprotocol/client';
 
 // Create transport targeting Extension 1
 const transport = new ExtensionClientTransport({
@@ -450,10 +476,15 @@ const transport = new ExtensionClientTransport({
 });
 
 // Create MCP client
-const client = new Client({
-  name: 'ClientExtension',
-  version: '1.0.0',
-});
+const client = new Client(
+  {
+    name: 'ClientExtension',
+    version: '1.0.0',
+  },
+  {
+    versionNegotiation: { mode: 'auto' },
+  }
+);
 
 // Connect and use
 await client.connect(transport);
@@ -493,18 +524,17 @@ const result = await client.callTool({
 
 ### Extension External Transport Flow
 
-1. Extension 1 creates `ExtensionExternalServerTransport` and listens on `chrome.runtime.onConnectExternal`
-2. Extension 2 creates `ExtensionExternalClientTransport` targeting Extension 1's ID
+1. Extension 1 creates `ExtensionServerTransport` instances from `chrome.runtime.onConnectExternal`
+2. Extension 2 creates an `ExtensionClientTransport` with Extension 1's ID
 3. Communication happens through Chrome's secure cross-extension messaging
 4. Server extension can validate connections and control access
 
 ## Key Features
 
-- **Automatic Server Discovery**: Tab clients can discover available servers
-- **Cross-Origin Support**: Configure CORS for tab transports
+- **Ready Handshake**: Tab and iframe clients wait for their server before sending
+- **Origin Controls**: Restrict incoming and outgoing `postMessage` origins
 - **Cross-Extension Communication**: Extensions can expose APIs to other extensions
 - **Tool Namespacing**: Extension hub prefixes tools to avoid conflicts
-- **Connection Management**: Automatic cleanup when tabs close
 - **Type Safety**: Full TypeScript support with proper typing
 
 ## Security Considerations
@@ -524,12 +554,12 @@ MCP is an open protocol that standardizes how AI applications connect to externa
 
 ### Which transport should I use?
 
-| Scenario                     | Recommended Transport                                                   |
-| ---------------------------- | ----------------------------------------------------------------------- |
-| Same-page communication      | `TabServerTransport` / `TabClientTransport`                             |
-| Parent page to iframe        | `IframeParentTransport` / `IframeChildTransport`                        |
-| Browser extension to webpage | `ExtensionClientTransport` / `ExtensionServerTransport`                 |
-| Extension to extension       | `ExtensionExternalClientTransport` / `ExtensionExternalServerTransport` |
+| Scenario                     | Recommended Transport                                   |
+| ---------------------------- | ------------------------------------------------------- |
+| Same-page communication      | `TabServerTransport` / `TabClientTransport`             |
+| Parent page to iframe        | `IframeParentTransport` / `IframeChildTransport`        |
+| Browser extension to webpage | `ExtensionClientTransport` / `ExtensionServerTransport` |
+| Extension to extension       | `ExtensionClientTransport` / `ExtensionServerTransport` |
 
 ### Is this compatible with Claude Desktop, Cursor, or VS Code Copilot?
 
@@ -557,9 +587,8 @@ Yes! `TabServerTransport` and `TabClientTransport` work entirely within a web pa
 
 - [`@mcp-b/global`](https://docs.mcp-b.ai/packages/global/reference) - Full MCP-B browser runtime
 - [`@mcp-b/react-webmcp`](https://docs.mcp-b.ai/packages/react-webmcp/reference) - React hooks for MCP tool registration
-- [`@mcp-b/extension-tools`](https://docs.mcp-b.ai/packages/extension-tools/reference) - 62+ Chrome Extension API tools for MCP
 - [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp) - Upstream Chrome DevTools MCP server
-- [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) - Official MCP SDK
+- [`@modelcontextprotocol/client`](https://www.npmjs.com/package/@modelcontextprotocol/client) and [`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server) - Official MCP TypeScript SDK v2 packages
 
 ## Resources