aipex-mcp-bridge 1.0.0

package/README.md

@@ -0,0 +1,119 @@
+# aipex-mcp-bridge
+
+MCP bridge that connects AI agents to the [AIPex](https://aipex.ai) browser extension via WebSocket.
+
+Works with **any** MCP client that supports stdio transport — Cursor, Claude Desktop, Claude Code, VS Code Copilot, Windsurf, Zed, and more.
+
+## How it works
+
+```
+AI Agent (MCP client) ──stdio──▶ aipex-mcp-bridge ──WebSocket──▶ AIPex Chrome Extension
+```
+
+The bridge starts a WebSocket server on `localhost:9223` (configurable) and communicates with your AI agent over stdio using the MCP protocol. The AIPex extension connects to the WebSocket server to expose browser control tools.
+
+## Quick start
+
+### 1. Configure your AI agent
+
+Add the following to your agent's MCP configuration:
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "aipex-browser": {
+      "command": "npx",
+      "args": ["-y", "aipex-mcp-bridge"]
+    }
+  }
+}
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "aipex-browser": {
+      "command": "npx",
+      "args": ["-y", "aipex-mcp-bridge"]
+    }
+  }
+}
+```
+
+**Claude Code**:
+
+```bash
+claude mcp add aipex-browser -- npx -y aipex-mcp-bridge
+```
+
+**VS Code Copilot** (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "aipex-browser": {
+      "command": "npx",
+      "args": ["-y", "aipex-mcp-bridge"]
+    }
+  }
+}
+```
+
+**Windsurf** (`mcp_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "aipex-browser": {
+      "command": "npx",
+      "args": ["-y", "aipex-mcp-bridge"]
+    }
+  }
+}
+```
+
+### 2. Connect AIPex extension
+
+1. Open Chrome → AIPex extension → Options page
+2. Set WebSocket URL to `ws://localhost:9223`
+3. Click **Connect**
+
+Your AI agent can now control the browser through AIPex.
+
+## Options
+
+```
+npx aipex-mcp-bridge [--port <port>]
+```
+
+| Option            | Default | Description                        |
+| ----------------- | ------- | ---------------------------------- |
+| `--port <port>`   | `9223`  | WebSocket port for AIPex extension |
+| `--help`, `-h`    |         | Show help message                  |
+| `--version`, `-v` |         | Show version                       |
+
+### Custom port example
+
+```json
+{
+  "mcpServers": {
+    "aipex-browser": {
+      "command": "npx",
+      "args": ["-y", "aipex-mcp-bridge", "--port", "8080"]
+    }
+  }
+}
+```
+
+## Requirements
+
+- Node.js >= 18
+- AIPex Chrome extension installed
+
+## License
+
+MIT

package/dist/bridge.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+// src/bridge.ts
+import { createServer } from "http";
+import { createInterface } from "readline";
+import { WebSocket, WebSocketServer } from "ws";
+var cliArgs = process.argv.slice(2);
+if (cliArgs.includes("--help") || cliArgs.includes("-h")) {
+  process.stderr.write(`
+AIPex MCP Bridge \u2014 connect AI agents to AIPex browser extension
+
+Usage:
+  npx aipex-mcp-bridge [--port <port>]
+
+Options:
+  --port <port>  WebSocket port for AIPex extension (default: 9223)
+  --help, -h     Show this help message
+  --version, -v  Show version
+
+After starting, open AIPex extension Options and connect to:
+  ws://localhost:<port>
+`);
+  process.exit(0);
+}
+if (cliArgs.includes("--version") || cliArgs.includes("-v")) {
+  process.stderr.write("aipex-mcp-bridge 1.0.0\n");
+  process.exit(0);
+}
+var portIdx = cliArgs.indexOf("--port");
+var WS_PORT = portIdx !== -1 ? parseInt(cliArgs[portIdx + 1], 10) : 9223;
+if (isNaN(WS_PORT) || WS_PORT < 1 || WS_PORT > 65535) {
+  process.stderr.write(`Invalid port number. Must be between 1 and 65535.
+`);
+  process.exit(1);
+}
+function log(msg) {
+  process.stderr.write(`[aipex-bridge] ${msg}
+`);
+}
+var aipexSocket = null;
+var aipexReady = false;
+var cachedTools = [];
+var nextAipexId = 1;
+var aipexPending = /* @__PURE__ */ new Map();
+function respond(id, result) {
+  const msg = { jsonrpc: "2.0", id, result };
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+function respondError(id, code, message) {
+  const msg = { jsonrpc: "2.0", id, error: { code, message } };
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+function sendToAipex(method, params = {}) {
+  if (!aipexSocket || aipexSocket.readyState !== WebSocket.OPEN) {
+    return Promise.reject(new Error("AIPex extension not connected"));
+  }
+  const id = nextAipexId++;
+  const msg = { jsonrpc: "2.0", id, method, params };
+  aipexSocket.send(JSON.stringify(msg));
+  return new Promise((resolve, reject) => {
+    aipexPending.set(id, { resolve, reject });
+  });
+}
+function handleAipexMessage(raw) {
+  let msg;
+  try {
+    msg = JSON.parse(raw);
+  } catch {
+    log(`Failed to parse AIPex message: ${raw.slice(0, 100)}`);
+    return;
+  }
+  if ("result" in msg || "error" in msg) {
+    const res = msg;
+    const p = aipexPending.get(res.id);
+    if (p) {
+      aipexPending.delete(res.id);
+      if (res.error) {
+        p.reject(new Error(res.error.message));
+      } else {
+        p.resolve(res.result);
+      }
+    }
+  }
+}
+async function doAipexHandshake(socket) {
+  log("Starting MCP handshake with AIPex...");
+  const initResult = await sendToAipex("initialize", {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: { name: "aipex-mcp-bridge", version: "1.0.0" }
+  });
+  const serverInfo = initResult?.serverInfo;
+  log(`AIPex server: ${serverInfo?.name ?? "?"} v${serverInfo?.version ?? "?"}`);
+  socket.send(
+    JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })
+  );
+  const toolsResult = await sendToAipex("tools/list");
+  cachedTools = toolsResult?.tools ?? [];
+  aipexReady = true;
+  log(`Handshake complete. ${cachedTools.length} tools available.`);
+}
+async function handleAgentRequest(req) {
+  const { id, method, params } = req;
+  if (method === "initialize") {
+    respond(id, {
+      protocolVersion: "2024-11-05",
+      capabilities: { tools: {} },
+      serverInfo: { name: "aipex-mcp-bridge", version: "1.0.0" }
+    });
+    return;
+  }
+  if (method === "notifications/initialized") {
+    return;
+  }
+  if (method === "tools/list") {
+    if (aipexReady && cachedTools.length > 0) {
+      respond(id, { tools: cachedTools });
+    } else {
+      respond(id, {
+        tools: [
+          {
+            name: "check_aipex_connection",
+            description: [
+              "AIPex extension is not connected. To enable browser control:",
+              `1. Open Chrome \u2192 AIPex extension \u2192 Options page`,
+              `2. Set WebSocket URL to: ws://localhost:${WS_PORT}`,
+              `3. Click Connect`,
+              `Then reload this MCP server.`
+            ].join("\n"),
+            inputSchema: { type: "object", properties: {} }
+          }
+        ]
+      });
+    }
+    return;
+  }
+  if (method === "tools/call") {
+    if (!aipexReady || !aipexSocket || aipexSocket.readyState !== WebSocket.OPEN) {
+      respondError(
+        id,
+        -32e3,
+        `AIPex extension not connected. Open AIPex Options and connect to ws://localhost:${WS_PORT}`
+      );
+      return;
+    }
+    try {
+      const result = await sendToAipex(
+        "tools/call",
+        params
+      );
+      respond(id, result);
+    } catch (e) {
+      respondError(id, -32e3, e instanceof Error ? e.message : String(e));
+    }
+    return;
+  }
+  if (method === "ping") {
+    if (aipexReady && aipexSocket?.readyState === WebSocket.OPEN) {
+      try {
+        const result = await sendToAipex("ping");
+        respond(id, result);
+      } catch {
+        respond(id, {});
+      }
+    } else {
+      respond(id, {});
+    }
+    return;
+  }
+  respondError(id, -32601, `Method not found: ${method}`);
+}
+var stdinRl = createInterface({ input: process.stdin });
+stdinRl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  let req;
+  try {
+    req = JSON.parse(trimmed);
+  } catch {
+    log(`Failed to parse stdin: ${trimmed.slice(0, 100)}`);
+    return;
+  }
+  handleAgentRequest(req).catch((e) => {
+    log(`Error handling request: ${e instanceof Error ? e.message : String(e)}`);
+    if (req.id != null) {
+      respondError(req.id, -32603, "Internal error");
+    }
+  });
+});
+stdinRl.on("close", () => {
+  log("stdin closed, shutting down");
+  process.exit(0);
+});
+var httpServer = createServer();
+var wss = new WebSocketServer({ server: httpServer });
+wss.on("connection", (socket, req) => {
+  const addr = req.socket.remoteAddress ?? "unknown";
+  if (aipexSocket && aipexSocket.readyState === WebSocket.OPEN) {
+    log(`New connection from ${addr}, closing previous`);
+    aipexSocket.close();
+  }
+  aipexSocket = socket;
+  aipexReady = false;
+  cachedTools = [];
+  log(`AIPex extension connected from ${addr}`);
+  socket.on("message", (data) => {
+    handleAipexMessage(data.toString());
+  });
+  socket.on("close", () => {
+    log("AIPex extension disconnected");
+    if (aipexSocket === socket) {
+      aipexSocket = null;
+      aipexReady = false;
+      cachedTools = [];
+    }
+  });
+  socket.on("error", (err) => {
+    log(`Socket error: ${err.message}`);
+  });
+  doAipexHandshake(socket).catch((err) => {
+    log(`Handshake failed: ${err.message}`);
+  });
+});
+wss.on("error", (err) => {
+  log(`WebSocket server error: ${err.message}`);
+});
+httpServer.listen(WS_PORT, () => {
+  log(`AIPex MCP Bridge started`);
+  log(`WebSocket server listening on ws://localhost:${WS_PORT}`);
+  log(`Waiting for AIPex extension to connect...`);
+  log(`Open AIPex Options \u2192 set URL to ws://localhost:${WS_PORT} \u2192 Connect`);
+});
+process.on("SIGINT", () => {
+  log("Shutting down...");
+  wss.close();
+  httpServer.close();
+  process.exit(0);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "aipex-mcp-bridge",
+  "version": "1.0.0",
+  "description": "MCP bridge that connects AI agents (Cursor, Claude, VS Code Copilot, etc.) to the AIPex browser extension via WebSocket",
+  "type": "module",
+  "bin": {
+    "aipex-mcp-bridge": "./dist/bridge.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/bridge.ts"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "aipex",
+    "browser",
+    "cursor",
+    "claude",
+    "copilot",
+    "websocket",
+    "bridge"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AIPexStudio/aipex-whole.git",
+    "directory": "aipex/mcp-bridge"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}