chuskybrowser-mcp 0.0.0-stage → 1.18.2

package/README.md

@@ -1,3 +1,240 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# chuskybrowser MCP server
+
+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.
+
+The initial MCP server implementation was contributed by [@epicsagas](https://github.com/epicsagas).
+
+## Architecture
+
+The MCP server is a thin stdio client over the chusky REST server. Two pieces:
+
+- **REST server** (`server.js`) — launches Camoufox, exposes the HTTP API on `:9377`. Run **once**, it stays up.
+- **MCP server** (`mcp/server.mjs`, exposed as the `chuskybrowser-mcp` bin) — translates MCP tool calls into REST calls. Claude Code spawns one **per session**.
+
+Registering the MCP server does **not** require being inside the chuskybrowser checkout. The examples below work from any directory.
+
+`mcp/` is also an **independently installable package** (`chuskybrowser-mcp`, its own `package.json`). It depends on nothing but `@modelcontextprotocol/sdk` — no `camoufox-js`, `playwright-core`, `express`, or the ~300MB browser binary download that the core server pulls in. Tool names, JSON-Schema parameters, REST routes, and response shaping are defined in `mcp/lib/tool-contracts.mjs`, which ships inside the standalone package. The OpenClaw plugin (`plugin.ts`) imports the same canonical module, so the two hosts cannot drift. See **Option D** below if you only want the MCP adapter (e.g. pointing `CHUSKY_BASE_URL` at a REST server running elsewhere).
+
+## 1. Start the REST server
+
+Clone the repo and start the server (one-time binary download on first run):
+
+```bash
+git clone https://github.com/zester4/chuskybrowser && cd chuskybrowser
+npm install   # downloads Camoufox (~300MB) on first run
+npm start     # → http://localhost:9377
+```
+
+This stays running in the background. It does not need to be your cwd afterwards.
+
+## 2. Install the `chuskybrowser-mcp` bin
+
+The MCP server is the same for every host — what differs is only the config file you paste into. First, make the `chuskybrowser-mcp` bin available on your PATH. Pick one:
+
+```bash
+# Option A — npm link (if you have the source checkout; picks up local edits)
+cd chuskybrowser && npm link
+
+# Option B — global install (no source checkout needed)
+npm install -g chuskybrowser
+
+# Option C — npx (no install; runs the published standalone adapter)
+#   Use this wherever a command is expected below.
+npx -y chuskybrowser-mcp
+
+# Option D — MCP adapter only, no core server deps (lightest footprint)
+#   Skips camoufox-js/playwright-core/express and the browser binary download —
+#   use this if a chuskybrowser REST server is already running (locally or
+#   remotely) and you only need the stdio adapter.
+git clone https://github.com/zester4/chuskybrowser && cd chuskybrowser/mcp
+npm install   # installs only @modelcontextprotocol/sdk (~24MB, no postinstall)
+npm link      # chuskybrowser-mcp now resolves from any directory
+```
+
+Verify the bin resolves from any directory:
+
+```bash
+which chuskybrowser-mcp   # → .../bin/chuskybrowser-mcp
+```
+
+## 3. Register with your host
+
+All five hosts speak standard MCP, so they all run the same `chuskybrowser-mcp` bin. Pick your host's config snippet below.
+
+### Claude Code
+
+```bash
+# CLI (user scope = available in every project)
+claude mcp add chuskybrowser -s user -- chuskybrowser-mcp
+```
+
+Or in `~/.claude.json` (user) / `.mcp.json` (project, checked in):
+
+```json
+{
+  "mcpServers": {
+    "chuskybrowser": {
+      "command": "chuskybrowser-mcp"
+    }
+  }
+}
+```
+
+### Codex CLI
+
+`~/.codex/config.toml` (user) or `.codex/config.toml` (project, trusted dirs only):
+
+```toml
+[mcp_servers.chuskybrowser]
+command = "chuskybrowser-mcp"
+env = { CHUSKY_BASE_URL = "http://localhost:9377" }
+```
+
+### Antigravity / agy
+
+Global `~/.gemini/config/mcp_config.json` or workspace `.agents/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "chuskybrowser": {
+      "command": "chuskybrowser-mcp"
+    }
+  }
+}
+```
+
+### Cursor
+
+Global `~/.cursor/mcp.json` or project `.cursor/mcp.json` (checked in):
+
+```json
+{
+  "mcpServers": {
+    "chuskybrowser": {
+      "command": "chuskybrowser-mcp"
+    }
+  }
+}
+```
+
+(Or via UI: Settings → Cursor Settings → MCP → Add New MCP Server.)
+
+### opencode
+
+`opencode.json` in the project root, or global `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "chuskybrowser": {
+      "type": "local",
+      "command": ["chuskybrowser-mcp"]
+    }
+  }
+}
+```
+
+### Common: env vars and from-source fallback
+
+If you need cookie import or a non-default REST URL, add env. Example for Claude Code:
+
+```bash
+claude mcp add chuskybrowser -s user \
+  --env CHUSKY_BASE_URL=http://localhost:9377 \
+  --env CHUSKY_API_KEY=<key> \
+  -- chuskybrowser-mcp
+```
+
+For the other hosts, add the same keys to the `env` / `environment` field of that host's snippet.
+
+**From-source fallback** (only if you're inside the checkout and haven't linked the bin):
+
+```bash
+# Replace `chuskybrowser-mcp` with `node /absolute/path/to/mcp/server.mjs`
+claude mcp add chuskybrowser -- node /Users/you/src/chuskybrowser/mcp/server.mjs
+```
+
+> ⚠️ Always prefer the `chuskybrowser-mcp` bin (options A/B/C/D above). The `node ./mcp/server.mjs` form is **path-dependent** — relative paths break outside the checkout.
+
+## 4. Verify
+
+| Host | How to verify |
+|------|---------------|
+| Claude Code | `/mcp` — `chuskybrowser` shows connected |
+| Codex CLI | `codex` then check MCP server list |
+| agy | `/mcp` overlay in the `agy` CLI |
+| 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.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `chusky_create_tab` | Open a URL → returns `tabId` |
+| `chusky_snapshot` | Accessibility snapshot + element refs (`e1`, `e2`, ...) + screenshot |
+| `chusky_navigate` | Go to a URL **or** use a search macro (`@google_search`, `@reddit_search`, ...) |
+| `chusky_click` | Click by element ref (`e1`) or CSS selector |
+| `chusky_type` | Type text into a ref/selector, optional `pressEnter` |
+| `chusky_scroll` | Scroll by pixels (unreliable on lazy-load pages — prefer `chusky_evaluate`) |
+| `chusky_screenshot` | Standalone screenshot |
+| `chusky_evaluate` | Run JS in page context — extract data, call page APIs, scroll via `window.scrollTo` |
+| `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`) |
+
+## Workflow
+
+Every interaction follows the same shape — **snapshot before you act**:
+
+1. `create_tab({ url })` → `tabId`
+2. `snapshot({ tabId })` → element refs (`e1`, `e2`, ...)
+3. `click`/`type` using those refs
+4. `snapshot` again to read the new state
+5. `close_tab` when done
+
+Element refs are unambiguous and preferred over CSS selectors — a selector that matches multiple elements returns `422 strict mode violation`, in which case re-snapshot and click by ref.
+
+## Environment variables
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `CHUSKY_BASE_URL` | `http://localhost:9377` | REST server URL |
+| `CHUSKY_USER_ID` | `mcp-<random>` | Session isolation (one MCP server = one chusky session) |
+| `CHUSKY_SESSION_KEY` | `default` | Tab partition within the user |
+| `CHUSKY_ACCESS_KEY` | _(unset)_ | Global bearer token gating the REST server (superkey). If set, forwarded as `Authorization: Bearer <key>` on **every** tool call automatically — must match the REST server's own `CHUSKY_ACCESS_KEY`. Without this, a globally-authenticated REST server rejects all tool calls except cookie import. |
+| `CHUSKY_API_KEY` | _(unset)_ | Self-chosen secret gating cookie import. Optional on localhost; required on remote/production and must match the REST server's `CHUSKY_API_KEY`. Only affects `chusky_import_cookies`. |
+
+## Troubleshooting
+
+- **`503 session_expired` / `tab create timed out`** — the REST server's browser session died (often after a prior failed call destabilized it). Restart `npm start`.
+- **`chusky_scroll` returns `{ok:true}` but the page doesn't move** — expected on lazy-load / virtual-scroll pages; the server's `mouse.wheel` no-ops there. Use `chusky_evaluate` with `window.scrollTo` / `scrollBy`.
+- **`422 strict mode violation ... resolved to N elements`** on `click` — CSS selector matched multiple elements. Re-snapshot and click by element ref.
+- **`403 Forbidden` on `chusky_import_cookies`** — key mismatch between REST server and MCP server, or hitting a remote server without `CHUSKY_API_KEY`.
+- **`401`/`403` on every tool call, not just cookie import** — the REST server has `CHUSKY_ACCESS_KEY` set. Set the same `CHUSKY_ACCESS_KEY` in the MCP server's env (see table above) — it's forwarded automatically as `Authorization: Bearer` once set.
+
+## Testing (developer)
+
+Two layers, covering different things:
+
+```bash
+# 1. `test:mcp` installs the standalone adapter's locked dependencies, then
+#    runs the in-repository and packed-tarball handshake tests. Neither needs
+#    a REST server.
+npm run test:mcp
+
+# 2. Mock-HTTP contract tests — verifies the actual REST traffic each tool
+#    produces: routes, methods, request bodies, CHUSKY_ACCESS_KEY/CHUSKY_API_KEY
+#    auth headers, cookie parsing (Netscape file → `{ cookies }` body, never a
+#    path), screenshot decoding, and error handling. Mocked REST server — no
+#    live chuskybrowser process needed. This is what makes the "OpenClaw and
+#    MCP send identical requests" claim verifiable, not just asserted.
+NODE_OPTIONS='--experimental-vm-modules' npx jest tests/unit/mcp-contracts.test.js
+```
+
+The packed-tarball check installs the generated `chuskybrowser-mcp` tarball in an empty directory before its handshake. It catches imports that reach outside the standalone package.

package/lib/config.mjs

@@ -0,0 +1,16 @@
+import os from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Load only the environment settings the standalone MCP adapter requires.
+ * This module intentionally does not import the core server configuration so
+ * chuskybrowser-mcp can run without the core package installed.
+ */
+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(),
+    cookiesDir: process.env.CHUSKY_COOKIES_DIR || join(os.homedir(), '.chusky', 'cookies'),
+  };
+}

package/lib/cookies.mjs

@@ -0,0 +1,147 @@
+/**
+ * Cookie file reading and parsing for chuskybrowser.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Parse a Netscape-format cookie file into structured cookie objects.
+ * @param {string} text - Raw cookie file content
+ * @returns {Array<{name: string, value: string, domain: string, path: string, expires: number, httpOnly?: boolean, secure?: boolean}>}
+ */
+function parseNetscapeCookieFile(text) {
+  const cookies = [];
+  const cleaned = text.replace(/^\uFEFF/, '');
+
+  for (const rawLine of cleaned.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (line.startsWith('#') && !line.startsWith('#HttpOnly_')) continue;
+
+    let httpOnly = false;
+    let working = line;
+    if (working.startsWith('#HttpOnly_')) {
+      httpOnly = true;
+      working = working.replace(/^#HttpOnly_/, '');
+    }
+
+    const parts = working.split('\t');
+    if (parts.length < 7) continue;
+
+    const domain = parts[0];
+    const cookiePath = parts[2];
+    const secure = parts[3].toUpperCase() === 'TRUE';
+    // Netscape cookie files use 0 (and, in the wild, occasionally a
+    // non-numeric placeholder) to mean "session cookie". Playwright's
+    // addCookies() spells that -1 instead and reads 0 as a Unix timestamp,
+    // i.e. 1970-01-01, so the cookie is already expired the moment it is
+    // added and is dropped without a word. Map anything that is not a
+    // positive number onto -1.
+    const rawExpires = Number(parts[4]);
+    const expires = Number.isFinite(rawExpires) && rawExpires > 0 ? rawExpires : -1;
+    const name = parts[5];
+    const value = parts.slice(6).join('\t');
+
+    cookies.push({ name, value, domain, path: cookiePath, expires, httpOnly, secure });
+  }
+
+  return cookies;
+}
+
+/**
+ * Read and parse cookies from a Netscape cookie file.
+ * @param {object} opts
+ * @param {string} opts.cookiesDir - Base directory for cookie files
+ * @param {string} opts.cookiesPath - Relative path to the cookie file within cookiesDir
+ * @param {string} [opts.domainSuffix] - Only include cookies whose domain ends with this suffix
+ * @param {number} [opts.maxBytes=5242880] - Maximum file size in bytes
+ * @returns {Promise<Array<{name: string, value: string, domain: string, path: string, expires: number, httpOnly: boolean, secure: boolean}>>}
+ */
+function isPathInside(basePath, targetPath) {
+  const relative = path.relative(basePath, targetPath);
+  return relative !== ''
+    && relative !== '..'
+    && !relative.startsWith(`..${path.sep}`)
+    && !path.isAbsolute(relative);
+}
+
+async function readCookieFile({ cookiesDir, cookiesPath, domainSuffix, maxBytes = 5 * 1024 * 1024 }) {
+  if (typeof cookiesPath !== 'string' || cookiesPath.length === 0) {
+    throw new Error('cookiesPath must be a non-empty string');
+  }
+  if (path.isAbsolute(cookiesPath)) {
+    throw new Error('cookiesPath must be a relative path within the cookies directory');
+  }
+
+  const realCookiesDir = await fs.realpath(cookiesDir);
+  const requestedPath = path.resolve(realCookiesDir, cookiesPath);
+  if (!isPathInside(realCookiesDir, requestedPath)) {
+    throw new Error('cookiesPath must be a relative path within the cookies directory');
+  }
+
+  const realCookiePath = await fs.realpath(requestedPath);
+  if (!isPathInside(realCookiesDir, realCookiePath)) {
+    throw new Error('cookiesPath resolves outside the cookies directory');
+  }
+
+  const stat = await fs.stat(realCookiePath);
+  if (stat.size > maxBytes) {
+    throw new Error('Cookie file too large (max 5MB)');
+  }
+
+  const text = await fs.readFile(realCookiePath, 'utf8');
+  let cookies = parseNetscapeCookieFile(text);
+  if (domainSuffix) {
+    cookies = cookies.filter((c) => c.domain.endsWith(domainSuffix));
+  }
+
+  return cookies.map((c) => ({
+    name: c.name,
+    value: c.value,
+    domain: c.domain,
+    path: c.path,
+    expires: c.expires,
+    httpOnly: !!c.httpOnly,
+    secure: !!c.secure,
+  }));
+}
+
+/**
+ * Import all cookies from the default bootstrap cookie file into a Playwright context.
+ * Intended for first-run session seeding before any persistent storage state exists.
+ * Missing file is treated as a no-op.
+ * @param {object} opts
+ * @param {string} opts.cookiesDir - Base directory for cookie files
+ * @param {object} opts.context - Playwright BrowserContext
+ * @param {string} [opts.cookiesPath='cookies.txt'] - Relative cookie file path within cookiesDir
+ * @param {object} [opts.logger=console] - Logger with warn()
+ * @returns {Promise<{imported: number, source: string|null}>}
+ */
+async function importBootstrapCookies({ cookiesDir, context, cookiesPath = 'cookies.txt', logger = console }) {
+  if (!cookiesDir || !context) {
+    return { imported: 0, source: null };
+  }
+
+  const resolved = path.resolve(cookiesDir, cookiesPath);
+
+  try {
+    const cookies = await readCookieFile({ cookiesDir, cookiesPath });
+    if (cookies.length === 0) {
+      return { imported: 0, source: resolved };
+    }
+    await context.addCookies(cookies);
+    return { imported: cookies.length, source: resolved };
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      return { imported: 0, source: null };
+    }
+    logger?.warn?.('failed to import bootstrap cookies', {
+      cookiesPath: resolved,
+      error: err?.message || String(err),
+    });
+    return { imported: 0, source: resolved };
+  }
+}
+
+export { parseNetscapeCookieFile, readCookieFile, importBootstrapCookies };

package/lib/tool-contracts.mjs

@@ -0,0 +1,780 @@
+/**
+ * Canonical tool contracts for the chuskybrowser REST API.
+ *
+ * Single source of truth shared by two hosts that expose the same 11 tools:
+ *   - mcp/server.mjs   (stdio MCP server for Claude Code, Codex, agy, Cursor, opencode)
+ *   - plugin.ts        (OpenClaw plugin)
+ *
+ * Importing this module from both hosts means tool names, JSON-Schema
+ * parameters, REST routes, request bodies, auth semantics, and response
+ * shaping cannot drift — the REST server sees identical traffic regardless of
+ * which host the agent reached it through.
+ *
+ * Auth model (mirrors lib/auth.js):
+ *   - CHUSKY_ACCESS_KEY (global superkey): when set, every route except
+ *     /health, cookie import, /auth-sessions, /stop requires
+ *     `Authorization: Bearer <accessKey>`.
+ *   - CHUSKY_API_KEY (cookie-only gate): the cookie-import route requires
+ *     `Authorization: Bearer <apiKey>` (or loopback + non-production).
+ *
+ * Each buildRequest() result declares `auth: 'accessKey' | 'apiKey' | 'none'`
+ * and `responseKind: 'json' | 'snapshot' | 'image'` so the host's fetch layer
+ * and response adapter stay declarative.
+ */
+
+import { readCookieFile } from './cookies.mjs';
+
+/**
+ * @typedef {Object} ToolDef
+ * @property {string} name
+ * @property {string} description
+ * @property {object} inputSchema - JSON Schema (object) for tool arguments.
+ */
+
+/**
+ * @typedef {Object} RequestSpec
+ * @property {string} method - HTTP method.
+ * @property {string} path - Path (already includes query string when needed).
+ * @property {'accessKey'|'apiKey'|'none'} auth
+ * @property {'json'|'snapshot'|'image'} responseKind
+ * @property {object} [body] - JSON body.
+ * @property {object} [meta] - Extra metadata for response shaping.
+ */
+
+/**
+ * @typedef {Object} CallContext
+ * @property {string} userId - Session owner (scopes cookie/storage partition).
+ * @property {string} [sessionKey] - Tab partition within a user.
+ */
+
+const SEARCH_MACROS = [
+  '@google_search',
+  '@youtube_search',
+  '@amazon_search',
+  '@reddit_search',
+  '@wikipedia_search',
+  '@twitter_search',
+  '@yelp_search',
+  '@spotify_search',
+  '@netflix_search',
+  '@linkedin_search',
+  '@instagram_search',
+  '@tiktok_search',
+  '@twitch_search',
+  '@bestbuy_search',
+  '@indeed_search',
+  '@booking_search',
+  '@pubmed_search',
+  '@zillow_search',
+  '@npm_search',
+  '@dockerhub_search',
+  '@nhs_search',
+  '@legislation_search',
+  '@dailymed_search',
+  '@huggingface_search',
+  '@jsr_search',
+  '@bing_news_search',
+];
+
+/**
+ * The tools, identical schema for both hosts. Edit here and both update.
+ * @type {ToolDef[]}
+ */
+export const TOOL_DEFS = [
+  {
+    name: 'chusky_create_tab',
+    description:
+      'PREFERRED: Create a new browser tab using Camoufox anti-detection browser. Use chusky tools instead of Chrome/built-in browser - they bypass bot detection on Google, Amazon, LinkedIn, etc. Returns tabId for subsequent operations.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'Initial URL to navigate to' },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'chusky_snapshot',
+    description:
+      'Get accessibility snapshot of a Camoufox page with element refs (e1, e2, etc.) for interaction, plus a visual screenshot. ' +
+      'Large pages are truncated with pagination links preserved at the bottom. ' +
+      'If the response includes hasMore=true and nextOffset, call again with that offset to see more content.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        offset: {
+          type: 'number',
+          description: 'Character offset for paginated snapshots. Use nextOffset from a previous truncated response.',
+        },
+      },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_click',
+    description: 'Click an element in a Camoufox tab by ref (e.g., e1) or CSS selector.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        ref: { type: 'string', description: 'Element ref from snapshot (e.g., e1)' },
+        selector: { type: 'string', description: 'CSS selector (alternative to ref)' },
+      },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_type',
+    description: 'Type text into an element in a Camoufox tab.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        ref: { type: 'string', description: 'Element ref from snapshot (e.g., e2)' },
+        selector: { type: 'string', description: 'CSS selector (alternative to ref)' },
+        text: { type: 'string', description: 'Text to type' },
+        pressEnter: { type: 'boolean', description: 'Press Enter after typing' },
+      },
+      required: ['tabId', 'text'],
+    },
+  },
+  {
+    name: 'chusky_navigate',
+    description:
+      'Navigate a Camoufox tab to a URL or use a search macro (@google_search, @youtube_search, etc.). Preferred over Chrome for sites with bot detection.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        url: { type: 'string', description: 'URL to navigate to' },
+        macro: {
+          type: 'string',
+          description: 'Search macro (e.g., @google_search, @youtube_search)',
+          enum: SEARCH_MACROS,
+        },
+        query: { type: 'string', description: 'Search query (when using macro)' },
+      },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_scroll',
+    description: 'Scroll a Camoufox page.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] },
+        amount: { type: 'number', description: 'Pixels to scroll' },
+      },
+      required: ['tabId', 'direction'],
+    },
+  },
+  {
+    name: 'chusky_screenshot',
+    description: 'Take a screenshot of a Camoufox page.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+      },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_close_tab',
+    description: 'Close a Camoufox browser tab.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+      },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_evaluate',
+    description:
+      "Execute JavaScript in a Camoufox tab's page context. Returns the result of the expression. Use for injecting scripts, reading page state, or calling web app APIs.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        expression: {
+          type: 'string',
+          description: 'JavaScript expression to evaluate in the page context',
+        },
+      },
+      required: ['tabId', 'expression'],
+    },
+  },
+  {
+    name: 'chusky_list_tabs',
+    description: 'List all open Chusky tabs for the current session.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'chusky_import_cookies',
+    description:
+      'Import cookies into the current Camoufox session (Netscape cookie file). Use to authenticate to sites like LinkedIn without interactive login. Requires CHUSKY_API_KEY on the REST server.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cookiesPath: {
+          type: 'string',
+          description: 'Relative path to a Netscape-format cookies.txt file within the server cookies directory',
+        },
+        domainSuffix: {
+          type: 'string',
+          description: 'Only import cookies whose domain ends with this suffix',
+        },
+      },
+      required: ['cookiesPath'],
+    },
+  },
+  {
+    name: 'chusky_handoff_start',
+    description:
+      'Hand a tab to the human for a login, a CAPTCHA or a check. Returns a controlUrl: send it to the user only, unchanged. The agent must not act on the tab until the handoff is released.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        reason: { type: 'string', description: 'Shown to the user, e.g. "Sign in to your bank"' },
+        idleMs: { type: 'number', description: 'Milliseconds of inactivity before control returns to the agent' },
+      },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_handoff_release',
+    description: 'Return control of a tab to the agent after a handoff.',
+    inputSchema: {
+      type: 'object',
+      properties: { tabId: { type: 'string', description: 'Tab identifier' } },
+      required: ['tabId'],
+    },
+  },
+  {
+    name: 'chusky_pay_arm',
+    description:
+      'Pay on this tab with the user\'s own card. Arms payment on the page: when the checkout sends its card request, it is paused until the user approves on their device with their passkey. The user never gives the card number, and the agent never sees it. Returns attachmentId; then call chusky_pay_status to get the approval link to send to the user.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier of the checkout page' },
+        merchant: { type: 'string', description: 'Store name, shown on the approval screen (max 120 characters)' },
+        amount: { type: 'integer', description: 'Most the user can be charged, in minor units (cents). 2306 is $23.06' },
+        currency: { type: 'string', description: 'Lowercase ISO 4217 code, e.g. usd' },
+        checkoutOrigin: { type: 'string', description: 'https origin of the checkout page, e.g. https://shop.example.com' },
+        cardId: { type: 'string', description: 'Which stored card to use; omit for the first one' },
+      },
+      required: ['tabId', 'merchant', 'amount', 'currency'],
+    },
+  },
+  {
+    name: 'chusky_pay_status',
+    description:
+      'Read a payment attachment. approvalUrl appears once a card request is paused: send it to the user unchanged. phase is idle, pending or completed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        attachmentId: { type: 'string', description: 'From chusky_pay_arm' },
+      },
+      required: ['tabId', 'attachmentId'],
+    },
+  },
+  {
+    name: 'chusky_pay_disarm',
+    description: 'Stop paying on a tab. Any paused card request that is not yet approved is cancelled.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tabId: { type: 'string', description: 'Tab identifier' },
+        attachmentId: { type: 'string', description: 'From chusky_pay_arm' },
+      },
+      required: ['tabId', 'attachmentId'],
+    },
+  },
+  {
+    name: 'agentcard_enrol',
+    description:
+      'Start storing the user\'s card with AgentCard. Returns has_card when a card is already stored (nothing to do), otherwise a vault link. Send the link to the user unchanged. The user enters the card on AgentCard\'s page. Card numbers never pass through this tool.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        addAnother: { type: 'boolean', description: 'true to add a second card for this user' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'agentcard_cards',
+    description: 'List the cards stored for this user (brand, last4, expiry). Card numbers are never returned.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'agentcard_buy',
+    description:
+      'Shop for the user at real stores through AgentCard: products, food delivery, table reservations (action reserve) and flights (action book). Pass the shopper\'s words in ask. Pass product_id or store_id only when the user picked one from a previous result. Set confirm true only when the user said yes to the cart. The response has links for the user: send them exactly as given, never change or summarise them.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ask: { type: 'string', description: 'What the user said, in their own words (max 2000 characters)' },
+        threadId: { type: 'string', description: 'The chat, so one purchase stays in one chat (max 128 characters)' },
+        confirm: { type: 'boolean', description: 'true only when the user said yes to the cart or asks to check out' },
+        new_order: { type: 'boolean', description: 'true only when the user drops the cart to start a new order' },
+        product_id: { type: 'string', description: 'The product the user picked from the last result' },
+        store_id: { type: 'string', description: 'The store the user picked from the last result' },
+      },
+      required: ['ask'],
+    },
+  },
+  {
+    name: 'agentcard_merchants',
+    description:
+      'Check whether AgentCard can pay at a store before sending the user there. supported is true (a real purchase went through), false (cannot pay there) or null (not known yet). For direct merchants such as DoorDash, link_status shows whether the user still has to connect.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', description: 'e.g. catalog or direct' },
+        q: { type: 'string', description: 'Part of a store name or domain (max 100 characters)' },
+        limit: { type: 'integer', description: '1 to 100' },
+        cursor: { type: 'string', description: 'next_cursor from the previous page' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'agentcard_placeholder',
+    description:
+      'The test card to type into a checkout for one of this user\'s stored cards: the card number, security code and expiry that match the card that pays. The real card number is never returned. Use the same cardId as chusky_pay_arm.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cardId: { type: 'string', description: 'Which stored card; omit for the first one. Pass the same cardId to chusky_pay_arm.' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'agentcard_presets_list',
+    description: 'List this user\'s spending rules (presets). Limits are enforced by AgentCard before any approval.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'agentcard_preset_set',
+    description:
+      'Create or change one of the user\'s spending rules. Money is in cents. Rules apply to the next purchase. Use this when the user sets a limit, such as a daily cap or merchants they allow.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        label: { type: 'string', description: '1 to 40 lowercase letters, digits or hyphens, e.g. groceries-weekly' },
+        rules: {
+          type: 'object',
+          description: 'At least one rule. Money fields are integer cents.',
+          properties: {
+            perDayCents: { type: 'integer' },
+            perWeekCents: { type: 'integer' },
+            perMonthCents: { type: 'integer' },
+            totalCents: { type: 'integer' },
+            onlyMerchants: { type: 'array', items: { type: 'string' } },
+            categories: { type: 'array', items: { type: 'string', enum: ['meals', 'groceries', 'travel', 'software', 'ai', 'wellness', 'retail'] } },
+            currencies: { type: 'array', items: { type: 'string' } },
+            onlyDays: { type: 'string' },
+            onlyHours: { type: 'string', description: 'e.g. 9-17' },
+            timezone: { type: 'string', description: 'IANA zone, e.g. Europe/London' },
+            mode: { type: 'string', enum: ['strict', 'watch'] },
+          },
+        },
+      },
+      required: ['label', 'rules'],
+    },
+  },
+  {
+    name: 'agentcard_preset_attach',
+    description: 'Attach one of the user\'s spending rules to one of their cards (default: the first card).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        label: { type: 'string', description: 'The rule\'s label' },
+        cardId: { type: 'string', description: 'Which stored card' },
+      },
+      required: ['label'],
+    },
+  },
+];
+
+/** Quick name → def lookup. */
+export const TOOL_BY_NAME = Object.fromEntries(TOOL_DEFS.map((t) => [t.name, t]));
+
+/** Tool names in canonical order. */
+export const TOOL_NAMES = TOOL_DEFS.map((t) => t.name);
+
+/**
+ * Strip the routing key (tabId) from args, returning the REST body fields.
+ * @param {Record<string, unknown>} args
+ * @param {string} [dropKey]
+ * @returns {Record<string, unknown>}
+ */
+function without(args, dropKey = 'tabId') {
+  const { [dropKey]: _omit, ...rest } = args;
+  return rest;
+}
+
+/**
+ * Build a REST request spec for a tool. Pure / synchronous — except cookie
+ * import, which needs async file parsing; use buildCookieRequest() for that.
+ *
+ * @param {string} name - Tool name.
+ * @param {Record<string, unknown>} args - Tool arguments.
+ * @param {CallContext} ctx - { userId, sessionKey }.
+ * @returns {RequestSpec}
+ * @throws {Error} if the tool is unknown.
+ */
+export function buildRequest(name, args, ctx) {
+  const userId = ctx.userId;
+  const sessionKey = ctx.sessionKey;
+  switch (name) {
+    case 'chusky_create_tab':
+      return {
+        method: 'POST',
+        path: '/tabs',
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { url: args.url, userId, sessionKey },
+      };
+    case 'chusky_snapshot': {
+      const params = new URLSearchParams({ userId, includeScreenshot: 'true' });
+      if (args.offset != null && args.offset !== '') params.set('offset', String(args.offset));
+      return {
+        method: 'GET',
+        path: `/tabs/${args.tabId}/snapshot?${params}`,
+        auth: 'accessKey',
+        responseKind: 'snapshot',
+      };
+    }
+    case 'chusky_click':
+      return {
+        method: 'POST',
+        path: `/tabs/${args.tabId}/click`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { ...without(args), userId },
+      };
+    case 'chusky_type':
+      return {
+        method: 'POST',
+        path: `/tabs/${args.tabId}/type`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { ...without(args), userId },
+      };
+    case 'chusky_navigate':
+      return {
+        method: 'POST',
+        path: `/tabs/${args.tabId}/navigate`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { ...without(args), userId },
+      };
+    case 'chusky_scroll':
+      return {
+        method: 'POST',
+        path: `/tabs/${args.tabId}/scroll`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { ...without(args), userId },
+      };
+    case 'chusky_screenshot':
+      return {
+        method: 'GET',
+        path: `/tabs/${args.tabId}/screenshot?${new URLSearchParams({ userId })}`,
+        auth: 'accessKey',
+        responseKind: 'image',
+      };
+    case 'chusky_close_tab':
+      return {
+        method: 'DELETE',
+        path: `/tabs/${args.tabId}?${new URLSearchParams({ userId })}`,
+        auth: 'accessKey',
+        responseKind: 'json',
+      };
+    case 'chusky_evaluate':
+      return {
+        method: 'POST',
+        path: `/tabs/${args.tabId}/evaluate`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId, expression: args.expression },
+      };
+    case 'chusky_list_tabs':
+      return {
+        method: 'GET',
+        path: `/tabs?${new URLSearchParams({ userId })}`,
+        auth: 'accessKey',
+        responseKind: 'json',
+      };
+    case 'chusky_import_cookies':
+      // Async (Netscape parse + path check) — caller must use buildCookieRequest().
+      throw new Error('chusky_import_cookies requires buildCookieRequest() (async cookie parsing)');
+    case 'chusky_handoff_start':
+      return {
+        method: 'POST',
+        path: `/tabs/${encodeURIComponent(args.tabId)}/handoff`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId, reason: args.reason, idleMs: args.idleMs },
+      };
+    case 'chusky_handoff_release':
+      return {
+        method: 'POST',
+        path: `/tabs/${encodeURIComponent(args.tabId)}/handoff/release`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId },
+      };
+    case 'chusky_pay_arm':
+      return {
+        method: 'POST',
+        path: `/agentcard/tabs/${encodeURIComponent(args.tabId)}/payment`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: {
+          userId,
+          merchant: args.merchant,
+          amount: args.amount,
+          currency: args.currency,
+          checkoutOrigin: args.checkoutOrigin,
+          cardId: args.cardId,
+        },
+      };
+    case 'chusky_pay_status':
+      return {
+        method: 'GET',
+        path: `/agentcard/tabs/${encodeURIComponent(args.tabId)}/payment/${encodeURIComponent(args.attachmentId)}?${new URLSearchParams({ userId })}`,
+        auth: 'accessKey',
+        responseKind: 'json',
+      };
+    case 'chusky_pay_disarm':
+      return {
+        method: 'DELETE',
+        path: `/agentcard/tabs/${encodeURIComponent(args.tabId)}/payment/${encodeURIComponent(args.attachmentId)}?${new URLSearchParams({ userId })}`,
+        auth: 'accessKey',
+        responseKind: 'json',
+      };
+    case 'agentcard_enrol':
+      return {
+        method: 'POST',
+        path: '/agentcard/vault/enrol',
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId, addAnother: args.addAnother === true },
+      };
+    case 'agentcard_placeholder':
+      return {
+        method: 'GET',
+        path: `/agentcard/cards/placeholder?${new URLSearchParams({ userId, ...(args.cardId ? { cardId: args.cardId } : {}) })}`,
+        auth: 'accessKey',
+        responseKind: 'json',
+      };
+    case 'agentcard_cards':
+      return {
+        method: 'GET',
+        path: `/agentcard/vault/cards?${new URLSearchParams({ userId })}`,
+        auth: 'accessKey',
+        responseKind: 'json',
+      };
+    case 'agentcard_buy': {
+      const body = { userId };
+      for (const key of ['ask', 'threadId', 'confirm', 'new_order', 'product_id', 'store_id']) {
+        if (args[key] !== undefined) body[key] = args[key];
+      }
+      return { method: 'POST', path: '/agentcard/commerce/buy', auth: 'accessKey', responseKind: 'json', body };
+    }
+    case 'agentcard_merchants': {
+      const params = new URLSearchParams({ userId });
+      for (const key of ['kind', 'q', 'limit', 'cursor']) {
+        if (args[key] !== undefined && args[key] !== '') params.set(key, String(args[key]));
+      }
+      return { method: 'GET', path: `/agentcard/merchants?${params}`, auth: 'accessKey', responseKind: 'json' };
+    }
+    case 'agentcard_presets_list':
+      return {
+        method: 'GET',
+        path: `/agentcard/presets?${new URLSearchParams({ userId })}`,
+        auth: 'accessKey',
+        responseKind: 'json',
+      };
+    case 'agentcard_preset_set':
+      return {
+        method: 'PUT',
+        path: `/agentcard/presets/${encodeURIComponent(args.label)}`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId, rules: args.rules },
+      };
+    case 'agentcard_preset_attach':
+      return {
+        method: 'POST',
+        path: `/agentcard/presets/${encodeURIComponent(args.label)}/attach`,
+        auth: 'accessKey',
+        responseKind: 'json',
+        body: { userId, cardId: args.cardId },
+      };
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+/**
+ * Cookie import is special: the Netscape file must be parsed locally (matching
+ * the OpenClaw plugin) and the REST route accepts a parsed `{ cookies: [...] }`
+ * body, never a path. This function does the parse and returns a request spec
+ * that the host fetch layer can dispatch like any other tool.
+ *
+ * @param {{cookiesPath: string, domainSuffix?: string}} args
+ * @param {CallContext} ctx
+ * @param {{apiKey: string, cookiesDir: string}} config - server config (apiKey + cookiesDir).
+ * @returns {Promise<RequestSpec & {meta: {imported: number, userId: string}}>}
+ * @throws {Error} if CHUSKY_API_KEY is unset.
+ */
+export async function buildCookieRequest(args, ctx, config) {
+  if (!config.apiKey) {
+    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.'
+    );
+  }
+  const cookies = await readCookieFile({
+    cookiesDir: config.cookiesDir,
+    cookiesPath: args.cookiesPath,
+    domainSuffix: args.domainSuffix,
+  });
+  return {
+    method: 'POST',
+    path: `/sessions/${encodeURIComponent(ctx.userId)}/cookies`,
+    auth: 'apiKey',
+    responseKind: 'json',
+    body: { cookies },
+    meta: { imported: cookies.length, userId: ctx.userId },
+  };
+}
+
+/**
+ * Resolve which bearer token a request needs, given server config.
+ * @param {RequestSpec} spec
+ * @param {{accessKey?: string, apiKey?: string}} config
+ * @returns {{header?: {Authorization: string}, missing?: string}}
+ */
+export function authHeaders(spec, config) {
+  if (spec.auth === 'accessKey') {
+    if (!config.accessKey) return {}; // server not gated — no header needed
+    return { Authorization: `Bearer ${config.accessKey}` };
+  }
+  if (spec.auth === 'apiKey') {
+    // apiKey presence is enforced by buildCookieRequest(); here we only attach it.
+    return { Authorization: `Bearer ${config.apiKey}` };
+  }
+  return {};
+}
+
+/**
+ * Execute a request spec against a REST base URL. Shared by the MCP server and
+ * the OpenClaw plugin so the wire-level behavior (auth headers, image decoding,
+ * error formatting) is identical across hosts.
+ *
+ * @param {string} baseUrl - REST server origin (e.g. http://localhost:9377).
+ * @param {RequestSpec} spec
+ * @param {{accessKey?: string, apiKey?: string}} config
+ * @returns {Promise<unknown>} JSON value, or an image content block for image specs.
+ * @throws {Error} on non-2xx, or when an image route returns non-image bytes.
+ */
+export async function fetchSpec(baseUrl, spec, config) {
+  const headers = {
+    'Content-Type': 'application/json',
+    ...authHeaders(spec, config),
+  };
+  const res = await fetch(`${baseUrl}${spec.path}`, {
+    method: spec.method,
+    headers,
+    body: spec.body ? JSON.stringify(spec.body) : undefined,
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`${res.status}: ${text}`);
+  }
+  if (spec.responseKind === 'image') {
+    const contentType = res.headers.get('content-type') || '';
+    // Guard: server may return JSON/text (e.g. error with 200) — don't base64 it.
+    if (!contentType.startsWith('image/')) {
+      const text = await res.text();
+      throw new Error(`Screenshot failed: ${text}`);
+    }
+    const data = Buffer.from(await res.arrayBuffer()).toString('base64');
+    return { type: 'image', data, mimeType: contentType };
+  }
+  return res.json();
+}
+
+/**
+ * Build + dispatch a tool call end-to-end. The single entry point both hosts
+ * call, so a tool's full behavior (request shape + auth + transport + response
+ * shaping) lives in exactly one place. Hosts only differ in how they source
+ * `ctx` (userId/sessionKey) and `config`.
+ *
+ * @param {string} name - Tool name.
+ * @param {Record<string, unknown>} args - Tool arguments.
+ * @param {CallContext} ctx - { userId, sessionKey }.
+ * @param {string} baseUrl - REST server origin.
+ * @param {{apiKey?: string, accessKey?: string, cookiesDir: string}} config - server config.
+ * @returns {Promise<{spec: RequestSpec, payload: unknown}>}
+ */
+export async function runTool(name, args, ctx, baseUrl, config) {
+  const spec =
+    name === 'chusky_import_cookies'
+      ? await buildCookieRequest(args, ctx, config)
+      : buildRequest(name, args, ctx);
+  const payload = await fetchSpec(baseUrl, spec, config);
+  return { spec, payload };
+}
+
+/**
+ * Shape a REST JSON payload into MCP/OpenClaw content blocks.
+ *
+ * - snapshot: splits the embedded screenshot out as an image block
+ * - image: already an image block produced by the fetch layer
+ * - json (default): pretty-printed JSON text block
+ *
+ * @param {RequestSpec} spec
+ * @param {unknown} payload - JSON value ('json'/'snapshot') or an image block ('image').
+ * @returns {Array<{type: string, text?: string, data?: string, mimeType?: string}>}
+ */
+export function adaptResponse(spec, payload) {
+  if (spec.responseKind === 'image') {
+    return [payload];
+  }
+  if (spec.responseKind === 'snapshot') {
+    const { screenshot, ...rest } = /** @type {any} */ (payload) || {};
+    const content = [{ type: 'text', text: JSON.stringify(rest, null, 2) }];
+    if (screenshot?.data) {
+      content.push({
+        type: 'image',
+        data: screenshot.data,
+        mimeType: screenshot.mimeType || 'image/png',
+      });
+    }
+    return content;
+  }
+  // Cookie import: surface the parsed count alongside the server reply.
+  if (spec.meta && spec.meta.imported != null) {
+    return [
+      {
+        type: 'text',
+        text: JSON.stringify({ imported: spec.meta.imported, userId: spec.meta.userId, result: payload }, null, 2),
+      },
+    ];
+  }
+  return [{ type: 'text', text: JSON.stringify(payload, null, 2) }];
+}

package/package.json

@@ -1,6 +1,48 @@
-{
-  "name": "chuskybrowser-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "chuskybrowser-mcp",
+  "version": "1.18.2",
+  "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",
+  "license": "MIT",
+  "author": "Jo Inc <oss@askjo.ai>",
+  "homepage": "https://github.com/zester4/chuskybrowser/tree/master/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zester4/chuskybrowser.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/zester4/chuskybrowser/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "chusky",
+    "camoufox",
+    "browser-automation",
+    "claude-code",
+    "codex",
+    "cursor",
+    "opencode"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "chuskybrowser-mcp": "server.mjs"
+  },
+  "files": [
+    "server.mjs",
+    "lib/",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  },
+  "overrides": {
+    "fast-uri": "3.1.8",
+    "hono": "4.13.7",
+    "qs": "6.16.0"
+  }
+}

package/server.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// chuskybrowser MCP server
+//
+// Standalone Model Context Protocol server that exposes the chuskybrowser
+// REST API (default http://localhost:9377) as MCP tools. Tool names, schemas,
+// REST routes, request bodies, auth, and response shaping are imported from
+// mcp/lib/tool-contracts.mjs — the SAME source of truth the OpenClaw plugin
+// (plugin.ts) uses — so behavior is identical whether an agent reaches chusky
+// via OpenClaw or MCP. Drift is structurally impossible.
+//
+// Transport: stdio (Claude Code / Codex / agy / Cursor / opencode spawn this as
+// a child process). The chusky REST server itself must be running (npm start) —
+// this server only forwards calls, it does not launch the browser.
+//
+// Auth:
+//   - CHUSKY_ACCESS_KEY (global): forwarded as `Authorization: Bearer` on every
+//     request so globally-authenticated REST servers accept MCP traffic.
+//   - CHUSKY_API_KEY (cookie import): forwarded as `Authorization: Bearer` on
+//     the cookie-import route only.
+
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+
+import { loadMcpConfig } from "./lib/config.mjs";
+import {
+  TOOL_DEFS,
+  runTool,
+  adaptResponse,
+} from "./lib/tool-contracts.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Version from this package's own package.json (single source — no hardcoded
+// duplicate). mcp/ is an independently installable package (chuskybrowser-mcp)
+// with its own manifest, so this reads locally rather than the parent repo's.
+const VERSION = JSON.parse(
+  readFileSync(join(__dirname, "package.json"), "utf8")
+).version;
+
+// Server config (apiKey / accessKey / cookiesDir / port). The standalone
+// 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}`;
+
+// Per-MCP-server userId so each host session gets an isolated chusky session
+// (cookie/storage partition). Falls back to a random id.
+const USER_ID = process.env.CHUSKY_USER_ID || `mcp-${randomUUID()}`;
+// sessionKey partitions tabs within a user (matches plugin.ts fallback "default").
+const SESSION_KEY = process.env.CHUSKY_SESSION_KEY || "default";
+
+// The standalone package declares the SDK directly. Surface a clear,
+// actionable error if an incomplete installation is missing it.
+let Server, StdioServerTransport, CallToolRequestSchema, ListToolsRequestSchema;
+try {
+  const serverMod = await import("@modelcontextprotocol/sdk/server/index.js");
+  Server = serverMod.Server;
+  const stdioMod = await import("@modelcontextprotocol/sdk/server/stdio.js");
+  StdioServerTransport = stdioMod.StdioServerTransport;
+  const typesMod = await import("@modelcontextprotocol/sdk/types.js");
+  CallToolRequestSchema = typesMod.CallToolRequestSchema;
+  ListToolsRequestSchema = typesMod.ListToolsRequestSchema;
+} catch {
+  console.error(
+    "[chuskybrowser-mcp] @modelcontextprotocol/sdk is not installed.\n" +
+      "Install the adapter dependencies with: npm install\n" +
+      "from the chuskybrowser-mcp package directory."
+  );
+  process.exit(1);
+}
+
+const server = new Server(
+  { name: "chuskybrowser", version: VERSION },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOL_DEFS.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  const def = TOOL_DEFS.find((t) => t.name === name);
+  if (!def) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Unknown tool: ${name}` }],
+    };
+  }
+  try {
+    const { spec, payload } = await runTool(
+      name,
+      args || {},
+      { userId: USER_ID, sessionKey: SESSION_KEY },
+      BASE_URL,
+      CONFIG
+    );
+    const content = adaptResponse(spec, payload);
+    return { content };
+  } catch (err) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `chusky error: ${err.message}` }],
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(
+  `[chuskybrowser-mcp] v${VERSION} connected → ${BASE_URL} (user=${USER_ID})`
+);