sessionmcp 0.2.0

package/README.md

@@ -0,0 +1,253 @@
+# SessionMCP Relay
+
+> Universal MCP browser bridge — connect Claude Code, Cursor, VS Code Copilot, Windsurf, and Cline to your **existing** Chrome session.
+> No new browser window. Your logins, your cookies, your tabs.
+
+---
+
+## How It Works
+
+SessionMCP has two parts that work together:
+
+```
+AI Tool (Claude Code / Cursor / etc.)
+        ↓  MCP stdio (JSON-RPC 2.0)
+  relay/index.js   ←→   ws://127.0.0.1:7337
+                              ↕  WebSocket + token auth
+             Chrome Extension (SessionMCP)
+                              ↕  chrome.debugger API
+                       Your Chrome Browser
+```
+
+1. **Chrome Extension** — installs into Chrome, holds your session
+2. **Relay** (this folder) — runs locally, bridges MCP ↔ extension via WebSocket
+
+---
+
+## Prerequisites
+
+- **Node.js 18+** — [nodejs.org](https://nodejs.org)
+- **Chrome** with the **SessionMCP extension** installed and connected (badge shows ✓)
+
+---
+
+## Installation
+
+### Option A — npm (recommended, global)
+
+```bash
+npm install -g sessionmcp
+```
+
+### Option B — run directly from this folder
+
+```bash
+cd relay
+npm install
+node index.js
+```
+
+---
+
+## Get Your Token
+
+1. Click the **SessionMCP** icon in Chrome's toolbar
+2. Click **Setup Wizard**
+3. Copy your token from Step 2
+
+The token is generated once on first install and persists. It authenticates the relay to your extension.
+
+---
+
+## Setup by AI Tool
+
+### Claude Code
+
+Config file: `~/.claude/claude_mcp_config.json`
+
+```json
+{
+  "mcpServers": {
+    "sessionmcp": {
+      "command": "sessionmcp",
+      "args": [],
+      "env": {
+        "SESSIONMCP_TOKEN": "YOUR_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+Or if running directly from source:
+
+```json
+{
+  "mcpServers": {
+    "sessionmcp": {
+      "command": "node",
+      "args": ["/absolute/path/to/sessionmcp/relay/index.js"],
+      "env": {
+        "SESSIONMCP_TOKEN": "YOUR_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code. Verify with: `claude mcp list`
+
+---
+
+### Cursor
+
+Config file: `~/.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "sessionmcp": {
+      "command": "sessionmcp",
+      "args": [],
+      "env": {
+        "SESSIONMCP_TOKEN": "YOUR_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor. The MCP server appears in **Settings → MCP**.
+
+---
+
+### Windsurf (Codeium)
+
+Config file: `~/.codeium/windsurf/mcp_config.json`
+
+```json
+{
+  "mcpServers": {
+    "sessionmcp": {
+      "command": "sessionmcp",
+      "args": [],
+      "env": {
+        "SESSIONMCP_TOKEN": "YOUR_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+Restart Windsurf. Check **Cascade → MCP** panel to confirm connected.
+
+---
+
+### Cline / RooCode (VS Code extension)
+
+1. Open VS Code
+2. Go to Cline extension sidebar → **MCP Servers** tab
+3. Click **Add Server** and use:
+
+```json
+{
+  "sessionmcp": {
+    "command": "sessionmcp",
+    "args": [],
+    "env": {
+      "SESSIONMCP_TOKEN": "YOUR_TOKEN_HERE"
+    }
+  }
+}
+```
+
+Or edit `~/.vscode/cline_mcp_settings.json` directly (path varies by OS).
+
+---
+
+### VS Code Copilot (GitHub Copilot)
+
+Config file: `.vscode/mcp.json` in your workspace, or user settings.
+
+```json
+{
+  "servers": {
+    "sessionmcp": {
+      "type": "stdio",
+      "command": "sessionmcp",
+      "args": [],
+      "env": {
+        "SESSIONMCP_TOKEN": "YOUR_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+Enable via **Command Palette → MCP: List Servers**.
+
+---
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `tabs_context` | List all open Chrome tabs with tabId, title, URL, active state |
+| `navigate` | Navigate a tab to a URL and wait for load |
+| `screenshot` | Take a screenshot of a tab — returns base64 PNG |
+| `click` | Click at x,y coordinates on a tab |
+| `type_text` | Type text into the focused element |
+| `evaluate` | Execute JavaScript in a tab and return the result |
+| `get_page_text` | Get the full visible text content of a page |
+| `scroll` | Scroll a tab by x/y pixels |
+| `get_console_logs` | Retrieve console messages from a tab |
+
+---
+
+## Known Limitations
+
+| Limitation | Details |
+|---|---|
+| `chrome://` pages | Chrome blocks debugger access to its own internal pages (`chrome://extensions`, `chrome://settings`, etc.). screenshot, evaluate, click and all CDP tools will return an error on these URLs. Use a regular web page tab instead. |
+| `file://` pages | Local HTML files opened via `file://` also block debugger access by default. |
+| Extension pages | `chrome-extension://` URLs are blocked the same way. |
+| PDFs opened in Chrome | Chrome's built-in PDF viewer blocks CDP commands. |
+| Multiple relay instances | Running two AI tool terminals simultaneously causes port 7337 conflict — second relay loses WebSocket connection. Fix coming in v0.2.0. |
+| Multiple Chrome windows | `tabs_context` returns one active tab per window. If you have 2+ Chrome windows open, it's ambiguous which tab the user is actually looking at. The focused/foreground window is not indicated. Fix coming in v0.2.0 — `tabs_context` will include a `windowFocused` field. |
+
+---
+
+## Troubleshooting
+
+**Extension badge shows ✗ (disconnected)**
+- Is the relay running? Start it: `sessionmcp` or `node index.js`
+- Check the port isn't blocked: `ws://127.0.0.1:7337`
+- Reload the extension in `chrome://extensions`
+
+**"Tool not found" in AI tool**
+- Verify token in `env.SESSIONMCP_TOKEN` matches the extension popup
+- Restart your AI tool after adding the MCP config
+
+**Screenshot returns empty**
+- The debugger permission requires user confirmation on some Chrome versions
+- Click "Allow" if Chrome prompts for debugger access
+
+**Windows path issues**
+- Use forward slashes or escaped backslashes in JSON config paths
+- Prefer the global `npm install -g sessionmcp` to avoid path problems
+
+---
+
+## Security
+
+- Token is 32-byte random (44-char base64url), generated once on install
+- Relay only accepts WebSocket connections with a valid token header
+- All traffic stays on `127.0.0.1` — nothing leaves your machine
+- No cloud, no telemetry, no accounts
+
+---
+
+## License
+
+MIT — © 2026 [Limitless GMTech Solutions, Lda](https://www.limitless-gmtech.com/)
+Built by [Ginquel Moreira](https://www.linkedin.com/in/ginquel-moreira/)

package/index.js

@@ -0,0 +1,476 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Limitless GMTech Solutions, Lda. All rights reserved.
+// Proprietary and confidential. Unauthorized copying or use is prohibited.
+// See LICENSE file for full terms.
+'use strict';
+
+const { WebSocketServer, WebSocket } = require('ws');
+const readline = require('readline');
+
+const PORT = parseInt(process.env.SESSIONMCP_PORT || '7337', 10);
+const TOKEN = process.env.SESSIONMCP_TOKEN || '';
+
+// ── STATE ───────────────────────────────────────────────────────────────────
+let isPrimary = false;
+
+// Primary-only
+let extensionSocket = null;
+const relayPeers = new Set();
+
+// Secondary-only
+let primarySocket = null;
+
+// Shared: in-flight requests waiting for a response
+const pendingRequests = new Map(); // id → { resolve, reject, timer }
+let nextId = 1;
+
+// ── PRIMARY: WS SERVER ──────────────────────────────────────────────────────
+function startServer() {
+  const wss = new WebSocketServer({ port: PORT, host: '127.0.0.1' });
+
+  wss.once('listening', () => {
+    isPrimary = true;
+    process.stderr.write(`[SessionMCP Relay] PRIMARY — listening on ws://127.0.0.1:${PORT}\n`);
+  });
+
+  wss.once('error', (err) => {
+    wss.close();
+    if (err.code === 'EADDRINUSE') {
+      process.stderr.write(`[SessionMCP Relay] SECONDARY — port ${PORT} in use, connecting to primary\n`);
+      connectToPrimary();
+    } else {
+      process.stderr.write(`[SessionMCP Relay] WS server error: ${err.message}\n`);
+    }
+  });
+
+  wss.on('connection', (socket, req) => {
+    const url = new URL(req.url, `http://127.0.0.1:${PORT}`);
+
+    // Token auth
+    if (TOKEN && url.searchParams.get('token') !== TOKEN) {
+      socket.close(4001, 'Invalid token');
+      return;
+    }
+
+    if (url.searchParams.get('relay') === '1') {
+      handleRelayPeer(socket);
+    } else {
+      handleExtension(socket);
+    }
+  });
+}
+
+function handleExtension(socket) {
+  extensionSocket = socket;
+  process.stderr.write('[SessionMCP Relay] Extension connected\n');
+
+  socket.on('message', (data) => {
+    try {
+      const msg = JSON.parse(data.toString());
+      if (msg.type === 'ping') return;
+      resolveRequest(msg);
+    } catch (e) {
+      process.stderr.write(`[SessionMCP Relay] Bad message from extension: ${e}\n`);
+    }
+  });
+
+  socket.on('close', () => {
+    if (extensionSocket === socket) extensionSocket = null;
+    process.stderr.write('[SessionMCP Relay] Extension disconnected\n');
+  });
+}
+
+function handleRelayPeer(socket) {
+  relayPeers.add(socket);
+  process.stderr.write(`[SessionMCP Relay] Secondary relay connected (${relayPeers.size} peers)\n`);
+
+  socket.on('message', async (data) => {
+    try {
+      const { id, method, params } = JSON.parse(data.toString());
+      try {
+        const result = await sendToExtension(method, params);
+        socket.send(JSON.stringify({ id, result }));
+      } catch (err) {
+        socket.send(JSON.stringify({ id, error: err.message }));
+      }
+    } catch (e) {
+      process.stderr.write(`[SessionMCP Relay] Bad message from peer: ${e}\n`);
+    }
+  });
+
+  socket.on('close', () => {
+    relayPeers.delete(socket);
+    process.stderr.write(`[SessionMCP Relay] Secondary relay disconnected (${relayPeers.size} peers)\n`);
+  });
+}
+
+// ── SECONDARY: CONNECT TO PRIMARY ───────────────────────────────────────────
+function connectToPrimary() {
+  const url = `ws://127.0.0.1:${PORT}${TOKEN ? `?token=${TOKEN}&relay=1` : '?relay=1'}`;
+
+  try {
+    primarySocket = new WebSocket(url);
+  } catch (e) {
+    primarySocket = null;
+    scheduleBecomePrimary();
+    return;
+  }
+
+  primarySocket.on('open', () => {
+    process.stderr.write('[SessionMCP Relay] Connected to primary relay\n');
+  });
+
+  primarySocket.on('message', (data) => {
+    try {
+      const msg = JSON.parse(data.toString());
+      resolveRequest(msg);
+    } catch (e) {
+      process.stderr.write(`[SessionMCP Relay] Bad message from primary: ${e}\n`);
+    }
+  });
+
+  primarySocket.on('close', () => {
+    primarySocket = null;
+    process.stderr.write('[SessionMCP Relay] Primary relay gone — attempting takeover\n');
+    scheduleBecomePrimary();
+  });
+
+  primarySocket.on('error', () => {
+    primarySocket = null;
+    scheduleBecomePrimary();
+  });
+}
+
+// Jitter prevents thundering herd when multiple secondaries race to become primary
+function scheduleBecomePrimary() {
+  const delay = 200 + Math.floor(Math.random() * 400);
+  setTimeout(() => {
+    isPrimary = false;
+    startServer();
+  }, delay);
+}
+
+// ── SHARED: REQUEST RESOLUTION ───────────────────────────────────────────────
+function resolveRequest(msg) {
+  if (!msg.id || !pendingRequests.has(msg.id)) return;
+  const { resolve, reject, timer } = pendingRequests.get(msg.id);
+  clearTimeout(timer);
+  pendingRequests.delete(msg.id);
+  if (msg.error) reject(new Error(msg.error));
+  else resolve(msg.result);
+}
+
+// ── SHARED: SEND TOOL CALL ───────────────────────────────────────────────────
+function sendToExtension(method, params) {
+  return new Promise((resolve, reject) => {
+    let target;
+
+    if (isPrimary) {
+      if (!extensionSocket || extensionSocket.readyState !== WebSocket.OPEN) {
+        reject(new Error('SessionMCP extension not connected. Is Chrome open with the SessionMCP extension installed?'));
+        return;
+      }
+      target = extensionSocket;
+    } else {
+      if (!primarySocket || primarySocket.readyState !== WebSocket.OPEN) {
+        reject(new Error('SessionMCP not connected to primary relay. Retry in a moment.'));
+        return;
+      }
+      target = primarySocket;
+    }
+
+    const id = nextId++;
+    const timer = setTimeout(() => {
+      if (pendingRequests.has(id)) {
+        pendingRequests.delete(id);
+        reject(new Error(`Extension command timed out after 30s`));
+      }
+    }, 30000);
+
+    pendingRequests.set(id, { resolve, reject, timer });
+    target.send(JSON.stringify({ id, method, params }));
+  });
+}
+
+// ── MCP STDIO SERVER ─────────────────────────────────────────────────────────
+const TOOLS = [
+  {
+    name: 'tabs_context',
+    description: 'List all open Chrome tabs. Call this first to get tabId values for other tools.',
+    inputSchema: { type: 'object', properties: {}, required: [] }
+  },
+  {
+    name: 'navigate',
+    description: 'Navigate a Chrome tab to a URL.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number', description: 'Tab ID from tabs_context' },
+        url: { type: 'string', description: 'URL to navigate to' }
+      },
+      required: ['tabId', 'url']
+    }
+  },
+  {
+    name: 'screenshot',
+    description: 'Take a screenshot of a Chrome tab. Returns base64 PNG. Optionally clip to a specific region.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number', description: 'Tab ID from tabs_context' },
+        clip: {
+          type: 'object',
+          description: 'Optional crop region in CSS pixels',
+          properties: {
+            x: { type: 'number' },
+            y: { type: 'number' },
+            width: { type: 'number' },
+            height: { type: 'number' }
+          },
+          required: ['x', 'y', 'width', 'height']
+        }
+      },
+      required: ['tabId']
+    }
+  },
+  {
+    name: 'click',
+    description: 'Click at coordinates in a Chrome tab.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' },
+        x: { type: 'number', description: 'X coordinate in CSS pixels' },
+        y: { type: 'number', description: 'Y coordinate in CSS pixels' }
+      },
+      required: ['tabId', 'x', 'y']
+    }
+  },
+  {
+    name: 'type_text',
+    description: 'Type text into the focused element in a Chrome tab.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' },
+        text: { type: 'string', description: 'Text to type' }
+      },
+      required: ['tabId', 'text']
+    }
+  },
+  {
+    name: 'evaluate',
+    description: 'Execute JavaScript in a Chrome tab and return the result.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' },
+        expression: { type: 'string', description: 'JavaScript expression to evaluate. No return statements.' }
+      },
+      required: ['tabId', 'expression']
+    }
+  },
+  {
+    name: 'get_page_text',
+    description: 'Get the visible text content of a Chrome tab.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' }
+      },
+      required: ['tabId']
+    }
+  },
+  {
+    name: 'scroll',
+    description: 'Scroll a Chrome tab by pixels.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' },
+        deltaY: { type: 'number', description: 'Pixels to scroll (positive = down, negative = up)' },
+        x: { type: 'number', description: 'X coordinate (default: center)' },
+        y: { type: 'number', description: 'Y coordinate (default: center)' }
+      },
+      required: ['tabId', 'deltaY']
+    }
+  },
+  {
+    name: 'get_console_logs',
+    description: 'Get browser console log messages from a Chrome tab.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' },
+        limit: { type: 'number', description: 'Max messages to return (default: 50)' }
+      },
+      required: ['tabId']
+    }
+  },
+  {
+    name: 'press_key',
+    description: 'Press a keyboard key or shortcut in a Chrome tab. Supports named keys (Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, F5, Space) and modifier combos like Ctrl+A, Ctrl+C, Ctrl+V, Ctrl+Z, Shift+Tab.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' },
+        key: { type: 'string', description: 'Key name or combo, e.g. "Enter", "Tab", "Escape", "Ctrl+A", "Shift+Tab"' }
+      },
+      required: ['tabId', 'key']
+    }
+  },
+  {
+    name: 'click_element',
+    description: 'Click a page element by CSS selector. More reliable than click() with coordinates — finds the element, computes its center, and clicks it. Use get_dom_snapshot first to discover selectors.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' },
+        selector: { type: 'string', description: 'CSS selector, e.g. "#submit-btn", "button[type=submit]", ".nav-link:first-child"' }
+      },
+      required: ['tabId', 'selector']
+    }
+  },
+  {
+    name: 'get_dom_snapshot',
+    description: 'Get a structured map of all interactive elements on the page (buttons, inputs, links, selects) with their text, CSS selectors, and x/y coordinates. Call this before click_element to discover what is on the page.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' }
+      },
+      required: ['tabId']
+    }
+  },
+  {
+    name: 'wait_for',
+    description: 'Wait until a condition is met in a Chrome tab. Polls every 300ms up to timeout. Use selector to wait for an element to appear, selector_hidden for it to disappear, text to wait for text, or network_idle to wait for requests to settle.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' },
+        selector: { type: 'string', description: 'CSS selector — wait until visible' },
+        selector_hidden: { type: 'string', description: 'CSS selector — wait until gone/hidden' },
+        text: { type: 'string', description: 'Text — wait until present in body' },
+        network_idle: { type: 'boolean', description: 'Wait for network activity to settle (500ms heuristic)' },
+        timeout: { type: 'number', description: 'Max wait in ms (default 10000)' }
+      },
+      required: ['tabId']
+    }
+  },
+  {
+    name: 'fill_form',
+    description: 'Fill a form field by CSS selector. Works with input, textarea, select, checkbox, and radio. Dispatches native input/change events so React, Angular, and Vue frameworks detect the change.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' },
+        selector: { type: 'string', description: 'CSS selector for the field, e.g. "#email", "input[name=username]"' },
+        value: { description: 'Value to set. String for text/select, true/false for checkbox/radio.' }
+      },
+      required: ['tabId', 'selector', 'value']
+    }
+  },
+  {
+    name: 'network_requests',
+    description: 'Return the last N completed network requests (XHR, Fetch, etc.) captured since the debugger attached to this tab.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' },
+        limit: { type: 'number', description: 'Max requests to return (default 20)' }
+      },
+      required: ['tabId']
+    }
+  },
+  {
+    name: 'handle_dialog',
+    description: 'Accept or dismiss a JavaScript dialog (alert, confirm, prompt) in a Chrome tab.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' },
+        accept: { type: 'boolean', description: 'true to accept/OK, false to dismiss/Cancel (default true)' },
+        promptText: { type: 'string', description: 'Text to fill in for prompt dialogs' }
+      },
+      required: ['tabId']
+    }
+  },
+  {
+    name: 'hover',
+    description: 'Move the mouse to coordinates in a Chrome tab (triggers hover/tooltip effects).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'number' },
+        x: { type: 'number', description: 'X coordinate in CSS pixels' },
+        y: { type: 'number', description: 'Y coordinate in CSS pixels' }
+      },
+      required: ['tabId', 'x', 'y']
+    }
+  }
+];
+
+async function handleMcpRequest(req) {
+  const { id, method, params = {} } = req;
+
+  if (method === 'initialize') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'sessionmcp', version: '0.1.0' }
+      }
+    };
+  }
+
+  if (method === 'tools/list') {
+    return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+  }
+
+  if (method === 'tools/call') {
+    const { name, arguments: args = {} } = params;
+
+    try {
+      const result = await sendToExtension(name, args);
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result, null, 2) }]
+        }
+      };
+    } catch (err) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          content: [{ type: 'text', text: `Error: ${err.message}` }],
+          isError: true
+        }
+      };
+    }
+  }
+
+  return { jsonrpc: '2.0', id, result: {} };
+}
+
+const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on('line', async (line) => {
+  if (!line.trim()) return;
+  try {
+    const req = JSON.parse(line);
+    if (req.id === undefined || req.id === null) return;
+    const response = await handleMcpRequest(req);
+    process.stdout.write(JSON.stringify(response) + '\n');
+  } catch (e) {
+    process.stderr.write(`[SessionMCP Relay] Parse error: ${e}\n`);
+  }
+});
+
+rl.on('close', () => process.exit(0));
+
+// Boot
+startServer();

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "sessionmcp",
+  "version": "0.2.0",
+  "description": "Universal MCP browser bridge — connect Claude Code, Cursor, VS Code, Windsurf & Cline to your existing Chrome session. No new browser. Real sessions, real cookies.",
+  "bin": {
+    "sessionmcp": "./index.js"
+  },
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "engines": { "node": ">=18" },
+  "keywords": [
+    "mcp",
+    "browser",
+    "chrome",
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "cline",
+    "bridge",
+    "model-context-protocol"
+  ],
+  "author": "Ginquel Moreira <contact@limitless-gmtech.com> (https://limitless-gmtech.com)",
+  "license": "MIT",
+  "homepage": "https://sessionmcp.limitless-gmtech.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devGinMoreira/sessionmcp"
+  },
+  "bugs": {
+    "url": "https://github.com/devGinMoreira/sessionmcp/issues"
+  }
+}