chuskybrowser-mcp 1.18.3 → 1.19.0

package/README.md

@@ -2,7 +2,7 @@
 
 A standalone [Model Context Protocol](https://modelcontextprotocol.io) server that exposes chuskybrowser to any MCP-compatible host — Claude Code, Cursor, etc. — without requiring OpenClaw.
 
-It mirrors the existing OpenClaw plugin **1:1**: same 24 tool names, identical JSON-Schema parameters, and the same REST routes. Whether an agent reaches chusky via OpenClaw or MCP, the behavior is identical.
+It mirrors the existing OpenClaw plugin **1:1**: same tool names (35 tools), identical JSON-Schema parameters, and the same REST routes. Whether an agent reaches chusky via OpenClaw or MCP, the behavior is identical.
 
 The initial MCP server implementation was contributed by [@epicsagas](https://github.com/epicsagas).
 
@@ -170,7 +170,7 @@ claude mcp add chuskybrowser -- node /Users/you/src/chuskybrowser/mcp/server.mjs
 | Cursor | Settings → MCP — server shows green |
 | opencode | `opencode mcp list` |
 
-You should see 24 tools: the 11 browser tools (`chusky_create_tab`, `chusky_snapshot`, `chusky_click`, `chusky_type`, `chusky_navigate`, `chusky_scroll`, `chusky_screenshot`, `chusky_evaluate`, `chusky_list_tabs`, `chusky_close_tab`, `chusky_import_cookies`), two handoff tools (`chusky_handoff_start`, `chusky_handoff_release`), three payment tools (`chusky_pay_arm`, `chusky_pay_status`, `chusky_pay_disarm`), and eight AgentCard tools (`agentcard_enrol`, `agentcard_cards`, `agentcard_placeholder`, `agentcard_buy`, `agentcard_merchants`, `agentcard_presets_list`, `agentcard_preset_set`, `agentcard_preset_attach`). The user id comes from `CHUSKY_USER_ID`, never from the model.
+You should see 35 tools: the 11 browser tools (`chusky_create_tab`, `chusky_snapshot`, `chusky_click`, `chusky_type`, `chusky_navigate`, `chusky_scroll`, `chusky_screenshot`, `chusky_evaluate`, `chusky_list_tabs`, `chusky_close_tab`, `chusky_import_cookies`), two handoff tools (`chusky_handoff_start`, `chusky_handoff_release`), three payment tools (`chusky_pay_arm`, `chusky_pay_status`, `chusky_pay_disarm`), eight AgentCard tools (`agentcard_enrol`, `agentcard_cards`, `agentcard_placeholder`, `agentcard_buy`, `agentcard_merchants`, `agentcard_presets_list`, `agentcard_preset_set`, `agentcard_preset_attach`). The user id comes from `CHUSKY_USER_ID`, never from the model.
 
 ## Tools
 
@@ -187,6 +187,17 @@ You should see 24 tools: the 11 browser tools (`chusky_create_tab`, `chusky_snap
 | `chusky_list_tabs` | List open tabs in this session |
 | `chusky_close_tab` | Close a tab |
 | `chusky_import_cookies` | Import a Netscape cookie file (needs `CHUSKY_API_KEY`) |
+| `chusky_viewer_link` | Live view link for a tab; `control: true` lets the user click and type. Needs `CHUSKY_ACCESS_KEY` on the server |
+| `chusky_extract` | Pull structured JSON from the page using a JSON Schema |
+| `chusky_select` | Choose an option in a native dropdown |
+| `chusky_upload` | Attach a file from the server's uploads folder to a file input |
+| `chusky_wait` | Wait for a selector or a fixed time |
+| `chusky_viewport` | Set the page size in pixels |
+| `chusky_checkpoint` | Check the page for something needing a person; hands the tab over if needed |
+| `chusky_dismiss_overlays` | Close cookie banners and pop-ups |
+| `chusky_page_state` | Current URL, title, loading state and who controls the tab |
+| `chusky_list_downloads` | Files downloaded in a tab |
+| `chusky_list_traces` | Recorded traces for the current user |
 
 ## Workflow
 

package/lib/config.mjs

@@ -10,7 +10,10 @@ export function loadMcpConfig() {
   return {
     port: parseInt(process.env.CHUSKY_PORT || process.env.PORT || '9377', 10),
     apiKey: process.env.CHUSKY_API_KEY || '',
-    accessKey: (process.env.CHUSKY_ACCESS_KEY || '').trim(),
+    // Customers set CHUSKYBROWSER_API_KEY. Self-hosted setups keep CHUSKY_ACCESS_KEY.
+    accessKey: (process.env.CHUSKYBROWSER_API_KEY || process.env.CHUSKY_ACCESS_KEY || '').trim(),
+    // True when the customer key is set, so requests go through the gateway.
+    gateway: Boolean(process.env.CHUSKYBROWSER_API_KEY),
     cookiesDir: process.env.CHUSKY_COOKIES_DIR || join(os.homedir(), '.chusky', 'cookies'),
   };
 }

package/lib/tool-contracts.mjs

@@ -405,6 +405,138 @@ export const TOOL_DEFS = [
       required: ['label'],
     },
   },
+  {
+    name: 'chusky_viewer_link',
+    description:
+      'Get a live view link for a tab so the user can watch it. Set control to true to let the user click and type too (the agent is paused on the tab until released). Send the url to the user only, unchanged. Needs CHUSKY_ACCESS_KEY on the server.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        control: { type: 'boolean', description: 'true to let the user control the tab' },
+        ttlSeconds: { type: 'number', description: 'How long the link stays valid, in seconds' },
+      },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_extract',
+    description:
+      'Pull structured data from the page as JSON. Give a schema describing the fields you want and get the extracted values back. Prefer this to reading the whole snapshot when you only need specific fields.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        schema: { type: 'object', description: 'JSON Schema of the fields to extract' },
+        kinds: { type: 'array', items: { type: 'string' }, description: 'Optional kinds of content to look at, e.g. ["links","tables"]' },
+      },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_select',
+    description: 'Choose an option in a native dropdown (select element). Give the element by ref from the snapshot, or by CSS selector.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        ref: { type: 'string', description: 'Element ref from the snapshot, e.g. e4' },
+        selector: { type: 'string', description: 'CSS selector, if no ref' },
+        option: { type: 'string', description: 'Text or value of the option to choose' },
+      },
+      required: ['tabId', 'option'],
+    },
+  },
+  {
+    name: 'chusky_upload',
+    description:
+      'Attach a file to a file input on the page. The file must already be in the server uploads folder; give its name or path inside that folder. Target the input by ref from the snapshot, or by CSS selector.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        path: { type: 'string', description: 'File name or path inside the server uploads folder' },
+        ref: { type: 'string', description: 'Element ref of the file input' },
+        selector: { type: 'string', description: 'CSS selector of the file input, if no ref' },
+        timeout: { type: 'number', description: 'Milliseconds to wait for the input' },
+      },
+      required: ['tabId', 'path'],
+    },
+  },
+  {
+    name: 'chusky_wait',
+    description: 'Wait until an element appears on the page, or for a fixed time. Use after an action that loads new content.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        selector: { type: 'string', description: 'CSS selector to wait for' },
+        timeout: { type: 'number', description: 'Milliseconds to wait before giving up' },
+      },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_viewport',
+    description: 'Set the page size in pixels, for example to check a mobile or desktop layout.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        width: { type: 'integer', description: 'Width in pixels' },
+        height: { type: 'integer', description: 'Height in pixels' },
+      },
+      required: ['tabId', 'width', 'height'],
+    },
+  },
+  {
+    name: 'chusky_checkpoint',
+    description:
+      'Check the page for something that needs a person (a login, a CAPTCHA, a confirmation). If one is found, the tab is handed to the user and the response includes a controlUrl to send them unchanged.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        idleMs: { type: 'number', description: 'Milliseconds of inactivity before control returns to the agent' },
+      },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_dismiss_overlays',
+    description: 'Close cookie banners, pop-ups and overlays that cover the page.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        maxClicks: { type: 'integer', description: 'Most close or accept clicks to make' },
+      },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_page_state',
+    description: 'Describe the current page: url, title, whether it is loading, and whether a person has control of the tab.',
+    inputSchema: {
+      type: 'object',
+      properties: { tabId: { type: 'string', description: 'Tab identifier' } },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_list_downloads',
+    description: 'List the files downloaded in a tab.',
+    inputSchema: {
+      type: 'object',
+      properties: { tabId: { type: 'string', description: 'Tab identifier' } },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_list_traces',
+    description: 'List recorded session traces for the current user, for debugging a run.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
 ];
 
 /** Quick name → def lookup. */
@@ -624,6 +756,91 @@ export function buildRequest(name, args, ctx) {
         responseKind: 'json',
         body: { userId, cardId: args.cardId },
       };
+    case 'chusky_viewer_link':
+      return {
+        method: 'POST',
+        path: '/live-viewer/links',
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId, tabId: args.tabId, control: args.control, ttlSeconds: args.ttlSeconds },
+      };
+    case 'chusky_extract':
+      return {
+        method: 'POST',
+        path: `/tabs/${encodeURIComponent(args.tabId)}/extract`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId, schema: args.schema, kinds: args.kinds },
+      };
+    case 'chusky_select':
+      return {
+        method: 'POST',
+        path: `/tabs/${encodeURIComponent(args.tabId)}/select`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId, ref: args.ref, selector: args.selector, option: args.option },
+      };
+    case 'chusky_upload':
+      return {
+        method: 'POST',
+        path: `/tabs/${encodeURIComponent(args.tabId)}/upload`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId, path: args.path, ref: args.ref, selector: args.selector, timeout: args.timeout },
+      };
+    case 'chusky_wait':
+      return {
+        method: 'POST',
+        path: `/tabs/${encodeURIComponent(args.tabId)}/wait`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId, selector: args.selector, timeout: args.timeout },
+      };
+    case 'chusky_viewport':
+      return {
+        method: 'POST',
+        path: `/tabs/${encodeURIComponent(args.tabId)}/viewport`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId, width: args.width, height: args.height },
+      };
+    case 'chusky_checkpoint':
+      return {
+        method: 'POST',
+        path: `/tabs/${encodeURIComponent(args.tabId)}/checkpoint`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId, idleMs: args.idleMs },
+      };
+    case 'chusky_dismiss_overlays':
+      return {
+        method: 'POST',
+        path: `/tabs/${encodeURIComponent(args.tabId)}/overlays/dismiss`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId, maxClicks: args.maxClicks },
+      };
+    case 'chusky_page_state':
+      return {
+        method: 'GET',
+        path: `/tabs/${encodeURIComponent(args.tabId)}/state?${new URLSearchParams({ userId })}`,
+        auth: 'accessKey',
+        responseKind: 'json',
+      };
+    case 'chusky_list_downloads':
+      return {
+        method: 'GET',
+        path: `/tabs/${encodeURIComponent(args.tabId)}/downloads?${new URLSearchParams({ userId })}`,
+        auth: 'accessKey',
+        responseKind: 'json',
+      };
+    case 'chusky_list_traces':
+      return {
+        method: 'GET',
+        path: `/sessions/${encodeURIComponent(userId)}/traces`,
+        auth: 'accessKey',
+        responseKind: 'json',
+      };
     default:
       throw new Error(`Unknown tool: ${name}`);
   }
@@ -642,7 +859,9 @@ export function buildRequest(name, args, ctx) {
  * @throws {Error} if CHUSKY_API_KEY is unset.
  */
 export async function buildCookieRequest(args, ctx, config) {
-  if (!config.apiKey) {
+  // Customer mode (CHUSKYBROWSER_API_KEY): the gateway holds the server's cookie key,
+  // so the host sends the customer key instead.
+  if (!config.apiKey && !config.gateway) {
     throw new Error(
       'CHUSKY_API_KEY is not set. Cookie import is disabled unless both the server and the host (MCP/OpenClaw) have CHUSKY_API_KEY.'
     );
@@ -655,7 +874,7 @@ export async function buildCookieRequest(args, ctx, config) {
   return {
     method: 'POST',
     path: `/sessions/${encodeURIComponent(ctx.userId)}/cookies`,
-    auth: 'apiKey',
+    auth: config.gateway ? 'accessKey' : 'apiKey',
     responseKind: 'json',
     body: { cookies },
     meta: { imported: cookies.length, userId: ctx.userId },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chuskybrowser-mcp",
-  "version": "1.18.3",
+  "version": "1.19.0",
   "description": "Standalone stdio MCP server exposing the chuskybrowser REST API as MCP tools (Claude Code, Codex, agy, Cursor, opencode). Proxies to an already-running chuskybrowser REST server — does not itself require the browser binary, Playwright, or the core server's dependencies. Initial MCP implementation contributed by @epicsagas.",
   "type": "module",
   "main": "server.mjs",

package/server.mjs

@@ -43,7 +43,13 @@ const VERSION = JSON.parse(
 // package reads only its own environment settings; CHUSKY_BASE_URL overrides
 // the derived local URL.
 const CONFIG = loadMcpConfig();
-const BASE_URL = process.env.CHUSKY_BASE_URL || `http://localhost:${CONFIG.port}`;
+// Customers set only CHUSKYBROWSER_API_KEY and reach the built-in gateway address.
+// Self-hosted setups keep CHUSKY_BASE_URL (or fall back to localhost).
+const CUSTOMER_GATEWAY_URL = "https://chuskybrowser-production.up.railway.app/v1";
+const BASE_URL =
+  process.env.CHUSKYBROWSER_BASE_URL ||
+  (CONFIG.gateway ? CUSTOMER_GATEWAY_URL : process.env.CHUSKY_BASE_URL) ||
+  `http://localhost:${CONFIG.port}`;
 
 // Per-MCP-server userId so each host session gets an isolated chusky session
 // (cookie/storage partition). Falls back to a random id.