iframer-cli 1.0.4 → 2.0.1

package/index.js

@@ -1,633 +0,0 @@
-#!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { readFileSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-
-// ─── Config ──────────────────────────────────────────────────────────
-
-const BASE_URL = process.env.IFRAMER_URL || "https://api.iframer.sh";
-const CREDENTIALS_PATH = join(homedir(), ".iframer", "credentials.json");
-
-let cachedToken = null;
-
-function loadToken() {
-  if (cachedToken) return cachedToken;
-  try {
-    const data = JSON.parse(readFileSync(CREDENTIALS_PATH, "utf8"));
-    cachedToken = data.token;
-    return cachedToken;
-  } catch {
-    throw new Error("Not logged in. Run: iframer login");
-  }
-}
-
-function authHeaders() {
-  return {
-    "Content-Type": "application/json",
-    Authorization: `Bearer ${loadToken()}`,
-  };
-}
-
-async function apiPost(endpoint, body) {
-  const res = await fetch(`${BASE_URL}${endpoint}`, {
-    method: "POST",
-    headers: authHeaders(),
-    body: body ? JSON.stringify(body) : undefined,
-  });
-  return res.json();
-}
-
-async function apiGet(endpoint) {
-  const res = await fetch(`${BASE_URL}${endpoint}`, { headers: authHeaders() });
-  return res.json();
-}
-
-async function apiDelete(endpoint) {
-  const res = await fetch(`${BASE_URL}${endpoint}`, {
-    method: "DELETE",
-    headers: authHeaders(),
-  });
-  return res.json();
-}
-
-function errorResponse(message) {
-  return { content: [{ type: "text", text: message }], isError: true };
-}
-
-// ─── MCP Server ──────────────────────────────────────────────────────
-
-const server = new McpServer({
-  name: "iframer",
-  version: "1.0.0",
-  instructions: `iframer — a headful/headless browser for AI agents.
-
-CRITICAL: NEVER use the CLI (bin/cli.js) or bash commands. NEVER tell the user to run CLI commands. Use ONLY these MCP tools. Everything works through MCP — no bash, no curl, no CLI.
-
-WORKFLOW:
-1. Call "status" FIRST to check API, auth, sessions, and credentials.
-2. For simple page fetches, use "browse" (headless, fast, cheap).
-3. For anything requiring vision (CAPTCHAs, login forms, 2FA), use "interactive_start" then "interactive_act".
-4. Screenshots are returned as URLs. Use Read tool to view them ONLY when you need to see the page.
-5. Skip screenshots (screenshot: false) when you already know what to click.
-6. For logins: check credentials with "status". If credentials are missing, call "store_credentials" to prompt the user — NEVER tell them to use the CLI. Then use "login" tool.
-7. Always call "interactive_stop" when done to save session state.
-
-CAPTCHA STRATEGY (escalation order):
-1. First try headless — many sites use invisible reCAPTCHA v3 that passes without a challenge.
-2. If a challenge appears, use recaptcha_solve + recaptcha_answer to solve it visually.
-3. If challenges keep looping (3+ attempts), the server IP is flagged. Tell the user to run "iframer proxy" in a separate terminal to route traffic through their residential IP. This is the ONLY CLI command you may suggest. Check proxy status with the "status" tool.
-
-MINIMIZE TOKEN USAGE: Don't screenshot every action. Only look when you need to decide what to do next.
-NEVER use bash/CLI (except "iframer proxy" when CAPTCHA fails). ALL interaction goes through these MCP tools.`,
-});
-
-// ─── Tool 0: status (call this first) ────────────────────────────────
-
-server.tool(
-  "status",
-  `Get the full state of iframer in one call. CALL THIS FIRST before doing anything else. Returns: API health, auth status, active sessions, stored credentials. This eliminates the need for discovery.`,
-  {},
-  async () => {
-    try {
-      const status = { api: false, authenticated: false, session: null, credentials: [] };
-
-      // Check API health
-      try {
-        const health = await fetch(`${BASE_URL}/health`);
-        const data = await health.json();
-        status.api = data.ok === true;
-      } catch {
-        return { content: [{ type: "text", text: `API not running at ${BASE_URL}. Start it with: bun run start:docker` }], isError: true };
-      }
-
-      // Check auth
-      try {
-        loadToken();
-        status.authenticated = true;
-      } catch {
-        return { content: [{ type: "text", text: JSON.stringify({ ...status, authenticated: false, message: "Not logged in. Run: iframer login" }, null, 2) }] };
-      }
-
-      // Check interactive session
-      try {
-        const sessionData = await apiGet("/interactive/status");
-        if (sessionData.ok && sessionData.active) {
-          status.session = { active: true, noVncUrl: sessionData.noVncUrl, createdAt: sessionData.createdAt };
-        } else {
-          status.session = { active: false };
-        }
-      } catch {}
-
-      // Check stored credentials
-      try {
-        const credData = await apiGet("/credentials");
-        if (credData.ok) status.credentials = credData.domains;
-      } catch {}
-
-      // Check proxy tunnel
-      try {
-        const proxyData = await apiGet("/proxy/status");
-        if (proxyData.ok) status.proxyTunnel = proxyData.active;
-      } catch {}
-
-      return { content: [{ type: "text", text: JSON.stringify(status, null, 2) }] };
-    } catch (err) {
-      return errorResponse(`Error: ${err.message}`);
-    }
-  }
-);
-
-// ─── Tool 1: browse ──────────────────────────────────────────────────
-
-server.tool(
-  "browse",
-  "Fetch a web page using a headless browser. Renders JavaScript, can execute actions (click, fill, scroll), and extract data. Session cookies persist across calls.",
-  {
-    url: z.string().describe("URL to navigate to"),
-    extract: z.string().optional().describe("JavaScript expression to evaluate on the page (e.g. 'document.title')"),
-    actions: z.array(z.object({
-      type: z.enum(["click", "fill", "wait", "scroll", "human-click", "human-type"]),
-      selector: z.string().optional(),
-      value: z.string().optional(),
-      ms: z.number().optional(),
-    })).optional().describe("Actions to execute before extracting"),
-    returnHtml: z.boolean().optional().describe("Return full page HTML"),
-    waitForSelector: z.string().optional().describe("Wait for this CSS selector before proceeding"),
-    sessionless: z.boolean().optional().describe("Skip session persistence for this request"),
-  },
-  async (params) => {
-    try {
-      const data = await apiPost("/fetch", params);
-      if (!data.ok) return errorResponse(`Error: ${data.error}`);
-      const { html, ...rest } = data;
-      const text = html
-        ? JSON.stringify(rest, null, 2) + "\n\n--- HTML ---\n" + html
-        : JSON.stringify(rest, null, 2);
-      return { content: [{ type: "text", text }] };
-    } catch (err) {
-      return errorResponse(`Connection error: ${err.message}. Is the API running at ${BASE_URL}?`);
-    }
-  }
-);
-
-// ─── Tool 2: interactive_start ───────────────────────────────────────
-
-server.tool(
-  "interactive_start",
-  "Start an interactive headful browser session. Opens a real Chromium window (streamed via noVNC). Use this when you need to see and interact with the page — CAPTCHAs, 2FA, login flows, etc.",
-  {
-    url: z.string().optional().describe("URL to navigate to on start"),
-  },
-  async (params) => {
-    try {
-      const data = await apiPost("/interactive/start", params);
-      if (!data.ok) return errorResponse(`Error: ${data.error}`);
-      return {
-        content: [{
-          type: "text",
-          text: `Interactive session started.\nnoVNC viewer: ${data.noVncUrl}\n\nUse interactive_screenshot to see the page, interactive_act to interact with it.`,
-        }],
-      };
-    } catch (err) {
-      return errorResponse(`Connection error: ${err.message}. Is the API running at ${BASE_URL}?`);
-    }
-  }
-);
-
-// ─── Tool 3: interactive_screenshot ──────────────────────────────────
-
-server.tool(
-  "interactive_screenshot",
-  "Take a screenshot of the current interactive browser session. Returns a URL to the image — use Read tool or WebFetch to view it.",
-  {},
-  async () => {
-    try {
-      const data = await apiGet("/interactive/screenshot");
-      if (!data.ok) return errorResponse(`Error: ${data.error}`);
-      return {
-        content: [{
-          type: "text",
-          text: `Page: ${data.title}\nURL: ${data.url}\nScreenshot: ${data.screenshotUrl}`,
-        }],
-      };
-    } catch (err) {
-      return errorResponse(`Connection error: ${err.message}. Is the API running at ${BASE_URL}?`);
-    }
-  }
-);
-
-// ─── Tool 4: interactive_act ─────────────────────────────────────────
-
-server.tool(
-  "interactive_act",
-  `Send an action to the interactive browser and get a screenshot URL of the result.
-
-Actions: click, human-click, human-type, fill, navigate, scroll, wait, evaluate, wait-for-selector, keyboard, type-code.
-type-code: Type a verification code into split digit inputs in one call. Pass the full code as value (e.g. "735948"). Optionally pass selector for the first input (defaults to input[type="tel"]).
-reCAPTCHA: recaptcha-click (click checkbox), recaptcha-select (select tiles by index), recaptcha-verify (click verify), recaptcha-info (get challenge metadata).
-
-Screenshots are saved as files and returned as URLs. Use Read tool to view them. For reCAPTCHA, individual tile image URLs are returned.`,
-  {
-    action: z.enum([
-      "click", "human-click", "human-type", "fill",
-      "navigate", "scroll", "wait", "evaluate",
-      "wait-for-selector", "keyboard", "type-code",
-      "recaptcha-click", "recaptcha-select", "recaptcha-verify", "recaptcha-info",
-    ]).describe("Action type to perform"),
-    selector: z.string().optional().describe("CSS selector (for click, fill, human-click, human-type, wait-for-selector)"),
-    value: z.string().optional().describe("Value to type (for fill, human-type)"),
-    url: z.string().optional().describe("URL for navigate action"),
-    x: z.number().optional().describe("X coordinate for human-click"),
-    y: z.number().optional().describe("Y coordinate for human-click"),
-    deltaY: z.number().optional().describe("Scroll pixels (default: full page)"),
-    ms: z.number().optional().describe("Milliseconds for wait action"),
-    expression: z.string().optional().describe("JavaScript for evaluate action"),
-    key: z.string().optional().describe("Key for keyboard action (e.g. Enter, Tab)"),
-    tiles: z.array(z.number()).optional().describe("Tile indices for recaptcha-select (e.g. [0, 2, 5])"),
-    timeout: z.number().optional().describe("Timeout in ms for wait-for-selector"),
-    screenshot: z.boolean().optional().describe("Set to false to skip screenshot (faster)"),
-  },
-  async (params) => {
-    try {
-      const { action: actionType, screenshot: wantScreenshot, ...rest } = params;
-      const actionObj = { type: actionType };
-
-      for (const [key, val] of Object.entries(rest)) {
-        if (val !== undefined) actionObj[key] = val;
-      }
-
-      const data = await apiPost("/interactive/act", { action: actionObj, screenshot: wantScreenshot });
-      if (!data.ok) return errorResponse(`Error: ${data.error}`);
-
-      const textData = { url: data.url, title: data.title };
-      if (data.result !== null && data.result !== undefined) textData.result = data.result;
-      if (data.screenshotUrl) textData.screenshotUrl = data.screenshotUrl;
-
-      // Include tile URLs for reCAPTCHA
-      if (data.tileUrls && data.tileUrls.length > 0) {
-        textData.tileUrls = data.tileUrls;
-      }
-
-      return { content: [{ type: "text", text: JSON.stringify(textData, null, 2) }] };
-    } catch (err) {
-      return errorResponse(`Connection error: ${err.message}. Is the API running at ${BASE_URL}?`);
-    }
-  }
-);
-
-// ─── Tool 4b: interactive_batch ──────────────────────────────────────
-
-server.tool(
-  "interactive_batch",
-  `Run multiple actions in a single call. Much faster than calling interactive_act repeatedly.
-Each action is an object with a "type" and its parameters. Actions run sequentially. Stops on first error unless continueOnError is true.
-Only one screenshot is taken at the end (or none if screenshot: false).
-
-Example: [
-  {"type": "navigate", "url": "https://example.com"},
-  {"type": "wait", "ms": 2000},
-  {"type": "click", "selector": "#login"},
-  {"type": "evaluate", "expression": "document.title"}
-]`,
-  {
-    actions: z.array(z.object({
-      type: z.string().describe("Action type"),
-      selector: z.string().optional(),
-      value: z.string().optional(),
-      url: z.string().optional(),
-      x: z.number().optional(),
-      y: z.number().optional(),
-      deltaY: z.number().optional(),
-      ms: z.number().optional(),
-      expression: z.string().optional(),
-      key: z.string().optional(),
-      tiles: z.array(z.number()).optional(),
-      timeout: z.number().optional(),
-      waitUntil: z.string().optional(),
-    })).describe("Array of actions to execute sequentially"),
-    screenshot: z.boolean().optional().describe("Take screenshot at the end (default true)"),
-    continueOnError: z.boolean().optional().describe("Continue executing actions even if one fails"),
-  },
-  async (params) => {
-    try {
-      const data = await apiPost("/interactive/batch", params);
-      if (!data.ok) return errorResponse(`Error: ${data.error}`);
-
-      const textData = {
-        url: data.url,
-        title: data.title,
-        results: data.results,
-      };
-      if (data.screenshotUrl) textData.screenshotUrl = data.screenshotUrl;
-
-      return { content: [{ type: "text", text: JSON.stringify(textData, null, 2) }] };
-    } catch (err) {
-      return errorResponse(`Connection error: ${err.message}. Is the API running at ${BASE_URL}?`);
-    }
-  }
-);
-
-// ─── Tool 5: interactive_stop ────────────────────────────────────────
-
-server.tool(
-  "interactive_stop",
-  "Stop the interactive browser session and save session state (cookies, localStorage) for future use.",
-  {},
-  async () => {
-    try {
-      const data = await apiPost("/interactive/stop");
-      if (!data.ok) return errorResponse(`Error: ${data.error}`);
-      return {
-        content: [{ type: "text", text: `Session stopped. State saved: ${data.sessionSaved}` }],
-      };
-    } catch (err) {
-      return errorResponse(`Connection error: ${err.message}. Is the API running at ${BASE_URL}?`);
-    }
-  }
-);
-
-// ─── Tool 6: interactive_status ──────────────────────────────────────
-
-server.tool(
-  "interactive_status",
-  "Check if an interactive browser session is currently active.",
-  {},
-  async () => {
-    try {
-      const data = await apiGet("/interactive/status");
-      if (!data.ok) return errorResponse(`Error: ${data.error}`);
-      if (!data.active) {
-        return { content: [{ type: "text", text: "No active interactive session." }] };
-      }
-      return {
-        content: [{
-          type: "text",
-          text: `Active session\nnoVNC: ${data.noVncUrl}\nStarted: ${data.createdAt}`,
-        }],
-      };
-    } catch (err) {
-      return errorResponse(`Connection error: ${err.message}. Is the API running at ${BASE_URL}?`);
-    }
-  }
-);
-
-// ─── Tool 7: clear_session ───────────────────────────────────────────
-
-server.tool(
-  "clear_session",
-  "Clear all stored browser session data (cookies, localStorage). Start fresh on next browse.",
-  {},
-  async () => {
-    try {
-      const data = await apiDelete("/session");
-      if (!data.ok) return errorResponse(`Error: ${data.error}`);
-      return { content: [{ type: "text", text: "Session cleared." }] };
-    } catch (err) {
-      return errorResponse(`Connection error: ${err.message}. Is the API running at ${BASE_URL}?`);
-    }
-  }
-);
-
-// ─── Tool 8: login ──────────────────────────────────────────────────
-
-server.tool(
-  "login",
-  `Log into a website using stored credentials. The server handles the login — passwords never enter the AI context.
-
-Users must store credentials first via store_credentials tool or CLI.
-
-The agent provides CSS selectors for the login form fields. The server decrypts credentials internally, fills the form with human-like typing, and clicks submit. If TOTP 2FA is configured, it generates and enters the code automatically.
-
-IMPORTANT: You will never see the actual credentials. You only need to identify the form selectors on the page.`,
-  {
-    domain: z.string().describe("Domain to log into (must match stored credentials, e.g. 'github.com')"),
-    usernameSelector: z.string().optional().describe("CSS selector for the username/email input field"),
-    passwordSelector: z.string().optional().describe("CSS selector for the password input field"),
-    submitSelector: z.string().optional().describe("CSS selector for the submit/login button"),
-    totpSelector: z.string().optional().describe("CSS selector for the TOTP/2FA code input (if applicable)"),
-  },
-  async (params) => {
-    try {
-      const data = await apiPost("/credentials/login", params);
-      if (!data.ok) return errorResponse(`Error: ${data.error}`);
-
-      const result = {
-        message: data.message,
-        totpGenerated: data.totpGenerated,
-        url: data.url,
-        title: data.title,
-      };
-      if (data.screenshotUrl) result.screenshotUrl = data.screenshotUrl;
-
-      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-    } catch (err) {
-      return errorResponse(`Connection error: ${err.message}. Is the API running at ${BASE_URL}?`);
-    }
-  }
-);
-
-// ─── Tool 9: list_credentials ───────────────────────────────────────
-
-server.tool(
-  "list_credentials",
-  "List domains for which the user has stored login credentials. Returns only domain names, never the actual credential values.",
-  {},
-  async () => {
-    try {
-      const data = await apiGet("/credentials");
-      if (!data.ok) return errorResponse(`Error: ${data.error}`);
-      if (data.domains.length === 0) {
-        return { content: [{ type: "text", text: "No credentials stored. User can add them with: iframer credentials add <domain>" }] };
-      }
-      return {
-        content: [{ type: "text", text: `Stored credentials for:\n${data.domains.map(d => `  - ${d}`).join("\n")}` }],
-      };
-    } catch (err) {
-      return errorResponse(`Connection error: ${err.message}. Is the API running at ${BASE_URL}?`);
-    }
-  }
-);
-
-// ─── Tool 10: store_credentials ─────────────────────────────────────
-
-server.tool(
-  "store_credentials",
-  `Store login credentials for a website. Prompts the user directly for their username, password, and optional TOTP secret. Credentials are encrypted and stored server-side — the AI never sees them.
-
-ALWAYS call this tool when credentials are needed but not stored. NEVER tell the user to run CLI commands — this tool handles it via a secure prompt.`,
-  {
-    domain: z.string().describe("Domain to store credentials for (e.g. 'github.com', 'mercadolivre.com.br')"),
-  },
-  async ({ domain }) => {
-    try {
-      const result = await server.server.elicitInput({
-        mode: "form",
-        message: `Enter your login credentials for ${domain}.\nThese will be encrypted and stored securely. The AI will never see them.`,
-        requestedSchema: {
-          type: "object",
-          properties: {
-            username: {
-              type: "string",
-              title: "Username / Email",
-              description: "Your username or email for this site",
-              minLength: 1,
-            },
-            password: {
-              type: "string",
-              title: "Password",
-              description: "Your password",
-              minLength: 1,
-            },
-            totp_secret: {
-              type: "string",
-              title: "TOTP Secret (optional)",
-              description: "Your authenticator app secret key for automatic 2FA. Leave empty if not using TOTP.",
-            },
-          },
-          required: ["username", "password"],
-        },
-      });
-
-      if (result.action === "decline" || !result.content) {
-        return { content: [{ type: "text", text: "Credential storage cancelled by user." }] };
-      }
-
-      const { username, password, totp_secret } = result.content;
-      const data = await apiPost("/credentials", {
-        domain,
-        username,
-        password,
-        totp_secret: totp_secret || undefined,
-      });
-
-      if (!data.ok) return errorResponse(`Error: ${data.error}`);
-
-      return {
-        content: [{
-          type: "text",
-          text: `Credentials stored securely for ${domain}. Use the login tool to log in.`,
-        }],
-      };
-    } catch (err) {
-      if (err.message?.includes("does not support")) {
-        return {
-          content: [{
-            type: "text",
-            text: `This client doesn't support secure input prompts. Please store credentials via the CLI instead:\n\niframer credentials add ${domain}`,
-          }],
-          isError: true,
-        };
-      }
-      return errorResponse(`Error: ${err.message}`);
-    }
-  }
-);
-
-// ─── Tool 11: recaptcha_solve ───────────────────────────────────────
-
-server.tool(
-  "recaptcha_solve",
-  `Start solving a reCAPTCHA. Clicks the checkbox and if a challenge appears, returns ALL tile images inline in one response along with the prompt text. Much faster than individual recaptcha-click + screenshot + recaptcha-info calls.
-
-If the reCAPTCHA is solved immediately (no challenge), returns solved: true.
-If a challenge appears, returns the prompt and all tile images. Then use recaptcha_answer with the tile indices to complete it.`,
-  {},
-  async () => {
-    try {
-      const data = await apiPost("/interactive/act", {
-        action: { type: "recaptcha-solve" },
-        screenshot: false,
-      });
-      if (!data.ok) return errorResponse(`Error: ${data.error}`);
-
-      const result = data.result;
-      if (result.solved) {
-        return { content: [{ type: "text", text: "reCAPTCHA solved automatically (no challenge needed)." }] };
-      }
-
-      // Build content blocks: prompt text + all tile images
-      const content = [];
-      content.push({
-        type: "text",
-        text: `reCAPTCHA Challenge: "${result.prompt}"\nGrid: ${result.rows}x${result.cols} (${result.tiles.length} tiles)\nSelect the correct tiles by index (0-${result.tiles.length - 1}) using recaptcha_answer.`,
-      });
-
-      for (const tile of result.tiles) {
-        if (tile.image) {
-          content.push({
-            type: "text",
-            text: `Tile ${tile.index}:`,
-          });
-          content.push({
-            type: "image",
-            data: tile.image,
-            mimeType: "image/jpeg",
-          });
-        }
-      }
-
-      return { content };
-    } catch (err) {
-      return errorResponse(`Connection error: ${err.message}. Is the API running at ${BASE_URL}?`);
-    }
-  }
-);
-
-// ─── Tool 12: recaptcha_answer ──────────────────────────────────────
-
-server.tool(
-  "recaptcha_answer",
-  `Submit tile selections and verify the reCAPTCHA in one call. Selects the specified tiles and clicks verify.
-
-If solved, returns success. If a new challenge appears (common with reCAPTCHA), returns the new prompt and tile images inline — just call recaptcha_answer again with new selections.`,
-  {
-    tiles: z.array(z.number()).describe("Tile indices to select (e.g. [0, 3, 6])"),
-  },
-  async ({ tiles }) => {
-    try {
-      const data = await apiPost("/interactive/act", {
-        action: { type: "recaptcha-answer", tiles },
-        screenshot: false,
-      });
-      if (!data.ok) return errorResponse(`Error: ${data.error}`);
-
-      const result = data.result;
-      if (result.solved) {
-        return { content: [{ type: "text", text: "reCAPTCHA solved!" }] };
-      }
-
-      // New challenge — return tiles inline
-      const content = [];
-      content.push({
-        type: "text",
-        text: `Not solved yet — new challenge: "${result.prompt || "unknown"}"\nGrid: ${result.rows}x${result.cols} (${result.tiles.length} tiles)\nSelect the correct tiles by index using recaptcha_answer again.`,
-      });
-
-      for (const tile of result.tiles) {
-        if (tile.image) {
-          content.push({
-            type: "text",
-            text: `Tile ${tile.index}:`,
-          });
-          content.push({
-            type: "image",
-            data: tile.image,
-            mimeType: "image/jpeg",
-          });
-        }
-      }
-
-      return { content };
-    } catch (err) {
-      return errorResponse(`Connection error: ${err.message}. Is the API running at ${BASE_URL}?`);
-    }
-  }
-);
-
-// ─── Start ───────────────────────────────────────────────────────────
-
-const transport = new StdioServerTransport();
-await server.connect(transport);