mcp-scraper 0.2.18 → 0.2.20

package/dist/bin/browser-agent-stdio-server.cjs

@@ -14,10 +14,22 @@ var import_node_os2 = require("os");
 var import_node_path2 = require("path");
 
 // src/version.ts
-var PACKAGE_VERSION = "0.2.18";
+var PACKAGE_VERSION = "0.2.20";
 
 // src/mcp/browser-agent-tool-schemas.ts
 var import_zod = require("zod");
+var NullableString = import_zod.z.string().nullable();
+var BrowserRawObject = import_zod.z.record(import_zod.z.unknown());
+var BrowserElementOutput = import_zod.z.record(import_zod.z.unknown());
+var BrowserBaseOutput = {
+  ok: import_zod.z.boolean().describe("Whether the browser-agent action succeeded."),
+  tool: import_zod.z.string().describe("Browser Agent MCP tool that produced this response."),
+  session_id: NullableString.describe("Browser session id when the response is scoped to a session.")
+};
+var BrowserReplayBaseOutput = {
+  ...BrowserBaseOutput,
+  replay_id: NullableString.describe("Replay id when the response is scoped to a replay.")
+};
 var BrowserOpenInputSchema = {
   label: import_zod.z.string().optional().describe("Optional human label for this session, shown in the watch console."),
   url: import_zod.z.string().url().optional().describe("Optional URL to navigate to immediately after opening."),
@@ -25,7 +37,7 @@ var BrowserOpenInputSchema = {
   timeout_seconds: import_zod.z.number().int().min(60).max(259200).optional().describe("How long the session may live before auto-termination. Defaults to 600. The browser idles into a zero-cost standby between actions, so a longer timeout is cheap.")
 };
 var BrowserSessionInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open.")
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself.")
 };
 var BrowserLocateTargetSchema = import_zod.z.object({
   name: import_zod.z.string().optional().describe("Optional label for this target, echoed in the result."),
@@ -37,43 +49,43 @@ var BrowserLocateTargetSchema = import_zod.z.object({
   message: "target requires selector or text"
 });
 var BrowserLocateInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
   targets: import_zod.z.array(BrowserLocateTargetSchema).min(1).max(20).describe("DOM targets to locate in the current viewport. Use selectors for exact elements, or text for visible text ranges.")
 };
 var BrowserGotoInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
   url: import_zod.z.string().url().describe("URL to navigate the browser to.")
 };
 var BrowserClickInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
-  x: import_zod.z.number().describe("X coordinate to click, in screenshot pixels. Use the x of an element from the latest screenshot."),
-  y: import_zod.z.number().describe("Y coordinate to click, in screenshot pixels."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  x: import_zod.z.number().describe("X coordinate to click, in screenshot pixels. Use only coordinates from the latest browser_screenshot, browser_read, or browser_locate result; do not guess."),
+  y: import_zod.z.number().describe("Y coordinate to click, in screenshot pixels. Use only coordinates from the latest browser_screenshot, browser_read, or browser_locate result; do not guess."),
   button: import_zod.z.enum(["left", "right", "middle"]).default("left").describe("Mouse button."),
   num_clicks: import_zod.z.number().int().min(1).max(3).optional().describe("Number of clicks, e.g. 2 for double-click.")
 };
 var BrowserTypeInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
   text: import_zod.z.string().describe("Text to type at the current focus. Click a field first to focus it."),
   delay: import_zod.z.number().int().min(0).max(500).optional().describe("Optional per-keystroke delay in ms for human-like typing.")
 };
 var BrowserScrollInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
   delta_y: import_zod.z.number().default(5).describe("Vertical scroll in wheel units. Positive scrolls down, negative up."),
   delta_x: import_zod.z.number().default(0).describe("Horizontal scroll in wheel units."),
   x: import_zod.z.number().optional().describe("X position to scroll at. Defaults to screen center."),
   y: import_zod.z.number().optional().describe("Y position to scroll at. Defaults to screen center.")
 };
 var BrowserPressInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
   keys: import_zod.z.array(import_zod.z.string()).min(1).describe('Keys or combinations to press, e.g. ["Return"], ["Ctrl+a"], ["Ctrl+Shift+Tab"].')
 };
 var BrowserReplayStopInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
-  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start.")
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays. Use only a returned replay_id; do not construct one yourself.")
 };
 var BrowserReplayDownloadInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
-  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays. Use only a returned replay_id; do not construct one yourself."),
   filename: import_zod.z.string().optional().describe("Optional local MP4 filename. Defaults to a timestamped replay filename.")
 };
 var BrowserReplayAnnotationSchema = import_zod.z.object({
@@ -95,7 +107,7 @@ var BrowserReplayAnnotationSchema = import_zod.z.object({
   thickness: import_zod.z.number().min(1).max(24).optional().describe("Stroke thickness in pixels. Defaults to 5.")
 });
 var BrowserReplayMarkInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open. A replay must already be recording."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself. A replay must already be recording."),
   target: BrowserLocateTargetSchema.describe("The exact DOM element or text range to mark in the current viewport."),
   type: import_zod.z.enum(["box", "circle", "underline", "arrow"]).default("box").describe("Annotation style to generate. Labels are included on the returned annotation when label is provided."),
   label: import_zod.z.string().max(120).optional().describe("Optional callout text to render near the target."),
@@ -106,8 +118,8 @@ var BrowserReplayMarkInputSchema = {
   duration_seconds: import_zod.z.number().min(0.5).max(30).default(4).describe("How long the generated annotation should remain visible.")
 };
 var BrowserReplayAnnotateInputSchema = {
-  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
-  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays."),
+  session_id: import_zod.z.string().describe("The session id returned by browser_open or browser_list_sessions. Use only a returned session_id; do not construct one yourself."),
+  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays. Use only a returned replay_id; do not construct one yourself."),
   annotations: import_zod.z.array(BrowserReplayAnnotationSchema).min(1).max(50).describe("Timed overlay annotations to render on the replay. Prefer annotations returned by browser_replay_mark; otherwise use exact DOM bounds from browser_locate/browser_screenshot/browser_read."),
   filename: import_zod.z.string().optional().describe("Optional output MP4 filename. Defaults to a timestamped annotated replay filename."),
   source_width: import_zod.z.number().positive().optional().describe("Width of the screenshot coordinate space used for annotations. Defaults to the replay video width."),
@@ -118,6 +130,113 @@ var BrowserReplayAnnotateInputSchema = {
 var BrowserListInputSchema = {
   include_closed: import_zod.z.boolean().default(false).describe("Include closed sessions in the list.")
 };
+var BrowserOpenOutputSchema = {
+  ok: import_zod.z.boolean(),
+  tool: import_zod.z.literal("browser_open"),
+  session_id: import_zod.z.string().describe("Session id returned by browser_open. Use only this exact value in later browser_* calls; do not construct one yourself."),
+  watch_url: import_zod.z.string().describe("Human watch/takeover URL for this browser session."),
+  live_view_url: NullableString.describe("Raw live-view URL from the browser service when available."),
+  url: NullableString.describe("Initial URL requested by the caller, when provided."),
+  hint: import_zod.z.string(),
+  raw: BrowserRawObject.optional()
+};
+var BrowserScreenshotOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_screenshot"),
+  url: NullableString,
+  title: NullableString,
+  text: import_zod.z.string(),
+  elements: import_zod.z.array(BrowserElementOutput),
+  screenshot: import_zod.z.object({
+    mime_type: import_zod.z.string(),
+    inline: import_zod.z.boolean()
+  }).nullable()
+};
+var BrowserReadOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_read"),
+  url: NullableString,
+  title: NullableString,
+  text: import_zod.z.string(),
+  elements: import_zod.z.array(BrowserElementOutput),
+  raw: BrowserRawObject.optional()
+};
+var BrowserLocateOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_locate"),
+  url: NullableString,
+  title: NullableString,
+  viewport: BrowserRawObject.nullable(),
+  replay: BrowserRawObject.nullable(),
+  targets: import_zod.z.array(BrowserRawObject),
+  raw: BrowserRawObject.optional()
+};
+var BrowserActionOutputSchema = {
+  ...BrowserBaseOutput,
+  result: BrowserRawObject.describe("Provider action result. Check ok and follow with browser_screenshot/browser_read when page state matters."),
+  nextRecommendedTool: import_zod.z.string().nullable()
+};
+var BrowserReplayStartOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_start"),
+  view_url: NullableString,
+  download_url: NullableString,
+  raw: BrowserRawObject.optional()
+};
+var BrowserReplayStopOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_stop"),
+  view_url: NullableString,
+  download_url: NullableString,
+  raw: BrowserRawObject.optional()
+};
+var BrowserListReplaysOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_list_replays"),
+  replays: import_zod.z.array(BrowserRawObject),
+  count: import_zod.z.number().int().min(0)
+};
+var BrowserReplayDownloadOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_download"),
+  file_path: NullableString,
+  bytes: import_zod.z.number().int().min(0).nullable(),
+  mime_type: NullableString,
+  download_url: NullableString
+};
+var BrowserReplayMarkOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_mark"),
+  annotation: BrowserRawObject,
+  source_width: import_zod.z.number().nullable(),
+  source_height: import_zod.z.number().nullable(),
+  target: BrowserRawObject.nullable(),
+  hint: import_zod.z.string()
+};
+var BrowserReplayAnnotateOutputSchema = {
+  ...BrowserReplayBaseOutput,
+  tool: import_zod.z.literal("browser_replay_annotate"),
+  source_file_path: NullableString,
+  annotated_file_path: NullableString,
+  bytes: import_zod.z.number().int().min(0).nullable(),
+  width: import_zod.z.number().int().min(0).nullable(),
+  height: import_zod.z.number().int().min(0).nullable(),
+  annotation_count: import_zod.z.number().int().min(0).nullable(),
+  mime_type: NullableString
+};
+var BrowserCloseOutputSchema = {
+  ...BrowserBaseOutput,
+  tool: import_zod.z.literal("browser_close"),
+  closed: import_zod.z.boolean(),
+  raw: BrowserRawObject.optional()
+};
+var BrowserListSessionsOutputSchema = {
+  ok: import_zod.z.boolean(),
+  tool: import_zod.z.literal("browser_list_sessions"),
+  session_id: import_zod.z.null(),
+  sessions: import_zod.z.array(BrowserRawObject),
+  count: import_zod.z.number().int().min(0)
+};
 
 // src/mcp/replay-annotator.ts
 var import_node_child_process = require("child_process");
@@ -380,8 +499,40 @@ async function annotateReplayVideo(inputFilePath, outputFilePath, options) {
 }
 
 // src/mcp/browser-agent-mcp-server.ts
-function textResult(value, isError = false) {
-  return { content: [{ type: "text", text: JSON.stringify(value) }], isError };
+function structuredResult(value, isError = false) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value) }],
+    structuredContent: value,
+    isError
+  };
+}
+function errorMessage(value) {
+  if (value && typeof value === "object") {
+    const data = value;
+    if (typeof data.error === "string") return data.error;
+    if (typeof data.message === "string") return data.message;
+  }
+  return typeof value === "string" ? value : "Browser Agent request failed";
+}
+function errorResult(tool, value, sessionId = null, replayId = null) {
+  return structuredResult({
+    ok: false,
+    tool,
+    session_id: sessionId,
+    ...replayId !== null ? { replay_id: replayId } : {},
+    error: errorMessage(value),
+    raw: value && typeof value === "object" ? value : { value }
+  }, true);
+}
+function actionResult(tool, sessionId, ok, data, nextRecommendedTool = "browser_screenshot") {
+  if (!ok) return errorResult(tool, data, sessionId);
+  return structuredResult({
+    ok: true,
+    tool,
+    session_id: sessionId,
+    result: data && typeof data === "object" ? data : { value: data },
+    nextRecommendedTool
+  });
 }
 function outputBaseDir() {
   return process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path2.join)((0, import_node_os2.homedir)(), "Downloads", "mcp-scraper");
@@ -486,6 +637,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Open Browser Session",
       description: "Open a fresh cloud browser you can drive. Returns a session_id used by all other browser_* tools, and a watch_url where a human can watch live or take over. Anti-bot stealth and automatic CAPTCHA/Cloudflare solving are on by default: if a Cloudflare or CAPTCHA challenge appears, do NOT click it \u2014 wait a few seconds and call browser_screenshot again; it is solved automatically. Billing: metered per second of active browser work at ~4 credits per minute; idle and standby time are free. Call browser_close when done to stop the meter. After opening, call browser_screenshot to see the page.",
       inputSchema: BrowserOpenInputSchema,
+      outputSchema: BrowserOpenOutputSchema,
       annotations: annotations("Open Browser Session")
     },
     async (input) => {
@@ -494,16 +646,20 @@ function registerBrowserAgentMcpTools(server2, opts) {
         profile: input.profile,
         timeout_seconds: input.timeout_seconds
       });
-      if (!open.ok) return textResult(open.data, true);
+      if (!open.ok) return errorResult("browser_open", open.data);
       const session = open.data;
       if (input.url) {
         await req("POST", `/agent/sessions/${session.session_id}/goto`, { url: input.url });
       }
-      return textResult({
+      return structuredResult({
+        ok: true,
+        tool: "browser_open",
         session_id: session.session_id,
         watch_url: `${consoleBase}/console/${session.session_id}`,
         live_view_url: session.live_view_url ?? null,
-        hint: "Call browser_screenshot to see the page. Click by the x,y of an element from the snapshot."
+        url: input.url ?? null,
+        hint: "Call browser_screenshot to see the page. Click by the x,y of an element from the snapshot.",
+        raw: session
       });
     }
   );
@@ -513,19 +669,30 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "See Page (Screenshot + Elements)",
       description: "Capture what the browser currently shows. Returns a screenshot image PLUS a text snapshot listing interactive elements with their center x,y coordinates, the page url and title, and visible text. This is your primary way to perceive the page. Click elements by their listed x,y. If a Cloudflare/CAPTCHA challenge is visible, wait and screenshot again rather than clicking it.",
       inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserScreenshotOutputSchema,
       annotations: annotations("See Page", true)
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/screenshot`);
-      if (!res.ok) return textResult(res.data, true);
+      if (!res.ok) return errorResult("browser_screenshot", res.data, input.session_id);
       const { image_base64, mime_type, url, title, elements, text } = res.data;
       const content = [];
       if (image_base64) content.push({ type: "image", data: image_base64, mimeType: mime_type ?? "image/png" });
+      const structured = {
+        ok: true,
+        tool: "browser_screenshot",
+        session_id: input.session_id,
+        url: url ?? null,
+        title: title ?? null,
+        text: typeof text === "string" ? text : "",
+        elements: Array.isArray(elements) ? elements : [],
+        screenshot: image_base64 ? { mime_type: mime_type ?? "image/png", inline: true } : null
+      };
       content.push({
         type: "text",
-        text: JSON.stringify({ url, title, elements, text })
+        text: JSON.stringify(structured)
       });
-      return { content };
+      return { content, structuredContent: structured };
     }
   );
   server2.registerTool(
@@ -534,11 +701,22 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Read Page Text + Elements",
       description: "Return the page url, title, visible text, and the list of interactive elements (with x,y) without an image. Cheaper than browser_screenshot when you only need to read content or find a target element to click.",
       inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserReadOutputSchema,
       annotations: annotations("Read Page", true)
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/read`);
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_read", res.data, input.session_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_read",
+        session_id: input.session_id,
+        url: res.data?.url ?? null,
+        title: res.data?.title ?? null,
+        text: typeof res.data?.text === "string" ? res.data.text : "",
+        elements: Array.isArray(res.data?.elements) ? res.data.elements : [],
+        raw: res.data
+      });
     }
   );
   server2.registerTool(
@@ -547,32 +725,46 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Locate DOM Targets",
       description: "Locate exact visible DOM elements or text ranges in the current browser viewport and return left/top/width/height bounds in screenshot pixels. Use this before drawing annotations or when a callout must literally circle, box, underline, or point to a real element. Prefer CSS selectors for exact UI elements; use text when selector is unknown. When a replay is actively recording, the result includes replay_elapsed_seconds for timing.",
       inputSchema: BrowserLocateInputSchema,
+      outputSchema: BrowserLocateOutputSchema,
       annotations: annotations("Locate DOM Targets", true)
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/locate`, { targets: input.targets });
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_locate", res.data, input.session_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_locate",
+        session_id: input.session_id,
+        url: res.data?.url ?? null,
+        title: res.data?.title ?? null,
+        viewport: res.data?.viewport ?? null,
+        replay: res.data?.replay ?? null,
+        targets: Array.isArray(res.data?.targets) ? res.data.targets : [],
+        raw: res.data
+      });
     }
   );
   server2.registerTool(
     "browser_goto",
     {
       title: "Navigate To URL",
-      description: "Navigate the browser to a URL. Follow with browser_screenshot to see the result.",
+      description: "Navigate an existing browser session to a URL when the user asks you to go to another page or continue browsing in the same session. Use browser_open first if no session exists. Follow with browser_screenshot to see redirects, login walls, CAPTCHA/Cloudflare state, or the loaded page.",
       inputSchema: BrowserGotoInputSchema,
+      outputSchema: BrowserActionOutputSchema,
       annotations: annotations("Navigate To URL")
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/goto`, { url: input.url });
-      return textResult(res.data, !res.ok);
+      return actionResult("browser_goto", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
     "browser_click",
     {
       title: "Click",
-      description: "Click at x,y (screenshot pixel coordinates). Use the x,y of a target element from the latest browser_screenshot or browser_read.",
+      description: "Click a visible page target using screenshot pixel coordinates. Use this when the user asks you to press a button, open a menu, choose a result, or activate a visible UI element. Use x/y only from the latest browser_screenshot, browser_read, or browser_locate result; do not guess coordinates. Follow with browser_screenshot when the click may change the page.",
       inputSchema: BrowserClickInputSchema,
+      outputSchema: BrowserActionOutputSchema,
       annotations: annotations("Click")
     },
     async (input) => {
@@ -582,28 +774,30 @@ function registerBrowserAgentMcpTools(server2, opts) {
         button: input.button,
         num_clicks: input.num_clicks
       });
-      return textResult(res.data, !res.ok);
+      return actionResult("browser_click", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
     "browser_type",
     {
       title: "Type Text",
-      description: 'Type text at the current focus. Click an input field first to focus it. Use browser_press with ["Return"] to submit.',
+      description: 'Type text into the currently focused browser field. Use this when the user asks you to fill a search box, form field, login field, or editable text area. Click or Tab to the field first if focus is uncertain. Use browser_press with ["Return"] to submit, and browser_screenshot afterward when page state matters.',
       inputSchema: BrowserTypeInputSchema,
+      outputSchema: BrowserActionOutputSchema,
       annotations: annotations("Type Text")
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/type`, { text: input.text, delay: input.delay });
-      return textResult(res.data, !res.ok);
+      return actionResult("browser_type", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
     "browser_scroll",
     {
       title: "Scroll",
-      description: "Scroll the page. Positive delta_y scrolls down. Follow with browser_screenshot to see newly revealed content.",
+      description: "Scroll the page to reveal more content before reading, clicking, or locating elements. Positive delta_y scrolls down; negative delta_y scrolls up. Follow with browser_screenshot or browser_read to inspect newly revealed content.",
       inputSchema: BrowserScrollInputSchema,
+      outputSchema: BrowserActionOutputSchema,
       annotations: annotations("Scroll")
     },
     async (input) => {
@@ -613,20 +807,21 @@ function registerBrowserAgentMcpTools(server2, opts) {
         x: input.x,
         y: input.y
       });
-      return textResult(res.data, !res.ok);
+      return actionResult("browser_scroll", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
     "browser_press",
     {
       title: "Press Keys",
-      description: 'Press keys or combinations, e.g. ["Return"] to submit, ["Ctrl+a"] to select all, ["Ctrl+Shift+Tab"] to switch tabs.',
+      description: 'Press keyboard keys or combinations in the active browser session. Use this for submit, Escape, Tab navigation, select-all, or keyboard shortcuts. Examples: ["Return"], ["Escape"], ["Tab"], ["Ctrl+a"], ["Ctrl+Shift+Tab"]. Use browser_type for text entry and browser_screenshot after keypresses that may change the page.',
       inputSchema: BrowserPressInputSchema,
+      outputSchema: BrowserActionOutputSchema,
       annotations: annotations("Press Keys")
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/press`, { keys: input.keys });
-      return textResult(res.data, !res.ok);
+      return actionResult("browser_press", input.session_id, res.ok, res.data, "browser_screenshot");
     }
   );
   server2.registerTool(
@@ -635,11 +830,21 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Start Recording",
       description: "Start recording an MP4 replay of the session. Returns replay_id, view_url when available, and a download_url. Use to capture a task for later review; stop with browser_replay_stop.",
       inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserReplayStartOutputSchema,
       annotations: annotations("Start Recording")
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/replay/start`);
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_replay_start", res.data, input.session_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_replay_start",
+        session_id: input.session_id,
+        replay_id: res.data?.replay_id ?? res.data?.replayId ?? null,
+        view_url: res.data?.view_url ?? res.data?.viewUrl ?? null,
+        download_url: res.data?.download_url ?? res.data?.downloadUrl ?? null,
+        raw: res.data
+      });
     }
   );
   server2.registerTool(
@@ -648,11 +853,21 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Stop Recording",
       description: "Stop a replay recording and expose the final view_url and download_url. Use browser_replay_download to save the MP4 locally.",
       inputSchema: BrowserReplayStopInputSchema,
+      outputSchema: BrowserReplayStopOutputSchema,
       annotations: annotations("Stop Recording")
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/replay/stop`, { replay_id: input.replay_id });
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_replay_stop", res.data, input.session_id, input.replay_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_replay_stop",
+        session_id: input.session_id,
+        replay_id: res.data?.replay_id ?? res.data?.replayId ?? input.replay_id,
+        view_url: res.data?.view_url ?? res.data?.viewUrl ?? null,
+        download_url: res.data?.download_url ?? res.data?.downloadUrl ?? null,
+        raw: res.data
+      });
     }
   );
   server2.registerTool(
@@ -661,11 +876,20 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "List Replay Videos",
       description: "List replay recordings for a browser session, including final view_url and authenticated download_url values when available.",
       inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserListReplaysOutputSchema,
       annotations: annotations("List Replay Videos", true)
     },
     async (input) => {
       const res = await req("GET", `/agent/sessions/${input.session_id}/replays`);
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_list_replays", res.data, input.session_id);
+      const replays = Array.isArray(res.data?.replays) ? res.data.replays : [];
+      return structuredResult({
+        ok: true,
+        tool: "browser_list_replays",
+        session_id: input.session_id,
+        replays,
+        count: replays.length
+      });
     }
   );
   server2.registerTool(
@@ -674,11 +898,22 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Download Replay MP4",
       description: "Download a replay recording through MCP Scraper and save the MP4 locally under MCP_SCRAPER_OUTPUT_DIR/browser-replays. Use after browser_replay_stop or browser_list_replays.",
       inputSchema: BrowserReplayDownloadInputSchema,
-      annotations: annotations("Download Replay MP4", true)
+      outputSchema: BrowserReplayDownloadOutputSchema,
+      annotations: annotations("Download Replay MP4")
     },
     async (input) => {
       const res = await downloadReplay(input.session_id, input.replay_id, input.filename);
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_replay_download", res.data, input.session_id, input.replay_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_replay_download",
+        session_id: input.session_id,
+        replay_id: input.replay_id,
+        file_path: res.data?.file_path ?? null,
+        bytes: typeof res.data?.bytes === "number" ? res.data.bytes : null,
+        mime_type: res.data?.mime_type ?? null,
+        download_url: res.data?.download_url ?? null
+      });
     }
   );
   server2.registerTool(
@@ -687,19 +922,20 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Mark Replay Annotation",
       description: "While a replay is actively recording, locate one exact DOM target and return a ready-to-use annotation object with DOM bounds and replay-relative timing. Use this instead of guessing start_seconds or drawing rough rectangles. Workflow: start browser_replay_start, navigate until the target is visible and stable, call browser_replay_mark for each callout, then stop the replay and pass the returned annotations to browser_replay_annotate.",
       inputSchema: BrowserReplayMarkInputSchema,
+      outputSchema: BrowserReplayMarkOutputSchema,
       annotations: annotations("Mark Replay Annotation", true)
     },
     async (input) => {
       const res = await req("POST", `/agent/sessions/${input.session_id}/locate`, { targets: [input.target] });
-      if (!res.ok) return textResult(res.data, true);
+      if (!res.ok) return errorResult("browser_replay_mark", res.data, input.session_id);
       const target = res.data?.targets?.[0];
       const element = target?.element;
       const elapsed = res.data?.replay?.replay_elapsed_seconds;
       if (!target?.found || !element) {
-        return textResult({ error: target?.error ?? "target not found in current viewport", target }, true);
+        return errorResult("browser_replay_mark", { error: target?.error ?? "target not found in current viewport", target }, input.session_id);
       }
       if (!finiteNumber2(elapsed)) {
-        return textResult({ error: "no active replay clock found; call browser_replay_start before browser_replay_mark" }, true);
+        return errorResult("browser_replay_mark", { error: "no active replay clock found; call browser_replay_start before browser_replay_mark" }, input.session_id);
       }
       const padded = expandElementBounds(element, res.data?.viewport, input.padding ?? 8);
       const start = Math.max(0, elapsed + (input.start_offset_seconds ?? -0.25));
@@ -716,7 +952,11 @@ function registerBrowserAgentMcpTools(server2, opts) {
         ...input.color ? { color: input.color } : {},
         ...input.thickness ? { thickness: input.thickness } : {}
       };
-      return textResult({
+      return structuredResult({
+        ok: true,
+        tool: "browser_replay_mark",
+        session_id: input.session_id,
+        replay_id: res.data?.replay?.replay_id ?? res.data?.replay?.replayId ?? null,
         annotation,
         source_width: padded.sourceWidth,
         source_height: padded.sourceHeight,
@@ -732,12 +972,13 @@ function registerBrowserAgentMcpTools(server2, opts) {
       title: "Annotate Replay MP4",
       description: "Download a browser replay MP4, render visual annotations over it, and save a new annotated MP4 locally. Use this after browser_replay_stop when the user wants proof videos with circles, boxes, arrows, underlines, or labels. For accurate timing and placement, prefer annotations returned by browser_replay_mark while the replay is recording; otherwise use exact left/top/width/height bounds from browser_locate. If the replay video size differs from the screenshot coordinate space, pass source_width and source_height.",
       inputSchema: BrowserReplayAnnotateInputSchema,
-      annotations: annotations("Annotate Replay MP4", true)
+      outputSchema: BrowserReplayAnnotateOutputSchema,
+      annotations: annotations("Annotate Replay MP4")
     },
     async (input) => {
       const sourceName = input.filename ? `${input.filename}-source` : void 0;
       const downloaded = await downloadReplay(input.session_id, input.replay_id, sourceName);
-      if (!downloaded.ok) return textResult(downloaded.data, true);
+      if (!downloaded.ok) return errorResult("browser_replay_annotate", downloaded.data, input.session_id, input.replay_id);
       try {
         const sourcePath = String(downloaded.data.file_path);
         const outputPath = annotatedReplayFilePath(input.session_id, input.replay_id, input.filename);
@@ -749,7 +990,10 @@ function registerBrowserAgentMcpTools(server2, opts) {
           sourceLeftOffset: input.source_left_offset,
           sourceTopOffset: input.source_top_offset
         });
-        return textResult({
+        return structuredResult({
+          ok: true,
+          tool: "browser_replay_annotate",
+          session_id: input.session_id,
           replay_id: input.replay_id,
           source_file_path: sourcePath,
           annotated_file_path: result.filePath,
@@ -760,7 +1004,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
           mime_type: "video/mp4"
         });
       } catch (err) {
-        return textResult({ error: err instanceof Error ? err.message : String(err) }, true);
+        return errorResult("browser_replay_annotate", { error: err instanceof Error ? err.message : String(err) }, input.session_id, input.replay_id);
       }
     }
   );
@@ -768,28 +1012,43 @@ function registerBrowserAgentMcpTools(server2, opts) {
     "browser_close",
     {
       title: "Close Browser Session",
-      description: "Close and release the browser session when the task is done.",
+      description: "Close and release a browser session when the task is done, when the user asks to stop the browser, or when active browser billing should end. Use browser_list_sessions first if you need to recover the session_id.",
       inputSchema: BrowserSessionInputSchema,
+      outputSchema: BrowserCloseOutputSchema,
       annotations: { title: "Close Browser Session", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
     },
     async (input) => {
       const res = await req("DELETE", `/agent/sessions/${input.session_id}`);
-      return textResult(res.data, !res.ok);
+      if (!res.ok) return errorResult("browser_close", res.data, input.session_id);
+      return structuredResult({
+        ok: true,
+        tool: "browser_close",
+        session_id: input.session_id,
+        closed: true,
+        raw: res.data
+      });
     }
   );
   server2.registerTool(
     "browser_list_sessions",
     {
       title: "List Browser Sessions",
-      description: "List your browser sessions and their status, with a watch_url for each.",
+      description: "List browser sessions and their status, with a watch_url for each. Use this to recover a session_id, find an active browser, or decide which session to close. Use browser_open to create a new session.",
       inputSchema: BrowserListInputSchema,
+      outputSchema: BrowserListSessionsOutputSchema,
       annotations: annotations("List Browser Sessions", true)
     },
     async (input) => {
       const res = await req("GET", `/agent/sessions${input.include_closed ? "?all=1" : ""}`);
-      if (!res.ok) return textResult(res.data, true);
+      if (!res.ok) return errorResult("browser_list_sessions", res.data);
       const sessions = (res.data.sessions ?? []).map((s) => ({ ...s, watch_url: `${consoleBase}/console/${s.session_id}` }));
-      return textResult({ sessions });
+      return structuredResult({
+        ok: true,
+        tool: "browser_list_sessions",
+        session_id: null,
+        sessions,
+        count: sessions.length
+      });
     }
   );
 }