@mcp-fe/mcp-worker 0.1.2 → 0.1.4

package/docs/architecture.md

@@ -160,12 +160,110 @@ public async handleRegisterTool(toolData: Record<string, unknown>) {
 
 1. **MCP Client** calls tool via MCP protocol
 2. **Worker** receives MCP tool call
-3. **Worker** sends `CALL_TOOL` message to main thread
-4. **Main Thread** executes handler function
+3. **Worker** sends `CALL_TOOL` message to main thread (with targetTabId if specified)
+4. **Main Thread** (specific tab) executes handler function
 5. **Main Thread** sends `TOOL_CALL_RESULT` back
 6. **Worker** resolves promise and returns to MCP
 7. **MCP Client** receives result
 
+## Multi-Tab Support
+
+### Architecture
+
+The library supports multiple browser tabs running the same application, with intelligent routing of tool calls:
+
+```
+┌─────────────────────┐
+│   MCP Client        │
+│   (Claude, etc.)    │
+└──────────┬──────────┘
+           │ MCP Protocol (with optional tabId param)
+           ▼
+┌─────────────────────┐
+│  Shared Worker      │
+│                     │
+│  Tab Registry       │
+│  ├─ Tab 1 (active)  │
+│  ├─ Tab 2           │
+│  └─ Tab 3           │
+│                     │
+│  Tool Registry      │
+│  └─ get_page_info   │
+│     ├─ Tab 1 ✓      │ ← Hybrid routing logic
+│     └─ Tab 2 ✓      │
+└──────────┬──────────┘
+           │ Route to specific tab or active tab
+           ▼
+┌─────────────────────┐
+│  Main Threads       │
+│  ├─ Tab 1 (active)  │ ← Focused/visible tab
+│  └─ Tab 2           │
+└─────────────────────┘
+```
+
+### Tab Management
+
+**Automatic Tab Registration:**
+- Each tab gets unique ID via `crypto.randomUUID()`
+- Stored in `sessionStorage` (persists across refreshes)
+- Registered with worker on init
+
+**Focus Tracking:**
+- Active tab tracked via `window.focus` and `document.visibilitychange`
+- Worker's `TabManager` is the single source of truth for `activeTabId`
+- Use `list_browser_tabs` tool to query which tab is currently active
+
+### Hybrid Routing Strategy
+
+When a tool is called, the worker uses this intelligent logic:
+
+1. **Explicit `tabId` parameter**: Route to specified tab (always respected)
+2. **Only one tab has tool**: Route to that tab automatically (even if not active) ⭐
+3. **Active tab has tool**: Route to focused tab (user is likely working there)
+4. **Active tab lacks tool**: Route to first available tab with the tool
+5. **No active tab**: Route to first available tab (fallback)
+
+**Example:**
+```typescript
+// Scenario: Tab A (inactive) has toolX, Tab B (active) doesn't
+
+// Agent calls without tabId
+get_page_info()
+// → Routes to Tab A automatically (only tab with the tool)
+// User doesn't get an error, tool "just works"
+
+// Agent discovers tabs first
+list_browser_tabs()
+// → [{ tabId: "abc-123", title: "Dashboard", isActive: false }, ...]
+
+// Agent targets specific tab
+get_page_info({ tabId: "abc-123" })
+// → Routes to Dashboard tab precisely
+```
+
+### Tool Schema Enhancement
+
+All tools automatically get optional `tabId` parameter:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    // ... your properties ...
+    "tabId": {
+      "type": "string",
+      "description": "Optional: Target specific tab by ID. If not provided, uses the currently focused tab."
+    }
+  }
+}
+```
+
+### Built-in Meta Tools
+
+**`list_browser_tabs`**: Discover available tabs
+- Returns tab IDs, URLs, titles, active status
+- Use before calling tools with specific tabIds
+
 ## Why This Works
 
 - **Worker**: Runs 24/7, maintains MCP connection

package/docs/guide.md

@@ -409,6 +409,128 @@ function MyComponent() {
 
 See [React Hooks Guide](../../react-event-tracker/REACT_MCP_TOOLS.md) for details.
 
+## Multi-Tab Applications
+
+The library automatically handles multiple browser tabs with intelligent routing.
+
+### How It Works
+
+Each tab gets a unique ID (via `crypto.randomUUID()`) stored in `sessionStorage`. Tools are registered per-tab, and the worker routes calls intelligently.
+
+### Automatic Routing (Smart Strategy)
+
+**Without `tabId` parameter**: Intelligently routes based on availability and focus
+
+```typescript
+// In any tab
+await workerClient.registerTool(
+  'get_page_url',
+  'Get current page URL',
+  { type: 'object', properties: {} },
+  async () => ({
+    content: [{
+      type: 'text',
+      text: window.location.href
+    }]
+  })
+);
+
+// Scenario 1: Only one tab has the tool
+// Tab A: Has get_page_url
+// Tab B: Doesn't have get_page_url (active)
+get_page_url()
+// → Automatically routes to Tab A (even though Tab B is active!)
+// No error, tool "just works"
+
+// Scenario 2: Multiple tabs have the tool
+// Tab A: Has get_page_url
+// Tab B: Has get_page_url (active)
+get_page_url()
+// → Routes to Tab B (active tab preferred when multiple available)
+```
+
+**With `tabId` parameter**: Routes to specific tab precisely
+
+```typescript
+// First, discover available tabs
+list_browser_tabs()
+// → [
+//   { tabId: "abc-123", url: "/dashboard", title: "Dashboard", isActive: true },
+//   { tabId: "def-456", url: "/settings", title: "Settings", isActive: false }
+// ]
+
+// Then target a specific tab
+get_page_url({ tabId: "def-456" })
+// → Routes to Settings tab specifically
+```
+
+### Built-in Meta Tool
+
+**`list_browser_tabs`**: Always available, lists all active tabs
+
+```typescript
+// Returns array of:
+{
+  tabId: string;      // Unique tab identifier
+  url: string;        // Current URL
+  title: string;      // Page title
+  isActive: boolean;  // Is this the focused tab?
+  lastSeen: string;   // ISO timestamp of last activity
+}
+```
+
+### Reference Counting
+
+When multiple tabs register the same tool:
+- Tool is registered once with MCP
+- Worker tracks all tabs that have the tool
+- Unregistration happens when last tab unmounts
+- Handler is always from the target tab's context
+
+### Tab Persistence
+
+Tab IDs persist across page refreshes (stored in `sessionStorage`):
+- Same tab keeps same ID after F5
+- Duplicate tab (Ctrl+K) gets new ID
+- New tab/window gets new ID
+
+### Use Cases
+
+**1. Compare data across tabs:**
+```typescript
+// Get state from multiple tabs
+const dashboardState = await get_react_state({ tabId: "tab-1" });
+const settingsState = await get_react_state({ tabId: "tab-2" });
+```
+
+**2. Debug specific tab:**
+```typescript
+// Agent: "Show me the state of the Settings tab"
+list_browser_tabs()
+// Find tabId for Settings
+get_react_state({ tabId: "settings-tab-id" })
+```
+
+**3. Focus-driven interaction:**
+```typescript
+// Agent: "What's on the current page?"
+get_page_info()  // No tabId needed - uses focused tab
+```
+
+### Debugging Multi-Tab
+
+```typescript
+import { workerClient } from '@mcp-fe/mcp-worker';
+
+// Get current tab info
+console.log(workerClient.getTabInfo());
+// → { tabId: "abc-123", url: "/dashboard", title: "Dashboard" }
+
+// Clear and regenerate tab ID (for testing)
+WorkerClient.clearTabId();
+// Refresh page to get new ID
+```
+
 ## Troubleshooting
 
 ### Tool doesn't register

package/docs/index.md

@@ -10,6 +10,7 @@ Complete guide to all documentation and examples in the MCP Worker library.
 | **See advanced patterns** | [examples/dynamic-tools.ts](../examples/dynamic-tools.ts) |
 | **Learn step-by-step** | [Guide](./guide.md) |
 | **Complete API reference** | [API Reference](./api.md) |
+| **Multi-tab applications** | [Multi-Tab Guide](./multi-tab.md) |
 | **Worker implementation** | [Worker Details](./worker-details.md) |
 | **Use with React** | [React Hooks Guide](../../react-event-tracker/REACT_MCP_TOOLS.md) |
 | **Understand architecture** | [Architecture](./architecture.md) |
@@ -25,6 +26,7 @@ libs/mcp-worker/
 │   ├── index.md                           ← This file
 │   ├── guide.md                           ← Complete guide
 │   ├── api.md                             ← API reference
+│   ├── multi-tab.md                       ← Multi-tab support
 │   ├── worker-details.md                  ← Worker implementation
 │   ├── architecture.md                    ← Technical architecture
 │   └── initialization.md                  ← Init handling
@@ -79,6 +81,12 @@ libs/react-event-tracker/
 ### "How does the proxy pattern work?"
 → [Architecture](./architecture.md)
 
+### "How do I handle multiple tabs?"
+→ [Multi-Tab Guide](./multi-tab.md)
+
+### "What tools are built-in?"
+→ [Multi-Tab Guide](./multi-tab.md#built-in-meta-tool) (list_browser_tabs)
+
 ### "How do I handle initialization?"
 → [Initialization](./initialization.md)