@aikeymouse/chromelink-mcp 1.2.0

package/README.md

@@ -0,0 +1,282 @@
+# ChromeLink MCP Server
+
+Model Context Protocol (MCP) server that exposes Chrome browser automation capabilities to AI agents like Claude, GPT, and other MCP-compatible tools.
+
+## Installation
+
+### Option 1: NPM (Recommended)
+
+```bash
+npm install -g @aikeymouse/chromelink-mcp
+```
+
+Then configure in your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "chrome-link": {
+      "command": "chromelink-mcp"
+    }
+  }
+}
+```
+
+### Option 2: From Source
+
+Clone the repository and use the server directly:
+
+```bash
+git clone https://github.com/aikeymouse/chrome-link.git
+cd chrome-link/mcp-server
+npm install
+```
+
+Configure with absolute path:
+
+```json
+{
+  "mcpServers": {
+    "chrome-link": {
+      "command": "node",
+      "args": ["/absolute/path/to/chrome-link/mcp-server/index.js"]
+    }
+  }
+}
+```
+
+## Prerequisites
+
+1. **Install ChromeLink extension** in Chrome
+2. **Start browser-link-server** (automatically started by extension on first connection)
+
+## Local Development
+
+For local development with file dependencies:
+
+```bash
+cd chrome-link/mcp-server
+npm install  # Creates symlink to ../clients/node
+```
+
+The MCP server uses a local file dependency (`"@aikeymouse/chromelink-client": "file:../clients/node"`) for development. This is automatically converted to an npm dependency (`^1.2.0`) during publishing via the `prepublishOnly` script.
+
+After version changes, update the symlink:
+```bash
+cd mcp-server && npm install
+```
+
+## Running the MCP Server
+
+### From NPM Installation
+```bash
+chromelink-mcp
+```
+
+### From Source
+```bash
+node mcp-server/index.js
+```
+
+The MCP server will:
+- Connect to `ws://localhost:9000` (browser-link-server)
+- Expose 18 Chrome automation tools via MCP protocol
+- Communicate with AI agents via stdio
+
+## Available Tools
+
+### Tab Management
+- `chrome_list_tabs` - List all open tabs
+- `chrome_open_tab` - Open new tab with URL
+- `chrome_navigate_tab` - Navigate tab to URL
+- `chrome_switch_tab` - Switch to specific tab
+- `chrome_close_tab` - Close a tab
+- `chrome_get_active_tab` - Get active tab info
+
+### Navigation History
+- `chrome_go_back` - Navigate back in history
+- `chrome_go_forward` - Navigate forward in history
+
+### DOM Interaction
+- `chrome_wait_for_element` - Wait for element to appear
+- `chrome_get_text` - Get element text content
+- `chrome_click` - Click an element
+- `chrome_type` - Type text into element
+
+### JavaScript Execution
+- `chrome_execute_js` - Execute arbitrary JavaScript
+- `chrome_call_helper` - Call predefined helper functions:
+  - **Element Interaction**: clickElement, typeText, appendChar, clearContentEditable
+  - **Element Query**: getText, getHTML, getLastHTML, elementExists, isVisible, waitForElement
+  - **Element Highlighting**: highlightElement, removeHighlights
+  - **Element Positioning**: getElementBounds, scrollElementIntoView
+  - **Element Inspection**: inspectElement, getContainerElements
+
+### Screenshots
+- `chrome_capture_screenshot` - Capture tab screenshot (PNG/JPEG)
+
+### Script Injection
+- `chrome_register_injection` - Register content script
+- `chrome_unregister_injection` - Unregister content script
+
+## Configuration for AI Agents
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "chrome-link": {
+      "command": "node",
+      "args": ["/absolute/path/to/chrome-driver-extension/mcp-server/index.js"]
+    }
+  }
+}
+```
+
+**Important**: Use absolute path to `index.js`
+
+After configuration:
+1. Restart Claude Desktop
+2. Start a conversation
+3. Ask Claude: "What Chrome tools do you have?"
+
+### Example Prompts
+
+```
+Open https://github.com in a new Chrome tab
+
+List all my open Chrome tabs
+
+Go to https://example.com and get the text of the h1 element
+
+Take a screenshot of the current tab in PNG format
+
+Fill out the login form:
+1. Open https://the-internet.herokuapp.com/login
+2. Type "tomsmith" in #username
+3. Type "SuperSecretPassword!" in #password
+4. Click the login button
+```
+
+## Architecture
+
+```
+AI Agent (Claude/GPT)
+    ↓ stdio (MCP protocol)
+MCP Server (this file)
+    ↓ WebSocket (ws://localhost:9000)
+browser-link-server
+    ↓ native messaging (stdin/stdout)
+Chrome Extension
+```
+
+**Key Design Points:**
+- MCP server runs as **separate process** (avoids stdio conflict)
+- Uses existing WebSocket client (thin wrapper, no code duplication)
+- Zero changes needed to browser-link-server or extension
+- Multiple MCP servers can connect simultaneously
+
+## Testing
+
+### Manual Test
+
+```bash
+# Start browser-link-server (if not auto-started)
+node native-host/browser-link-server.js
+
+# In another terminal, test MCP server
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node mcp-server/index.js
+```
+
+Expected output:
+```json
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"chrome-link","version":"1.0.0"}}}
+```
+
+### Test Tool Invocation
+
+```bash
+# Create test file
+cat > /tmp/test-mcp.json << 'EOF'
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}
+{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"chrome_list_tabs","arguments":{}}}
+EOF
+
+# Run test
+cat /tmp/test-mcp.json | node native-host/mcp-server.js 2>/dev/null
+```
+
+### Using MCP Inspector
+
+```bash
+npm install -g @modelcontextprotocol/inspector
+npx @modelcontextprotocol/inspector node mcp-server/index.js
+```
+
+Opens web UI for testing tools interactively.
+
+## Troubleshooting
+
+### MCP Server Won't Connect
+
+**Error**: `Failed to connect to browser-link-server`
+
+**Solution**:
+1. Check Chrome extension is installed: `chrome://extensions/`
+2. Check browser-link-server is running: `curl http://localhost:9000/session` (expect `{"status":"ready","message":"Upgrade to WebSocket"}`)
+3. Test WebSocket manually: `wscat -c ws://localhost:9000`
+
+### Tools Not Showing in Claude
+
+**Error**: Claude doesn't list Chrome tools
+
+**Solution**:
+1. Verify config file path is absolute (not relative)
+2. Check JSON syntax: `python3 -m json.tool < ~/Library/Application\ Support/Claude/claude_desktop_config.json`
+3. Restart Claude Desktop
+4. Check Claude logs: `~/Library/Logs/Claude/`
+
+### Tool Execution Fails
+
+**Error**: `TypeError: tabId is not a number`
+
+**Solution**:
+1. Use `chrome_list_tabs` first to get valid tab IDs
+2. Ensure tab still exists (not closed)
+3. Check MCP server logs (stderr output)
+
+## Logging
+
+MCP server logs to **stderr** (stdout is reserved for MCP protocol):
+- Connection status
+- Tool invocations
+- Errors and warnings
+
+To see logs:
+```bash
+node native-host/mcp-server.js 2>&1 | grep "\[MCP Server\]"
+```
+
+## Security
+
+⚠️ **MCP server has full browser control** - use with trusted AI agents only
+
+Recommendations:
+- Run in separate browser profile for automation
+- Monitor AI agent actions via logs
+- Disable MCP server when not needed
+- Consider adding authentication for production use
+
+## Documentation
+
+- [MCP Server Architecture](../docs/dev/MCP_SERVER_ARCHITECTURE.md) - Detailed design docs
+- [MCP Server Configuration](../docs/dev/MCP_SERVER_CONFIGURATION.md) - Setup guide for various clients
+- [ChromeLink Protocol](../docs/PROTOCOL.md) - WebSocket protocol specification
+- [Node.js Client](../clients/node/README.md) - Client library used by MCP server
+
+## License
+
+MIT - See LICENSE file in repository root

package/bin/chromelink-mcp

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+/**
+ * ChromeLink MCP Server - Executable
+ * 
+ * This script launches the MCP server for Chrome browser automation.
+ * It connects to the browser-link-server via WebSocket and exposes
+ * Chrome automation capabilities via the Model Context Protocol.
+ */
+
+require('../index.js');

package/index.js

@@ -0,0 +1,658 @@
+#!/usr/bin/env node
+
+/**
+ * ChromeLink MCP Server
+ * 
+ * Model Context Protocol (MCP) server that exposes Chrome browser automation
+ * capabilities to AI agents like Claude, GPT, etc.
+ * 
+ * This server acts as a thin wrapper around the ChromeLink WebSocket client,
+ * exposing browser automation as MCP tools that AI agents can discover and use.
+ * 
+ * Architecture:
+ *   AI Agent (Claude/GPT) <-> MCP Server (this file) <-> browser-link-server <-> Chrome Extension
+ *   
+ * Communication:
+ *   - AI Agent ↔ MCP Server: stdio (MCP protocol)
+ *   - MCP Server ↔ browser-link-server: WebSocket (ws://localhost:9000)
+ *   
+ * Usage:
+ *   node mcp-server.js
+ *   
+ * Configuration (Claude Desktop):
+ *   Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
+ *   {
+ *     "mcpServers": {
+ *       "chrome-link": {
+ *         "command": "node",
+ *         "args": ["/path/to/chrome-driver-extension/native-host/mcp-server.js"]
+ *       }
+ *     }
+ *   }
+ */
+
+const ChromeLinkClient = require('@aikeymouse/chromelink-client');
+
+// MCP Protocol Implementation
+class MCPServer {
+  constructor() {
+    this.client = null;
+    this.requestId = 1;
+  }
+
+  /**
+   * Log to stderr (stdout is reserved for MCP protocol)
+   */
+  log(message, ...args) {
+    console.error(`[MCP Server] ${message}`, ...args);
+  }
+
+  /**
+   * Send MCP response to stdout
+   */
+  sendResponse(response) {
+    const message = JSON.stringify(response);
+    process.stdout.write(message + '\n');
+  }
+
+  /**
+   * Send error response
+   */
+  sendError(id, code, message) {
+    this.sendResponse({
+      jsonrpc: '2.0',
+      id,
+      error: {
+        code,
+        message
+      }
+    });
+  }
+
+  /**
+   * Initialize connection to browser-link-server
+   */
+  async initialize() {
+    try {
+      this.client = new ChromeLinkClient('ws://localhost:9000');
+      await this.client.connect();
+      this.log('Connected to browser-link-server');
+    } catch (error) {
+      this.log('Failed to connect to browser-link-server:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Get list of available MCP tools
+   */
+  getTools() {
+    return {
+      tools: [
+        // Tab Management
+        {
+          name: 'chrome_list_tabs',
+          description: 'List all open tabs in the browser',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: []
+          }
+        },
+        {
+          name: 'chrome_open_tab',
+          description: 'Open a new tab with the specified URL',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              url: {
+                type: 'string',
+                description: 'URL to open in the new tab'
+              },
+              focus: {
+                type: 'boolean',
+                description: 'Whether to focus the new tab (default: true)',
+                default: true
+              }
+            },
+            required: ['url']
+          }
+        },
+        {
+          name: 'chrome_navigate_tab',
+          description: 'Navigate an existing tab to a new URL',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              tabId: {
+                type: 'number',
+                description: 'ID of the tab to navigate'
+              },
+              url: {
+                type: 'string',
+                description: 'URL to navigate to'
+              },
+              focus: {
+                type: 'boolean',
+                description: 'Whether to focus the tab (default: true)',
+                default: true
+              }
+            },
+            required: ['tabId', 'url']
+          }
+        },
+        {
+          name: 'chrome_switch_tab',
+          description: 'Switch to (focus) a specific tab',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              tabId: {
+                type: 'number',
+                description: 'ID of the tab to switch to'
+              }
+            },
+            required: ['tabId']
+          }
+        },
+        {
+          name: 'chrome_close_tab',
+          description: 'Close a specific tab',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              tabId: {
+                type: 'number',
+                description: 'ID of the tab to close'
+              }
+            },
+            required: ['tabId']
+          }
+        },
+        {
+          name: 'chrome_get_active_tab',
+          description: 'Get information about the currently active tab',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: []
+          }
+        },
+
+        // Navigation History
+        {
+          name: 'chrome_go_back',
+          description: 'Navigate back in tab history (only works after user navigation, not programmatic)',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              tabId: {
+                type: 'number',
+                description: 'ID of the tab to navigate back'
+              }
+            },
+            required: ['tabId']
+          }
+        },
+        {
+          name: 'chrome_go_forward',
+          description: 'Navigate forward in tab history (only works after user navigation, not programmatic)',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              tabId: {
+                type: 'number',
+                description: 'ID of the tab to navigate forward'
+              }
+            },
+            required: ['tabId']
+          }
+        },
+
+        // DOM Interaction
+        {
+          name: 'chrome_wait_for_element',
+          description: 'Wait for an element matching the CSS selector to appear on the page',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              selector: {
+                type: 'string',
+                description: 'CSS selector for the element'
+              },
+              tabId: {
+                type: 'number',
+                description: 'ID of the tab'
+              },
+              timeout: {
+                type: 'number',
+                description: 'Maximum time to wait in milliseconds (default: 5000)',
+                default: 5000
+              }
+            },
+            required: ['selector', 'tabId']
+          }
+        },
+        {
+          name: 'chrome_get_text',
+          description: 'Get the text content of an element matching the CSS selector',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              selector: {
+                type: 'string',
+                description: 'CSS selector for the element'
+              },
+              tabId: {
+                type: 'number',
+                description: 'ID of the tab'
+              }
+            },
+            required: ['selector', 'tabId']
+          }
+        },
+        {
+          name: 'chrome_click',
+          description: 'Click an element matching the CSS selector',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              selector: {
+                type: 'string',
+                description: 'CSS selector for the element to click'
+              },
+              tabId: {
+                type: 'number',
+                description: 'ID of the tab'
+              }
+            },
+            required: ['selector', 'tabId']
+          }
+        },
+        {
+          name: 'chrome_type',
+          description: 'Type text into an element matching the CSS selector',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              selector: {
+                type: 'string',
+                description: 'CSS selector for the input element'
+              },
+              text: {
+                type: 'string',
+                description: 'Text to type into the element'
+              },
+              tabId: {
+                type: 'number',
+                description: 'ID of the tab'
+              }
+            },
+            required: ['selector', 'text', 'tabId']
+          }
+        },
+
+        // JavaScript Execution
+        {
+          name: 'chrome_execute_js',
+          description: 'Execute arbitrary JavaScript code in the page context',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              code: {
+                type: 'string',
+                description: 'JavaScript code to execute'
+              },
+              tabId: {
+                type: 'number',
+                description: 'ID of the tab'
+              }
+            },
+            required: ['code', 'tabId']
+          }
+        },
+        {
+          name: 'chrome_call_helper',
+          description: 'Call a predefined DOM helper function for CSP-restricted pages. Available helpers: Element Interaction (clickElement, typeText, appendChar, clearContentEditable), Element Query (getText, getHTML, getLastHTML, elementExists, isVisible, waitForElement), Element Highlighting (highlightElement, removeHighlights), Element Positioning (getElementBounds, scrollElementIntoView), Element Inspection (inspectElement, getContainerElements)',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              functionName: {
+                type: 'string',
+                description: 'Name of the helper function',
+                enum: [
+                  'clickElement', 
+                  'typeText', 
+                  'appendChar', 
+                  'clearContentEditable',
+                  'getText', 
+                  'getHTML', 
+                  'getLastHTML', 
+                  'elementExists', 
+                  'isVisible', 
+                  'waitForElement',
+                  'highlightElement', 
+                  'removeHighlights',
+                  'getElementBounds', 
+                  'scrollElementIntoView',
+                  'inspectElement', 
+                  'getContainerElements'
+                ]
+              },
+              args: {
+                type: 'array',
+                description: 'Arguments to pass to the helper function',
+                items: {}
+              },
+              tabId: {
+                type: 'number',
+                description: 'ID of the tab'
+              }
+            },
+            required: ['functionName', 'args', 'tabId']
+          }
+        },
+
+        // Screenshots
+        {
+          name: 'chrome_capture_screenshot',
+          description: 'Capture a screenshot of the current tab',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              format: {
+                type: 'string',
+                description: 'Image format (png or jpeg)',
+                enum: ['png', 'jpeg'],
+                default: 'png'
+              },
+              quality: {
+                type: 'number',
+                description: 'JPEG quality (0-100, only for jpeg format)',
+                minimum: 0,
+                maximum: 100,
+                default: 90
+              }
+            },
+            required: []
+          }
+        },
+
+        // Script Injection
+        {
+          name: 'chrome_register_injection',
+          description: 'Register a content script to be injected into matching pages',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              id: {
+                type: 'string',
+                description: 'Unique identifier for this injection'
+              },
+              code: {
+                type: 'string',
+                description: 'JavaScript code to inject'
+              },
+              matches: {
+                type: 'array',
+                description: 'URL patterns to match (e.g., ["https://*.example.com/*"])',
+                items: {
+                  type: 'string'
+                }
+              },
+              runAt: {
+                type: 'string',
+                description: 'When to inject the script',
+                enum: ['document_start', 'document_end', 'document_idle'],
+                default: 'document_idle'
+              }
+            },
+            required: ['id', 'code', 'matches']
+          }
+        },
+        {
+          name: 'chrome_unregister_injection',
+          description: 'Unregister a previously registered content script',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              id: {
+                type: 'string',
+                description: 'ID of the injection to unregister'
+              }
+            },
+            required: ['id']
+          }
+        }
+      ]
+    };
+  }
+
+  /**
+   * Handle tool invocation
+   */
+  async handleToolCall(name, args) {
+    this.log(`Tool call: ${name}`, args);
+
+    try {
+      let result;
+
+      switch (name) {
+        // Tab Management
+        case 'chrome_list_tabs':
+          result = await this.client.listTabs();
+          break;
+
+        case 'chrome_open_tab':
+          result = await this.client.openTab(args.url, args.focus);
+          break;
+
+        case 'chrome_navigate_tab':
+          result = await this.client.navigateTab(args.tabId, args.url, args.focus);
+          break;
+
+        case 'chrome_switch_tab':
+          result = await this.client.switchTab(args.tabId);
+          break;
+
+        case 'chrome_close_tab':
+          result = await this.client.closeTab(args.tabId);
+          break;
+
+        case 'chrome_get_active_tab':
+          result = await this.client.getActiveTab();
+          break;
+
+        // Navigation History
+        case 'chrome_go_back':
+          result = await this.client.goBack(args.tabId);
+          break;
+
+        case 'chrome_go_forward':
+          result = await this.client.goForward(args.tabId);
+          break;
+
+        // DOM Interaction
+        case 'chrome_wait_for_element':
+          result = await this.client.waitForElement(args.selector, args.timeout || 5000, args.tabId);
+          break;
+
+        case 'chrome_get_text':
+          result = await this.client.getText(args.selector, args.tabId);
+          break;
+
+        case 'chrome_click':
+          result = await this.client.click(args.selector, args.tabId);
+          break;
+
+        case 'chrome_type':
+          result = await this.client.type(args.selector, args.text, args.tabId);
+          break;
+
+        // JavaScript Execution
+        case 'chrome_execute_js':
+          result = await this.client.executeJS(args.code, args.tabId);
+          break;
+
+        case 'chrome_call_helper':
+          result = await this.client.callHelper(args.functionName, args.args, args.tabId);
+          break;
+
+        // Screenshots
+        case 'chrome_capture_screenshot':
+          result = await this.client.captureScreenshot({
+            format: args.format || 'png',
+            quality: args.quality || 90
+          });
+          break;
+
+        // Script Injection
+        case 'chrome_register_injection':
+          result = await this.client.registerInjection(
+            args.id,
+            args.code,
+            args.matches,
+            args.runAt || 'document_idle'
+          );
+          break;
+
+        case 'chrome_unregister_injection':
+          result = await this.client.unregisterInjection(args.id);
+          break;
+
+        default:
+          throw new Error(`Unknown tool: ${name}`);
+      }
+
+      this.log(`Tool result for ${name}:`, result);
+      return result;
+
+    } catch (error) {
+      this.log(`Tool error for ${name}:`, error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Handle incoming MCP request
+   */
+  async handleRequest(request) {
+    const { id, method, params } = request;
+
+    try {
+      switch (method) {
+        case 'initialize':
+          this.sendResponse({
+            jsonrpc: '2.0',
+            id,
+            result: {
+              protocolVersion: '2024-11-05',
+              capabilities: {
+                tools: {}
+              },
+              serverInfo: {
+                name: 'chrome-link',
+                version: '1.2.0'
+              }
+            }
+          });
+          break;
+
+        case 'tools/list':
+          this.sendResponse({
+            jsonrpc: '2.0',
+            id,
+            result: this.getTools()
+          });
+          break;
+
+        case 'tools/call':
+          const result = await this.handleToolCall(params.name, params.arguments || {});
+          this.sendResponse({
+            jsonrpc: '2.0',
+            id,
+            result: {
+              content: [
+                {
+                  type: 'text',
+                  text: JSON.stringify(result, null, 2)
+                }
+              ]
+            }
+          });
+          break;
+
+        default:
+          this.sendError(id, -32601, `Method not found: ${method}`);
+      }
+    } catch (error) {
+      this.sendError(id, -32603, error.message);
+    }
+  }
+
+  /**
+   * Start the MCP server
+   */
+  async start() {
+    this.log('Starting MCP server...');
+
+    // Connect to browser-link-server
+    await this.initialize();
+
+    // Handle stdin for MCP protocol
+    let buffer = '';
+    process.stdin.on('data', (chunk) => {
+      buffer += chunk.toString();
+      
+      // Process complete JSON-RPC messages
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || ''; // Keep incomplete line in buffer
+
+      for (const line of lines) {
+        if (line.trim()) {
+          try {
+            const request = JSON.parse(line);
+            this.handleRequest(request);
+          } catch (error) {
+            this.log('Failed to parse request:', error.message);
+          }
+        }
+      }
+    });
+
+    process.stdin.on('end', () => {
+      this.log('Stdin closed, shutting down...');
+      this.shutdown();
+    });
+
+    // Handle process signals
+    process.on('SIGINT', () => {
+      this.log('Received SIGINT, shutting down...');
+      this.shutdown();
+    });
+
+    process.on('SIGTERM', () => {
+      this.log('Received SIGTERM, shutting down...');
+      this.shutdown();
+    });
+
+    this.log('MCP server started successfully');
+  }
+
+  /**
+   * Shutdown the server
+   */
+  shutdown() {
+    if (this.client) {
+      this.client.close();
+    }
+    process.exit(0);
+  }
+}
+
+// Start the server
+const server = new MCPServer();
+server.start().catch((error) => {
+  console.error('[MCP Server] Fatal error:', error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@aikeymouse/chromelink-mcp",
+  "version": "1.2.0",
+  "description": "Model Context Protocol (MCP) server for Chrome browser automation via AI agents",
+  "main": "index.js",
+  "bin": {
+    "chromelink-mcp": "./bin/chromelink-mcp"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepublishOnly": "node scripts/prepare-publish.js",
+    "postpublish": "node scripts/restore-publish.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "chrome",
+    "browser-automation",
+    "ai",
+    "claude",
+    "gpt",
+    "automation",
+    "testing",
+    "websocket"
+  ],
+  "author": "aikeymouse",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aikeymouse/chrome-link.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://github.com/aikeymouse/chrome-link#readme",
+  "bugs": {
+    "url": "https://github.com/aikeymouse/chrome-link/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "@aikeymouse/chromelink-client": "^1.2.0",
+    "ws": "^8.16.0"
+  },
+  "peerDependencies": {},
+  "files": [
+    "index.js",
+    "bin/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/scripts/prepare-publish.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+/**
+ * Prepare package.json for publishing to npm
+ * 
+ * This script runs before `npm publish` to:
+ * 1. Backup the current package.json
+ * 2. Replace local file dependency with npm version dependency
+ * 
+ * The local dependency "@aikeymouse/chromelink-client": "file:../clients/node"
+ * is replaced with "@aikeymouse/chromelink-client": "^{VERSION}"
+ * where VERSION comes from the VERSION file in the project root.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const PACKAGE_JSON = path.join(__dirname, '..', 'package.json');
+const BACKUP_FILE = PACKAGE_JSON + '.bak';
+const VERSION_FILE = path.join(__dirname, '..', '..', 'VERSION');
+
+try {
+  // Read VERSION file
+  if (!fs.existsSync(VERSION_FILE)) {
+    console.error('ERROR: VERSION file not found at', VERSION_FILE);
+    process.exit(1);
+  }
+
+  const version = fs.readFileSync(VERSION_FILE, 'utf8').trim();
+  if (!version.match(/^\d+\.\d+\.\d+$/)) {
+    console.error('ERROR: Invalid version format in VERSION file:', version);
+    process.exit(1);
+  }
+
+  console.log(`Preparing package.json for npm publish (version: ${version})`);
+
+  // Read package.json
+  const packageJson = JSON.parse(fs.readFileSync(PACKAGE_JSON, 'utf8'));
+
+  // Backup original package.json
+  fs.writeFileSync(BACKUP_FILE, JSON.stringify(packageJson, null, 2) + '\n');
+  console.log('✓ Backed up package.json');
+
+  // Replace file dependency with npm version
+  if (packageJson.dependencies && packageJson.dependencies['@aikeymouse/chromelink-client']) {
+    const oldDep = packageJson.dependencies['@aikeymouse/chromelink-client'];
+    packageJson.dependencies['@aikeymouse/chromelink-client'] = `^${version}`;
+    console.log(`✓ Updated dependency: ${oldDep} → ^${version}`);
+  }
+
+  // Write updated package.json
+  fs.writeFileSync(PACKAGE_JSON, JSON.stringify(packageJson, null, 2) + '\n');
+  console.log('✓ Package.json ready for publishing');
+
+} catch (error) {
+  console.error('ERROR preparing package.json:', error.message);
+  
+  // Try to restore from backup if it exists
+  if (fs.existsSync(BACKUP_FILE)) {
+    try {
+      fs.copyFileSync(BACKUP_FILE, PACKAGE_JSON);
+      fs.unlinkSync(BACKUP_FILE);
+      console.log('✓ Restored package.json from backup');
+    } catch (restoreError) {
+      console.error('ERROR restoring backup:', restoreError.message);
+    }
+  }
+  
+  process.exit(1);
+}

package/scripts/restore-publish.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+/**
+ * Restore package.json after publishing to npm
+ * 
+ * This script runs after `npm publish` to:
+ * 1. Restore package.json from backup
+ * 2. Clean up backup file
+ * 
+ * This ensures the local file dependency is restored for development.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const PACKAGE_JSON = path.join(__dirname, '..', 'package.json');
+const BACKUP_FILE = PACKAGE_JSON + '.bak';
+
+try {
+  if (!fs.existsSync(BACKUP_FILE)) {
+    console.log('No backup file found, skipping restore');
+    process.exit(0);
+  }
+
+  console.log('Restoring package.json from backup');
+
+  // Restore from backup
+  const backup = fs.readFileSync(BACKUP_FILE, 'utf8');
+  fs.writeFileSync(PACKAGE_JSON, backup);
+  console.log('✓ Restored package.json');
+
+  // Clean up backup file
+  fs.unlinkSync(BACKUP_FILE);
+  console.log('✓ Removed backup file');
+
+  console.log('✓ Package.json restored to development state');
+
+} catch (error) {
+  console.error('ERROR restoring package.json:', error.message);
+  console.error('You may need to manually restore from', BACKUP_FILE);
+  process.exit(1);
+}