@mcp-fe/mcp-worker 0.1.11 → 0.2.2

package/docs/native-webmcp.md

@@ -0,0 +1,232 @@
+# WebMCP Integration
+
+## Overview
+
+The MCP Worker library includes a built-in adapter for the **WebMCP API** (`navigator.modelContext`), a browser-native mechanism for registering MCP tools directly with the user-agent. When the browser supports this API, tools registered via `WorkerClient` are **automatically** advertised through the native channel as well, enabling browser-level tool discovery by AI agents, browser's agents, and assistive technologies.
+
+**Enabled by default** — if the browser supports `navigator.modelContext`, it just works. No configuration needed. You can explicitly disable it if needed.
+
+Based on the [WebMCP specification](https://webmachinelearning.github.io/webmcp/) published by the W3C Web Machine Learning Community Group.
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    WorkerClient                           │
+│                                                           │
+│  registerTool('my-tool', ...)                             │
+│       │                                                   │
+│       ├──→ ToolRegistry (local, immediate)                │
+│       │                                                   │
+│       ├──→ SharedWorker / ServiceWorker (transport)       │
+│       │        └──→ WebSocket → Backend MCP Server        │
+│       │                                                   │
+│       └──→ WebMcpAdapter (auto-enabled if supported)      │
+│                └──→ navigator.modelContext.registerTool()  │
+│                     (browser-native registration)         │
+└──────────────────────────────────────────────────────────┘
+```
+
+**Key principle**: The worker transport remains the **primary** channel. WebMCP registration is a **secondary, additive** channel for browser-level discovery. Both systems coexist.
+
+## WebMCP Spec API Surface
+
+The adapter maps to the following browser API (per spec §5):
+
+```webidl
+// §5.1 Navigator extension
+partial interface Navigator {
+  [SecureContext, SameObject] readonly attribute ModelContext modelContext;
+};
+
+// §5.2 ModelContext interface
+interface ModelContext {
+  undefined provideContext(optional ModelContextOptions options = {});
+  undefined clearContext();
+  undefined registerTool(ModelContextTool tool);
+  undefined unregisterTool(DOMString name);
+};
+
+// §5.2.2 ModelContextTool dictionary
+dictionary ModelContextTool {
+  required DOMString name;
+  required DOMString description;
+  object inputSchema;
+  required ToolExecuteCallback execute;
+  ToolAnnotations annotations;
+};
+
+dictionary ToolAnnotations {
+  boolean readOnlyHint;
+};
+
+callback ToolExecuteCallback = Promise<any> (object input, ModelContextClient client);
+
+// §5.2.3 ModelContextClient
+interface ModelContextClient {
+  Promise<any> requestUserInteraction(UserInteractionCallback callback);
+};
+```
+
+## Feature Detection
+
+```typescript
+import { WorkerClient, WebMcpAdapter } from '@anthropic/mcp-worker';
+
+// Static check: does the browser support navigator.modelContext?
+if (WorkerClient.isWebMcpSupported()) {
+  console.log('Browser supports WebMCP!');
+}
+
+// Or use the adapter directly:
+if (WebMcpAdapter.isSupported()) {
+  console.log('navigator.modelContext is available');
+}
+```
+
+## Configuration
+
+### Default behavior (auto-enabled)
+
+No configuration needed. If `navigator.modelContext` is available, tools are automatically registered via WebMCP:
+
+```typescript
+import { workerClient } from '@anthropic/mcp-worker';
+
+await workerClient.init({
+  sharedWorkerUrl: '/mcp-shared-worker.js',
+  backendWsUrl: 'ws://localhost:3001',
+  // enableWebMcp defaults to true — auto-detects browser support
+});
+```
+
+### Explicitly disable
+
+```typescript
+await workerClient.init({
+  sharedWorkerUrl: '/mcp-shared-worker.js',
+  backendWsUrl: 'ws://localhost:3001',
+  enableWebMcp: false,  // ← disable WebMCP registration
+});
+```
+
+### Toggle at runtime
+
+```typescript
+// Disable — calls navigator.modelContext.clearContext()
+workerClient.setWebMcpEnabled(false);
+
+// Re-enable — syncs all existing tools to navigator.modelContext
+workerClient.setWebMcpEnabled(true);
+```
+
+## Registering Tools
+
+No changes to tool registration are needed. When WebMCP is available, `registerTool()` automatically registers in both systems:
+
+```typescript
+await workerClient.registerTool(
+  'get-user-profile',
+  'Fetch the current user profile',
+  {
+    type: 'object',
+    properties: {
+      userId: { type: 'string', description: 'User ID' },
+    },
+    required: ['userId'],
+  },
+  async (args: unknown) => {
+    const { userId } = args as { userId: string };
+    const profile = await fetchProfile(userId);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(profile) }],
+    };
+  },
+  { annotations: { readOnlyHint: true } },
+);
+
+// Check where the tool is registered:
+workerClient.isToolRegistered('get-user-profile');            // true (local + worker)
+workerClient.isToolRegisteredViaWebMcp('get-user-profile');   // true (navigator.modelContext)
+```
+
+## Querying WebMCP Registrations
+
+```typescript
+// Check if a specific tool is registered via WebMCP
+workerClient.isToolRegisteredViaWebMcp('my-tool'); // boolean
+
+// Get all WebMCP-registered tool names
+workerClient.getWebMcpRegisteredTools(); // string[]
+
+// Check if WebMCP is currently enabled AND supported
+workerClient.isWebMcpAvailable(); // boolean
+```
+
+## Cleanup
+
+WebMCP registrations are cleaned up automatically:
+
+- **On `unregisterTool()`** — calls `navigator.modelContext.unregisterTool(name)`
+- **On page unload** (`beforeunload` / `pagehide`) — calls `navigator.modelContext.clearContext()`
+- **On `setWebMcpEnabled(false)`** — calls `navigator.modelContext.clearContext()`
+
+## Architecture
+
+### Files
+
+| File | Purpose |
+|------|---------|
+| `web-mcp-types.ts` | TypeScript types matching the WebMCP spec (`ModelContext`, `ModelContextTool`, `ModelContextClient`, etc.) |
+| `web-mcp-adapter.ts` | Adapter that bridges ToolRegistry ↔ `navigator.modelContext` |
+| `worker-client.ts` | Integration point (uses adapter internally) |
+
+### Type Augmentation
+
+The `web-mcp-types.ts` file extends the global `Navigator` interface:
+
+```typescript
+declare global {
+  interface Navigator {
+    readonly modelContext?: ModelContext;
+  }
+}
+```
+
+### WebMcpAdapter
+
+The adapter is a standalone class, enabled by default:
+
+- **`isSupported()`** — static, checks `navigator.modelContext` existence
+- **`isAvailable()`** — instance, respects enabled flag + browser support
+- **`registerTool()`** — builds `ModelContextTool` dict and calls `navigator.modelContext.registerTool(tool)` (synchronous)
+- **`unregisterTool()`** — calls `navigator.modelContext.unregisterTool(name)` (synchronous)
+- **`clearAll()`** — calls `navigator.modelContext.clearContext()` (per spec §5.2)
+- **`toModelContextTool()`** — static utility to convert internal `ToolDefinition` + handler
+
+### Handler Mapping
+
+The spec defines `ToolExecuteCallback` as:
+
+```typescript
+callback ToolExecuteCallback = Promise<any> (object input, ModelContextClient client);
+```
+
+The adapter wraps the internal `ToolHandler` (which takes `args: unknown` and returns `{ content: [...] }`) into this format. The `ModelContextClient` parameter gives access to `requestUserInteraction()` for user consent flows.
+
+## Error Handling
+
+All WebMCP operations are **best-effort**:
+
+- Registration failures are logged as warnings, never thrown
+- The worker-based system is unaffected by WebMCP errors
+- Per spec, `registerTool()` throws if a duplicate name exists — the adapter unregisters first
+- `clearAll()` falls back to individual `unregisterTool()` calls if `clearContext()` throws
+
+## Browser Support
+
+The WebMCP specification is a CG-DRAFT published by the W3C Web Machine Learning Community Group (February 2026). The adapter is forward-compatible:
+
+- When the API is unavailable, all WebMCP operations are silent no-ops
+- Zero runtime cost when browser doesn't support it (no feature detection on hot paths)
+- The type definitions follow the spec and can be updated as the standard evolves

package/docs/project-structure.md

@@ -1,172 +1,172 @@
-# Project Structure
-
-This document explains the organization of the `@mcp-fe/mcp-worker` codebase.
-
-## Directory Layout
-
-```
-libs/mcp-worker/src/
-├── index.ts                    # Main entry point (re-exports from client/)
-├── mcp-shared-worker.ts        # SharedWorker entry point
-├── mcp-service-worker.ts       # ServiceWorker entry point
-├── client/                     # Client-side code (application runtime)
-│   ├── index.ts                # Client API exports
-│   └── worker-client.ts        # Main WorkerClient class
-├── worker/                     # Worker-side code (background processing)
-│   ├── index.ts                # Worker internal exports
-│   ├── mcp-controller.ts       # MCP server controller & lifecycle
-│   ├── mcp-server.ts           # MCP server setup & handlers
-│   ├── websocket-transport.ts  # WebSocket transport for MCP
-│   ├── tool-registry.ts        # Dynamic tool registration
-│   ├── tab-manager.ts          # Multi-tab coordination
-│   ├── built-in-tools.ts       # Default MCP tools
-│   └── tab-manager.spec.ts     # Tests for TabManager
-└── shared/                     # Shared code (both contexts)
-    ├── types.ts                # TypeScript type definitions
-    ├── logger.ts               # Logging utilities
-    └── database.ts             # IndexedDB operations
-```
-
-## Module Responsibilities
-
-### Client (`client/`)
-
-**Purpose:** Code that runs in the main browser thread (your application).
-
-**Key Files:**
-- `worker-client.ts` - Main API for communicating with workers
-  - Handles worker initialization (SharedWorker vs ServiceWorker)
-  - Manages tool registration and lifecycle
-  - Handles multi-tab coordination
-  - Provides request/response messaging
-
-**Used by:** Your application code
-
-**Example:**
-```typescript
-import { workerClient } from '@mcp-fe/mcp-worker';
-await workerClient.init();
-```
-
-### Worker (`worker/`)
-
-**Purpose:** Code that runs inside Web Workers (background processing).
-
-**Key Files:**
-- `mcp-controller.ts` - Main controller for MCP server lifecycle
-  - WebSocket connection management
-  - Tool call routing and execution
-  - Tab management coordination
-  - Event storage and querying
-
-- `mcp-server.ts` - MCP server setup using @modelcontextprotocol/sdk
-  - Request handlers (ListTools, CallTool)
-  - Server configuration and capabilities
-
-- `tool-registry.ts` - Dynamic tool management
-  - Tool definition storage
-  - Handler registration and lookup
-  - Tool lifecycle management
-
-- `tab-manager.ts` - Multi-tab coordination
-  - Tab registration and tracking
-  - Active tab management
-  - Smart tool routing across tabs
-
-- `built-in-tools.ts` - Default MCP tools
-  - Event querying tools
-  - Tab listing tools
-  - Navigation history tools
-
-**Used by:** Worker entry points (`mcp-shared-worker.ts`, `mcp-service-worker.ts`)
-
-### Shared (`shared/`)
-
-**Purpose:** Code used by both client and worker contexts.
-
-**Key Files:**
-- `types.ts` - TypeScript type definitions
-  - `UserEvent`, `ToolDefinition`, `ToolHandler`
-  - `TabInfo`, `EventFilters`, etc.
-  - Ensures type consistency across contexts
-
-- `logger.ts` - Logging utilities
-  - Environment-aware logging (dev vs production)
-  - Consistent logging interface
-  - Works in both main thread and workers
-
-- `database.ts` - IndexedDB operations
-  - Event storage and retrieval
-  - Query filtering and pagination
-  - Available in both contexts (IndexedDB works everywhere)
-
-**Used by:** Both client and worker code
-
-## Communication Flow
-
-```
-Application Code
-    ↓ (imports)
-client/worker-client.ts
-    ↓ (postMessage)
-mcp-shared-worker.ts or mcp-service-worker.ts
-    ↓ (uses)
-worker/mcp-controller.ts
-    ↓ (uses)
-worker/mcp-server.ts
-    ↓ (uses)
-worker/tool-registry.ts
-    ↓ (WebSocket)
-MCP Proxy Server
-```
-
-## Import Patterns
-
-### For Application Code
-
-```typescript
-// Import from the main package
-import { workerClient, type ToolDefinition } from '@mcp-fe/mcp-worker';
-```
-
-### Internal Worker Code
-
-```typescript
-// Worker modules import from shared/
-import { logger } from '../shared/logger';
-import type { UserEvent } from '../shared/types';
-
-// Worker modules import from other worker modules
-import { toolRegistry } from './tool-registry';
-import { TabManager } from './tab-manager';
-```
-
-### Internal Client Code
-
-```typescript
-// Client modules import from shared/
-import { logger } from '../shared/logger';
-import type { ToolDefinition } from '../shared/types';
-```
-
-## Why This Structure?
-
-### Clear Separation of Concerns
-- **Client code** only deals with communication and API
-- **Worker code** handles MCP protocol and business logic
-- **Shared code** provides common utilities and types
-
-### Better Tree-Shaking
-- Applications only import client code
-- Worker bundles only include worker code
-- No unnecessary code in either bundle
-
-### Maintainability
-- Easy to find where specific functionality lives
-- Clear boundaries between contexts
-- Prevents accidental mixing of client/worker code
-
-### Future-Proof
-- Ready for splitting into separate npm packages if needed
-- Can add more worker types (e.g., dedicated workers)
-- Easy to add more shared utilities
+# Project Structure
+
+This document explains the organization of the `@mcp-fe/mcp-worker` codebase.
+
+## Directory Layout
+
+```
+libs/mcp-worker/src/
+├── index.ts                    # Main entry point (re-exports from client/)
+├── mcp-shared-worker.ts        # SharedWorker entry point
+├── mcp-service-worker.ts       # ServiceWorker entry point
+├── client/                     # Client-side code (application runtime)
+│   ├── index.ts                # Client API exports
+│   └── worker-client.ts        # Main WorkerClient class
+├── worker/                     # Worker-side code (background processing)
+│   ├── index.ts                # Worker internal exports
+│   ├── mcp-controller.ts       # MCP server controller & lifecycle
+│   ├── mcp-server.ts           # MCP server setup & handlers
+│   ├── websocket-transport.ts  # WebSocket transport for MCP
+│   ├── tool-registry.ts        # Dynamic tool registration
+│   ├── tab-manager.ts          # Multi-tab coordination
+│   ├── built-in-tools.ts       # Default MCP tools
+│   └── tab-manager.spec.ts     # Tests for TabManager
+└── shared/                     # Shared code (both contexts)
+    ├── types.ts                # TypeScript type definitions
+    ├── logger.ts               # Logging utilities
+    └── database.ts             # IndexedDB operations
+```
+
+## Module Responsibilities
+
+### Client (`client/`)
+
+**Purpose:** Code that runs in the main browser thread (your application).
+
+**Key Files:**
+- `worker-client.ts` - Main API for communicating with workers
+  - Handles worker initialization (SharedWorker vs ServiceWorker)
+  - Manages tool registration and lifecycle
+  - Handles multi-tab coordination
+  - Provides request/response messaging
+
+**Used by:** Your application code
+
+**Example:**
+```typescript
+import { workerClient } from '@mcp-fe/mcp-worker';
+await workerClient.init();
+```
+
+### Worker (`worker/`)
+
+**Purpose:** Code that runs inside Web Workers (background processing).
+
+**Key Files:**
+- `mcp-controller.ts` - Main controller for MCP server lifecycle
+  - WebSocket connection management
+  - Tool call routing and execution
+  - Tab management coordination
+  - Event storage and querying
+
+- `mcp-server.ts` - MCP server setup using @modelcontextprotocol/sdk
+  - Request handlers (ListTools, CallTool)
+  - Server configuration and capabilities
+
+- `tool-registry.ts` - Dynamic tool management
+  - Tool definition storage
+  - Handler registration and lookup
+  - Tool lifecycle management
+
+- `tab-manager.ts` - Multi-tab coordination
+  - Tab registration and tracking
+  - Active tab management
+  - Smart tool routing across tabs
+
+- `built-in-tools.ts` - Default MCP tools
+  - Event querying tools
+  - Tab listing tools
+  - Navigation history tools
+
+**Used by:** Worker entry points (`mcp-shared-worker.ts`, `mcp-service-worker.ts`)
+
+### Shared (`shared/`)
+
+**Purpose:** Code used by both client and worker contexts.
+
+**Key Files:**
+- `types.ts` - TypeScript type definitions
+  - `UserEvent`, `ToolDefinition`, `ToolHandler`
+  - `TabInfo`, `EventFilters`, etc.
+  - Ensures type consistency across contexts
+
+- `logger.ts` - Logging utilities
+  - Environment-aware logging (dev vs production)
+  - Consistent logging interface
+  - Works in both main thread and workers
+
+- `database.ts` - IndexedDB operations
+  - Event storage and retrieval
+  - Query filtering and pagination
+  - Available in both contexts (IndexedDB works everywhere)
+
+**Used by:** Both client and worker code
+
+## Communication Flow
+
+```
+Application Code
+    ↓ (imports)
+client/worker-client.ts
+    ↓ (postMessage)
+mcp-shared-worker.ts or mcp-service-worker.ts
+    ↓ (uses)
+worker/mcp-controller.ts
+    ↓ (uses)
+worker/mcp-server.ts
+    ↓ (uses)
+worker/tool-registry.ts
+    ↓ (WebSocket)
+MCP Proxy Server
+```
+
+## Import Patterns
+
+### For Application Code
+
+```typescript
+// Import from the main package
+import { workerClient, type ToolDefinition } from '@mcp-fe/mcp-worker';
+```
+
+### Internal Worker Code
+
+```typescript
+// Worker modules import from shared/
+import { logger } from '../shared/logger';
+import type { UserEvent } from '../shared/types';
+
+// Worker modules import from other worker modules
+import { toolRegistry } from './tool-registry';
+import { TabManager } from './tab-manager';
+```
+
+### Internal Client Code
+
+```typescript
+// Client modules import from shared/
+import { logger } from '../shared/logger';
+import type { ToolDefinition } from '../shared/types';
+```
+
+## Why This Structure?
+
+### Clear Separation of Concerns
+- **Client code** only deals with communication and API
+- **Worker code** handles MCP protocol and business logic
+- **Shared code** provides common utilities and types
+
+### Better Tree-Shaking
+- Applications only import client code
+- Worker bundles only include worker code
+- No unnecessary code in either bundle
+
+### Maintainability
+- Easy to find where specific functionality lives
+- Clear boundaries between contexts
+- Prevents accidental mixing of client/worker code
+
+### Future-Proof
+- Ready for splitting into separate npm packages if needed
+- Can add more worker types (e.g., dedicated workers)
+- Easy to add more shared utilities