capskip-mcp 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -10,6 +10,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Nothing yet. Add entries here as changes land; they move into a version
 section at release time.
 
+## [1.1.0] - 2026-09-12
+
+### Added
+
+- **`capskip_solve_altcha`** — solve an ALTCHA proof-of-work challenge. Takes
+  `url` plus one of `challenge_url` (the endpoint the `<altcha-widget>` fetches
+  from, which CapSkip fetches for you) or `challenge_json` (the challenge
+  document itself, solved locally with no network request). Returns `token`, the
+  payload to submit verbatim in the site's form field named `altcha`, and
+  `number`, the counter that solved it.
+- Calling it with neither challenge parameter returns an error naming what is
+  missing, and where to find it, rather than spending a round trip to learn
+  CapSkip's `ERROR_BAD_PARAMETERS`.
+- `number` is reported for both ALTCHA generations — the legacy scheme and
+  proof-of-work v2 (PBKDF2/SHA), whose token carries no top-level `number` at
+  all. Verified against live v1 and v2 deployments.
+
+### Changed
+
+- Requires `capskip` >= 1.2.0, which is where `altcha()` was added.
+- The server instructions now list ALTCHA among the solvable types.
+
+### Notes
+
+- ALTCHA uses `CAPSKIP_DEFAULT_TIMEOUT`, not `CAPSKIP_RECAPTCHA_TIMEOUT` — it is
+  CPU proof-of-work measured in milliseconds, not a browser solve.
+- A `proxy` passed to this tool applies only to the `challenge_url` fetch; an
+  inline `challenge_json` never touches the network.
+
 ## [1.0.0] - 2026-08-09
 
 ### Added

package/README.md

@@ -5,7 +5,7 @@
 [![Tests](https://github.com/capskip/capskip-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/capskip/capskip-mcp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/capskip-mcp.svg)](https://www.npmjs.com/package/capskip-mcp)
 
-**A captcha solver [MCP](https://modelcontextprotocol.io) server that lets AI agents solve reCAPTCHA, Cloudflare Turnstile, GeeTest and image captchas instead of stalling on them.**
+**A captcha solver [MCP](https://modelcontextprotocol.io) server that lets AI agents solve reCAPTCHA, Cloudflare Turnstile, GeeTest, ALTCHA and image captchas instead of stalling on them.**
 
 Works with Claude Desktop, Claude Code, Cursor, VS Code, and any Model Context Protocol client. Powered by [CapSkip](https://capskip.com) — a **local captcha solver** that runs on your own machine, licensed once rather than billed per solve.
 
@@ -31,6 +31,7 @@ CapSkip runs as a desktop app exposing a captcha-solving HTTP API on `127.0.0.1:
 | **reCAPTCHA v3 solver** | `capskip_solve_recaptcha` | Pass `version: "v3"` and the page's `action` |
 | **Cloudflare Turnstile solver** | `capskip_solve_turnstile` | Widget and interstitial challenge pages |
 | **GeeTest v3 solver** | `capskip_solve_geetest` | Slide puzzle; returns challenge/validate/seccode |
+| **ALTCHA solver** | `capskip_solve_altcha` | Proof-of-work; returns the token for the `altcha` field |
 | **Image captcha solver** (text/OCR) | `capskip_solve_image_captcha` | File path, URL, data URI, or base64 |
 
 **Not supported: hCaptcha and FunCaptcha/Arkose.** There is no tool for them and `capskip_solve_recaptcha` will not work on one. hCaptcha is the easiest to misidentify since it also carries a `data-sitekey` — check for `class="h-captcha"` or a `js.hcaptcha.com` script first.
@@ -112,6 +113,7 @@ CapSkip exposes the familiar `in.php` / `res.php` endpoints, so it works as a **
 | `capskip_solve_recaptcha` | Solve reCAPTCHA v2 or v3, including invisible and Enterprise | `sitekey`, `url` |
 | `capskip_solve_turnstile` | Solve a Cloudflare Turnstile widget or challenge page | `sitekey`, `url` |
 | `capskip_solve_geetest` | Solve a GeeTest v3 slide-puzzle captcha | `gt`, `challenge`, `url` |
+| `capskip_solve_altcha` | Solve an ALTCHA proof-of-work challenge | `url`, and one of `challenge_url` / `challenge_json` |
 
 > **There is no `min_score` parameter on `capskip_solve_recaptcha`.** reCAPTCHA v3 scores are assigned by Google from signals no solver has access to — local or cloud, none can raise a score after the fact. A `min_score` option would promise control that does not exist, so it is deliberately left out. Passing it anyway is rejected as an unrecognized key, not silently ignored.
 
@@ -152,6 +154,10 @@ For non-agent scripts, use the language SDKs directly — see the [Playwright](h
 | `CAPSKIP_PORT` | `8080` | API port from CapSkip settings |
 | `CAPSKIP_TIMEOUT` | `120` | Default `timeout` for `capskip_solve_image_captcha`, seconds |
 | `CAPSKIP_RECAPTCHA_TIMEOUT` | `300` | Default `timeout` for the reCAPTCHA / Turnstile / GeeTest tools, seconds |
+
+ALTCHA uses `CAPSKIP_DEFAULT_TIMEOUT`, not the reCAPTCHA one — it is CPU
+proof-of-work measured in milliseconds, not a browser solve.
+
 | `CAPSKIP_POLLING_INTERVAL` | `5` | Max seconds between polls |
 
 CLI flags override environment variables, which override the defaults:
@@ -179,6 +185,7 @@ Every solve tool returns a human-readable text block and `structuredContent` mat
 
 - **`capskip_solve_turnstile`** adds `userAgent`. Submit the token with this exact User-Agent — Cloudflare rejects a token replayed under a different one.
 - **`capskip_solve_geetest`** adds `challenge`, `validate` and `seccode`, to post back exactly as the site's own front-end would; `code` keeps the raw JSON string CapSkip returns.
+- **`capskip_solve_altcha`** adds `token`, the base64 payload to submit verbatim in the site's form field named `altcha`, and `number`, the counter that solved the challenge; `code` holds the same string as `token`.
 
 Long solves emit MCP progress notifications, so a 45-second reCAPTCHA does not trip your client's tool-call timeout.
 
@@ -221,11 +228,11 @@ The MCP server is MIT-licensed and free. It requires the CapSkip desktop app, wh
 
 ### Which captchas can it solve?
 
-reCAPTCHA v2 (checkbox and invisible), reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, GeeTest v3, and image/text captchas. hCaptcha and FunCaptcha/Arkose are not supported.
+reCAPTCHA v2 (checkbox and invisible), reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, GeeTest v3, ALTCHA, and image/text captchas. hCaptcha and FunCaptcha/Arkose are not supported.
 
 ### Why does my reCAPTCHA v3 token get a low score?
 
-Google assigns v3 scores from signals such as IP reputation and browsing history. A solver returns a valid token, but cannot raise the score. If a site enforces a high threshold, solve from a cleaner IP — a proxy is supported on the reCAPTCHA, Turnstile and GeeTest tools.
+Google assigns v3 scores from signals such as IP reputation and browsing history. A solver returns a valid token, but cannot raise the score. If a site enforces a high threshold, solve from a cleaner IP — a proxy is supported on the reCAPTCHA, Turnstile, GeeTest and ALTCHA tools (for ALTCHA it applies only to the challenge fetch).
 
 ### Does it need my captcha to be on a public page?
 

package/dist/schemas.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.statusOutput = exports.geetestOutput = exports.turnstileOutput = exports.baseSolveOutput = exports.pageUrlSchema = exports.timeoutSchema = exports.proxySchema = void 0;
+exports.statusOutput = exports.altchaOutput = exports.geetestOutput = exports.turnstileOutput = exports.baseSolveOutput = exports.pageUrlSchema = exports.timeoutSchema = exports.proxySchema = void 0;
 const zod_1 = require("zod");
 /**
  * CapSkip maps only these four proxy schemes and answers ERROR_BAD_PARAMETERS
@@ -42,6 +42,12 @@ exports.geetestOutput = exports.baseSolveOutput.extend({
     validate: zod_1.z.string().optional(),
     seccode: zod_1.z.string().optional(),
 });
+exports.altchaOutput = exports.baseSolveOutput.extend({
+    /** The base64 payload to submit in the site's `altcha` form field, verbatim. */
+    token: zod_1.z.string(),
+    /** The counter that satisfied the challenge. Absent if the payload did not decode. */
+    number: zod_1.z.number().optional(),
+});
 exports.statusOutput = zod_1.z.object({
     reachable: zod_1.z.boolean(),
     host: zod_1.z.string(),

package/dist/schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB;;;GAGG;AACU,QAAA,WAAW,GAAG,OAAC,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,OAAC;SACJ,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;SAC5C,QAAQ,CAAC,iDAAiD,CAAC;IAC9D,GAAG,EAAE,OAAC;SACH,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,6DAA6D,CAAC;CAC3E,CAAC,CAAC;AAIH;;;GAGG;AACU,QAAA,aAAa,GAAG,OAAC;KAC3B,MAAM,EAAE;KACR,GAAG,EAAE;KACL,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,QAAQ,EAAE;KACV,QAAQ,CAAC,gDAAgD,CAAC,CAAC;AAEjD,QAAA,aAAa,GAAG,OAAC;KAC3B,GAAG,EAAE;KACL,QAAQ,CAAC,gEAAgE,CAAC,CAAC;AAEjE,QAAA,eAAe,GAAG,OAAC,CAAC,MAAM,CAAC;IACtC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE;IACrB,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAChB,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE;CACzB,CAAC,CAAC;AAEU,QAAA,eAAe,GAAG,uBAAe,CAAC,MAAM,CAAC;IACpD,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAEU,QAAA,aAAa,GAAG,uBAAe,CAAC,MAAM,CAAC;IAClD,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC;AAEU,QAAA,YAAY,GAAG,OAAC,CAAC,MAAM,CAAC;IACnC,SAAS,EAAE,OAAC,CAAC,OAAO,EAAE;IACtB,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAChB,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC","sourcesContent":["import { z } from 'zod';\n\n/**\n * CapSkip maps only these four proxy schemes and answers ERROR_BAD_PARAMETERS\n * for anything else, SOCKS4 included.\n */\nexport const proxySchema = z.object({\n  type: z\n    .enum(['HTTP', 'HTTPS', 'SOCKS5', 'SOCKS5H'])\n    .describe('Proxy scheme. CapSkip supports only these four.'),\n  uri: z\n    .string()\n    .min(1)\n    .describe('Proxy address as `host:port` or `login:password@host:port`.'),\n});\n\nexport type ProxyInput = z.infer<typeof proxySchema>;\n\n/**\n * Bounded at 600s. A larger value is rejected rather than clamped so the caller\n * learns the limit instead of silently getting a shorter wait.\n */\nexport const timeoutSchema = z\n  .number()\n  .int()\n  .min(1)\n  .max(600)\n  .optional()\n  .describe('Seconds to wait before giving up. Maximum 600.');\n\nexport const pageUrlSchema = z\n  .url()\n  .describe('Full URL of the page the captcha appears on, including scheme.');\n\nexport const baseSolveOutput = z.object({\n  captchaId: z.string(),\n  code: z.string(),\n  solveSeconds: z.number(),\n});\n\nexport const turnstileOutput = baseSolveOutput.extend({\n  userAgent: z.string().optional(),\n});\n\nexport const geetestOutput = baseSolveOutput.extend({\n  challenge: z.string().optional(),\n  validate: z.string().optional(),\n  seccode: z.string().optional(),\n});\n\nexport const statusOutput = z.object({\n  reachable: z.boolean(),\n  host: z.string(),\n  port: z.number(),\n  latencyMs: z.number().optional(),\n  detail: z.string(),\n});\n"]}
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB;;;GAGG;AACU,QAAA,WAAW,GAAG,OAAC,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,OAAC;SACJ,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;SAC5C,QAAQ,CAAC,iDAAiD,CAAC;IAC9D,GAAG,EAAE,OAAC;SACH,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,6DAA6D,CAAC;CAC3E,CAAC,CAAC;AAIH;;;GAGG;AACU,QAAA,aAAa,GAAG,OAAC;KAC3B,MAAM,EAAE;KACR,GAAG,EAAE;KACL,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,QAAQ,EAAE;KACV,QAAQ,CAAC,gDAAgD,CAAC,CAAC;AAEjD,QAAA,aAAa,GAAG,OAAC;KAC3B,GAAG,EAAE;KACL,QAAQ,CAAC,gEAAgE,CAAC,CAAC;AAEjE,QAAA,eAAe,GAAG,OAAC,CAAC,MAAM,CAAC;IACtC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE;IACrB,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAChB,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE;CACzB,CAAC,CAAC;AAEU,QAAA,eAAe,GAAG,uBAAe,CAAC,MAAM,CAAC;IACpD,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAEU,QAAA,aAAa,GAAG,uBAAe,CAAC,MAAM,CAAC;IAClD,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC;AAEU,QAAA,YAAY,GAAG,uBAAe,CAAC,MAAM,CAAC;IACjD,gFAAgF;IAChF,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;IACjB,sFAAsF;IACtF,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC;AAEU,QAAA,YAAY,GAAG,OAAC,CAAC,MAAM,CAAC;IACnC,SAAS,EAAE,OAAC,CAAC,OAAO,EAAE;IACtB,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAChB,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC","sourcesContent":["import { z } from 'zod';\n\n/**\n * CapSkip maps only these four proxy schemes and answers ERROR_BAD_PARAMETERS\n * for anything else, SOCKS4 included.\n */\nexport const proxySchema = z.object({\n  type: z\n    .enum(['HTTP', 'HTTPS', 'SOCKS5', 'SOCKS5H'])\n    .describe('Proxy scheme. CapSkip supports only these four.'),\n  uri: z\n    .string()\n    .min(1)\n    .describe('Proxy address as `host:port` or `login:password@host:port`.'),\n});\n\nexport type ProxyInput = z.infer<typeof proxySchema>;\n\n/**\n * Bounded at 600s. A larger value is rejected rather than clamped so the caller\n * learns the limit instead of silently getting a shorter wait.\n */\nexport const timeoutSchema = z\n  .number()\n  .int()\n  .min(1)\n  .max(600)\n  .optional()\n  .describe('Seconds to wait before giving up. Maximum 600.');\n\nexport const pageUrlSchema = z\n  .url()\n  .describe('Full URL of the page the captcha appears on, including scheme.');\n\nexport const baseSolveOutput = z.object({\n  captchaId: z.string(),\n  code: z.string(),\n  solveSeconds: z.number(),\n});\n\nexport const turnstileOutput = baseSolveOutput.extend({\n  userAgent: z.string().optional(),\n});\n\nexport const geetestOutput = baseSolveOutput.extend({\n  challenge: z.string().optional(),\n  validate: z.string().optional(),\n  seccode: z.string().optional(),\n});\n\nexport const altchaOutput = baseSolveOutput.extend({\n  /** The base64 payload to submit in the site's `altcha` form field, verbatim. */\n  token: z.string(),\n  /** The counter that satisfied the challenge. Absent if the payload did not decode. */\n  number: z.number().optional(),\n});\n\nexport const statusOutput = z.object({\n  reachable: z.boolean(),\n  host: z.string(),\n  port: z.number(),\n  latencyMs: z.number().optional(),\n  detail: z.string(),\n});\n"]}

package/dist/server.js

@@ -4,13 +4,14 @@ exports.SERVER_VERSION = exports.SERVER_NAME = void 0;
 exports.createServer = createServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const solver_js_1 = require("./solver.js");
+const altcha_js_1 = require("./tools/altcha.js");
 const geetest_js_1 = require("./tools/geetest.js");
 const image_js_1 = require("./tools/image.js");
 const recaptcha_js_1 = require("./tools/recaptcha.js");
 const status_js_1 = require("./tools/status.js");
 const turnstile_js_1 = require("./tools/turnstile.js");
 exports.SERVER_NAME = 'capskip';
-exports.SERVER_VERSION = '1.0.0';
+exports.SERVER_VERSION = '1.1.0';
 /** Build a fully-registered MCP server. Does not connect a transport. */
 function createServer(config) {
     const server = new mcp_js_1.McpServer({ name: exports.SERVER_NAME, version: exports.SERVER_VERSION }, {
@@ -18,7 +19,7 @@ function createServer(config) {
             + 'tools when browser automation is blocked by a captcha: read the sitekey '
             + 'from the page, call the matching tool, then place the returned token in '
             + "the page's response field. CapSkip solves image captchas, reCAPTCHA v2 "
-            + 'and v3, Cloudflare Turnstile, and GeeTest v3 — it cannot solve hCaptcha '
+            + 'and v3, Cloudflare Turnstile, GeeTest v3, and ALTCHA — it cannot solve hCaptcha '
             + 'or FunCaptcha/Arkose, so do not call these tools for those. An hCaptcha '
             + 'widget renders as <div class="h-captcha" data-sitekey="…">, which is '
             + 'easy to mistake for reCAPTCHA when scanning the DOM for data-sitekey. '
@@ -31,6 +32,7 @@ function createServer(config) {
     (0, recaptcha_js_1.registerRecaptchaTool)(server, ctx);
     (0, turnstile_js_1.registerTurnstileTool)(server, ctx);
     (0, geetest_js_1.registerGeetestTool)(server, ctx);
+    (0, altcha_js_1.registerAltchaTool)(server, ctx);
     return server;
 }
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";;;AAcA,oCA2BC;AAzCD,oEAAoE;AAGpE,2CAA4C;AAC5C,mDAAyD;AACzD,+CAAqD;AACrD,uDAA6D;AAC7D,iDAAuD;AACvD,uDAA6D;AAEhD,QAAA,WAAW,GAAG,SAAS,CAAC;AACxB,QAAA,cAAc,GAAG,OAAO,CAAC;AAEtC,yEAAyE;AACzE,SAAgB,YAAY,CAAC,MAAqB;IAChD,MAAM,MAAM,GAAG,IAAI,kBAAS,CAC1B,EAAE,IAAI,EAAE,mBAAW,EAAE,OAAO,EAAE,sBAAc,EAAE,EAC9C;QACE,YAAY,EACV,0EAA0E;cACxE,0EAA0E;cAC1E,0EAA0E;cAC1E,yEAAyE;cACzE,0EAA0E;cAC1E,0EAA0E;cAC1E,uEAAuE;cACvE,wEAAwE;cACxE,yEAAyE;cACzE,UAAU;KACf,CACF,CAAC;IAEF,MAAM,GAAG,GAAG,IAAA,yBAAa,EAAC,MAAM,CAAC,CAAC;IAElC,IAAA,8BAAkB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,IAAA,4BAAiB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/B,IAAA,oCAAqB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,IAAA,oCAAqB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,IAAA,gCAAmB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEjC,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\n\nimport type { CapSkipConfig } from './config.js';\nimport { createContext } from './solver.js';\nimport { registerGeetestTool } from './tools/geetest.js';\nimport { registerImageTool } from './tools/image.js';\nimport { registerRecaptchaTool } from './tools/recaptcha.js';\nimport { registerStatusTool } from './tools/status.js';\nimport { registerTurnstileTool } from './tools/turnstile.js';\n\nexport const SERVER_NAME = 'capskip';\nexport const SERVER_VERSION = '1.0.0';\n\n/** Build a fully-registered MCP server. Does not connect a transport. */\nexport function createServer(config: CapSkipConfig): McpServer {\n  const server = new McpServer(\n    { name: SERVER_NAME, version: SERVER_VERSION },\n    {\n      instructions:\n        'Solve captchas through a locally-running CapSkip desktop app. Use these '\n        + 'tools when browser automation is blocked by a captcha: read the sitekey '\n        + 'from the page, call the matching tool, then place the returned token in '\n        + \"the page's response field. CapSkip solves image captchas, reCAPTCHA v2 \"\n        + 'and v3, Cloudflare Turnstile, and GeeTest v3 — it cannot solve hCaptcha '\n        + 'or FunCaptcha/Arkose, so do not call these tools for those. An hCaptcha '\n        + 'widget renders as <div class=\"h-captcha\" data-sitekey=\"…\">, which is '\n        + 'easy to mistake for reCAPTCHA when scanning the DOM for data-sitekey. '\n        + 'If a solve fails unexpectedly, call capskip_status to check CapSkip is '\n        + 'running.',\n    },\n  );\n\n  const ctx = createContext(config);\n\n  registerStatusTool(server, ctx);\n  registerImageTool(server, ctx);\n  registerRecaptchaTool(server, ctx);\n  registerTurnstileTool(server, ctx);\n  registerGeetestTool(server, ctx);\n\n  return server;\n}\n"]}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";;;AAeA,oCA4BC;AA3CD,oEAAoE;AAGpE,2CAA4C;AAC5C,iDAAuD;AACvD,mDAAyD;AACzD,+CAAqD;AACrD,uDAA6D;AAC7D,iDAAuD;AACvD,uDAA6D;AAEhD,QAAA,WAAW,GAAG,SAAS,CAAC;AACxB,QAAA,cAAc,GAAG,OAAO,CAAC;AAEtC,yEAAyE;AACzE,SAAgB,YAAY,CAAC,MAAqB;IAChD,MAAM,MAAM,GAAG,IAAI,kBAAS,CAC1B,EAAE,IAAI,EAAE,mBAAW,EAAE,OAAO,EAAE,sBAAc,EAAE,EAC9C;QACE,YAAY,EACV,0EAA0E;cACxE,0EAA0E;cAC1E,0EAA0E;cAC1E,yEAAyE;cACzE,kFAAkF;cAClF,0EAA0E;cAC1E,uEAAuE;cACvE,wEAAwE;cACxE,yEAAyE;cACzE,UAAU;KACf,CACF,CAAC;IAEF,MAAM,GAAG,GAAG,IAAA,yBAAa,EAAC,MAAM,CAAC,CAAC;IAElC,IAAA,8BAAkB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,IAAA,4BAAiB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/B,IAAA,oCAAqB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,IAAA,oCAAqB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,IAAA,gCAAmB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,IAAA,8BAAkB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEhC,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\n\nimport type { CapSkipConfig } from './config.js';\nimport { createContext } from './solver.js';\nimport { registerAltchaTool } from './tools/altcha.js';\nimport { registerGeetestTool } from './tools/geetest.js';\nimport { registerImageTool } from './tools/image.js';\nimport { registerRecaptchaTool } from './tools/recaptcha.js';\nimport { registerStatusTool } from './tools/status.js';\nimport { registerTurnstileTool } from './tools/turnstile.js';\n\nexport const SERVER_NAME = 'capskip';\nexport const SERVER_VERSION = '1.1.0';\n\n/** Build a fully-registered MCP server. Does not connect a transport. */\nexport function createServer(config: CapSkipConfig): McpServer {\n  const server = new McpServer(\n    { name: SERVER_NAME, version: SERVER_VERSION },\n    {\n      instructions:\n        'Solve captchas through a locally-running CapSkip desktop app. Use these '\n        + 'tools when browser automation is blocked by a captcha: read the sitekey '\n        + 'from the page, call the matching tool, then place the returned token in '\n        + \"the page's response field. CapSkip solves image captchas, reCAPTCHA v2 \"\n        + 'and v3, Cloudflare Turnstile, GeeTest v3, and ALTCHA — it cannot solve hCaptcha '\n        + 'or FunCaptcha/Arkose, so do not call these tools for those. An hCaptcha '\n        + 'widget renders as <div class=\"h-captcha\" data-sitekey=\"…\">, which is '\n        + 'easy to mistake for reCAPTCHA when scanning the DOM for data-sitekey. '\n        + 'If a solve fails unexpectedly, call capskip_status to check CapSkip is '\n        + 'running.',\n    },\n  );\n\n  const ctx = createContext(config);\n\n  registerStatusTool(server, ctx);\n  registerImageTool(server, ctx);\n  registerRecaptchaTool(server, ctx);\n  registerTurnstileTool(server, ctx);\n  registerGeetestTool(server, ctx);\n  registerAltchaTool(server, ctx);\n\n  return server;\n}\n"]}

package/dist/tools/altcha.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAltchaTool = registerAltchaTool;
+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({
+    url: schemas_js_1.pageUrlSchema,
+    challenge_url: zod_1.z
+        .string()
+        .min(1)
+        .optional()
+        .describe('The endpoint the ALTCHA widget fetches its challenge from, e.g. '
+        + "'https://site.com/altcha/challenge'. CapSkip fetches it for you. Pass "
+        + 'this or challenge_json.'),
+    challenge_json: zod_1.z
+        .string()
+        .min(1)
+        .optional()
+        .describe('The challenge document itself, as a JSON string, when you already have '
+        + 'it. Solved locally with no network request. Pass this or challenge_url.'),
+    proxy: schemas_js_1.proxySchema
+        .optional()
+        .describe('Fetch the challenge through this proxy. Used ONLY for the challenge_url '
+        + 'fetch — an inline challenge_json never touches the network.'),
+    timeout: schemas_js_1.timeoutSchema,
+});
+function registerAltchaTool(server, ctx) {
+    server.registerTool('capskip_solve_altcha', {
+        title: 'Solve ALTCHA',
+        description: 'Solve an ALTCHA proof-of-work challenge. ALTCHA is not a recognition '
+            + 'captcha — there is nothing to read; the client brute-forces a number '
+            + 'that satisfies a challenge, so a solve is deterministic and takes '
+            + 'milliseconds. Give it either challenge_url (the endpoint the '
+            + '<altcha-widget> fetches from, which CapSkip will fetch) or '
+            + 'challenge_json (the challenge document itself). Returns a token to put '
+            + "in the page's form field named `altcha`, verbatim. IMPORTANT: "
+            + 'challenges expire quickly — some sites inside two minutes — so read '
+            + 'the challenge immediately before calling and submit the token '
+            + 'promptly. An expired challenge is rejected with a bare "verification '
+            + 'failed" that looks exactly like a wrong answer.',
+        inputSchema,
+        outputSchema: schemas_js_1.altchaOutput,
+        // destructiveHint defaults to *true* whenever readOnlyHint is false, so
+        // omitting it would advertise 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 challenge that expires.
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, async (args, extra) => {
+        // CapSkip answers ERROR_BAD_PARAMETERS when neither is sent. zod cannot
+        // express "at least one of" on a strictObject without reshaping the schema
+        // into a union, which renders poorly in tool listings — so check here and
+        // name what is missing.
+        if (args.challenge_url === undefined && args.challenge_json === undefined) {
+            return {
+                isError: true,
+                content: [{
+                        type: 'text',
+                        text: 'ALTCHA needs a challenge. Pass challenge_url (the endpoint the '
+                            + '<altcha-widget> fetches from — look in DevTools → Network for a '
+                            + 'request like /altcha/challenge) or challenge_json (that '
+                            + "endpoint's JSON response). Widget v1/v2 name it in a "
+                            + 'challengeurl="…" attribute; v3+ uses challenge="…" for both a '
+                            + 'URL and inline data.',
+                    }],
+            };
+        }
+        const timeout = args.timeout ?? ctx.config.defaultTimeout;
+        const options = {};
+        if (args.challenge_url !== undefined)
+            options.challenge_url = args.challenge_url;
+        if (args.challenge_json !== undefined)
+            options.challenge_json = args.challenge_json;
+        if (args.proxy !== undefined)
+            options.proxy = args.proxy;
+        return (0, solve_js_1.runSolve)(ctx, extra, { label: 'Solving ALTCHA', timeoutSeconds: timeout }, (client) => client.altcha(args.url, options), (result, seconds) => {
+            const token = result.token ?? String(result.code ?? '');
+            const number = result.number;
+            const structured = {
+                captchaId: String(result.captchaId ?? ''),
+                code: String(result.code ?? ''),
+                solveSeconds: Number(seconds.toFixed(2)),
+                token,
+                ...(number !== undefined ? { number } : {}),
+            };
+            return {
+                structured,
+                text: `Solved ALTCHA in ${structured.solveSeconds}s.\n`
+                    + 'Submit this verbatim in the form field the widget uses, named '
+                    + '`altcha` — do not re-encode, trim or re-order it, or the '
+                    + "server's signature check fails:\n"
+                    + `altcha: ${token}\n`
+                    + (number !== undefined ? `(counter ${number}; ` : '(')
+                    + `CapSkip captcha id ${structured.captchaId})`,
+            };
+        });
+    });
+}
+//# sourceMappingURL=altcha.js.map

package/dist/tools/altcha.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"altcha.js","sourceRoot":"","sources":["../../src/tools/altcha.ts"],"names":[],"mappings":"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","sourcesContent":["import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { z } from 'zod';\n\nimport { altchaOutput, pageUrlSchema, proxySchema, timeoutSchema } from '../schemas.js';\nimport { runSolve } from '../solve.js';\nimport type { ToolContext } from '../solver.js';\n\nconst inputSchema = z.strictObject({\n  url: pageUrlSchema,\n  challenge_url: z\n    .string()\n    .min(1)\n    .optional()\n    .describe(\n      'The endpoint the ALTCHA widget fetches its challenge from, e.g. '\n      + \"'https://site.com/altcha/challenge'. CapSkip fetches it for you. Pass \"\n      + 'this or challenge_json.',\n    ),\n  challenge_json: z\n    .string()\n    .min(1)\n    .optional()\n    .describe(\n      'The challenge document itself, as a JSON string, when you already have '\n      + 'it. Solved locally with no network request. Pass this or challenge_url.',\n    ),\n  proxy: proxySchema\n    .optional()\n    .describe(\n      'Fetch the challenge through this proxy. Used ONLY for the challenge_url '\n      + 'fetch — an inline challenge_json never touches the network.',\n    ),\n  timeout: timeoutSchema,\n});\n\nexport function registerAltchaTool(server: McpServer, ctx: ToolContext): void {\n  server.registerTool(\n    'capskip_solve_altcha',\n    {\n      title: 'Solve ALTCHA',\n      description:\n        'Solve an ALTCHA proof-of-work challenge. ALTCHA is not a recognition '\n        + 'captcha — there is nothing to read; the client brute-forces a number '\n        + 'that satisfies a challenge, so a solve is deterministic and takes '\n        + 'milliseconds. Give it either challenge_url (the endpoint the '\n        + '<altcha-widget> fetches from, which CapSkip will fetch) or '\n        + 'challenge_json (the challenge document itself). Returns a token to put '\n        + \"in the page's form field named `altcha`, verbatim. IMPORTANT: \"\n        + 'challenges expire quickly — some sites inside two minutes — so read '\n        + 'the challenge immediately before calling and submit the token '\n        + 'promptly. An expired challenge is rejected with a bare \"verification '\n        + 'failed\" that looks exactly like a wrong answer.',\n      inputSchema,\n      outputSchema: altchaOutput,\n      // destructiveHint defaults to *true* whenever readOnlyHint is false, so\n      // omitting it would advertise this tool as potentially destructive and cost\n      // it auto-approval in clients that read the hint. Solving a captcha\n      // destroys nothing. idempotentHint is deliberately left at its false\n      // default: each call consumes a challenge that expires.\n      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },\n    },\n    async (args, extra) => {\n      // CapSkip answers ERROR_BAD_PARAMETERS when neither is sent. zod cannot\n      // express \"at least one of\" on a strictObject without reshaping the schema\n      // into a union, which renders poorly in tool listings — so check here and\n      // name what is missing.\n      if (args.challenge_url === undefined && args.challenge_json === undefined) {\n        return {\n          isError: true,\n          content: [{\n            type: 'text' as const,\n            text:\n              'ALTCHA needs a challenge. Pass challenge_url (the endpoint the '\n              + '<altcha-widget> fetches from — look in DevTools → Network for a '\n              + 'request like /altcha/challenge) or challenge_json (that '\n              + \"endpoint's JSON response). Widget v1/v2 name it in a \"\n              + 'challengeurl=\"…\" attribute; v3+ uses challenge=\"…\" for both a '\n              + 'URL and inline data.',\n          }],\n        };\n      }\n\n      const timeout = args.timeout ?? ctx.config.defaultTimeout;\n\n      const options: Record<string, unknown> = {};\n      if (args.challenge_url !== undefined) options.challenge_url = args.challenge_url;\n      if (args.challenge_json !== undefined) options.challenge_json = args.challenge_json;\n      if (args.proxy !== undefined) options.proxy = args.proxy;\n\n      return runSolve(\n        ctx,\n        extra,\n        { label: 'Solving ALTCHA', timeoutSeconds: timeout },\n        (client) => client.altcha(args.url, options as never),\n        (result, seconds) => {\n          const token = (result.token as string | undefined) ?? String(result.code ?? '');\n          const number = result.number as number | undefined;\n\n          const structured = {\n            captchaId: String(result.captchaId ?? ''),\n            code: String(result.code ?? ''),\n            solveSeconds: Number(seconds.toFixed(2)),\n            token,\n            ...(number !== undefined ? { number } : {}),\n          };\n\n          return {\n            structured,\n            text:\n              `Solved ALTCHA in ${structured.solveSeconds}s.\\n`\n              + 'Submit this verbatim in the form field the widget uses, named '\n              + '`altcha` — do not re-encode, trim or re-order it, or the '\n              + \"server's signature check fails:\\n\"\n              + `altcha: ${token}\\n`\n              + (number !== undefined ? `(counter ${number}; ` : '(')\n              + `CapSkip captcha id ${structured.captchaId})`,\n          };\n        },\n      );\n    },\n  );\n}\n"]}

package/docs/API_REFERENCE.md

@@ -15,6 +15,7 @@ Every solve tool declares an `outputSchema` and returns MCP `structuredContent`
 | `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_solve_altcha` | Solve an ALTCHA proof-of-work challenge | Yes (challenge fetch only) |
 
 ---
 
@@ -153,7 +154,7 @@ Solve a Google reCAPTCHA v2 or v3 widget, including invisible and Enterprise var
 | `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`):
+`proxy` shape (shared with `capskip_solve_turnstile`, `capskip_solve_geetest` and `capskip_solve_altcha`):
 
 | Field | Type | Required | Description |
 |---|---|---|---|
@@ -321,6 +322,69 @@ Text output: `Solved GeeTest in 14.2s.\nPost these back exactly as the site's ow
 
 ---
 
+## `capskip_solve_altcha`
+
+Solve an ALTCHA proof-of-work challenge. ALTCHA is not a recognition captcha — there is nothing to read; the client brute-forces a number that satisfies a challenge, so a solve is deterministic and takes milliseconds. Give it either `challenge_url` (the endpoint the `<altcha-widget>` fetches from, which CapSkip will fetch) or `challenge_json` (the challenge document itself). Returns a token to put in the page's form field named `altcha`, verbatim. IMPORTANT: challenges expire quickly — some sites inside two minutes — so read the challenge immediately before calling and submit the token promptly. An expired challenge is rejected with a bare "verification failed" that looks exactly like a wrong answer.
+
+### Parameters
+
+| Name | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `url` | string (URL) | Yes | — | "Full URL of the page the captcha appears on, including scheme." |
+| `challenge_url` | string | One of the two | — | "The endpoint the ALTCHA widget fetches its challenge from. CapSkip fetches it for you." |
+| `challenge_json` | string | One of the two | — | "The challenge document itself, as a JSON string, when you already have it. Solved locally with no network request." |
+| `proxy` | object | No | — | "Fetch the challenge through this proxy. Used ONLY for the challenge_url fetch." |
+| `timeout` | integer | No | `CAPSKIP_DEFAULT_TIMEOUT` (120) | "Seconds to wait before giving up. Maximum 600." |
+
+Passing neither `challenge_url` nor `challenge_json` returns an error naming what is missing, rather than spending a round trip to learn CapSkip's `ERROR_BAD_PARAMETERS`. Passing both is allowed — the inline document wins.
+
+`proxy` has the same `{ type, uri }` shape documented under `capskip_solve_recaptcha` above.
+
+### Finding the challenge
+
+Open DevTools → Network on the target page and look for the request the `<altcha-widget>` makes for its challenge (often something like `/altcha/challenge`). The request URL is `challenge_url`; its JSON response is `challenge_json`. The widget attribute naming that endpoint depends on the widget version: v1/v2 use `challengeurl="…"`, while v3+ uses `challenge="…"` for both a URL and inline data.
+
+### Output shape
+
+| Field | Type | Always present | Description |
+|---|---|---|---|
+| `captchaId` | string | yes | CapSkip's internal id for this solve |
+| `code` | string | yes | The base64 token — the same string as `token` |
+| `solveSeconds` | number | yes | Wall-clock time the solve took |
+| `token` | string | yes | The payload to submit in the `altcha` form field |
+| `number` | number | when the server reports one | The counter that satisfied the challenge. Present for both the legacy and proof-of-work v2 schemes, whose tokens carry it differently. |
+
+### Example
+
+Request:
+
+```json
+{
+  "url": "https://example.com/signup",
+  "challenge_url": "https://example.com/captcha/api/altcha/challenge"
+}
+```
+
+Response (`structuredContent`):
+
+```json
+{
+  "captchaId": "10433",
+  "code": "eyJhbGdvcml0aG0iOiJTSEEtMjU2Iiwi...",
+  "solveSeconds": 0.27,
+  "token": "eyJhbGdvcml0aG0iOiJTSEEtMjU2Iiwi...",
+  "number": 9661
+}
+```
+
+Text output: `Solved ALTCHA in 0.27s.\nSubmit this verbatim in the form field the widget uses, named \`altcha\` — do not re-encode, trim or re-order it, or the server's signature check fails:\naltcha: eyJhbGdvcml0aG0iOiJTSEEtMjU2Iiwi...\n(counter 9661; CapSkip captcha id 10433)`
+
+### Unsupported algorithms
+
+CapSkip solves the legacy scheme (SHA-1/256/384/512) and PoW v2 with PBKDF2 or SHA. **Argon2id and scrypt are refused**, not attempted: the solve returns `ERROR_CAPTCHA_UNSOLVABLE` and is never retried. ALTCHA recommends PBKDF2 as the default, so this affects a minority of sites.
+
+---
+
 ## 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:

package/docs/TROUBLESHOOTING.md

@@ -156,6 +156,28 @@ The timeout error also names the CapSkip captcha id when one was assigned, so a
 
 ---
 
+## ALTCHA is rejected even though the solve succeeded
+
+**Symptom:** `capskip_solve_altcha` returns a token, but the site answers "verification failed".
+
+**Cause:** The challenge expired before the token was submitted. A v1 challenge carries its expiry inside `salt` (`…?expires=1788669437`); a v2 challenge declares it as `parameters.expiresAt`. The windows are tighter than people expect — some sites issue challenges valid for about two minutes. An expired challenge produces a technically correct token that the site refuses with no explanation, which looks exactly like a wrong answer.
+
+**Fix:** Read the challenge immediately before calling the tool, and submit the token straight away. Do not fetch a batch of challenges in advance, and do not hold a token while a user fills in a form.
+
+Passing `challenge_url` rather than `challenge_json` helps: if the challenge expires while the job is queued, CapSkip fetches a fresh one automatically, the way the widget's own `refetchonexpire` does.
+
+---
+
+## ALTCHA returns ERROR_CAPTCHA_UNSOLVABLE immediately
+
+**Symptom:** The solve fails in well under a second, with no retry.
+
+**Cause:** Either the challenge uses an algorithm CapSkip does not implement — **Argon2id** or **scrypt**, both memory-hard KDFs with no implementation in the .NET runtime CapSkip ships — or the inline `challenge_json` had already expired or was malformed. None of those can succeed on a second attempt, so they are refused rather than retried.
+
+**Fix:** Check the challenge document's `algorithm` field. CapSkip solves the legacy scheme (SHA-1/256/384/512) and PoW v2 with PBKDF2 or SHA; ALTCHA itself recommends PBKDF2 as the default, so an Argon2id site is unusual and worth reporting. If the algorithm is supported, fetch a fresh challenge — the one you sent had expired.
+
+---
+
 ## GeeTest always fails
 
 **Symptom:** `capskip_solve_geetest` fails or times out even though `gt` and `challenge` look correct.
@@ -190,7 +212,7 @@ If the site loads GeeTest from a non-default domain, pass it through as `api_ser
 
 **Symptom:** `capskip_solve_recaptcha` is called on a widget that has a `data-sitekey`, and every attempt fails, times out, or returns a token the site rejects.
 
-**Cause:** The captcha is not a reCAPTCHA. CapSkip supports exactly four types — image captchas, reCAPTCHA v2/v3, Cloudflare Turnstile, and GeeTest v3. It **cannot** solve hCaptcha or FunCaptcha/Arkose, and there is no tool for them.
+**Cause:** The captcha is not a reCAPTCHA. CapSkip supports exactly five types — image captchas, reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest v3, and ALTCHA. It **cannot** solve hCaptcha or FunCaptcha/Arkose, and there is no tool for them.
 
 hCaptcha is easy to misidentify because it also carries a `data-sitekey`:
 

package/docs/TUTORIAL.md

@@ -19,7 +19,8 @@ For each captcha type, four questions in order:
 6. [Turnstile widget](#6-turnstile-widget)
 7. [Turnstile challenge page](#7-turnstile-challenge-page)
 8. [GeeTest v3](#8-geetest-v3)
-9. [Using a proxy](#9-using-a-proxy)
+9. [ALTCHA](#9-altcha)
+10. [Using a proxy](#10-using-a-proxy)
 
 ---
 
@@ -242,9 +243,47 @@ A three-field post-back: `challenge`, `validate`, and `seccode` from the respons
 
 ---
 
-## 9. Using a proxy
+## 9. ALTCHA
 
-Solving through the same IP you will submit from generally improves acceptance for reCAPTCHA, Turnstile, and GeeTest. All three tools accept an optional `proxy` object:
+### How do I recognize this captcha on a page?
+
+An `<altcha-widget>` element, or a checkbox-style control whose container mentions "altcha". Unlike the others there is no sitekey: the widget names a challenge source instead. Read the page source rather than assuming which attribute — v1/v2 widgets use `challengeurl="…"` (with `challengejson="…"` for an inline challenge), while v3+ uses a single `challenge="…"` that takes either a URL or the challenge data.
+
+Some deployments generate the challenge in-page and fetch nothing at all. In that case there is no network request to watch — read the challenge out of the widget.
+
+### What do I pass to the tool?
+
+`url`, plus **one** of:
+
+- `challenge_url` — the endpoint the widget fetches from; CapSkip fetches it for you
+- `challenge_json` — the challenge document itself, as a JSON string; solved locally with no network request
+
+```json
+{
+  "url": "https://example.com/signup",
+  "challenge_url": "https://example.com/captcha/api/altcha/challenge"
+}
+```
+
+Find the endpoint in DevTools → Network: it is the request the widget makes for its challenge, often something like `/altcha/challenge`. Its JSON response is what `challenge_json` would carry.
+
+> **Challenges expire, and the window is short** — some sites inside two minutes. Fetch one immediately before solving and submit the token promptly. An expired challenge is rejected with a bare "verification failed" that looks exactly like a wrong answer, which sends people hunting for a solver bug that is not there.
+
+### Where does the answer go?
+
+A single field. Submit `token` under the name `altcha`, exactly as the widget would:
+
+```
+email=someone%40example.com&altcha=eyJhbGdvcml0aG0iOiJTSEEtMjU2Iiwi...
+```
+
+Do not re-encode, trim or re-order it: the token is base64 of a JSON document whose fields are covered by the server's HMAC signature, so any modification invalidates it. Some integrations read the payload from a JSON body field instead — check what the page's own submit sends and mirror it.
+
+---
+
+## 10. Using a proxy
+
+Solving through the same IP you will submit from generally improves acceptance for reCAPTCHA, Turnstile, and GeeTest. All three tools accept an optional `proxy` object, as does `capskip_solve_altcha` — though there it applies only to the challenge fetch, never to the solve itself:
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capskip-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Captcha solver MCP server for AI agents: solve reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest and image captchas via CapSkip, a local unlimited captcha solver with no per-solve fees.",
   "main": "./dist/server.js",
   "exports": {
@@ -33,7 +33,7 @@
   "files": ["dist", "docs", "examples", "CHANGELOG.md", "SECURITY.md"],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "capskip": "^1.1.0",
+    "capskip": "^1.2.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {