openclaw-navigator 4.2.0 → 4.3.0

package/cli.mjs

@@ -18,6 +18,8 @@ import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createServer } from "node:http";
 import { networkInterfaces, hostname, userInfo } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 // readline reserved for future interactive mode
 
 // ── Colors (ANSI) ──────────────────────────────────────────────────────────
@@ -506,6 +508,7 @@ async function main() {
   let port = 18790;
   let bindHost = "127.0.0.1";
   let noTunnel = false;
+  let withMcp = false;
 
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--port" && args[i + 1]) {
@@ -517,17 +520,22 @@ async function main() {
     if (args[i] === "--no-tunnel") {
       noTunnel = true;
     }
+    if (args[i] === "--mcp") {
+      withMcp = true;
+    }
     if (args[i] === "--help" || args[i] === "-h") {
       console.log(`
 ${BOLD}openclaw-navigator${RESET} — One-command bridge + tunnel for Navigator
 
 ${BOLD}Usage:${RESET}
   npx openclaw-navigator                  Auto-tunnel mode (default, works anywhere)
+  npx openclaw-navigator --mcp            Bridge + MCP server (for OpenClaw agent)
   npx openclaw-navigator --no-tunnel      Local-only mode (SSH/LAN)
   npx openclaw-navigator --port 18790     Custom port
 
 ${BOLD}Options:${RESET}
   --port <port>    Bridge server port (default: 18790)
+  --mcp            Also start the MCP server (stdio) for OpenClaw agent
   --no-tunnel      Skip auto-tunnel, use SSH or LAN instead
   --bind <host>    Bind address (default: 127.0.0.1)
   --help           Show this help
@@ -651,9 +659,39 @@ ${BOLD}How it works:${RESET}
   console.log(`${BOLD}${GREEN}Bridge is running.${RESET} Waiting for Navigator to connect...`);
   console.log(`${DIM}Press Ctrl+C to stop.${RESET}\n`);
 
+  // ── Step 6 (optional): Start MCP server ─────────────────────────────
+  let mcpProcess = null;
+  if (withMcp) {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const mcpPath = join(__dirname, "mcp.mjs");
+    const mcpEnv = { ...process.env, NAVIGATOR_BRIDGE_URL: `http://localhost:${port}` };
+
+    mcpProcess = spawn(process.execPath, [mcpPath], {
+      stdio: ["pipe", "pipe", "inherit"], // stdin/stdout piped for MCP protocol, stderr visible
+      env: mcpEnv,
+    });
+
+    mcpProcess.on("error", (err) => {
+      warn(`MCP server failed to start: ${err.message}`);
+    });
+    mcpProcess.on("exit", (code) => {
+      if (code !== null && code !== 0) {
+        warn(`MCP server exited with code ${code}`);
+      }
+      mcpProcess = null;
+    });
+
+    ok(`MCP server started (PID ${mcpProcess.pid}) — bridge: http://localhost:${port}`);
+    info(`  OpenClaw can connect via stdio to this process's MCP server`);
+    console.log("");
+  }
+
   // ── Graceful shutdown ─────────────────────────────────────────────────
   const shutdown = () => {
     console.log(`\n${DIM}Shutting down bridge...${RESET}`);
+    if (mcpProcess) {
+      mcpProcess.kill();
+    }
     if (tunnelProcess) {
       tunnelProcess.kill();
     }

package/mcp.mjs

@@ -0,0 +1,507 @@
+#!/usr/bin/env node
+
+/**
+ * openclaw-navigator MCP server v4.3.0
+ *
+ * Exposes the Navigator bridge HTTP API as MCP tools so the OpenClaw agent
+ * can control the browser natively via its tool schema.
+ *
+ * Runs on the OC machine alongside the bridge (cli.mjs).
+ * Uses stdio transport — the gateway wires it in via mcporter or MCP config.
+ *
+ * Usage:
+ *   node mcp.mjs
+ *   NAVIGATOR_BRIDGE_URL=http://host:18790 node mcp.mjs
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+// ── Configuration ─────────────────────────────────────────────────────────
+
+const BRIDGE_URL =
+  process.env.NAVIGATOR_BRIDGE_URL ?? "http://localhost:18790";
+const POLL_INTERVAL_MS = 500;
+const DEFAULT_TIMEOUT_MS = 15_000;
+const WAIT_READY_TIMEOUT_MS = 20_000;
+
+// All logging to stderr — stdout is reserved for MCP JSON-RPC protocol
+const log = (...args) => console.error("[navigator-mcp]", ...args);
+
+// ── HTTP helpers ──────────────────────────────────────────────────────────
+
+async function bridgeGet(path) {
+  const res = await fetch(`${BRIDGE_URL}${path}`);
+  if (!res.ok) {
+    throw new Error(`Bridge GET ${path} returned ${res.status}`);
+  }
+  return res.json();
+}
+
+async function bridgePost(path, body) {
+  const res = await fetch(`${BRIDGE_URL}${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    throw new Error(`Bridge POST ${path} returned ${res.status}`);
+  }
+  return res.json();
+}
+
+// ── Event polling engine ──────────────────────────────────────────────────
+
+/**
+ * Poll GET /navigator/events for an event matching `predicate`.
+ * Uses a timestamp watermark — only considers events newer than startTime.
+ *
+ * @param {(event: object) => boolean} predicate
+ * @param {number} startTime - timestamp watermark (Date.now() before command)
+ * @param {number} [timeout] - max wait in ms
+ * @returns {Promise<object|null>} matched event or null on timeout
+ */
+async function waitForEvent(
+  predicate,
+  startTime,
+  timeout = DEFAULT_TIMEOUT_MS,
+) {
+  const deadline = Date.now() + timeout;
+
+  while (Date.now() < deadline) {
+    try {
+      const data = await bridgeGet("/navigator/events?limit=50");
+      if (data.ok && Array.isArray(data.events)) {
+        for (const event of data.events) {
+          if (event.timestamp > startTime && predicate(event)) {
+            return event;
+          }
+        }
+      }
+    } catch (err) {
+      log("Poll error:", err.message);
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+
+  return null;
+}
+
+// ── sendCommand — post command + optionally poll for result ────────────────
+
+/**
+ * @param {string} command  - Bridge command name (e.g. "navigate", "click")
+ * @param {object} payload  - Command payload
+ * @param {object} [poll]   - If provided, wait for result event
+ * @param {string} [poll.eventType]   - Match event by type (e.g. "tabs.list")
+ * @param {string} [poll.commandName] - Match command.result by data.command
+ * @param {number} [poll.timeout]     - Custom timeout in ms
+ */
+async function sendCommand(command, payload, poll) {
+  const startTime = Date.now();
+
+  let postResult;
+  try {
+    postResult = await bridgePost("/navigator/command", { command, payload });
+  } catch (err) {
+    return {
+      ok: false,
+      error: `Bridge unreachable at ${BRIDGE_URL}: ${err.message}`,
+    };
+  }
+
+  if (!postResult.ok) {
+    return postResult;
+  }
+
+  // Fire-and-forget — return immediately
+  if (!poll) {
+    return { ok: true, commandId: postResult.commandId, command };
+  }
+
+  // Build predicate based on poll options
+  let predicate;
+  if (poll.eventType) {
+    predicate = (e) => e.type === poll.eventType;
+  } else if (poll.commandName) {
+    predicate = (e) =>
+      e.type === "command.result" && e.data?.command === poll.commandName;
+  } else {
+    return { ok: true, commandId: postResult.commandId, command };
+  }
+
+  const timeout = poll.timeout ?? DEFAULT_TIMEOUT_MS;
+  const event = await waitForEvent(predicate, startTime, timeout);
+
+  if (!event) {
+    return {
+      ok: false,
+      error: "Command timed out. Navigator may not be connected.",
+      commandId: postResult.commandId,
+    };
+  }
+
+  return {
+    ok: true,
+    commandId: postResult.commandId,
+    event: {
+      type: event.type,
+      data: event.data,
+      url: event.url,
+      title: event.title,
+      content: event.content,
+    },
+  };
+}
+
+// ── Tool definitions (15 tools) ───────────────────────────────────────────
+
+const TOOLS = [
+  // ── Direct HTTP ──
+  {
+    name: "navigator_status",
+    description:
+      "Get the Navigator bridge status — connection state, active tabs, current URL, uptime, pending commands.",
+    inputSchema: { type: "object", properties: {} },
+  },
+
+  // ── Fire-and-forget ──
+  {
+    name: "navigator_navigate",
+    description:
+      "Navigate the active browser tab to a URL. Returns immediately after queuing the command.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "The URL to navigate to" },
+      },
+      required: ["url"],
+    },
+  },
+  {
+    name: "navigator_open_tab",
+    description:
+      "Open a new browser tab, optionally loading a URL. Returns immediately after queuing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description: "URL to load (opens blank tab if omitted)",
+        },
+      },
+    },
+  },
+  {
+    name: "navigator_close_tab",
+    description:
+      "Close a browser tab by its index or ID. Returns immediately after queuing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tabIndex: { type: "number", description: "Tab index (0-based)" },
+        tabId: { type: "string", description: "Tab ID" },
+      },
+    },
+  },
+
+  // ── Poll by event type ──
+  {
+    name: "navigator_list_tabs",
+    description:
+      "List all open tabs in the Navigator browser with their URLs, titles, and IDs.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "navigator_snapshot",
+    description:
+      "Get a snapshot of the browser state — active tab, URL, title, and full tab list.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "navigator_get_text",
+    description:
+      "Get the text content of the active page (equivalent to document.body.innerText).",
+    inputSchema: { type: "object", properties: {} },
+  },
+
+  // ── Poll by command.result ──
+  {
+    name: "navigator_click",
+    description:
+      "Click an element on the page by CSS selector. Waits for confirmation from the browser.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        selector: {
+          type: "string",
+          description: "CSS selector of the element to click",
+        },
+      },
+      required: ["selector"],
+    },
+  },
+  {
+    name: "navigator_fill",
+    description:
+      "Fill an input field with text. Waits for confirmation from the browser.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        selector: {
+          type: "string",
+          description: "CSS selector of the input element",
+        },
+        value: {
+          type: "string",
+          description: "Text to fill into the field",
+        },
+      },
+      required: ["selector", "value"],
+    },
+  },
+  {
+    name: "navigator_submit",
+    description:
+      "Submit a form. Optionally specify a selector for the form or an element inside it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        selector: {
+          type: "string",
+          description:
+            "CSS selector of the form or an element inside it (submits closest form)",
+        },
+      },
+    },
+  },
+  {
+    name: "navigator_scroll",
+    description:
+      "Scroll the page in a direction (up/down/top/bottom) or by exact pixel offsets.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        direction: {
+          type: "string",
+          enum: ["up", "down", "top", "bottom"],
+          description: "Scroll direction shortcut",
+        },
+        x: {
+          type: "number",
+          description: "Horizontal pixels to scroll (positive = right)",
+        },
+        y: {
+          type: "number",
+          description: "Vertical pixels to scroll (positive = down)",
+        },
+      },
+    },
+  },
+  {
+    name: "navigator_execute_js",
+    description:
+      "Execute arbitrary JavaScript in the active tab and return the result. Use for anything the other tools don't cover.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        code: {
+          type: "string",
+          description: "JavaScript code to execute in the page context",
+        },
+      },
+      required: ["code"],
+    },
+  },
+  {
+    name: "navigator_get_html",
+    description: "Get the full HTML source of the active page.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "navigator_query_element",
+    description:
+      "Query a DOM element by CSS selector — returns its tag name, text content, and attributes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        selector: { type: "string", description: "CSS selector" },
+      },
+      required: ["selector"],
+    },
+  },
+  {
+    name: "navigator_wait_ready",
+    description:
+      'Wait until document.readyState is "complete". Useful after navigation to ensure the page is fully loaded. Times out after 20 seconds.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        timeout: {
+          type: "number",
+          description: "Max wait in milliseconds (default: 10000)",
+        },
+      },
+    },
+  },
+];
+
+// ── Tool handler dispatch ─────────────────────────────────────────────────
+
+function jsonResult(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+function errorResult(message) {
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+    isError: true,
+  };
+}
+
+async function handleTool(name, args) {
+  try {
+    switch (name) {
+      // ── Direct HTTP ──
+      case "navigator_status":
+        return jsonResult(await bridgeGet("/navigator/status"));
+
+      // ── Fire-and-forget ──
+      case "navigator_navigate":
+        return jsonResult(await sendCommand("navigate", { url: args.url }));
+
+      case "navigator_open_tab":
+        return jsonResult(await sendCommand("tabs.open", { url: args.url }));
+
+      case "navigator_close_tab":
+        return jsonResult(
+          await sendCommand("tabs.close", {
+            tabIndex: args.tabIndex,
+            tabId: args.tabId,
+          }),
+        );
+
+      // ── Poll by event type ──
+      case "navigator_list_tabs":
+        return jsonResult(
+          await sendCommand("tabs.list", {}, { eventType: "tabs.list" }),
+        );
+
+      case "navigator_snapshot":
+        return jsonResult(
+          await sendCommand("snapshot", {}, { eventType: "snapshot" }),
+        );
+
+      case "navigator_get_text":
+        return jsonResult(
+          await sendCommand("page.content", {}, { eventType: "page.content" }),
+        );
+
+      // ── Poll by command.result ──
+      case "navigator_click":
+        return jsonResult(
+          await sendCommand(
+            "click",
+            { selector: args.selector },
+            { commandName: "click" },
+          ),
+        );
+
+      case "navigator_fill":
+        return jsonResult(
+          await sendCommand(
+            "input.fill",
+            { selector: args.selector, value: args.value },
+            { commandName: "input.fill" },
+          ),
+        );
+
+      case "navigator_submit":
+        return jsonResult(
+          await sendCommand(
+            "input.submit",
+            { selector: args.selector },
+            { commandName: "input.submit" },
+          ),
+        );
+
+      case "navigator_scroll":
+        return jsonResult(
+          await sendCommand(
+            "scroll",
+            { direction: args.direction, x: args.x, y: args.y },
+            { commandName: "scroll" },
+          ),
+        );
+
+      case "navigator_execute_js":
+        return jsonResult(
+          await sendCommand(
+            "execute",
+            { code: args.code },
+            { commandName: "execute" },
+          ),
+        );
+
+      case "navigator_get_html":
+        return jsonResult(
+          await sendCommand("page.html", {}, { commandName: "page.html" }),
+        );
+
+      case "navigator_query_element":
+        return jsonResult(
+          await sendCommand(
+            "dom.query",
+            { selector: args.selector },
+            { commandName: "dom.query" },
+          ),
+        );
+
+      case "navigator_wait_ready":
+        return jsonResult(
+          await sendCommand(
+            "wait.ready",
+            { timeout: args.timeout },
+            { commandName: "wait.ready", timeout: WAIT_READY_TIMEOUT_MS },
+          ),
+        );
+
+      default:
+        return errorResult(`Unknown tool: ${name}`);
+    }
+  } catch (err) {
+    log(`Tool ${name} error:`, err.message);
+    return errorResult(err.message);
+  }
+}
+
+// ── MCP server wiring ─────────────────────────────────────────────────────
+
+const server = new Server(
+  { name: "openclaw-navigator", version: "4.3.0" },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS,
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+  log(`\u2192 ${name}`, JSON.stringify(args));
+  const result = await handleTool(name, args);
+  log(`\u2190 ${name}`, result.isError ? "ERROR" : "ok");
+  return result;
+});
+
+// ── Start stdio transport ─────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+log(`MCP server started \u2014 bridge: ${BRIDGE_URL}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-navigator",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "One-command bridge + tunnel for the Navigator browser — works on any machine, any OS",
   "keywords": [
     "browser",
@@ -13,13 +13,16 @@
   ],
   "license": "MIT",
   "bin": {
-    "openclaw-navigator": "cli.mjs"
+    "openclaw-navigator": "cli.mjs",
+    "openclaw-navigator-mcp": "mcp.mjs"
   },
   "files": [
-    "cli.mjs"
+    "cli.mjs",
+    "mcp.mjs"
   ],
   "type": "module",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
     "cloudflared": "^0.7.1"
   },
   "engines": {