capskip-mcp 1.0.0

package/dist/tools/status.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerStatusTool = registerStatusTool;
+const node_http_1 = __importDefault(require("node:http"));
+const zod_1 = require("zod");
+const schemas_js_1 = require("../schemas.js");
+const PROBE_TIMEOUT_MS = 3000;
+// A CapSkip res.php reply is a few dozen bytes. Anything else on this port could
+// stream indefinitely, so cap what we buffer and destroy the request once the
+// cap is hit. That matters for time, not just memory: `timeout` below only
+// fires on a gap in activity, so a peer that keeps sending data — resetting
+// that inactivity clock — would otherwise hold the probe open indefinitely.
+const MAX_BODY_BYTES = 4096;
+const KEY_REJECTED = /ERROR_(WRONG_USER_KEY|KEY_DOES_NOT_EXIST)/;
+function classify(statusCode, body) {
+    if (statusCode !== 200) {
+        return 'not-capskip';
+    }
+    return KEY_REJECTED.test(body) ? 'key-rejected' : 'ok';
+}
+function probe(host, port, apiKey) {
+    return new Promise((resolve) => {
+        const startedAt = Date.now();
+        const path = `/res.php?key=${encodeURIComponent(apiKey)}&action=get&id=0`;
+        // classify() only needs to see the first MAX_BODY_BYTES, so once a caller
+        // settles the probe further events (a late 'error' from destroy(), a
+        // stray 'end') must be ignored rather than resolving a second time.
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        const req = node_http_1.default.request({ host, port, path, method: 'GET', timeout: PROBE_TIMEOUT_MS }, (res) => {
+            const chunks = [];
+            let size = 0;
+            const finishWithBody = () => {
+                const body = Buffer.concat(chunks).toString('utf-8');
+                settle({
+                    outcome: classify(res.statusCode, body),
+                    latencyMs: Date.now() - startedAt,
+                    statusCode: res.statusCode,
+                });
+            };
+            res.on('data', (chunk) => {
+                if (size >= MAX_BODY_BYTES)
+                    return;
+                chunks.push(chunk);
+                size += chunk.length;
+                if (size >= MAX_BODY_BYTES) {
+                    // Enough to classify — stop a peer that streams continuously from
+                    // keeping the probe pending past PROBE_TIMEOUT_MS.
+                    req.destroy();
+                    finishWithBody();
+                }
+            });
+            res.on('end', finishWithBody);
+        });
+        req.on('timeout', () => {
+            req.destroy();
+            settle({ outcome: 'no-response', error: `no response within ${PROBE_TIMEOUT_MS}ms` });
+        });
+        req.on('error', (err) => settle({ outcome: 'no-response', error: err.message }));
+        req.end();
+    });
+}
+function describe(result, host, port) {
+    switch (result.outcome) {
+        case 'ok':
+            return `CapSkip answered at ${host}:${port} in ${result.latencyMs}ms.`;
+        case 'key-rejected':
+            return (`CapSkip is running at ${host}:${port}, but it rejected the API key. Set `
+                + 'CAPSKIP_API_KEY to the key shown in CapSkip settings, or disable key '
+                + 'validation there. Solves will fail until this is fixed.');
+        case 'not-capskip':
+            return (`Something is listening on ${host}:${port} but it did not answer as CapSkip `
+                + `(HTTP ${result.statusCode}). Check the API port in CapSkip settings, and `
+                + 'that nothing else has taken that port — override with CAPSKIP_HOST / '
+                + 'CAPSKIP_PORT.');
+        default:
+            return (`No response from ${host}:${port} (${result.error}). Start the CapSkip `
+                + 'desktop app, then confirm its API port matches — override with '
+                + 'CAPSKIP_HOST / CAPSKIP_PORT.');
+    }
+}
+function registerStatusTool(server, ctx) {
+    server.registerTool('capskip_status', {
+        title: 'Check CapSkip status',
+        description: 'Check whether the CapSkip desktop app is running and reachable. Call this '
+            + 'first when a solve fails unexpectedly, to tell "CapSkip is not running" '
+            + 'apart from "the sitekey was wrong". Takes no arguments.',
+        inputSchema: zod_1.z.strictObject({}),
+        outputSchema: schemas_js_1.statusOutput,
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async () => {
+        const { host, port, apiKey } = ctx.config;
+        const result = await probe(host, port, apiKey);
+        // A rejected key still means CapSkip is there — the model should fix the
+        // key, not go looking for a process that is already running.
+        const reachable = result.outcome === 'ok' || result.outcome === 'key-rejected';
+        const detail = describe(result, host, port);
+        const structured = {
+            reachable,
+            host,
+            port,
+            ...(result.latencyMs !== undefined ? { latencyMs: result.latencyMs } : {}),
+            detail,
+        };
+        return {
+            content: [{ type: 'text', text: detail }],
+            structuredContent: structured,
+        };
+    });
+}
+//# sourceMappingURL=status.js.map

package/dist/tools/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/tools/status.ts"],"names":[],"mappings":"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","sourcesContent":["import http from 'node:http';\n\nimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { z } from 'zod';\n\nimport { statusOutput } from '../schemas.js';\nimport type { ToolContext } from '../solver.js';\n\nconst PROBE_TIMEOUT_MS = 3000;\n\n// A CapSkip res.php reply is a few dozen bytes. Anything else on this port could\n// stream indefinitely, so cap what we buffer and destroy the request once the\n// cap is hit. That matters for time, not just memory: `timeout` below only\n// fires on a gap in activity, so a peer that keeps sending data — resetting\n// that inactivity clock — would otherwise hold the probe open indefinitely.\nconst MAX_BODY_BYTES = 4096;\n\nconst KEY_REJECTED = /ERROR_(WRONG_USER_KEY|KEY_DOES_NOT_EXIST)/;\n\n/**\n * What the probe found. `reachable` alone is not enough: port 8080 is commonly\n * occupied, and a decoy that answers 404 to everything would otherwise be\n * reported as a healthy CapSkip moments before a solve fails against it.\n */\ntype ProbeOutcome =\n  /** CapSkip answered normally. */\n  | 'ok'\n  /** CapSkip answered, but rejected the API key. It is running; the key is wrong. */\n  | 'key-rejected'\n  /** Something answered on this port, but not as CapSkip. */\n  | 'not-capskip'\n  /** Nothing answered at all. */\n  | 'no-response';\n\ninterface Probe {\n  outcome: ProbeOutcome;\n  latencyMs?: number;\n  statusCode?: number;\n  error?: string;\n}\n\nfunction classify(statusCode: number | undefined, body: string): ProbeOutcome {\n  if (statusCode !== 200) {\n    return 'not-capskip';\n  }\n  return KEY_REJECTED.test(body) ? 'key-rejected' : 'ok';\n}\n\nfunction probe(host: string, port: number, apiKey: string): Promise<Probe> {\n  return new Promise((resolve) => {\n    const startedAt = Date.now();\n    const path = `/res.php?key=${encodeURIComponent(apiKey)}&action=get&id=0`;\n\n    // classify() only needs to see the first MAX_BODY_BYTES, so once a caller\n    // settles the probe further events (a late 'error' from destroy(), a\n    // stray 'end') must be ignored rather than resolving a second time.\n    let settled = false;\n    const settle = (result: Probe) => {\n      if (settled) return;\n      settled = true;\n      resolve(result);\n    };\n\n    const req = http.request(\n      { host, port, path, method: 'GET', timeout: PROBE_TIMEOUT_MS },\n      (res) => {\n        const chunks: Buffer[] = [];\n        let size = 0;\n        const finishWithBody = () => {\n          const body = Buffer.concat(chunks).toString('utf-8');\n          settle({\n            outcome: classify(res.statusCode, body),\n            latencyMs: Date.now() - startedAt,\n            statusCode: res.statusCode,\n          });\n        };\n        res.on('data', (chunk: Buffer) => {\n          if (size >= MAX_BODY_BYTES) return;\n          chunks.push(chunk);\n          size += chunk.length;\n          if (size >= MAX_BODY_BYTES) {\n            // Enough to classify — stop a peer that streams continuously from\n            // keeping the probe pending past PROBE_TIMEOUT_MS.\n            req.destroy();\n            finishWithBody();\n          }\n        });\n        res.on('end', finishWithBody);\n      },\n    );\n\n    req.on('timeout', () => {\n      req.destroy();\n      settle({ outcome: 'no-response', error: `no response within ${PROBE_TIMEOUT_MS}ms` });\n    });\n    req.on('error', (err: Error) => settle({ outcome: 'no-response', error: err.message }));\n    req.end();\n  });\n}\n\nfunction describe(result: Probe, host: string, port: number): string {\n  switch (result.outcome) {\n    case 'ok':\n      return `CapSkip answered at ${host}:${port} in ${result.latencyMs}ms.`;\n    case 'key-rejected':\n      return (\n        `CapSkip is running at ${host}:${port}, but it rejected the API key. Set `\n        + 'CAPSKIP_API_KEY to the key shown in CapSkip settings, or disable key '\n        + 'validation there. Solves will fail until this is fixed.'\n      );\n    case 'not-capskip':\n      return (\n        `Something is listening on ${host}:${port} but it did not answer as CapSkip `\n        + `(HTTP ${result.statusCode}). Check the API port in CapSkip settings, and `\n        + 'that nothing else has taken that port — override with CAPSKIP_HOST / '\n        + 'CAPSKIP_PORT.'\n      );\n    default:\n      return (\n        `No response from ${host}:${port} (${result.error}). Start the CapSkip `\n        + 'desktop app, then confirm its API port matches — override with '\n        + 'CAPSKIP_HOST / CAPSKIP_PORT.'\n      );\n  }\n}\n\nexport function registerStatusTool(server: McpServer, ctx: ToolContext): void {\n  server.registerTool(\n    'capskip_status',\n    {\n      title: 'Check CapSkip status',\n      description:\n        'Check whether the CapSkip desktop app is running and reachable. Call this '\n        + 'first when a solve fails unexpectedly, to tell \"CapSkip is not running\" '\n        + 'apart from \"the sitekey was wrong\". Takes no arguments.',\n      inputSchema: z.strictObject({}),\n      outputSchema: statusOutput,\n      annotations: { readOnlyHint: true, openWorldHint: true },\n    },\n    async () => {\n      const { host, port, apiKey } = ctx.config;\n      const result = await probe(host, port, apiKey);\n\n      // A rejected key still means CapSkip is there — the model should fix the\n      // key, not go looking for a process that is already running.\n      const reachable = result.outcome === 'ok' || result.outcome === 'key-rejected';\n      const detail = describe(result, host, port);\n\n      const structured = {\n        reachable,\n        host,\n        port,\n        ...(result.latencyMs !== undefined ? { latencyMs: result.latencyMs } : {}),\n        detail,\n      };\n\n      return {\n        content: [{ type: 'text' as const, text: detail }],\n        structuredContent: structured,\n      };\n    },\n  );\n}\n"]}

package/dist/tools/turnstile.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTurnstileTool = registerTurnstileTool;
+const zod_1 = require("zod");
+const schemas_js_1 = require("../schemas.js");
+const solve_js_1 = require("../solve.js");
+const inputSchema = zod_1.z.strictObject({
+    sitekey: zod_1.z
+        .string()
+        .min(1)
+        .describe("The Turnstile site key, from the widget's data-sitekey attribute."),
+    url: schemas_js_1.pageUrlSchema,
+    action: zod_1.z
+        .string()
+        .optional()
+        .describe('The action from data-action or turnstile.render().'),
+    cdata: zod_1.z
+        .string()
+        .optional()
+        .describe('The cData value. Interstitial challenge pages only, not ordinary widgets.'),
+    pagedata: zod_1.z
+        .string()
+        .optional()
+        .describe('The chlPageData value. Interstitial challenge pages only.'),
+    proxy: schemas_js_1.proxySchema
+        .optional()
+        .describe('Solve through this proxy so the token is issued against its IP.'),
+    timeout: schemas_js_1.timeoutSchema,
+});
+function registerTurnstileTool(server, ctx) {
+    server.registerTool('capskip_solve_turnstile', {
+        title: 'Solve Cloudflare Turnstile',
+        description: 'Solve a Cloudflare Turnstile widget or interstitial challenge page. Returns a '
+            + 'token for the page\'s "cf-turnstile-response" field. IMPORTANT: submit the '
+            + 'token using the returned userAgent — Cloudflare rejects a token replayed '
+            + 'under a different User-Agent. For an interstitial challenge page, also pass '
+            + 'cdata and pagedata read from the page.',
+        inputSchema,
+        outputSchema: schemas_js_1.turnstileOutput,
+        // destructiveHint defaults to *true* whenever readOnlyHint is false, so
+        // omitting it advertised this tool as potentially destructive and cost it
+        // auto-approval in clients that read the hint. Solving a captcha destroys
+        // nothing. idempotentHint is deliberately left at its false default: each
+        // call consumes a fresh, single-use challenge.
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, async (args, extra) => {
+        const timeout = args.timeout ?? ctx.config.recaptchaTimeout;
+        const options = {};
+        if (args.action !== undefined)
+            options.action = args.action;
+        if (args.cdata !== undefined)
+            options.data = args.cdata;
+        if (args.pagedata !== undefined)
+            options.pagedata = args.pagedata;
+        if (args.proxy !== undefined)
+            options.proxy = args.proxy;
+        return (0, solve_js_1.runSolve)(ctx, extra, { label: 'Solving Turnstile', timeoutSeconds: timeout }, (client) => client.turnstile(args.sitekey, args.url, options), (result, seconds) => {
+            const userAgent = result.userAgent;
+            const structured = {
+                captchaId: String(result.captchaId ?? ''),
+                code: String(result.code ?? ''),
+                solveSeconds: Number(seconds.toFixed(2)),
+                ...(userAgent ? { userAgent } : {}),
+            };
+            const uaLine = userAgent
+                ? `\nSend the token with this exact User-Agent: ${userAgent}`
+                : '';
+            return {
+                structured,
+                text: `Solved Turnstile in ${structured.solveSeconds}s.\n`
+                    + 'Put this token in the "cf-turnstile-response" field, then submit the form.\n'
+                    + `Token: ${structured.code}${uaLine}\n`
+                    + `(CapSkip captcha id ${structured.captchaId})`,
+            };
+        });
+    });
+}
+//# sourceMappingURL=turnstile.js.map

package/dist/tools/turnstile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnstile.js","sourceRoot":"","sources":["../../src/tools/turnstile.ts"],"names":[],"mappings":"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","sourcesContent":["import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { z } from 'zod';\n\nimport { pageUrlSchema, proxySchema, timeoutSchema, turnstileOutput } from '../schemas.js';\nimport { runSolve } from '../solve.js';\nimport type { ToolContext } from '../solver.js';\n\nconst inputSchema = z.strictObject({\n  sitekey: z\n    .string()\n    .min(1)\n    .describe(\"The Turnstile site key, from the widget's data-sitekey attribute.\"),\n  url: pageUrlSchema,\n  action: z\n    .string()\n    .optional()\n    .describe('The action from data-action or turnstile.render().'),\n  cdata: z\n    .string()\n    .optional()\n    .describe('The cData value. Interstitial challenge pages only, not ordinary widgets.'),\n  pagedata: z\n    .string()\n    .optional()\n    .describe('The chlPageData value. Interstitial challenge pages only.'),\n  proxy: proxySchema\n    .optional()\n    .describe('Solve through this proxy so the token is issued against its IP.'),\n  timeout: timeoutSchema,\n});\n\nexport function registerTurnstileTool(server: McpServer, ctx: ToolContext): void {\n  server.registerTool(\n    'capskip_solve_turnstile',\n    {\n      title: 'Solve Cloudflare Turnstile',\n      description:\n        'Solve a Cloudflare Turnstile widget or interstitial challenge page. Returns a '\n        + 'token for the page\\'s \"cf-turnstile-response\" field. IMPORTANT: submit the '\n        + 'token using the returned userAgent — Cloudflare rejects a token replayed '\n        + 'under a different User-Agent. For an interstitial challenge page, also pass '\n        + 'cdata and pagedata read from the page.',\n      inputSchema,\n      outputSchema: turnstileOutput,\n      // destructiveHint defaults to *true* whenever readOnlyHint is false, so\n      // omitting it advertised this tool as potentially destructive and cost it\n      // auto-approval in clients that read the hint. Solving a captcha destroys\n      // nothing. idempotentHint is deliberately left at its false default: each\n      // call consumes a fresh, single-use challenge.\n      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },\n    },\n    async (args, extra) => {\n      const timeout = args.timeout ?? ctx.config.recaptchaTimeout;\n\n      const options: Record<string, unknown> = {};\n      if (args.action !== undefined) options.action = args.action;\n      if (args.cdata !== undefined) options.data = args.cdata;\n      if (args.pagedata !== undefined) options.pagedata = args.pagedata;\n      if (args.proxy !== undefined) options.proxy = args.proxy;\n\n      return runSolve(\n        ctx,\n        extra,\n        { label: 'Solving Turnstile', timeoutSeconds: timeout },\n        (client) => client.turnstile(args.sitekey, args.url, options as never),\n        (result, seconds) => {\n          const userAgent = result.userAgent as string | undefined;\n          const structured = {\n            captchaId: String(result.captchaId ?? ''),\n            code: String(result.code ?? ''),\n            solveSeconds: Number(seconds.toFixed(2)),\n            ...(userAgent ? { userAgent } : {}),\n          };\n\n          const uaLine = userAgent\n            ? `\\nSend the token with this exact User-Agent: ${userAgent}`\n            : '';\n\n          return {\n            structured,\n            text:\n              `Solved Turnstile in ${structured.solveSeconds}s.\\n`\n              + 'Put this token in the \"cf-turnstile-response\" field, then submit the form.\\n'\n              + `Token: ${structured.code}${uaLine}\\n`\n              + `(CapSkip captcha id ${structured.captchaId})`,\n          };\n        },\n      );\n    },\n  );\n}\n"]}

package/docs/API_REFERENCE.md

@@ -0,0 +1,345 @@
+# CapSkip MCP Server — API Reference
+
+Complete reference for all five tools `capskip-mcp` registers. Parameter descriptions below are copied verbatim from each tool's schema in `src/tools/` so this document cannot drift from what a client actually sees when it lists tools.
+
+Every solve tool declares an `outputSchema` and returns MCP `structuredContent` matching it, plus a human-readable text block for clients that do not render structured output. Every tool schema rejects unknown keys — a misspelled or unsupported parameter is rejected by name rather than silently ignored.
+
+---
+
+## Tools at a glance
+
+| Tool | Purpose | Proxy support |
+|---|---|---|
+| `capskip_status` | Check whether CapSkip is running and reachable | n/a |
+| `capskip_solve_image_captcha` | Read the text out of a distorted-text captcha image | No |
+| `capskip_solve_recaptcha` | Solve a Google reCAPTCHA v2 or v3 widget | Yes |
+| `capskip_solve_turnstile` | Solve a Cloudflare Turnstile widget or challenge page | Yes |
+| `capskip_solve_geetest` | Solve a GeeTest v3 slide-puzzle captcha | Yes |
+
+---
+
+## `capskip_status`
+
+Check whether the CapSkip desktop app is running and reachable. Call this first when a solve fails unexpectedly, to tell "CapSkip is not running" apart from "the sitekey was wrong". Takes no arguments.
+
+### Parameters
+
+None. The tool rejects any argument it is passed, naming the key.
+
+### Output shape
+
+| Field | Type | Always present | Description |
+|---|---|---|---|
+| `reachable` | boolean | yes | Whether CapSkip itself answered |
+| `host` | string | yes | Host that was probed |
+| `port` | number | yes | Port that was probed |
+| `latencyMs` | number | whenever anything answered | Round-trip time of the probe |
+| `detail` | string | yes | Human-readable summary — also the tool's text output |
+
+`capskip_status` never returns `isError: true` for an unreachable CapSkip; it reports the problem in `reachable` / `detail` instead, so the model can read the result rather than handle an error.
+
+The probe reads the response, not merely the fact that one arrived. Four outcomes are distinguished:
+
+| Situation | `reachable` | `detail` says |
+|---|---|---|
+| CapSkip answered normally | `true` | `CapSkip answered at <host>:<port> in <n>ms.` |
+| CapSkip answered but rejected the API key | `true` | `CapSkip is running at <host>:<port>, but it rejected the API key. …` |
+| Something else holds the port | `false` | `Something is listening on <host>:<port> but it did not answer as CapSkip (HTTP <code>). …` |
+| Nothing answered | `false` | `No response from <host>:<port> (<error>). …` |
+
+A rejected key counts as reachable on purpose: CapSkip *is* running, and the fix is the key, not the process.
+
+### Example
+
+Request: no arguments.
+
+Response (`structuredContent`):
+
+```json
+{
+  "reachable": true,
+  "host": "127.0.0.1",
+  "port": 8080,
+  "latencyMs": 6,
+  "detail": "CapSkip answered at 127.0.0.1:8080 in 6ms."
+}
+```
+
+When nothing is listening:
+
+```json
+{
+  "reachable": false,
+  "host": "127.0.0.1",
+  "port": 8080,
+  "detail": "No response from 127.0.0.1:8080 (connect ECONNREFUSED 127.0.0.1:8080). Start the CapSkip desktop app, then confirm its API port matches — override with CAPSKIP_HOST / CAPSKIP_PORT."
+}
+```
+
+When something else holds the port:
+
+```json
+{
+  "reachable": false,
+  "host": "127.0.0.1",
+  "port": 8080,
+  "latencyMs": 3,
+  "detail": "Something is listening on 127.0.0.1:8080 but it did not answer as CapSkip (HTTP 404). Check the API port in CapSkip settings, and that nothing else has taken that port — override with CAPSKIP_HOST / CAPSKIP_PORT."
+}
+```
+
+---
+
+## `capskip_solve_image_captcha`
+
+Read the text out of a distorted-text captcha image. Returns the recognized text, which you type into the page's captcha field. Proxies are not supported for image captchas.
+
+### Parameters
+
+| Name | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `image` | string | Yes | — | "The captcha image: a local file path, an http(s) URL, a data: URI, or a raw base64 string." |
+| `timeout` | integer | No | `CAPSKIP_TIMEOUT` (120) | "Seconds to wait before giving up. Maximum 600." |
+
+There is no `proxy` field on this tool. Passing one is rejected as an unrecognized key — CapSkip does not support proxying image-captcha solves.
+
+### Output shape
+
+| Field | Type | Description |
+|---|---|---|
+| `captchaId` | string | CapSkip's internal id for this solve |
+| `code` | string | The recognized text |
+| `solveSeconds` | number | Wall-clock time the solve took |
+
+### Example
+
+Request:
+
+```json
+{
+  "image": "https://example.com/captcha.png"
+}
+```
+
+Response (`structuredContent`):
+
+```json
+{
+  "captchaId": "48213",
+  "code": "8fx3k2",
+  "solveSeconds": 4.31
+}
+```
+
+Text output: `Solved the image captcha in 4.31s.\nText: 8fx3k2\n(CapSkip captcha id 48213)`
+
+---
+
+## `capskip_solve_recaptcha`
+
+Solve a Google reCAPTCHA v2 or v3 widget, including invisible and Enterprise variants. Returns a token to place in the page's `g-recaptcha-response` field before submitting the form. Read the sitekey from the page first — a guessed sitekey fails. Note that reCAPTCHA v3 returns a score assigned by Google; no solver can raise it.
+
+### Parameters
+
+| Name | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `sitekey` | string | Yes | — | "The site key, from the widget's data-sitekey attribute or the grecaptcha config." |
+| `url` | string (URL) | Yes | — | "Full URL of the page the captcha appears on, including scheme." |
+| `version` | `"v2"` \| `"v3"` | No | `v2` | "Which reCAPTCHA generation the page uses. Defaults to v2." |
+| `invisible` | boolean | No | `false` | "v2 only. True when the widget renders with size=invisible." |
+| `enterprise` | boolean | No | `false` | "True for reCAPTCHA Enterprise. Works with both v2 and v3." |
+| `action` | string | No | — | "v3 only. The action passed to grecaptcha.execute(), e.g. 'login'." |
+| `data_s` | string | No | — | "v2 only. The data-s value, used by Google's own services. Rarely needed — CapSkip rejects it on a v3 submit." |
+| `proxy` | object | No | — | "Solve through this proxy so the token is issued against its IP." |
+| `timeout` | integer | No | `CAPSKIP_RECAPTCHA_TIMEOUT` (300) | "Seconds to wait before giving up. Maximum 600." |
+
+`proxy` shape (shared with `capskip_solve_turnstile` and `capskip_solve_geetest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `type` | `"HTTP"` \| `"HTTPS"` \| `"SOCKS5"` \| `"SOCKS5H"` | Yes | "Proxy scheme. CapSkip supports only these four." |
+| `uri` | string | Yes | "Proxy address as `host:port` or `login:password@host:port`." |
+
+**There is no `min_score` parameter.** CapSkip solves locally and returns whatever score Google assigns — it cannot re-solve to clear a threshold the way a cloud service can, so a `min_score` option would promise control that does not exist. Passing `min_score` is rejected as an unrecognized key (`Unrecognized key: "min_score"`), not silently dropped.
+
+`action` applies only to `version: "v3"`; `invisible` applies only to `version: "v2"` (the default). Supplying either against the wrong version is rejected with a message naming the conflict — `'action' is only supported for reCAPTCHA v3.` and `invisible is only supported for reCAPTCHA v2.` respectively.
+
+### Output shape
+
+| Field | Type | Description |
+|---|---|---|
+| `captchaId` | string | CapSkip's internal id for this solve |
+| `code` | string | The `g-recaptcha-response` token |
+| `solveSeconds` | number | Wall-clock time the solve took |
+
+### Example
+
+Request (reCAPTCHA v3):
+
+```json
+{
+  "sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
+  "url": "https://example.com/login",
+  "version": "v3",
+  "action": "submit"
+}
+```
+
+Response (`structuredContent`):
+
+```json
+{
+  "captchaId": "93841",
+  "code": "03AGdBq26f_score0.9token...",
+  "solveSeconds": 9.62
+}
+```
+
+Text output: `Solved reCAPTCHA v3 in 9.62s.\nPut this token in the "g-recaptcha-response" field, then submit the form.\nToken: 03AGdBq26f_score0.9token...\n(CapSkip captcha id 93841)`
+
+---
+
+## `capskip_solve_turnstile`
+
+Solve a Cloudflare Turnstile widget or interstitial challenge page. Returns a token for the page's `cf-turnstile-response` field. IMPORTANT: submit the token using the returned `userAgent` — Cloudflare rejects a token replayed under a different User-Agent. For an interstitial challenge page, also pass `cdata` and `pagedata` read from the page.
+
+### Parameters
+
+| Name | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `sitekey` | string | Yes | — | "The Turnstile site key, from the widget's data-sitekey attribute." |
+| `url` | string (URL) | Yes | — | "Full URL of the page the captcha appears on, including scheme." |
+| `action` | string | No | — | "The action from data-action or turnstile.render()." |
+| `cdata` | string | No | — | "The cData value. Interstitial challenge pages only, not ordinary widgets." |
+| `pagedata` | string | No | — | "The chlPageData value. Interstitial challenge pages only." |
+| `proxy` | object | No | — | "Solve through this proxy so the token is issued against its IP." |
+| `timeout` | integer | No | `CAPSKIP_RECAPTCHA_TIMEOUT` (300) | "Seconds to wait before giving up. Maximum 600." |
+
+`proxy` has the same `{ type, uri }` shape documented under `capskip_solve_recaptcha` above.
+
+### Output shape
+
+| Field | Type | Always present | Description |
+|---|---|---|---|
+| `captchaId` | string | yes | CapSkip's internal id for this solve |
+| `code` | string | yes | The `cf-turnstile-response` token |
+| `solveSeconds` | number | yes | Wall-clock time the solve took |
+| `userAgent` | string | when CapSkip returns one | User-Agent the token must be submitted with |
+
+### Example
+
+Request:
+
+```json
+{
+  "sitekey": "0x4AAAAAAA...",
+  "url": "https://example.com"
+}
+```
+
+Response (`structuredContent`):
+
+```json
+{
+  "captchaId": "77120",
+  "code": "0.k9J3n...token",
+  "solveSeconds": 6.05,
+  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ..."
+}
+```
+
+Text output: `Solved Turnstile in 6.05s.\nPut this token in the "cf-turnstile-response" field, then submit the form.\nToken: 0.k9J3n...token\nSend the token with this exact User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ...\n(CapSkip captcha id 77120)`
+
+For a challenge page, add `cdata` and `pagedata` read from the page:
+
+```json
+{
+  "sitekey": "0x4AAAAAAA...",
+  "url": "https://example.com/challenge",
+  "action": "managed",
+  "cdata": "0=abc123...",
+  "pagedata": "3fH...pagedata"
+}
+```
+
+---
+
+## `capskip_solve_geetest`
+
+Solve a GeeTest v3 slide-puzzle captcha. Returns `geetest_challenge`, `geetest_validate`, and `geetest_seccode` to post back exactly as the site's own front-end would. IMPORTANT: the challenge value is single-use and expires in roughly a minute, so fetch `gt` and `challenge` from the page immediately before calling. A stale challenge is the most common failure.
+
+### Parameters
+
+| Name | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `gt` | string | Yes | — | "The gt value. Static per site, so it can be reused." |
+| `challenge` | string | Yes | — | "The challenge value. Single-use and expires in about a minute — fetch a fresh one immediately before calling this." |
+| `url` | string (URL) | Yes | — | "Full URL of the page the captcha appears on, including scheme." |
+| `api_server` | string | No | — | "A non-default GeeTest API domain, e.g. 'api-na.geetest.com'." |
+| `proxy` | object | No | — | "Solve through this proxy so the answer is produced from its IP." |
+| `timeout` | integer | No | `CAPSKIP_RECAPTCHA_TIMEOUT` (300) | "Seconds to wait before giving up. Maximum 600." |
+
+`proxy` has the same `{ type, uri }` shape documented under `capskip_solve_recaptcha` above.
+
+### Output shape
+
+| Field | Type | Always present | Description |
+|---|---|---|---|
+| `captchaId` | string | yes | CapSkip's internal id for this solve |
+| `code` | string | yes | The raw JSON string CapSkip returns |
+| `solveSeconds` | number | yes | Wall-clock time the solve took |
+| `challenge` | string | when parsed from the answer | `geetest_challenge` to post back |
+| `validate` | string | when parsed from the answer | `geetest_validate` to post back |
+| `seccode` | string | when parsed from the answer | `geetest_seccode` to post back |
+
+### Example
+
+Request:
+
+```json
+{
+  "gt": "81388ea1fc187e0c335c0a8907ff2625",
+  "challenge": "7cf6a8b1a2c34d5e6f7089abcdef0123",
+  "url": "https://example.com/login"
+}
+```
+
+Response (`structuredContent`):
+
+```json
+{
+  "captchaId": "10432",
+  "code": "{\"geetest_challenge\":\"7cf6a8b1...\",\"geetest_validate\":\"a1b2c3...\",\"geetest_seccode\":\"a1b2c3...|jordan\"}",
+  "solveSeconds": 14.2,
+  "challenge": "7cf6a8b1a2c34d5e6f7089abcdef0123",
+  "validate": "a1b2c3d4e5f6...",
+  "seccode": "a1b2c3d4e5f6...|jordan"
+}
+```
+
+Text output: `Solved GeeTest in 14.2s.\nPost these back exactly as the site's own front-end would:\ngeetest_challenge: 7cf6a8b1a2c34d5e6f7089abcdef0123\ngeetest_validate: a1b2c3d4e5f6...\ngeetest_seccode: a1b2c3d4e5f6...|jordan\n(CapSkip captcha id 10432)`
+
+---
+
+## Validation errors
+
+Every tool's schema is a strict object: any key it does not declare is rejected rather than ignored, and every required key must be present. These failures return `isError: true` before the call ever reaches CapSkip. Examples:
+
+| Situation | Message contains |
+|---|---|
+| Unknown key, e.g. `min_score` on `capskip_solve_recaptcha` | `Unrecognized key: "min_score"` |
+| Missing required key, e.g. `image` omitted | `... at image` |
+| `timeout` above 600 | `... expected number to be <=600 at timeout` |
+| `url` without a scheme | `Invalid URL at url` |
+| Unsupported `proxy.type`, e.g. `SOCKS4` | `Invalid option: expected one of "HTTP"\|"HTTPS"\|"SOCKS5"\|"SOCKS5H" at proxy.type` |
+
+The 600-second cap applies only to the `timeout` argument on an individual tool call — it is rejected outright above 600, never silently reduced. `CAPSKIP_TIMEOUT` and `CAPSKIP_RECAPTCHA_TIMEOUT`, which supply the *default* when `timeout` is omitted, are a separate setting validated at startup with their own bound (1–3600 seconds); a default above 600 is accepted and simply is not capped by the per-call schema.
+
+---
+
+## See also
+
+- [Tutorial](TUTORIAL.md) — recognizing each captcha type on a page and placing the answer
+- [Getting Started](GETTING_STARTED.md) — installation and client setup
+- [Troubleshooting](TROUBLESHOOTING.md) — fixes for common errors
+- [CapSkip API docs](https://capskip.com/api-docs/) — the raw HTTP API `capskip-mcp` wraps