mcp-web-bridge 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hemanth HM
+
+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,114 @@
+# mcp-web-bridge
+
+Connect any MCP server to Chrome's WebMCP API.
+
+You have MCP servers. You want them in the browser. This module connects to a remote MCP server, discovers its tools, and registers them with `navigator.modelContext`.
+
+```bash
+npm install mcp-web-bridge
+```
+
+## Usage
+
+```javascript
+import { WebMCPBridge } from 'mcp-web-bridge';
+
+const bridge = new WebMCPBridge('https://mcp.example.com');
+await bridge.connect();
+bridge.register();
+```
+
+That's it. Tools are now available to Chrome's AI agent.
+
+## With context enrichment
+
+```javascript
+const bridge = new WebMCPBridge('https://mcp.example.com', {
+  enrichContext: (toolName, args) => ({
+    ...args,
+    user_locale: navigator.language,
+    user_timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+  }),
+  onResponse: (toolName, result) => {
+    console.log(`[${toolName}]`, result);
+    return result;
+  },
+});
+
+await bridge.connect();
+bridge.register();
+```
+
+## With auth
+
+```javascript
+const bridge = new WebMCPBridge('https://mcp.example.com');
+bridge.setAuth({ type: 'bearer', token: 'sk-...' });
+await bridge.connect();
+```
+
+Supports `bearer`, `apikey`, and `basic` auth. OAuth with PKCE is handled by the `MCPAuth` class.
+
+## Custom headers
+
+```javascript
+const bridge = new WebMCPBridge('https://mcp.example.com', {
+  headers: {
+    'X-Custom-Header': 'value',
+    'Authorization': 'Bearer sk-...',
+  },
+});
+```
+
+Custom headers are merged into every request. Auth headers from `setAuth()` are applied first, then your custom headers override.
+
+## Add page-local tools
+
+```javascript
+bridge.register([
+  {
+    name: 'get_selection',
+    description: 'Get the currently selected text on the page',
+    inputSchema: { type: 'object', properties: {} },
+    execute: async () => ({
+      content: [{ type: 'text', text: window.getSelection().toString() }],
+    }),
+  },
+]);
+```
+
+Mix remote MCP tools with local browser capabilities.
+
+## API
+
+### `new WebMCPBridge(serverUrl, options?)`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `headers` | `object` | Custom headers merged into every request |
+| `enrichContext` | `(name, args) => args` | Enrich tool args before proxying |
+| `onToolCall` | `(name, args) => void` | Called before each tool call |
+| `onResponse` | `(name, result) => result` | Transform responses |
+| `onError` | `(name, error) => void` | Error handler |
+| `logger` | `object` | Custom logger (default: `console`) |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `connect()` | `{ tools, prompts, resources }` | Initialize + discover |
+| `register(extraTools?)` | `tool[]` | Register with WebMCP |
+| `callTool(name, args)` | `result` | Call a tool |
+| `getPrompt(name, args)` | `result` | Get a prompt |
+| `readResource(uri)` | `result` | Read a resource |
+| `setAuth({ type, token })` | — | Set auth before connecting |
+| `disconnect()` | — | Clear context + logout |
+
+## Browser requirements
+
+- Chrome 146+ with `chrome://flags/#enable-webmcp-testing`
+- Without WebMCP, `connect()` and `callTool()` still work — you just can't `register()`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+    "name": "mcp-web-bridge",
+    "version": "1.0.0",
+    "description": "Connect any MCP server to Chrome's WebMCP API",
+    "type": "module",
+    "main": "src/index.js",
+    "module": "src/index.js",
+    "exports": {
+        ".": "./src/index.js"
+    },
+    "files": [
+        "src/"
+    ],
+    "keywords": [
+        "mcp",
+        "webmcp",
+        "model-context-protocol",
+        "chrome",
+        "ai",
+        "agents",
+        "browser"
+    ],
+    "author": "Hemanth HM <hemanth.hm@gmail.com>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/hemanth/webmcp-bridge"
+    },
+    "homepage": "https://github.com/hemanth/webmcp-bridge"
+}

package/src/auth.js

@@ -0,0 +1,139 @@
+/**
+ * MCP Auth — handles OAuth (PKCE), API key, Basic, and Bearer auth.
+ */
+export class MCPAuth {
+    constructor(serverUrl) {
+        this.serverUrl = serverUrl;
+        this.token = null;
+        this.tokenType = 'Bearer';
+        this.clientId = null;
+        this.authMeta = null;
+        this.sessionId = null;
+    }
+
+    async discover() {
+        const baseUrl = new URL(this.serverUrl).origin;
+        const metaUrl = `${baseUrl}/.well-known/oauth-authorization-server`;
+
+        try {
+            const res = await fetch(metaUrl, {
+                method: 'GET',
+                headers: { Accept: 'application/json' },
+            });
+
+            if (res.status === 404 || !res.ok) {
+                return { type: 'none', requiresAuth: false };
+            }
+
+            const meta = await res.json();
+            this.authMeta = meta;
+
+            const thirdParty = meta.identity_providers || meta.supported_identity_providers || [];
+
+            return {
+                type: 'oauth',
+                requiresAuth: true,
+                meta,
+                isOwnIdp: thirdParty.length === 0 && !!meta.authorization_endpoint,
+                thirdParty,
+                supportsRegistration: !!meta.registration_endpoint,
+            };
+        } catch {
+            return { type: 'none', requiresAuth: false };
+        }
+    }
+
+    async registerClient(redirectUri) {
+        if (!this.authMeta?.registration_endpoint) {
+            throw new Error('Server does not support dynamic client registration');
+        }
+
+        const res = await fetch(this.authMeta.registration_endpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                client_name: 'WebMCP Bridge',
+                redirect_uris: [redirectUri],
+                grant_types: ['authorization_code', 'refresh_token'],
+                response_types: ['code'],
+                token_endpoint_auth_method: 'none',
+                scope: 'openid profile mcp:tools mcp:read mcp:write',
+            }),
+        });
+
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            throw new Error(err.error_description || 'Client registration failed');
+        }
+
+        const data = await res.json();
+        this.clientId = data.client_id;
+        return data;
+    }
+
+    async generatePKCE() {
+        const array = new Uint8Array(32);
+        crypto.getRandomValues(array);
+        const verifier = Array.from(array, b => b.toString(16).padStart(2, '0')).join('');
+
+        const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+        const challenge = btoa(String.fromCharCode(...new Uint8Array(hash)))
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=+$/, '');
+
+        return { verifier, challenge };
+    }
+
+    setApiKey(apiKey) {
+        this.token = apiKey;
+        this.tokenType = 'X-API-Key';
+    }
+
+    setBasicAuth(username, password) {
+        this.token = btoa(`${username}:${password}`);
+        this.tokenType = 'Basic';
+    }
+
+    setBearerToken(token) {
+        this.token = token;
+        this.tokenType = 'Bearer';
+    }
+
+    setSessionId(id) {
+        this.sessionId = id;
+    }
+
+    getHeaders(includeSession = true) {
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+        };
+
+        if (this.token) {
+            if (this.tokenType === 'X-API-Key') {
+                headers['X-API-Key'] = this.token;
+            } else if (this.tokenType === 'Basic') {
+                headers['Authorization'] = `Basic ${this.token}`;
+            } else {
+                headers['Authorization'] = `Bearer ${this.token}`;
+            }
+        }
+
+        if (includeSession && this.sessionId) {
+            headers['Mcp-Session-Id'] = this.sessionId;
+        }
+
+        return headers;
+    }
+
+    isAuthenticated() {
+        return !!this.token;
+    }
+
+    logout() {
+        this.token = null;
+        this.clientId = null;
+        this.sessionId = null;
+    }
+}

package/src/index.js

@@ -0,0 +1,235 @@
+import { MCPAuth } from './auth.js';
+import { parseSSEorJSON } from './parser.js';
+
+export { MCPAuth } from './auth.js';
+export { parseSSEorJSON } from './parser.js';
+
+/**
+ * WebMCP Bridge — connect any MCP server to Chrome's WebMCP API.
+ *
+ * @example
+ * const bridge = new WebMCPBridge('https://mcp.example.com');
+ * await bridge.connect();
+ * // Tools are now registered with navigator.modelContext
+ */
+export class WebMCPBridge {
+    constructor(serverUrl, options = {}) {
+        this.serverUrl = serverUrl;
+        this.auth = new MCPAuth(serverUrl);
+        this.tools = [];
+        this.prompts = [];
+        this.resources = [];
+        this.serverInfo = null;
+        this.capabilities = null;
+
+        // Custom headers merged into every request
+        this.headers = options.headers || {};
+
+        // Hooks
+        this.onToolCall = options.onToolCall || null;
+        this.onResponse = options.onResponse || null;
+        this.onError = options.onError || null;
+        this.enrichContext = options.enrichContext || null;
+        this.logger = options.logger || console;
+    }
+
+    /**
+     * Set auth credentials before connecting.
+     */
+    setAuth({ type, token, username, password }) {
+        if (type === 'bearer') this.auth.setBearerToken(token);
+        else if (type === 'apikey') this.auth.setApiKey(token);
+        else if (type === 'basic') this.auth.setBasicAuth(username, password);
+    }
+
+    /**
+     * Connect to the MCP server, discover capabilities, register with WebMCP.
+     */
+    async connect() {
+        // 1. Initialize session
+        const initPayload = {
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+                protocolVersion: '2024-11-05',
+                capabilities: { tools: {} },
+                clientInfo: { name: 'webmcp-bridge', version: '1.0.0' },
+            },
+        };
+
+        const initResponse = await fetch(this.serverUrl, {
+            method: 'POST',
+            headers: this._getHeaders(false),
+            body: JSON.stringify(initPayload),
+        });
+
+        if (initResponse.status === 401 || initResponse.status === 403) {
+            throw new Error('Authentication required');
+        }
+
+        const initData = await parseSSEorJSON(initResponse);
+        if (initData.error) throw new Error(initData.error.message || 'Initialize failed');
+
+        // Capture session ID
+        const sessionId = initResponse.headers.get('Mcp-Session-Id');
+        if (sessionId) this.auth.setSessionId(sessionId);
+
+        this.serverInfo = initData.result?.serverInfo || null;
+        this.capabilities = initData.result?.capabilities || null;
+
+        // 2. Discover tools, prompts, resources
+        this.tools = await this._list('tools/list', 'tools');
+        this.prompts = await this._list('prompts/list', 'prompts');
+        this.resources = await this._list('resources/list', 'resources');
+
+        this.logger.log(`[webmcp-bridge] Connected. ${this.tools.length} tools, ${this.prompts.length} prompts, ${this.resources.length} resources.`);
+
+        return {
+            serverInfo: this.serverInfo,
+            capabilities: this.capabilities,
+            tools: this.tools,
+            prompts: this.prompts,
+            resources: this.resources,
+        };
+    }
+
+    /**
+     * Register discovered tools with navigator.modelContext (WebMCP).
+     * Call after connect(). Optionally pass extra page-local tools.
+     */
+    register(extraTools = []) {
+        if (!navigator.modelContext) {
+            throw new Error('navigator.modelContext not available. Enable chrome://flags/#enable-webmcp-testing');
+        }
+
+        const webMCPTools = this.tools.map(tool => ({
+            name: tool.name,
+            description: tool.description || '',
+            inputSchema: tool.inputSchema || { type: 'object', properties: {} },
+            execute: async (args) => this.callTool(tool.name, args),
+        }));
+
+        const allTools = [...webMCPTools, ...extraTools];
+
+        navigator.modelContext.provideContext({ tools: allTools });
+        this.logger.log(`[webmcp-bridge] Registered ${allTools.length} tools with WebMCP.`);
+
+        return allTools;
+    }
+
+    /**
+     * Call a tool on the remote MCP server.
+     */
+    async callTool(name, args = {}) {
+        // Enrich args if hook is provided
+        const enriched = this.enrichContext ? await this.enrichContext(name, args) : args;
+
+        // Notify onToolCall hook
+        if (this.onToolCall) this.onToolCall(name, enriched);
+
+        const payload = {
+            jsonrpc: '2.0',
+            id: Date.now(),
+            method: 'tools/call',
+            params: { name, arguments: enriched },
+        };
+
+        try {
+            const response = await fetch(this.serverUrl, {
+                method: 'POST',
+                headers: this._getHeaders(),
+                body: JSON.stringify(payload),
+            });
+
+            const result = await parseSSEorJSON(response);
+
+            if (result.error) {
+                const err = new Error(result.error.message || 'Tool call failed');
+                if (this.onError) this.onError(name, err);
+                return { content: [{ type: 'text', text: `Error: ${result.error.message}` }] };
+            }
+
+            // Transform response if hook is provided
+            let output = result.result?.content ? result.result : {
+                content: [{
+                    type: 'text',
+                    text: typeof result.result === 'string' ? result.result : JSON.stringify(result.result, null, 2),
+                }],
+            };
+
+            if (this.onResponse) output = await this.onResponse(name, output) || output;
+
+            return output;
+        } catch (error) {
+            if (this.onError) this.onError(name, error);
+            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+        }
+    }
+
+    /**
+     * Get a prompt from the server.
+     */
+    async getPrompt(name, args = {}) {
+        return this._rpc('prompts/get', { name, arguments: args });
+    }
+
+    /**
+     * Read a resource from the server.
+     */
+    async readResource(uri) {
+        return this._rpc('resources/read', { uri });
+    }
+
+    /**
+     * Disconnect — clear context.
+     */
+    disconnect() {
+        if (navigator.modelContext?.clearContext) {
+            navigator.modelContext.clearContext();
+        }
+        this.tools = [];
+        this.prompts = [];
+        this.resources = [];
+        this.auth.logout();
+        this.logger.log('[webmcp-bridge] Disconnected.');
+    }
+
+    // --- Internal ---
+
+    _getHeaders(includeSession = true) {
+        return { ...this.auth.getHeaders(includeSession), ...this.headers };
+    }
+
+    async _list(method, key) {
+        try {
+            const result = await this._rpc(method, {});
+            return result?.[key] || [];
+        } catch {
+            return [];
+        }
+    }
+
+    async _rpc(method, params) {
+        const response = await fetch(this.serverUrl, {
+            method: 'POST',
+            headers: this._getHeaders(),
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: Date.now(),
+                method,
+                params,
+            }),
+        });
+
+        if (response.status === 401 || response.status === 403) {
+            throw new Error('Authentication failed');
+        }
+
+        const data = await parseSSEorJSON(response);
+        if (data.error) throw new Error(data.error.message || `${method} failed`);
+        return data.result;
+    }
+}
+
+export default WebMCPBridge;

package/src/parser.js

@@ -0,0 +1,37 @@
+/**
+ * Parse SSE or JSON response from MCP server.
+ */
+export async function parseSSEorJSON(response) {
+    const contentType = response.headers.get('content-type') || '';
+    const text = await response.text();
+
+    if (contentType.includes('application/json')) {
+        return JSON.parse(text);
+    }
+
+    if (contentType.includes('text/event-stream') || text.startsWith('event:')) {
+        const events = text.split('\n\n').map(c => c.trim()).filter(Boolean);
+        const payloads = [];
+
+        for (const chunk of events) {
+            const data = chunk
+                .split('\n')
+                .filter(l => l.startsWith('data:'))
+                .map(l => l.substring(5).trim())
+                .filter(Boolean)
+                .join('\n');
+            if (!data) continue;
+            try { payloads.push(JSON.parse(data)); } catch { }
+        }
+
+        if (payloads.length > 0) return payloads[payloads.length - 1];
+
+        try { return JSON.parse(text); } catch {
+            throw new Error(`Failed to parse SSE response: ${text.substring(0, 100)}...`);
+        }
+    }
+
+    try { return JSON.parse(text); } catch {
+        throw new Error(`Unexpected response format: ${text.substring(0, 100)}...`);
+    }
+}