@mcp-b/webmcp-ts-sdk 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# @mcp-b/webmcp-ts-sdk
+
+> Browser-adapted Model Context Protocol TypeScript SDK
+
+[![npm version](https://img.shields.io/npm/v/@mcp-b/webmcp-ts-sdk?style=flat-square)](https://www.npmjs.com/package/@mcp-b/webmcp-ts-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+This package adapts the official [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) for browser environments with modifications to support dynamic tool registration required by the [W3C Web Model Context API](https://github.com/webmachinelearning/webmcp) (`window.navigator.modelContext`).
+
+## Why This Package Exists
+
+The official MCP TypeScript SDK has a restriction that prevents registering server capabilities (like tools) after a transport connection is established. This is enforced by this check in the `Server` class:
+
+```typescript
+public registerCapabilities(capabilities: ServerCapabilities): void {
+    if (this.transport) {
+        throw new Error('Cannot register capabilities after connecting to transport');
+    }
+    ...
+}
+```
+
+For the Web Model Context API, this restriction is incompatible because:
+
+1. **Tools arrive dynamically** - Web pages call `window.navigator.modelContext.provideContext({ tools: [...] })` at any time
+2. **Transport must be ready immediately** - The MCP server/transport needs to be connected when the page loads
+3. **Asynchronous registration** - Tools are registered as the page's JavaScript executes, potentially long after initialization
+
+This package solves the problem by **pre-registering tool capabilities** before the transport connects, allowing dynamic tool registration to work seamlessly.
+
+## Modifications from Official SDK
+
+### BrowserMcpServer Class
+
+The `BrowserMcpServer` extends `McpServer` with these changes:
+
+```typescript
+export class BrowserMcpServer extends BaseMcpServer {
+  constructor(serverInfo, options?) {
+    // Pre-register tool capabilities in constructor
+    const enhancedOptions = {
+      ...options,
+      capabilities: mergeCapabilities(options?.capabilities || {}, {
+        tools: { listChanged: true }
+      })
+    };
+    super(serverInfo, enhancedOptions);
+  }
+
+  async connect(transport: Transport) {
+    // Ensure capabilities are set before connecting
+    // This bypasses the "cannot register after connect" restriction
+    return super.connect(transport);
+  }
+}
+```
+
+**Key Difference**: Capabilities are registered **before** connecting, allowing tools to be added dynamically afterward.
+
+## What's Re-Exported
+
+This package re-exports almost everything from the official SDK:
+
+### Types
+- All MCP protocol types (`Tool`, `Resource`, `Prompt`, etc.)
+- Request/response schemas
+- Client and server capabilities
+- Error codes and constants
+
+### Classes
+- `Server` - Base server class (unchanged)
+- `McpServer` - Aliased to `BrowserMcpServer` with our modifications
+
+### Utilities
+- `Transport` interface
+- `mergeCapabilities` helper
+- Protocol version constants
+
+## Installation
+
+```bash
+npm install @mcp-b/webmcp-ts-sdk
+# or
+pnpm add @mcp-b/webmcp-ts-sdk
+```
+
+## Usage
+
+Use it exactly like the official SDK:
+
+```typescript
+import { McpServer } from '@mcp-b/webmcp-ts-sdk';
+import { TabServerTransport } from '@mcp-b/transports';
+
+const server = new McpServer({
+  name: 'my-web-app',
+  version: '1.0.0'
+});
+
+// Connect transport first
+const transport = new TabServerTransport({ allowedOrigins: ['*'] });
+await server.connect(transport);
+
+// Now you can register tools dynamically (this would fail with official SDK)
+server.registerTool('my-tool', {
+  description: 'A dynamically registered tool',
+  inputSchema: { message: z.string() },
+  outputSchema: { result: z.string() }
+}, async ({ message }) => {
+  return {
+    content: [{ type: 'text', text: `Echo: ${message}` }],
+    structuredContent: { result: `Echo: ${message}` }
+  };
+});
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────┐
+│  @mcp-b/webmcp-ts-sdk           │
+│                                 │
+│  ┌───────────────────────────┐  │
+│  │ BrowserMcpServer          │  │
+│  │ (Modified behavior)        │  │
+│  └───────────┬───────────────┘  │
+│              │ extends          │
+│              ▼                  │
+│  ┌───────────────────────────┐  │
+│  │ @modelcontextprotocol/sdk │  │
+│  │ (Official SDK)             │  │
+│  │ - Types                    │  │
+│  │ - Protocol                 │  │
+│  │ - Validation               │  │
+│  └───────────────────────────┘  │
+└─────────────────────────────────┘
+```
+
+## Maintenance Strategy
+
+This package is designed for **minimal maintenance**:
+
+- ✅ **~50 lines** of custom code
+- ✅ **Automatic updates** for types, protocol, validation via official SDK dependency
+- ✅ **Single modification point** - only capability registration behavior
+- ✅ **Type-safe** - no prototype hacks or unsafe casts
+
+### Syncing with Upstream
+
+When the official SDK updates:
+
+1. Update the catalog version in `pnpm-workspace.yaml`
+2. Run `pnpm install` to get latest SDK
+3. Test that capability registration still works
+4. Update this README if SDK behavior changes
+
+The modification is minimal and unlikely to conflict with upstream changes.
+
+## Related Packages
+
+- [`@mcp-b/global`](../global) - W3C Web Model Context API implementation (uses this package)
+- [`@mcp-b/transports`](../transports) - Browser-specific MCP transports
+- [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) - Official MCP SDK
+
+## Resources
+
+- [Web Model Context API Explainer](https://github.com/webmachinelearning/webmcp)
+- [Model Context Protocol Spec](https://modelcontextprotocol.io/)
+- [Official MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+
+## License
+
+MIT - see [LICENSE](../../LICENSE) for details
+
+## Support
+
+- [GitHub Issues](https://github.com/WebMCP-org/npm-packages/issues)
+- [Documentation](https://docs.mcp-b.ai)

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { Server, ServerOptions } from "@modelcontextprotocol/sdk/server/index.js";
+import { mergeCapabilities } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { CallToolRequest, CallToolRequestSchema, CallToolResult, CallToolResultSchema, ClientCapabilities, ClientNotification, ClientRequest, ClientResult, CreateMessageRequest, CreateMessageRequestSchema, CreateMessageResult, CreateMessageResultSchema, ElicitRequest, ElicitRequestSchema, ElicitResult, ElicitResultSchema, ErrorCode, GetPromptRequest, GetPromptRequestSchema, GetPromptResult, GetPromptResultSchema, Implementation, Implementation as Implementation$1, InitializeRequest, InitializeRequestSchema, InitializeResult, InitializeResultSchema, JSONRPCMessage, LATEST_PROTOCOL_VERSION, ListPromptsRequest, ListPromptsRequestSchema, ListPromptsResult, ListPromptsResultSchema, ListResourcesRequest, ListResourcesRequestSchema, ListResourcesResult, ListResourcesResultSchema, ListToolsRequest, ListToolsRequestSchema, ListToolsResult, ListToolsResultSchema, LoggingLevel, LoggingLevelSchema, LoggingMessageNotification, McpError, Notification, Prompt, PromptMessage, ReadResourceRequest, ReadResourceRequestSchema, ReadResourceResult, ReadResourceResultSchema, Request, Resource, ResourceContents, ResourceTemplate, Result, SUPPORTED_PROTOCOL_VERSIONS, ServerCapabilities, ServerNotification, ServerRequest, ServerResult, Tool, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Transport, Transport as Transport$1 } from "@modelcontextprotocol/sdk/shared/transport.js";
+
+//#region src/browser-server.d.ts
+
+/**
+ * Browser-optimized MCP Server for Web Model Context API (window.agent).
+ *
+ * This class extends McpServer to support dynamic tool registration after
+ * transport connection, which is required for the Web Model Context API
+ * where tools are registered via window.agent.provideContext() at any time.
+ *
+ * Key differences from base McpServer:
+ * - Pre-registers tool capabilities before connection
+ * - Allows tools to be registered after transport is connected
+ * - Designed for browser environments where tools arrive asynchronously
+ */
+declare class BrowserMcpServer extends McpServer {
+  constructor(serverInfo: Implementation$1, options?: ServerOptions);
+  /**
+   * Override connect to ensure tool request handlers are initialized
+   * BEFORE the transport connection is established.
+   *
+   * This prevents the "Cannot register capabilities after connecting to transport"
+   * error when tools are registered dynamically after connection.
+   */
+  connect(transport: Transport$1): Promise<void>;
+}
+//#endregion
+export { BrowserMcpServer, BrowserMcpServer as McpServer, type CallToolRequest, CallToolRequestSchema, type CallToolResult, CallToolResultSchema, type ClientCapabilities, type ClientNotification, type ClientRequest, type ClientResult, type CreateMessageRequest, CreateMessageRequestSchema, type CreateMessageResult, CreateMessageResultSchema, type ElicitRequest, ElicitRequestSchema, type ElicitResult, ElicitResultSchema, ErrorCode, type GetPromptRequest, GetPromptRequestSchema, type GetPromptResult, GetPromptResultSchema, type Implementation, type InitializeRequest, InitializeRequestSchema, type InitializeResult, InitializeResultSchema, type JSONRPCMessage, LATEST_PROTOCOL_VERSION, type ListPromptsRequest, ListPromptsRequestSchema, type ListPromptsResult, ListPromptsResultSchema, type ListResourcesRequest, ListResourcesRequestSchema, type ListResourcesResult, ListResourcesResultSchema, type ListToolsRequest, ListToolsRequestSchema, type ListToolsResult, ListToolsResultSchema, type LoggingLevel, LoggingLevelSchema, type LoggingMessageNotification, type McpError, type Notification, type Prompt, type PromptMessage, type ReadResourceRequest, ReadResourceRequestSchema, type ReadResourceResult, ReadResourceResultSchema, type Request, type Resource, type ResourceContents, type ResourceTemplate, type Result, SUPPORTED_PROTOCOL_VERSIONS, Server, type ServerCapabilities, type ServerNotification, type ServerRequest, type ServerResult, type Tool, type ToolAnnotations, type Transport, mergeCapabilities };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/browser-server.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAkBA;;;;;;;;;cAAa,gBAAA,SAAyB,SAAA;0BACZ,4BAA0B;;;;;;;;qBAqBhB,cAAY"}

package/dist/index.js

@@ -0,0 +1,42 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { mergeCapabilities, mergeCapabilities as mergeCapabilities$1 } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { CallToolRequestSchema, CallToolResultSchema, CreateMessageRequestSchema, CreateMessageResultSchema, ElicitRequestSchema, ElicitResultSchema, ErrorCode, GetPromptRequestSchema, GetPromptResultSchema, InitializeRequestSchema, InitializeResultSchema, LATEST_PROTOCOL_VERSION, ListPromptsRequestSchema, ListPromptsResultSchema, ListResourcesRequestSchema, ListResourcesResultSchema, ListToolsRequestSchema, ListToolsResultSchema, LoggingLevelSchema, ReadResourceRequestSchema, ReadResourceResultSchema, SUPPORTED_PROTOCOL_VERSIONS } from "@modelcontextprotocol/sdk/types.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/browser-server.ts
+/**
+* Browser-optimized MCP Server for Web Model Context API (window.agent).
+*
+* This class extends McpServer to support dynamic tool registration after
+* transport connection, which is required for the Web Model Context API
+* where tools are registered via window.agent.provideContext() at any time.
+*
+* Key differences from base McpServer:
+* - Pre-registers tool capabilities before connection
+* - Allows tools to be registered after transport is connected
+* - Designed for browser environments where tools arrive asynchronously
+*/
+var BrowserMcpServer = class extends McpServer {
+	constructor(serverInfo, options) {
+		const enhancedOptions = {
+			...options,
+			capabilities: mergeCapabilities$1(options?.capabilities || {}, { tools: { listChanged: true } })
+		};
+		super(serverInfo, enhancedOptions);
+	}
+	/**
+	* Override connect to ensure tool request handlers are initialized
+	* BEFORE the transport connection is established.
+	*
+	* This prevents the "Cannot register capabilities after connecting to transport"
+	* error when tools are registered dynamically after connection.
+	*/
+	async connect(transport) {
+		this.setToolRequestHandlers();
+		return super.connect(transport);
+	}
+};
+
+//#endregion
+export { BrowserMcpServer, BrowserMcpServer as McpServer, CallToolRequestSchema, CallToolResultSchema, CreateMessageRequestSchema, CreateMessageResultSchema, ElicitRequestSchema, ElicitResultSchema, ErrorCode, GetPromptRequestSchema, GetPromptResultSchema, InitializeRequestSchema, InitializeResultSchema, LATEST_PROTOCOL_VERSION, ListPromptsRequestSchema, ListPromptsResultSchema, ListResourcesRequestSchema, ListResourcesResultSchema, ListToolsRequestSchema, ListToolsResultSchema, LoggingLevelSchema, ReadResourceRequestSchema, ReadResourceResultSchema, SUPPORTED_PROTOCOL_VERSIONS, Server, mergeCapabilities };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["BaseMcpServer","enhancedOptions: ServerOptions","mergeCapabilities"],"sources":["../src/browser-server.ts"],"sourcesContent":["import type { ServerOptions } from '@modelcontextprotocol/sdk/server/index.js';\nimport { McpServer as BaseMcpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { mergeCapabilities } from '@modelcontextprotocol/sdk/shared/protocol.js';\nimport type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';\nimport type { Implementation } from '@modelcontextprotocol/sdk/types.js';\n\n/**\n * Browser-optimized MCP Server for Web Model Context API (window.agent).\n *\n * This class extends McpServer to support dynamic tool registration after\n * transport connection, which is required for the Web Model Context API\n * where tools are registered via window.agent.provideContext() at any time.\n *\n * Key differences from base McpServer:\n * - Pre-registers tool capabilities before connection\n * - Allows tools to be registered after transport is connected\n * - Designed for browser environments where tools arrive asynchronously\n */\nexport class BrowserMcpServer extends BaseMcpServer {\n  constructor(serverInfo: Implementation, options?: ServerOptions) {\n    // Ensure tools capability is registered from the start\n    const enhancedOptions: ServerOptions = {\n      ...options,\n      capabilities: mergeCapabilities(options?.capabilities || {}, {\n        tools: {\n          listChanged: true,\n        },\n      }),\n    };\n\n    super(serverInfo, enhancedOptions);\n  }\n\n  /**\n   * Override connect to ensure tool request handlers are initialized\n   * BEFORE the transport connection is established.\n   *\n   * This prevents the \"Cannot register capabilities after connecting to transport\"\n   * error when tools are registered dynamically after connection.\n   */\n  override async connect(transport: Transport): Promise<void> {\n    // Call setToolRequestHandlers() BEFORE connecting the transport\n    // This will:\n    // 1. Register tool capabilities (won't throw since transport isn't connected yet)\n    // 2. Set up ListTools and CallTool request handlers\n    // 3. Set _toolHandlersInitialized = true\n    //\n    // After this, any future registerTool() calls will skip registerCapabilities()\n    // because _toolHandlersInitialized is true, allowing dynamic tool registration\n\n    // Type-safe access to private method - we need to call this internal method\n    // to initialize tool handlers before connecting\n    (this as unknown as { setToolRequestHandlers: () => void }).setToolRequestHandlers();\n\n    // Now connect with the transport\n    return super.connect(transport);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAkBA,IAAa,mBAAb,cAAsCA,UAAc;CAClD,YAAY,YAA4B,SAAyB;EAE/D,MAAMC,kBAAiC;GACrC,GAAG;GACH,cAAcC,oBAAkB,SAAS,gBAAgB,EAAE,EAAE,EAC3D,OAAO,EACL,aAAa,MACd,EACF,CAAC;GACH;AAED,QAAM,YAAY,gBAAgB;;;;;;;;;CAUpC,MAAe,QAAQ,WAAqC;AAY1D,EAAC,KAA2D,wBAAwB;AAGpF,SAAO,MAAM,QAAQ,UAAU"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@mcp-b/webmcp-ts-sdk",
+  "version": "1.0.1",
+  "description": "TypeScript SDK adapter for Model Context Protocol with dynamic tool registration support for browsers",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "browser",
+    "typescript",
+    "sdk",
+    "adapter",
+    "web-model-context",
+    "navigator.modelContext",
+    "w3c"
+  ],
+  "homepage": "https://github.com/MiguelsPizza/WebMCP#readme",
+  "bugs": {
+    "url": "https://github.com/MiguelsPizza/WebMCP/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MiguelsPizza/WebMCP.git",
+    "directory": "packages/webmcp-ts-sdk"
+  },
+  "license": "MIT",
+  "author": "Alex Nahas",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.15.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "tsdown": "^0.15.10",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "biome check --write .",
+    "clean": "rm -rf dist .turbo",
+    "format": "biome format --write .",
+    "lint": "biome lint --write .",
+    "publish:dry": "pnpm publish --access public --dry-run",
+    "publish:npm": "pnpm publish --access public",
+    "typecheck": "tsc --noEmit",
+    "version:major": "pnpm version major --no-git-tag-version",
+    "version:minor": "pnpm version minor --no-git-tag-version",
+    "version:patch": "pnpm version patch --no-git-tag-version"
+  }
+}