capskip-mcp 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing yet. Add entries here as changes land; they move into a version
+section at release time.
+
+## [1.0.0] - 2026-08-09
+
+### Added
+
+- `capskip_status` — check that the CapSkip desktop app is running and reachable.
+- `capskip_solve_image_captcha` — read the text from a distorted-text captcha.
+- `capskip_solve_recaptcha` — reCAPTCHA v2 and v3, including invisible and Enterprise.
+- `capskip_solve_turnstile` — Cloudflare Turnstile widgets and challenge pages,
+  returning the User-Agent the token must be submitted with.
+- `capskip_solve_geetest` — GeeTest v3 sliders, returning `geetest_challenge`,
+  `geetest_validate`, and `geetest_seccode`.
+- Progress notifications during long solves, so MCP clients do not time out.
+- Configuration via `CAPSKIP_*` environment variables or CLI flags.
+
+[Unreleased]: https://github.com/capskip/capskip-mcp/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/capskip/capskip-mcp/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CapSkip
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# CapSkip MCP Server — Unlimited Captcha Solver for AI Agents
+
+[![Node.js 18+](https://img.shields.io/badge/node-18%2B-brightgreen.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![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.**
+
+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.
+
+```bash
+npx -y capskip-mcp
+```
+
+---
+
+## What this solves
+
+An AI agent driving a browser hits a captcha and stops. This server gives it five tools so it can read the sitekey, solve the challenge, and carry on — without a human stepping in and without a per-solve API bill.
+
+CapSkip runs as a desktop app exposing a captcha-solving HTTP API on `127.0.0.1:8080`. `capskip-mcp` is a thin translation layer over that API: the fifth official CapSkip client, alongside the [Python](https://github.com/capskip/capskip-python), [Node.js](https://github.com/capskip/capskip-node), [PHP](https://github.com/capskip/capskip-php) and [.NET](https://github.com/capskip/capskip-dotnet) SDKs.
+
+## Supported captcha types
+
+| Captcha | Tool | Notes |
+|---|---|---|
+| **reCAPTCHA v2 solver** (checkbox) | `capskip_solve_recaptcha` | Returns a `g-recaptcha-response` token |
+| **reCAPTCHA v2 invisible solver** | `capskip_solve_recaptcha` | Pass `invisible: true` |
+| **reCAPTCHA Enterprise solver** | `capskip_solve_recaptcha` | Pass `enterprise: true`, works with v2 and v3 |
+| **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 |
+| **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.
+
+Try them against live widgets on the [captcha demo pages](https://capskip.com/captcha-demo/).
+
+---
+
+## Quick start (5 minutes)
+
+### 1. Install the CapSkip captcha solver
+
+Download and run the CapSkip desktop app from [capskip.com](https://capskip.com). Leave it running in the background.
+
+In CapSkip settings, note the **API port** (default `8080`) and **API key** (optional — if key validation is disabled, any string works).
+
+### 2. Add capskip-mcp to your MCP client
+
+No install step — `npx` fetches and runs it on demand.
+
+```json
+{
+  "mcpServers": {
+    "capskip": {
+      "command": "npx",
+      "args": ["-y", "capskip-mcp"],
+      "env": {
+        "CAPSKIP_HOST": "127.0.0.1",
+        "CAPSKIP_PORT": "8080",
+        "CAPSKIP_API_KEY": "capskip"
+      }
+    }
+  }
+}
+```
+
+| MCP client | Config file | Example |
+|---|---|---|
+| Claude Desktop | `claude_desktop_config.json` | [examples/claude-desktop.json](examples/claude-desktop.json) |
+| Claude Code | `claude mcp add` (CLI) | [examples/claude-code.md](examples/claude-code.md) |
+| Cursor | `.cursor/mcp.json` | [examples/cursor.json](examples/cursor.json) |
+| VS Code | `.vscode/mcp.json` | [examples/vscode.json](examples/vscode.json) |
+
+### 3. Restart your client
+
+It should list five tools, all prefixed `capskip_`.
+
+### 4. Ask your agent to solve a captcha
+
+> "Call capskip_status to confirm CapSkip is running, then solve the reCAPTCHA on this page and submit the form."
+
+The agent reads the sitekey off the page, calls `capskip_solve_recaptcha`, and places the returned token in the page's `g-recaptcha-response` field.
+
+---
+
+## Why a local captcha solver
+
+Cloud captcha APIs bill per solve, so an agent that retries is an agent that costs money, and every page URL and sitekey you solve leaves your network.
+
+CapSkip runs on your machine:
+
+- **Unlimited captcha solving** — licensed once, no per-solve fees, no credit balance to top up
+- **Local by default** — the solver talks to `127.0.0.1`; nothing is proxied through a third-party queue
+- **No rate limit per key** — throughput is bounded by your machine, not a vendor's plan tier
+- **Fast** — image captchas return in well under a second; typical reCAPTCHA v2 solves land in 30–45s
+
+### Using an existing 2captcha or Anti-Captcha integration?
+
+CapSkip exposes the familiar `in.php` / `res.php` endpoints, so it works as a **2captcha API alternative** — point your existing client at `127.0.0.1:8080` and keep your code. See the [migration notes](https://capskip.com/2captcha-api-alternative/). This MCP server is the equivalent for AI agents rather than scripts.
+
+---
+
+## Tools
+
+| Tool | Purpose | Required arguments |
+|---|---|---|
+| `capskip_status` | Check whether the CapSkip desktop app is running and reachable | none |
+| `capskip_solve_image_captcha` | Read the text out of a distorted-text captcha image | `image` |
+| `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` |
+
+> **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.
+
+Full parameter tables and worked examples: [API Reference](docs/API_REFERENCE.md).
+
+| Guide | Description |
+|---|---|
+| [Tutorial](docs/TUTORIAL.md) | Every captcha type — how to recognize it, what to read off the page, what call to make, where the answer goes |
+| [Getting Started](docs/GETTING_STARTED.md) | Full setup: CapSkip app, client config, first solve |
+| [API Reference](docs/API_REFERENCE.md) | Every tool, parameter, and return shape |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Connection errors, timeouts, rejected tokens |
+
+---
+
+## Browser automation: Playwright, Puppeteer and Selenium
+
+This server solves the captcha and hands back a token; your agent's existing browser tooling does the driving. The pattern is the same whichever you use:
+
+1. Read the sitekey from the page (`data-sitekey`, or the widget's config object).
+2. Call the matching `capskip_solve_*` tool with that sitekey and the page URL.
+3. Write the token into the response field and submit.
+
+```js
+// The agent does this via its browser tool after capskip_solve_recaptcha returns
+document.querySelector('#g-recaptcha-response').value = TOKEN;
+```
+
+For non-agent scripts, use the language SDKs directly — see the [Playwright](https://capskip.com/playwright-captcha-solver/), [Puppeteer](https://capskip.com/puppeteer-captcha-solver/) and [Selenium](https://capskip.com/selenium-captcha-solver/) guides.
+
+---
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `CAPSKIP_API_KEY` | `capskip` | Any string when key validation is off |
+| `CAPSKIP_HOST` | `127.0.0.1` | CapSkip host |
+| `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 |
+| `CAPSKIP_POLLING_INTERVAL` | `5` | Max seconds between polls |
+
+CLI flags override environment variables, which override the defaults:
+
+```
+capskip-mcp --api-key <key> --host <host> --port <port> --timeout <seconds> \
+            --recaptcha-timeout <seconds> --polling-interval <seconds>
+```
+
+An invalid value (non-numeric port, port outside 1–65535, a negative or out-of-range timeout, an unknown flag) fails at startup naming the offending flag or variable, rather than surfacing later as a confusing solve failure.
+
+---
+
+## What you get back
+
+Every solve tool returns a human-readable text block and `structuredContent` matching its declared output schema:
+
+```json
+{
+  "captchaId": "12345",
+  "code": "03AGdBq26f...",
+  "solveSeconds": 11.8
+}
+```
+
+- **`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.
+
+Long solves emit MCP progress notifications, so a 45-second reCAPTCHA does not trip your client's tool-call timeout.
+
+---
+
+## Errors
+
+Every tool call returns `isError: true` with readable text on failure — never a stack trace or a bare protocol error — so the model can read the message and correct course.
+
+| Cause | Message |
+|---|---|
+| CapSkip unreachable | `CapSkip is not reachable at <host>:<port>. Confirm the CapSkip desktop app is running and that its API port matches this setting (override with CAPSKIP_HOST / CAPSKIP_PORT).` |
+| Another process holds the port | `Something is listening on <host>:<port> but it did not answer as CapSkip (HTTP <code>). Check the API port in CapSkip settings, and that nothing else has taken that port — override with CAPSKIP_HOST / CAPSKIP_PORT.` |
+| Wrong API key | `CapSkip rejected the API key. Set CAPSKIP_API_KEY to the key shown in CapSkip settings, or disable key validation there.` |
+| `ERROR_CAPTCHA_UNSOLVABLE` | `CapSkip could not solve this captcha. Fetch a fresh sitekey or challenge from the page and try again.` |
+| `ERROR_GOOGLEKEY` | `CapSkip rejected the sitekey. Re-read data-sitekey from the page and retry.` |
+| `ERROR_PAGEURL` | `CapSkip rejected the url. Pass the full page URL, including its scheme.` |
+| `ERROR_INVALID_IMAGE` | `CapSkip could not read that image. Check the file is a valid, uncorrupted PNG or JPEG.` |
+| `ERROR_BAD_PARAMETERS` | `CapSkip rejected the parameters for this captcha type. Re-check the values supplied.` |
+| Solve exceeded `timeout` | `The solve did not finish within <elapsed>s. Raise the timeout parameter, or check CapSkip's own queue.` — plus the captcha id when one was assigned |
+| Unknown or misspelled parameter | Rejected before the call reaches CapSkip, naming the key, e.g. `Unrecognized key: "min_score"` |
+
+See [Troubleshooting](docs/TROUBLESHOOTING.md) for fixes.
+
+---
+
+## FAQ
+
+### Can AI agents solve captchas?
+
+Not on their own — a model cannot produce a valid reCAPTCHA or Turnstile token. It needs a solver. This MCP server connects your agent to CapSkip so it can request a real token and continue the task.
+
+### Does this work with Claude, Cursor and VS Code?
+
+Yes. It is a standard MCP stdio server, so it works with any Model Context Protocol client, including Claude Desktop, Claude Code, Cursor and VS Code. Config examples for each are in [examples/](examples/).
+
+### Is there a free captcha solver here?
+
+The MCP server is MIT-licensed and free. It requires the CapSkip desktop app, which is licensed once and then solves without per-solve charges — unlike cloud APIs that bill per captcha.
+
+### 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.
+
+### 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.
+
+### Does it need my captcha to be on a public page?
+
+Yes for widget captchas — CapSkip loads the page URL you pass. Image captchas need only the image, which can be a local file.
+
+### Can I use it with Playwright or Puppeteer?
+
+Yes. The agent drives the browser; this server supplies the token. See the [browser automation section](#browser-automation-playwright-puppeteer-and-selenium).
+
+---
+
+## Requirements
+
+- Node.js 18 or newer
+- The CapSkip desktop app installed and running ([download](https://capskip.com))
+
+## Links
+
+- [CapSkip — unlimited captcha solver](https://capskip.com)
+- [Captcha demo pages](https://capskip.com/captcha-demo/) — live reCAPTCHA, Turnstile, GeeTest and image widgets
+- [HTTP API docs](https://capskip.com/api-docs/)
+- SDKs: [Python](https://github.com/capskip/capskip-python) · [Node.js](https://github.com/capskip/capskip-node) · [PHP](https://github.com/capskip/capskip-php) · [.NET](https://github.com/capskip/capskip-dotnet)
+- [Report an issue](https://github.com/capskip/capskip-mcp/issues)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| 1.0.x | Yes |
+
+## Reporting a vulnerability
+
+If you discover a security vulnerability in the CapSkip MCP server, please report it responsibly.
+
+**Do not** open a public GitHub issue for security vulnerabilities.
+
+Instead, email **support@capskip.com** with:
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+We aim to acknowledge reports within 48 hours and provide a status update within 7 days.
+
+## Scope
+
+This policy covers the `capskip-mcp` npm package in this repository.
+
+The CapSkip desktop application itself is maintained separately — report app-level issues to CapSkip support.
+
+## Best practices for running this server
+
+- Configure `CAPSKIP_API_KEY` through your MCP client's `env` block, not by hard-coding it into a committed config file
+- Client configuration files (`claude_desktop_config.json`, `.mcp.json`, `.vscode/mcp.json`) often live in a repository — keep API keys and proxy credentials out of them
+- CapSkip runs locally — ensure your firewall rules match your security requirements
+- When using proxies, avoid logging credentials in application logs

package/dist/config.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigError = void 0;
+exports.resolveConfig = resolveConfig;
+/** Thrown at startup when a setting is missing or malformed. */
+class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+exports.ConfigError = ConfigError;
+// CLI flag -> [config key, env var name]. The env name is carried so an
+// invalid value can be reported under whichever spelling the user actually
+// supplied.
+const NUMERIC = {
+    '--port': ['port', 'CAPSKIP_PORT'],
+    '--timeout': ['defaultTimeout', 'CAPSKIP_TIMEOUT'],
+    '--recaptcha-timeout': ['recaptchaTimeout', 'CAPSKIP_RECAPTCHA_TIMEOUT'],
+    '--polling-interval': ['pollingInterval', 'CAPSKIP_POLLING_INTERVAL'],
+};
+const STRING = {
+    '--api-key': ['apiKey', 'CAPSKIP_API_KEY'],
+    '--host': ['host', 'CAPSKIP_HOST'],
+};
+function parseArgv(argv) {
+    const known = new Set([...Object.keys(NUMERIC), ...Object.keys(STRING)]);
+    const out = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            throw new ConfigError(`Unexpected argument '${arg}'.`);
+        }
+        const eq = arg.indexOf('=');
+        const flag = eq === -1 ? arg : arg.slice(0, eq);
+        if (!known.has(flag)) {
+            throw new ConfigError(`Unknown option '${flag}'. Supported: ${[...known].sort().join(', ')}.`);
+        }
+        if (eq !== -1) {
+            out[flag] = arg.slice(eq + 1);
+            continue;
+        }
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('--')) {
+            throw new ConfigError(`Option '${flag}' requires a value.`);
+        }
+        out[flag] = value;
+        i += 1;
+    }
+    return out;
+}
+function readNumber(raw, label, min, max) {
+    const value = Number(raw);
+    if (!Number.isInteger(value)) {
+        throw new ConfigError(`${label} must be a whole number, got '${raw}'.`);
+    }
+    if (value < min || value > max) {
+        throw new ConfigError(`${label} must be between ${min} and ${max}, got ${value}.`);
+    }
+    return value;
+}
+/** CLI flags beat environment variables, which beat defaults. */
+function resolveConfig(argv, env) {
+    const flags = parseArgv(argv);
+    const config = {
+        apiKey: 'capskip',
+        host: '127.0.0.1',
+        port: 8080,
+        defaultTimeout: 120,
+        recaptchaTimeout: 300,
+        pollingInterval: 5,
+    };
+    for (const [flag, [key, envName]] of Object.entries(STRING)) {
+        const raw = flags[flag] ?? env[envName];
+        if (raw !== undefined && raw !== '') {
+            config[key] = raw;
+        }
+    }
+    const bounds = {
+        port: [1, 65535],
+        defaultTimeout: [1, 3600],
+        recaptchaTimeout: [1, 3600],
+        pollingInterval: [1, 60],
+    };
+    for (const [flag, [key, envName]] of Object.entries(NUMERIC)) {
+        const fromFlag = flags[flag];
+        const raw = fromFlag ?? env[envName];
+        if (raw === undefined || raw === '') {
+            continue;
+        }
+        const label = fromFlag !== undefined ? flag : envName;
+        const [min, max] = bounds[key];
+        config[key] = readNumber(raw, label, min, max);
+    }
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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","sourcesContent":["/** Resolved CapSkip connection and polling settings. */\nexport interface CapSkipConfig {\n  apiKey: string;\n  host: string;\n  port: number;\n  defaultTimeout: number;\n  recaptchaTimeout: number;\n  pollingInterval: number;\n}\n\n/** Thrown at startup when a setting is missing or malformed. */\nexport class ConfigError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'ConfigError';\n  }\n}\n\n// CLI flag -> [config key, env var name]. The env name is carried so an\n// invalid value can be reported under whichever spelling the user actually\n// supplied.\nconst NUMERIC = {\n  '--port': ['port', 'CAPSKIP_PORT'],\n  '--timeout': ['defaultTimeout', 'CAPSKIP_TIMEOUT'],\n  '--recaptcha-timeout': ['recaptchaTimeout', 'CAPSKIP_RECAPTCHA_TIMEOUT'],\n  '--polling-interval': ['pollingInterval', 'CAPSKIP_POLLING_INTERVAL'],\n} as const;\n\nconst STRING = {\n  '--api-key': ['apiKey', 'CAPSKIP_API_KEY'],\n  '--host': ['host', 'CAPSKIP_HOST'],\n} as const;\n\nfunction parseArgv(argv: string[]): Record<string, string> {\n  const known = new Set([...Object.keys(NUMERIC), ...Object.keys(STRING)]);\n  const out: Record<string, string> = {};\n\n  for (let i = 0; i < argv.length; i += 1) {\n    const arg = argv[i];\n    if (!arg.startsWith('--')) {\n      throw new ConfigError(`Unexpected argument '${arg}'.`);\n    }\n\n    const eq = arg.indexOf('=');\n    const flag = eq === -1 ? arg : arg.slice(0, eq);\n\n    if (!known.has(flag)) {\n      throw new ConfigError(\n        `Unknown option '${flag}'. Supported: ${[...known].sort().join(', ')}.`,\n      );\n    }\n\n    if (eq !== -1) {\n      out[flag] = arg.slice(eq + 1);\n      continue;\n    }\n\n    const value = argv[i + 1];\n    if (value === undefined || value.startsWith('--')) {\n      throw new ConfigError(`Option '${flag}' requires a value.`);\n    }\n    out[flag] = value;\n    i += 1;\n  }\n\n  return out;\n}\n\nfunction readNumber(raw: string, label: string, min: number, max: number): number {\n  const value = Number(raw);\n  if (!Number.isInteger(value)) {\n    throw new ConfigError(`${label} must be a whole number, got '${raw}'.`);\n  }\n  if (value < min || value > max) {\n    throw new ConfigError(`${label} must be between ${min} and ${max}, got ${value}.`);\n  }\n  return value;\n}\n\n/** CLI flags beat environment variables, which beat defaults. */\nexport function resolveConfig(argv: string[], env: NodeJS.ProcessEnv): CapSkipConfig {\n  const flags = parseArgv(argv);\n\n  const config: CapSkipConfig = {\n    apiKey: 'capskip',\n    host: '127.0.0.1',\n    port: 8080,\n    defaultTimeout: 120,\n    recaptchaTimeout: 300,\n    pollingInterval: 5,\n  };\n\n  for (const [flag, [key, envName]] of Object.entries(STRING)) {\n    const raw = flags[flag] ?? env[envName];\n    if (raw !== undefined && raw !== '') {\n      config[key] = raw;\n    }\n  }\n\n  const bounds: Record<string, [number, number]> = {\n    port: [1, 65535],\n    defaultTimeout: [1, 3600],\n    recaptchaTimeout: [1, 3600],\n    pollingInterval: [1, 60],\n  };\n\n  for (const [flag, [key, envName]] of Object.entries(NUMERIC)) {\n    const fromFlag = flags[flag];\n    const raw = fromFlag ?? env[envName];\n    if (raw === undefined || raw === '') {\n      continue;\n    }\n    const label = fromFlag !== undefined ? flag : envName;\n    const [min, max] = bounds[key];\n    config[key] = readNumber(raw, label, min, max);\n  }\n\n  return config;\n}\n"]}

package/dist/errors.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolError = toolError;
+exports.mapError = mapError;
+const capskip_1 = require("capskip");
+/** Build a tool result the model can read and act on. */
+function toolError(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+function messageOf(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
+// CapSkip surfaces API failures as an error code inside the exception message.
+const API_CODES = [
+    [
+        /ERROR_(KEY_DOES_NOT_EXIST|WRONG_USER_KEY)/,
+        () => 'CapSkip rejected the API key. Set CAPSKIP_API_KEY to the key shown in '
+            + 'CapSkip settings, or disable key validation there.',
+    ],
+    [
+        /ERROR_CAPTCHA_UNSOLVABLE/,
+        () => 'CapSkip could not solve this captcha. Fetch a fresh sitekey or challenge '
+            + 'from the page and try again.',
+    ],
+    [
+        /ERROR_GOOGLEKEY/,
+        () => 'CapSkip rejected the sitekey. Re-read data-sitekey from the page and retry.',
+    ],
+    [
+        /ERROR_PAGEURL/,
+        () => 'CapSkip rejected the url. Pass the full page URL, including its scheme.',
+    ],
+    [
+        /ERROR_INVALID_IMAGE/,
+        () => 'CapSkip could not read that image. Check the file is a valid, uncorrupted PNG or JPEG.',
+    ],
+    [
+        /ERROR_BAD_PARAMETERS/,
+        () => 'CapSkip rejected the parameters for this captcha type. Re-check the values supplied.',
+    ],
+];
+function unreachable(ctx) {
+    return (`CapSkip is not reachable at ${ctx.host}:${ctx.port}. Confirm the CapSkip `
+        + 'desktop app is running and that its API port matches this setting '
+        + '(override with CAPSKIP_HOST / CAPSKIP_PORT).');
+}
+// The SDK reports a non-200 from in.php/res.php as `bad response: <code>`.
+// Something *is* listening on that port, so "not reachable" would send the model
+// looking for a process that is already running. This mirrors the wording
+// capskip_status uses for the same situation.
+const BAD_RESPONSE = /bad response: (\d{3})/;
+/**
+ * A connection-level failure, whether the SDK wrapped it or Node raised it raw.
+ * One function so both call sites cannot drift apart.
+ */
+function networkFailure(message, ctx) {
+    const badResponse = BAD_RESPONSE.exec(message);
+    if (badResponse) {
+        return toolError(`Something is listening on ${ctx.host}:${ctx.port} but it did not answer as `
+            + `CapSkip (HTTP ${badResponse[1]}). Check the API port in CapSkip settings, `
+            + 'and that nothing else has taken that port — override with CAPSKIP_HOST / '
+            + 'CAPSKIP_PORT.');
+    }
+    return toolError(`${unreachable(ctx)} (underlying error: ${message})`);
+}
+/** Translate anything thrown during a solve into an actionable tool error. */
+function mapError(err, ctx) {
+    const message = messageOf(err);
+    if (err instanceof capskip_1.TimeoutException) {
+        const elapsed = ctx.elapsedSeconds !== undefined
+            ? `${ctx.elapsedSeconds.toFixed(1)}s`
+            : 'the configured timeout';
+        const id = ctx.captchaId
+            ? ` CapSkip captcha id ${ctx.captchaId} may still complete — it can be read later `
+                + 'via res.php or any CapSkip SDK.'
+            : '';
+        return toolError(`The solve did not finish within ${elapsed}. Raise the timeout parameter, or `
+            + `check CapSkip's own queue.${id}`);
+    }
+    if (err instanceof capskip_1.ApiException) {
+        for (const [pattern, build] of API_CODES) {
+            if (pattern.test(message)) {
+                return toolError(build(ctx));
+            }
+        }
+        return toolError(`CapSkip returned an error: ${message}`);
+    }
+    if (err instanceof capskip_1.NetworkException) {
+        return networkFailure(message, ctx);
+    }
+    if (err instanceof capskip_1.ValidationException) {
+        return toolError(message);
+    }
+    // Connection failures can surface as plain Node errors before the SDK wraps them.
+    if (/ECONNREFUSED|ECONNRESET|EHOSTUNREACH|ETIMEDOUT|ENOTFOUND/.test(message)) {
+        return networkFailure(message, ctx);
+    }
+    return toolError(`Unexpected failure while solving: ${message}`);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';\nimport {\n  ApiException,\n  NetworkException,\n  TimeoutException,\n  ValidationException,\n} from 'capskip';\n\nexport interface ErrorContext {\n  host: string;\n  port: number;\n  captchaId?: string;\n  elapsedSeconds?: number;\n}\n\n/** Build a tool result the model can read and act on. */\nexport function toolError(message: string): CallToolResult {\n  return { content: [{ type: 'text', text: message }], isError: true };\n}\n\nfunction messageOf(err: unknown): string {\n  if (err instanceof Error) {\n    return err.message;\n  }\n  return String(err);\n}\n\n// CapSkip surfaces API failures as an error code inside the exception message.\nconst API_CODES: Array<[RegExp, (ctx: ErrorContext) => string]> = [\n  [\n    /ERROR_(KEY_DOES_NOT_EXIST|WRONG_USER_KEY)/,\n    () =>\n      'CapSkip rejected the API key. Set CAPSKIP_API_KEY to the key shown in '\n      + 'CapSkip settings, or disable key validation there.',\n  ],\n  [\n    /ERROR_CAPTCHA_UNSOLVABLE/,\n    () =>\n      'CapSkip could not solve this captcha. Fetch a fresh sitekey or challenge '\n      + 'from the page and try again.',\n  ],\n  [\n    /ERROR_GOOGLEKEY/,\n    () => 'CapSkip rejected the sitekey. Re-read data-sitekey from the page and retry.',\n  ],\n  [\n    /ERROR_PAGEURL/,\n    () => 'CapSkip rejected the url. Pass the full page URL, including its scheme.',\n  ],\n  [\n    /ERROR_INVALID_IMAGE/,\n    () => 'CapSkip could not read that image. Check the file is a valid, uncorrupted PNG or JPEG.',\n  ],\n  [\n    /ERROR_BAD_PARAMETERS/,\n    () => 'CapSkip rejected the parameters for this captcha type. Re-check the values supplied.',\n  ],\n];\n\nfunction unreachable(ctx: ErrorContext): string {\n  return (\n    `CapSkip is not reachable at ${ctx.host}:${ctx.port}. Confirm the CapSkip `\n    + 'desktop app is running and that its API port matches this setting '\n    + '(override with CAPSKIP_HOST / CAPSKIP_PORT).'\n  );\n}\n\n// The SDK reports a non-200 from in.php/res.php as `bad response: <code>`.\n// Something *is* listening on that port, so \"not reachable\" would send the model\n// looking for a process that is already running. This mirrors the wording\n// capskip_status uses for the same situation.\nconst BAD_RESPONSE = /bad response: (\\d{3})/;\n\n/**\n * A connection-level failure, whether the SDK wrapped it or Node raised it raw.\n * One function so both call sites cannot drift apart.\n */\nfunction networkFailure(message: string, ctx: ErrorContext): CallToolResult {\n  const badResponse = BAD_RESPONSE.exec(message);\n  if (badResponse) {\n    return toolError(\n      `Something is listening on ${ctx.host}:${ctx.port} but it did not answer as `\n      + `CapSkip (HTTP ${badResponse[1]}). Check the API port in CapSkip settings, `\n      + 'and that nothing else has taken that port — override with CAPSKIP_HOST / '\n      + 'CAPSKIP_PORT.',\n    );\n  }\n  return toolError(`${unreachable(ctx)} (underlying error: ${message})`);\n}\n\n/** Translate anything thrown during a solve into an actionable tool error. */\nexport function mapError(err: unknown, ctx: ErrorContext): CallToolResult {\n  const message = messageOf(err);\n\n  if (err instanceof TimeoutException) {\n    const elapsed = ctx.elapsedSeconds !== undefined\n      ? `${ctx.elapsedSeconds.toFixed(1)}s`\n      : 'the configured timeout';\n    const id = ctx.captchaId\n      ? ` CapSkip captcha id ${ctx.captchaId} may still complete — it can be read later `\n        + 'via res.php or any CapSkip SDK.'\n      : '';\n    return toolError(\n      `The solve did not finish within ${elapsed}. Raise the timeout parameter, or `\n      + `check CapSkip's own queue.${id}`,\n    );\n  }\n\n  if (err instanceof ApiException) {\n    for (const [pattern, build] of API_CODES) {\n      if (pattern.test(message)) {\n        return toolError(build(ctx));\n      }\n    }\n    return toolError(`CapSkip returned an error: ${message}`);\n  }\n\n  if (err instanceof NetworkException) {\n    return networkFailure(message, ctx);\n  }\n\n  if (err instanceof ValidationException) {\n    return toolError(message);\n  }\n\n  // Connection failures can surface as plain Node errors before the SDK wraps them.\n  if (/ECONNREFUSED|ECONNRESET|EHOSTUNREACH|ETIMEDOUT|ENOTFOUND/.test(message)) {\n    return networkFailure(message, ctx);\n  }\n\n  return toolError(`Unexpected failure while solving: ${message}`);\n}\n"]}

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const config_js_1 = require("./config.js");
+const server_js_1 = require("./server.js");
+async function main() {
+    let config;
+    try {
+        config = (0, config_js_1.resolveConfig)(process.argv.slice(2), process.env);
+    }
+    catch (err) {
+        if (err instanceof config_js_1.ConfigError) {
+            process.stderr.write(`capskip-mcp: ${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    const server = (0, server_js_1.createServer)(config);
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    // stdout carries protocol traffic only; anything else corrupts the stream.
+    process.stderr.write(`capskip-mcp ready (CapSkip at ${config.host}:${config.port})\n`);
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`capskip-mcp: fatal: ${message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAEA,wEAAiF;AAEjF,2CAAyD;AACzD,2CAA2C;AAE3C,KAAK,UAAU,IAAI;IACjB,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,IAAA,yBAAa,EAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,uBAAW,EAAE,CAAC;YAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;YACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAG,IAAA,wBAAY,EAAC,MAAM,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,2EAA2E;IAC3E,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iCAAiC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,CACjE,CAAC;AACJ,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,OAAO,IAAI,CAAC,CAAC;IACzD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\n\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\n\nimport { ConfigError, resolveConfig } from './config.js';\nimport { createServer } from './server.js';\n\nasync function main(): Promise<void> {\n  let config;\n  try {\n    config = resolveConfig(process.argv.slice(2), process.env);\n  } catch (err) {\n    if (err instanceof ConfigError) {\n      process.stderr.write(`capskip-mcp: ${err.message}\\n`);\n      process.exit(1);\n    }\n    throw err;\n  }\n\n  const server = createServer(config);\n  const transport = new StdioServerTransport();\n  await server.connect(transport);\n\n  // stdout carries protocol traffic only; anything else corrupts the stream.\n  process.stderr.write(\n    `capskip-mcp ready (CapSkip at ${config.host}:${config.port})\\n`,\n  );\n}\n\nmain().catch((err: unknown) => {\n  const message = err instanceof Error ? err.message : String(err);\n  process.stderr.write(`capskip-mcp: fatal: ${message}\\n`);\n  process.exit(1);\n});\n"]}