@sensaiorg/adapter-chrome 0.1.0

package/src/tools/chrome-tools.ts

@@ -0,0 +1,743 @@
+/**
+ * Chrome MCP Tools — registered when Chrome is connected via CDP.
+ *
+ * Uses the CdpBridge to send Chrome DevTools Protocol commands
+ * and collect console/network events.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { CdpBridge } from "../transport/cdp-bridge.js";
+
+/* ── Stored event types ──────────────────────────────────────────── */
+
+interface ConsoleEntry {
+  level: string;
+  text: string;
+  timestamp: number;
+  url?: string;
+  line?: number;
+}
+
+interface NetworkEntry {
+  requestId: string;
+  method: string;
+  url: string;
+  status?: number;
+  statusText?: string;
+  type?: string;
+  startTime: number;
+  endTime?: number;
+  encodedDataLength?: number;
+  error?: string;
+}
+
+/* ── Event collector ─────────────────────────────────────────────── */
+
+/**
+ * Manages CDP domain subscriptions and stores events for later retrieval.
+ */
+export class CdpEventCollector {
+  private readonly consoleLogs: ConsoleEntry[] = [];
+  private readonly networkEntries = new Map<string, NetworkEntry>();
+  private readonly maxEntries = 500;
+  private domainsEnabled = false;
+
+  /** Enable Console + Network domains and start collecting events. */
+  async enableDomains(bridge: CdpBridge): Promise<void> {
+    if (this.domainsEnabled) return;
+
+    // Listen for CDP events via the bridge
+    bridge.onEvent("Runtime.consoleAPICalled", (params) => {
+      const p = params as {
+        type: string;
+        args?: Array<{ value?: unknown; description?: string }>;
+        timestamp: number;
+        stackTrace?: { callFrames?: Array<{ url?: string; lineNumber?: number }> };
+      };
+      const text = (p.args ?? [])
+        .map((a) => a.value !== undefined ? String(a.value) : (a.description ?? ""))
+        .join(" ");
+      const frame = p.stackTrace?.callFrames?.[0];
+      this.addConsoleEntry({
+        level: p.type ?? "log",
+        text,
+        timestamp: p.timestamp ?? Date.now(),
+        url: frame?.url,
+        line: frame?.lineNumber,
+      });
+    });
+
+    bridge.onEvent("Runtime.exceptionThrown", (params) => {
+      const p = params as {
+        timestamp: number;
+        exceptionDetails?: {
+          text?: string;
+          exception?: { description?: string };
+          url?: string;
+          lineNumber?: number;
+        };
+      };
+      const details = p.exceptionDetails;
+      this.addConsoleEntry({
+        level: "error",
+        text: details?.exception?.description ?? details?.text ?? "Unknown exception",
+        timestamp: p.timestamp ?? Date.now(),
+        url: details?.url,
+        line: details?.lineNumber,
+      });
+    });
+
+    bridge.onEvent("Network.requestWillBeSent", (params) => {
+      const p = params as {
+        requestId: string;
+        request: { method: string; url: string };
+        type?: string;
+        timestamp: number;
+      };
+      this.networkEntries.set(p.requestId, {
+        requestId: p.requestId,
+        method: p.request.method,
+        url: p.request.url,
+        type: p.type,
+        startTime: p.timestamp,
+      });
+      this.trimNetwork();
+    });
+
+    bridge.onEvent("Network.responseReceived", (params) => {
+      const p = params as {
+        requestId: string;
+        response: { status: number; statusText: string };
+        timestamp: number;
+      };
+      const entry = this.networkEntries.get(p.requestId);
+      if (entry) {
+        entry.status = p.response.status;
+        entry.statusText = p.response.statusText;
+        entry.endTime = p.timestamp;
+      }
+    });
+
+    bridge.onEvent("Network.loadingFinished", (params) => {
+      const p = params as {
+        requestId: string;
+        encodedDataLength: number;
+        timestamp: number;
+      };
+      const entry = this.networkEntries.get(p.requestId);
+      if (entry) {
+        entry.encodedDataLength = p.encodedDataLength;
+        entry.endTime = p.timestamp;
+      }
+    });
+
+    bridge.onEvent("Network.loadingFailed", (params) => {
+      const p = params as {
+        requestId: string;
+        errorText: string;
+        timestamp: number;
+      };
+      const entry = this.networkEntries.get(p.requestId);
+      if (entry) {
+        entry.error = p.errorText;
+        entry.endTime = p.timestamp;
+      }
+    });
+
+    // Enable CDP domains
+    await bridge.send("Runtime.enable");
+    await bridge.send("Network.enable");
+    await bridge.send("Page.enable");
+    this.domainsEnabled = true;
+  }
+
+  getConsoleLogs(maxCount?: number): ConsoleEntry[] {
+    const limit = maxCount ?? this.consoleLogs.length;
+    return this.consoleLogs.slice(-limit);
+  }
+
+  getNetworkEntries(maxCount?: number): NetworkEntry[] {
+    const all = Array.from(this.networkEntries.values());
+    const limit = maxCount ?? all.length;
+    return all.slice(-limit);
+  }
+
+  private addConsoleEntry(entry: ConsoleEntry): void {
+    this.consoleLogs.push(entry);
+    if (this.consoleLogs.length > this.maxEntries) {
+      this.consoleLogs.splice(0, this.consoleLogs.length - this.maxEntries);
+    }
+  }
+
+  private trimNetwork(): void {
+    if (this.networkEntries.size > this.maxEntries) {
+      const keys = Array.from(this.networkEntries.keys());
+      const toRemove = keys.slice(0, keys.length - this.maxEntries);
+      for (const k of toRemove) {
+        this.networkEntries.delete(k);
+      }
+    }
+  }
+}
+
+/* ── Tool registration ───────────────────────────────────────────── */
+
+export function registerChromeTools(
+  server: McpServer,
+  bridge: CdpBridge,
+  collector: CdpEventCollector,
+  prefix: string,
+): void {
+
+  // ── chrome_diagnose_page ──────────────────────────────────────
+  server.tool(
+    `${prefix}diagnose_page`,
+    "Get a comprehensive diagnosis of the current web page: URL, title, console errors, network failures, DOM element counts. START HERE for any Chrome debugging session.",
+    {
+      includeNetwork: z.boolean().optional().describe("Include recent network requests (default: true)"),
+    },
+    async ({ includeNetwork }) => {
+      try {
+        const [pageInfo, docResult] = await Promise.all([
+          bridge.send("Runtime.evaluate", {
+            expression: "JSON.stringify({ url: location.href, title: document.title, readyState: document.readyState, viewport: { width: window.innerWidth, height: window.innerHeight }, cookieCount: document.cookie.split(';').filter(c => c.trim()).length })",
+            returnByValue: true,
+          }) as Promise<{ result: { value?: string } }>,
+          bridge.send("Runtime.evaluate", {
+            expression: "JSON.stringify({ elements: document.querySelectorAll('*').length, forms: document.forms.length, images: document.images.length, links: document.links.length, scripts: document.scripts.length })",
+            returnByValue: true,
+          }) as Promise<{ result: { value?: string } }>,
+        ]);
+
+        const page = pageInfo.result.value ? JSON.parse(pageInfo.result.value) : {};
+        const dom = docResult.result.value ? JSON.parse(docResult.result.value) : {};
+
+        const consoleErrors = collector.getConsoleLogs()
+          .filter((e) => e.level === "error" || e.level === "warning")
+          .slice(-20);
+
+        const result: Record<string, unknown> = {
+          page,
+          dom,
+          consoleErrors: consoleErrors.length,
+          recentErrors: consoleErrors,
+        };
+
+        if (includeNetwork !== false) {
+          const networkEntries = collector.getNetworkEntries();
+          const failures = networkEntries.filter(
+            (e) => e.error || (e.status && e.status >= 400),
+          );
+          result.networkSummary = {
+            totalRequests: networkEntries.length,
+            failedRequests: failures.length,
+            failures: failures.slice(-10),
+          };
+        }
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(result) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `diagnose_page failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── chrome_take_screenshot ────────────────────────────────────
+  server.tool(
+    `${prefix}take_screenshot`,
+    "Capture the current web page as a PNG screenshot via CDP.",
+    {
+      fullPage: z.boolean().optional().describe("Capture full page including scroll (default: false)"),
+    },
+    async ({ fullPage }) => {
+      try {
+        let clip: { x: number; y: number; width: number; height: number; scale: number } | undefined;
+
+        if (fullPage) {
+          const metrics = await bridge.send("Page.getLayoutMetrics") as {
+            contentSize: { width: number; height: number };
+          };
+          clip = {
+            x: 0,
+            y: 0,
+            width: metrics.contentSize.width,
+            height: metrics.contentSize.height,
+            scale: 1,
+          };
+        }
+
+        const result = await bridge.send("Page.captureScreenshot", {
+          format: "png",
+          ...(clip ? { clip } : {}),
+        }) as { data: string };
+
+        return {
+          content: [{
+            type: "image" as const,
+            data: result.data,
+            mimeType: "image/png",
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Screenshot failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── chrome_get_console_logs ───────────────────────────────────
+  server.tool(
+    `${prefix}get_console_logs`,
+    "Get recent console messages (log, warn, error, info) from the web page.",
+    {
+      level: z.enum(["log", "warn", "error", "info", "debug", "all"]).optional()
+        .describe("Filter by log level (default: all)"),
+      maxLines: z.number().optional().describe("Maximum entries to return (default: 100)"),
+      grep: z.string().optional().describe("Filter messages by regex pattern"),
+    },
+    async ({ level, maxLines, grep }) => {
+      try {
+        let entries = collector.getConsoleLogs(maxLines ?? 100);
+
+        if (level && level !== "all") {
+          entries = entries.filter((e) => e.level === level);
+        }
+
+        if (grep) {
+          const regex = new RegExp(grep, "i");
+          entries = entries.filter((e) => regex.test(e.text));
+        }
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              totalCollected: collector.getConsoleLogs().length,
+              returned: entries.length,
+              entries,
+            }),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `get_console_logs failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── chrome_get_network ────────────────────────────────────────
+  server.tool(
+    `${prefix}get_network`,
+    "Get recent network requests with URL, status, method, timing, and errors.",
+    {
+      maxEntries: z.number().optional().describe("Maximum entries to return (default: 100)"),
+      onlyFailed: z.boolean().optional().describe("Only return failed requests (4xx/5xx or network errors)"),
+      urlPattern: z.string().optional().describe("Filter by URL substring"),
+    },
+    async ({ maxEntries, onlyFailed, urlPattern }) => {
+      try {
+        let entries = collector.getNetworkEntries(maxEntries ?? 100);
+
+        if (onlyFailed) {
+          entries = entries.filter(
+            (e) => e.error || (e.status && e.status >= 400),
+          );
+        }
+
+        if (urlPattern) {
+          const lower = urlPattern.toLowerCase();
+          entries = entries.filter((e) => e.url.toLowerCase().includes(lower));
+        }
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              totalCollected: collector.getNetworkEntries().length,
+              returned: entries.length,
+              entries: entries.map((e) => ({
+                method: e.method,
+                url: e.url,
+                status: e.status ?? null,
+                statusText: e.statusText ?? null,
+                type: e.type ?? null,
+                error: e.error ?? null,
+                durationMs: e.endTime && e.startTime
+                  ? Math.round((e.endTime - e.startTime) * 1000)
+                  : null,
+                size: e.encodedDataLength ?? null,
+              })),
+            }),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `get_network failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── chrome_evaluate ───────────────────────────────────────────
+  server.tool(
+    `${prefix}evaluate`,
+    "Execute JavaScript in the page context and return the result. The expression is evaluated via CDP Runtime.evaluate.",
+    {
+      expression: z.string().describe("JavaScript expression to evaluate"),
+      awaitPromise: z.boolean().optional().describe("If true, await the result if it is a Promise (default: false)"),
+    },
+    async ({ expression, awaitPromise }) => {
+      try {
+        const result = await bridge.send("Runtime.evaluate", {
+          expression,
+          returnByValue: true,
+          awaitPromise: awaitPromise ?? false,
+          generatePreview: true,
+        }) as {
+          result: { type: string; value?: unknown; description?: string; subtype?: string };
+          exceptionDetails?: { text?: string; exception?: { description?: string } };
+        };
+
+        if (result.exceptionDetails) {
+          const ex = result.exceptionDetails;
+          return {
+            content: [{
+              type: "text" as const,
+              text: JSON.stringify({
+                error: true,
+                message: ex.exception?.description ?? ex.text ?? "Evaluation error",
+              }),
+            }],
+            isError: true,
+          };
+        }
+
+        const value = result.result.value !== undefined
+          ? result.result.value
+          : result.result.description ?? `[${result.result.type}${result.result.subtype ? `:${result.result.subtype}` : ""}]`;
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ type: result.result.type, value }),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `evaluate failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── chrome_get_dom ────────────────────────────────────────────
+  server.tool(
+    `${prefix}get_dom`,
+    "Get a simplified DOM tree of the visible page. Returns tag names, ids, classes, and truncated text content.",
+    {
+      selector: z.string().optional().describe("CSS selector to scope the tree (default: 'body')"),
+      maxDepth: z.number().optional().describe("Maximum depth to traverse (default: 5)"),
+      maxNodes: z.number().optional().describe("Maximum nodes to return (default: 200)"),
+    },
+    async ({ selector, maxDepth, maxNodes }) => {
+      try {
+        const sel = selector ?? "body";
+        const depth = maxDepth ?? 5;
+        const limit = maxNodes ?? 200;
+
+        // Use Runtime.evaluate to traverse the DOM in-page for efficiency
+        const expression = `
+          (function() {
+            const root = document.querySelector(${JSON.stringify(sel)});
+            if (!root) return JSON.stringify({ error: "Selector not found: " + ${JSON.stringify(sel)} });
+            const nodes = [];
+            let count = 0;
+            function walk(el, d) {
+              if (count >= ${limit} || d > ${depth}) return;
+              count++;
+              const tag = el.tagName ? el.tagName.toLowerCase() : '#text';
+              const node = { tag: tag };
+              if (el.id) node.id = el.id;
+              if (el.className && typeof el.className === 'string' && el.className.trim())
+                node.classes = el.className.trim().split(/\\s+/).slice(0, 5);
+              if (el.childNodes.length === 1 && el.childNodes[0].nodeType === 3) {
+                const txt = el.textContent.trim();
+                if (txt) node.text = txt.slice(0, 100);
+              }
+              if (el.children && el.children.length > 0) {
+                node.children = [];
+                for (let i = 0; i < el.children.length; i++) {
+                  walk(el.children[i], d + 1);
+                  if (count < ${limit}) node.children.push(nodes[nodes.length - 1]);
+                }
+              }
+              nodes.push(node);
+            }
+            walk(root, 0);
+            return JSON.stringify({ nodeCount: count, tree: nodes[nodes.length - 1] });
+          })()
+        `;
+
+        const result = await bridge.send("Runtime.evaluate", {
+          expression,
+          returnByValue: true,
+        }) as { result: { value?: string } };
+
+        const parsed = result.result.value ? JSON.parse(result.result.value) : { error: "No result" };
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(parsed) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `get_dom failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── chrome_click ──────────────────────────────────────────────
+  server.tool(
+    `${prefix}click`,
+    "Click on an element by CSS selector or at specific x,y coordinates.",
+    {
+      selector: z.string().optional().describe("CSS selector of element to click"),
+      x: z.number().optional().describe("X coordinate to click (used if no selector)"),
+      y: z.number().optional().describe("Y coordinate to click (used if no selector)"),
+    },
+    async ({ selector, x, y }) => {
+      try {
+        if (selector) {
+          // Use Runtime.evaluate to find element and click it, returning center coordinates
+          const result = await bridge.send("Runtime.evaluate", {
+            expression: `
+              (function() {
+                const el = document.querySelector(${JSON.stringify(selector)});
+                if (!el) return JSON.stringify({ error: "Element not found: " + ${JSON.stringify(selector)} });
+                const rect = el.getBoundingClientRect();
+                const cx = Math.round(rect.left + rect.width / 2);
+                const cy = Math.round(rect.top + rect.height / 2);
+                el.click();
+                return JSON.stringify({ ok: true, selector: ${JSON.stringify(selector)}, clicked: { x: cx, y: cy } });
+              })()
+            `,
+            returnByValue: true,
+          }) as { result: { value?: string } };
+
+          const parsed = result.result.value ? JSON.parse(result.result.value) : { error: "No result" };
+          if (parsed.error) {
+            return {
+              content: [{ type: "text" as const, text: JSON.stringify(parsed) }],
+              isError: true,
+            };
+          }
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(parsed) }],
+          };
+        }
+
+        if (x !== undefined && y !== undefined) {
+          // Use CDP Input.dispatchMouseEvent for coordinate-based click
+          await bridge.send("Input.dispatchMouseEvent", {
+            type: "mousePressed",
+            x,
+            y,
+            button: "left",
+            clickCount: 1,
+          });
+          await bridge.send("Input.dispatchMouseEvent", {
+            type: "mouseReleased",
+            x,
+            y,
+            button: "left",
+            clickCount: 1,
+          });
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify({ ok: true, clicked: { x, y } }) }],
+          };
+        }
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ error: "Provide either 'selector' or x/y coordinates" }) }],
+          isError: true,
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `click failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── chrome_type_text ──────────────────────────────────────────
+  server.tool(
+    `${prefix}type_text`,
+    "Type text into the currently focused element or a specific element by selector. Optionally clear existing content first.",
+    {
+      text: z.string().describe("Text to type"),
+      selector: z.string().optional().describe("CSS selector to focus before typing"),
+      clearFirst: z.boolean().optional().describe("Select all and clear before typing (default: false)"),
+    },
+    async ({ text, selector, clearFirst }) => {
+      try {
+        // Focus the element if selector is provided
+        if (selector) {
+          await bridge.send("Runtime.evaluate", {
+            expression: `
+              (function() {
+                const el = document.querySelector(${JSON.stringify(selector)});
+                if (el) { el.focus(); el.scrollIntoView({ block: 'center' }); }
+              })()
+            `,
+          });
+        }
+
+        // Clear existing content if requested
+        if (clearFirst) {
+          // Select all (Ctrl+A / Cmd+A), then delete
+          await bridge.send("Input.dispatchKeyEvent", {
+            type: "keyDown",
+            key: "a",
+            code: "KeyA",
+            windowsVirtualKeyCode: 65,
+            nativeVirtualKeyCode: 65,
+            modifiers: 2, // Ctrl
+          });
+          await bridge.send("Input.dispatchKeyEvent", {
+            type: "keyUp",
+            key: "a",
+            code: "KeyA",
+            windowsVirtualKeyCode: 65,
+            nativeVirtualKeyCode: 65,
+            modifiers: 2,
+          });
+          await bridge.send("Input.dispatchKeyEvent", {
+            type: "keyDown",
+            key: "Backspace",
+            code: "Backspace",
+            windowsVirtualKeyCode: 8,
+            nativeVirtualKeyCode: 8,
+          });
+          await bridge.send("Input.dispatchKeyEvent", {
+            type: "keyUp",
+            key: "Backspace",
+            code: "Backspace",
+            windowsVirtualKeyCode: 8,
+            nativeVirtualKeyCode: 8,
+          });
+        }
+
+        // Type text using insertText for reliable input
+        await bridge.send("Input.insertText", { text });
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ ok: true, typed: text.length }) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `type_text failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── chrome_navigate ───────────────────────────────────────────
+  server.tool(
+    `${prefix}navigate`,
+    "Navigate the current tab to a URL via CDP Page.navigate.",
+    {
+      url: z.string().describe("URL to navigate to"),
+      waitForLoad: z.boolean().optional().describe("Wait for page load event (default: true)"),
+    },
+    async ({ url, waitForLoad }) => {
+      try {
+        const result = await bridge.send("Page.navigate", { url }) as {
+          frameId?: string;
+          errorText?: string;
+        };
+
+        if (result.errorText) {
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify({ error: result.errorText, url }) }],
+            isError: true,
+          };
+        }
+
+        // Optionally wait for load
+        if (waitForLoad !== false) {
+          // Wait up to 30s for the page load by polling readyState
+          const deadline = Date.now() + 30_000;
+          while (Date.now() < deadline) {
+            try {
+              const state = await bridge.send("Runtime.evaluate", {
+                expression: "document.readyState",
+                returnByValue: true,
+              }) as { result: { value?: string } };
+              if (state.result.value === "complete") break;
+            } catch {
+              // page may be navigating, retry
+            }
+            await new Promise((r) => setTimeout(r, 200));
+          }
+        }
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ ok: true, url, frameId: result.frameId }) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `navigate failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── chrome_get_page_info ──────────────────────────────────────
+  server.tool(
+    `${prefix}get_page_info`,
+    "Get current page URL, title, viewport size, cookies count, and readyState.",
+    {},
+    async () => {
+      try {
+        const result = await bridge.send("Runtime.evaluate", {
+          expression: `JSON.stringify({
+            url: location.href,
+            title: document.title,
+            readyState: document.readyState,
+            viewport: { width: window.innerWidth, height: window.innerHeight },
+            screenSize: { width: screen.width, height: screen.height },
+            cookieCount: document.cookie.split(';').filter(c => c.trim()).length,
+            localStorage: Object.keys(localStorage).length,
+            sessionStorage: Object.keys(sessionStorage).length,
+          })`,
+          returnByValue: true,
+        }) as { result: { value?: string } };
+
+        const info = result.result.value ? JSON.parse(result.result.value) : {};
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(info) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `get_page_info failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}