assistme 0.3.0 → 0.3.2

package/src/mcp/browser-server.ts

@@ -0,0 +1,258 @@
+import {
+  createSdkMcpServer,
+  tool,
+  type McpSdkServerConfigWithInstance,
+} from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod/v4";
+import { executeTool } from "../tools/index.js";
+import { getLimiterForTool } from "../utils/rate-limiter.js";
+
+// ── Helper ──────────────────────────────────────────────────────────
+
+/** Wrap executeTool with rate limiting and text result. */
+async function callTool(
+  name: string,
+  input: Record<string, unknown>
+): Promise<{ content: Array<{ type: "text"; text: string }> }> {
+  const limiter = getLimiterForTool(name);
+  if (limiter) await limiter.acquire();
+  const result = await executeTool(name, input);
+  return { content: [{ type: "text", text: result }] };
+}
+
+// ── Browser MCP Server ──────────────────────────────────────────────
+
+export const BROWSER_TOOL_NAMES = [
+  "browser_connect",
+  "browser_navigate",
+  "browser_read_page",
+  "browser_screenshot",
+  "browser_click",
+  "browser_type",
+  "browser_press_key",
+  "browser_scroll",
+  "browser_get_elements",
+  "browser_select",
+  "browser_snapshot",
+  "browser_act",
+  "browser_evaluate",
+  "browser_list_tabs",
+  "browser_switch_tab",
+  "browser_new_tab",
+  "browser_request_user_action",
+] as const;
+
+export function createBrowserMcpServer(): McpSdkServerConfigWithInstance {
+  return createSdkMcpServer({
+    name: "assistme-browser",
+    version: "1.0.0",
+    tools: [
+      tool(
+        "browser_connect",
+        "Connect to the user's real Chrome browser via CDP. Chrome will be auto-launched if not already running.",
+        { tab_index: z.number().optional().describe("Tab index (default: 0)") },
+        async (args) => callTool("browser_connect", args)
+      ),
+      tool(
+        "browser_navigate",
+        "Navigate the user's browser to a URL, using the user's real browser with all their cookies and logins.",
+        { url: z.string().describe("URL to navigate to") },
+        async (args) => callTool("browser_navigate", args)
+      ),
+      tool(
+        "browser_read_page",
+        "Read the text content of the currently open page. Returns page title, URL, and main text content.",
+        {},
+        async () => callTool("browser_read_page", {})
+      ),
+      tool(
+        "browser_screenshot",
+        "Take a screenshot of the current browser page. Returns a base64-encoded PNG image.",
+        {},
+        async () => {
+          const limiter = getLimiterForTool("browser_screenshot");
+          if (limiter) await limiter.acquire();
+          const base64 = await executeTool("browser_screenshot", {});
+          if (base64.length > 100) {
+            return {
+              content: [
+                {
+                  type: "image" as const,
+                  data: base64,
+                  mimeType: "image/png",
+                } as unknown as { type: "text"; text: string },
+              ],
+            };
+          }
+          return { content: [{ type: "text", text: base64 }] };
+        }
+      ),
+      tool(
+        "browser_click",
+        "Click on an element in the user's browser using a CSS selector.",
+        { selector: z.string().describe("CSS selector of the element to click") },
+        async (args) => callTool("browser_click", args)
+      ),
+      tool(
+        "browser_type",
+        "Type text into an input field in the user's browser.",
+        {
+          selector: z.string().describe("CSS selector of the input element"),
+          text: z.string().describe("Text to type"),
+        },
+        async (args) => callTool("browser_type", args)
+      ),
+      tool(
+        "browser_press_key",
+        "Press a keyboard key in the browser. Supports: Enter, Tab, Escape, Backspace, ArrowDown, ArrowUp.",
+        { key: z.string().describe("Key to press") },
+        async (args) => callTool("browser_press_key", args)
+      ),
+      tool(
+        "browser_scroll",
+        "Scroll the page up or down.",
+        { direction: z.string().describe("'down' or 'up'") },
+        async (args) => callTool("browser_scroll", args)
+      ),
+      tool(
+        "browser_get_elements",
+        "Find all interactive elements (links, buttons, inputs) on the current page.",
+        {},
+        async () => callTool("browser_get_elements", {})
+      ),
+      tool(
+        "browser_select",
+        "Select an option from a dropdown menu. Handles both native <select> elements and custom dropdowns (Material Design, React, Angular). Use this instead of manually clicking dropdown items.",
+        {
+          selector: z
+            .string()
+            .describe(
+              "CSS selector of the dropdown, or its label/placeholder text (e.g. 'Month', 'Gender', '#country')"
+            ),
+          option: z
+            .string()
+            .describe("Visible text of the option to select (e.g. 'March', 'Male')"),
+        },
+        async (args) => callTool("browser_select", args)
+      ),
+      tool(
+        "browser_snapshot",
+        "Take a screenshot and discover all interactive elements with numbered refs. " +
+          "Returns a screenshot + a compact ref table. PREFERRED way to understand a page. " +
+          "Set annotate=true to overlay red ref badges (useful for simple pages). " +
+          "Use the ref numbers with browser_act to interact with elements.",
+        {
+          annotate: z
+            .boolean()
+            .optional()
+            .describe(
+              "Overlay ref badges on the screenshot. Default false. Use true for simple pages where visual context helps."
+            ),
+        },
+        async (args) => {
+          const limiter = getLimiterForTool("browser_snapshot");
+          if (limiter) await limiter.acquire();
+          const result = await executeTool("browser_snapshot", args);
+
+          // Parse the composite result: ref table text + image data
+          const parts = result.split("\n__SNAPSHOT_IMAGE__:");
+          const refTable = parts[0];
+          const imageData = parts[1] || "";
+
+          const content: Array<{ type: "text"; text: string }> = [];
+          if (imageData.length > 100) {
+            content.push({
+              type: "image" as const,
+              data: imageData,
+              mimeType: "image/png",
+            } as unknown as { type: "text"; text: string });
+          }
+          content.push({ type: "text", text: refTable });
+
+          return { content };
+        }
+      ),
+      tool(
+        "browser_act",
+        "Execute actions using ref numbers from browser_snapshot. Supports: click, type, select, press, scroll, wait. " +
+          "Batch multiple actions in one call to reduce round-trips. Set screenshot=true to see the result.",
+        {
+          actions: z
+            .array(
+              z.object({
+                action: z
+                  .enum(["click", "type", "select", "press", "scroll", "wait"])
+                  .describe("Action type"),
+                ref: z.number().optional().describe("Ref number from browser_snapshot"),
+                text: z.string().optional().describe("Text to type (for 'type' action)"),
+                option: z.string().optional().describe("Option to select (for 'select' action)"),
+                key: z.string().optional().describe("Key to press (for 'press' action)"),
+                direction: z.string().optional().describe("'up' or 'down' (for 'scroll')"),
+                ms: z.number().optional().describe("Wait duration in ms (for 'wait', max 5000)"),
+              })
+            )
+            .describe("Actions to execute sequentially"),
+          screenshot: z
+            .boolean()
+            .optional()
+            .describe("Take screenshot after actions (default: false)"),
+        },
+        async (args) => {
+          const limiter = getLimiterForTool("browser_act");
+          if (limiter) await limiter.acquire();
+          const result = await executeTool("browser_act", {
+            actions: args.actions,
+            screenshot: args.screenshot,
+          });
+
+          // Parse composite result: action results + optional screenshot
+          const parts = result.split("\n__ACT_SCREENSHOT__:");
+          const actionText = parts[0];
+          const screenshotData = parts[1] || "";
+
+          const content: Array<{ type: "text"; text: string }> = [];
+          content.push({ type: "text", text: actionText });
+          if (screenshotData.length > 100) {
+            content.push({
+              type: "image" as const,
+              data: screenshotData,
+              mimeType: "image/png",
+            } as unknown as { type: "text"; text: string });
+          }
+
+          return { content };
+        }
+      ),
+      tool(
+        "browser_evaluate",
+        "Execute JavaScript in the browser page context. Use as a last resort when browser_snapshot + browser_act cannot handle the interaction.",
+        { expression: z.string().describe("JavaScript expression to evaluate") },
+        async (args) => callTool("browser_evaluate", args)
+      ),
+      tool("browser_list_tabs", "List all open tabs in the user's browser.", {}, async () =>
+        callTool("browser_list_tabs", {})
+      ),
+      tool(
+        "browser_switch_tab",
+        "Switch to a different browser tab by index.",
+        { index: z.number().describe("Tab index") },
+        async (args) => callTool("browser_switch_tab", args)
+      ),
+      tool(
+        "browser_new_tab",
+        "Open a new tab in the user's browser, optionally navigating to a URL.",
+        { url: z.string().optional().describe("URL to open (default: blank)") },
+        async (args) => callTool("browser_new_tab", args)
+      ),
+      tool(
+        "browser_request_user_action",
+        "Request the user to perform an action in their browser (login, CAPTCHA, 2FA, etc.).",
+        {
+          message: z.string().describe("Clear description of what the user needs to do"),
+          wait_seconds: z.number().optional().describe("How long to wait (default: 60)"),
+        },
+        async (args) => callTool("browser_request_user_action", args)
+      ),
+    ],
+  });
+}