capskip-mcp 1.0.0

package/docs/GETTING_STARTED.md

@@ -0,0 +1,161 @@
+# Getting Started
+
+This guide walks you through installing CapSkip, adding `capskip-mcp` to your MCP client, and running your first captcha solve.
+
+---
+
+## Prerequisites
+
+| Requirement | Details |
+|---|---|
+| **CapSkip app** | Windows desktop app from [capskip.com](https://capskip.com) |
+| **Node.js** | 18 or newer (`capskip-mcp` runs via `npx`, no separate install) |
+| **An MCP client** | Claude Desktop, Claude Code, Cursor, or VS Code |
+
+---
+
+## Step 1 — Install and configure CapSkip
+
+1. Download CapSkip from [capskip.com](https://capskip.com).
+2. Install and launch the application. Leave it running in the background — `capskip-mcp` talks to it over `localhost`, so it must be running whenever a tool is called.
+3. Open **Settings** and note:
+   - **Port** — default is `8080`
+   - **API key validation** — if enabled, copy your API key; if disabled, any string (e.g. `capskip`) is accepted
+
+### Verify CapSkip is running
+
+**Windows (PowerShell):**
+
+```powershell
+Invoke-WebRequest "http://127.0.0.1:8080/res.php?key=capskip&action=get&id=0" -UseBasicParsing
+```
+
+**Linux / macOS:**
+
+```bash
+curl "http://127.0.0.1:8080/res.php?key=capskip&action=get&id=0"
+```
+
+Any response — even an error like `ERROR_WRONG_CAPTCHA_ID` — confirms CapSkip is up and listening.
+
+---
+
+## Step 2 — Add capskip-mcp to your client
+
+Every client points at the same command:
+
+```json
+{
+  "mcpServers": {
+    "capskip": {
+      "command": "npx",
+      "args": ["-y", "capskip-mcp"],
+      "env": {
+        "CAPSKIP_HOST": "127.0.0.1",
+        "CAPSKIP_PORT": "8080",
+        "CAPSKIP_API_KEY": "capskip"
+      }
+    }
+  }
+}
+```
+
+Substitute your own port and API key from Step 1. Where that block goes differs per client:
+
+### Claude Desktop
+
+Open **Settings → Developer → Edit Config** (or edit `claude_desktop_config.json` directly — `%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) and paste the block above. Full file: [examples/claude-desktop.json](../examples/claude-desktop.json).
+
+### Claude Code
+
+Add the server from the command line — no config file to edit:
+
+```bash
+claude mcp add capskip -- npx -y capskip-mcp
+```
+
+See [examples/claude-code.md](../examples/claude-code.md) for the custom-port variant and how to confirm it connected.
+
+### Cursor
+
+Paste the block above into `.cursor/mcp.json` (project-level) or your global Cursor MCP settings. Full file: [examples/cursor.json](../examples/cursor.json).
+
+### VS Code
+
+VS Code's MCP config uses `servers` instead of `mcpServers` and an explicit `type`:
+
+```json
+{
+  "servers": {
+    "capskip": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "capskip-mcp"],
+      "env": { "CAPSKIP_PORT": "8080" }
+    }
+  }
+}
+```
+
+Paste this into `.vscode/mcp.json`. Full file: [examples/vscode.json](../examples/vscode.json).
+
+---
+
+## Step 3 — Verify with `capskip_status`
+
+Restart your client, open a new chat, and ask it to call `capskip_status` (no arguments). With CapSkip running on the configured host and port, the tool returns:
+
+```json
+{
+  "reachable": true,
+  "host": "127.0.0.1",
+  "port": 8080,
+  "latencyMs": 6,
+  "detail": "CapSkip answered at 127.0.0.1:8080 in 6ms."
+}
+```
+
+If CapSkip is not running, or the port is wrong, `capskip_status` still returns a normal (non-error) result — it reports the problem rather than failing — with `reachable: false` and a `detail` explaining what to check:
+
+```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."
+}
+```
+
+---
+
+## Step 4 — Your first solve
+
+With CapSkip confirmed reachable, ask your agent to solve a captcha it has encountered while browsing, or try it directly. For a reCAPTCHA v2 widget with sitekey `6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-` on `https://example.com/login`, the agent calls:
+
+```json
+{
+  "sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
+  "url": "https://example.com/login"
+}
+```
+
+against `capskip_solve_recaptcha`, and gets back:
+
+```json
+{
+  "captchaId": "48213",
+  "code": "03AGdBq26f...",
+  "solveSeconds": 9.4
+}
+```
+
+`code` is the token — it goes in the page's `g-recaptcha-response` field before the form is submitted.
+
+---
+
+## Next steps
+
+- [Tutorial](TUTORIAL.md) — every captcha type, end to end
+- [API Reference](API_REFERENCE.md) — every tool, parameter, and return shape
+- [Troubleshooting](TROUBLESHOOTING.md) — fix common errors
+- [CapSkip API docs](https://capskip.com/api-docs/) — the raw HTTP API `capskip-mcp` wraps

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,236 @@
+# Troubleshooting
+
+Common issues when running `capskip-mcp` and how to fix them.
+
+---
+
+## Client shows the server as failed to start
+
+**Symptom:** Claude Desktop / Claude Code / Cursor / VS Code lists `capskip` as errored, crashed, or disconnected, with no useful detail in the UI.
+
+**Cause:** Usually one of: Node.js is missing or too old, `npx` cannot reach the registry, or a config error (bad flag, bad env value) makes the process exit immediately.
+
+**Fix**
+
+1. Confirm Node 18+:
+
+```bash
+node --version
+```
+
+2. Run the server by hand and read stderr directly — this is the fastest way to see the real failure, since MCP clients often swallow it:
+
+```bash
+npx -y capskip-mcp
+```
+
+A healthy start prints one line to stderr and then waits:
+
+```
+capskip-mcp ready (CapSkip at 127.0.0.1:8080)
+```
+
+A config problem exits immediately with a message naming the offending flag or variable, e.g.:
+
+```
+capskip-mcp: CAPSKIP_PORT must be a whole number, got 'abc'.
+```
+
+3. If it hangs with no output at all, the client is probably fine and CapSkip itself is the problem — see the next section.
+
+---
+
+## Every tool says "not reachable"
+
+**Symptom:** A solve fails with:
+
+```
+CapSkip is not reachable at 127.0.0.1:8080. Confirm the CapSkip desktop app is running and that its API port matches this setting (override with CAPSKIP_HOST / CAPSKIP_PORT).
+```
+
+and `capskip_status` reports `reachable: false` with:
+
+```
+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.
+```
+
+**Cause:** The CapSkip desktop app is not running, or its API port does not match the `CAPSKIP_PORT` the server was started with.
+
+**Fix**
+
+1. Launch (or un-minimize) the CapSkip desktop app.
+2. Open CapSkip Settings and confirm the **API port**.
+3. Match it in your client config:
+
+```json
+"env": { "CAPSKIP_HOST": "127.0.0.1", "CAPSKIP_PORT": "8080" }
+```
+
+4. Call `capskip_status` again — it reports `reachable` and a `detail` string without needing CapSkip to solve anything, so it is the fastest way to confirm the fix worked.
+
+---
+
+## "Something is listening … but it did not answer as CapSkip"
+
+**Symptom:** `capskip_status` reports `reachable: false` with:
+
+```
+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.
+```
+
+**Cause:** A different process holds that port. 8080 is a common default for local dev servers, proxies, and admin UIs, so this is easy to hit. CapSkip may not be running at all, or may be running on a different port.
+
+**Fix**
+
+1. Find what actually holds the port:
+
+```bash
+# macOS / Linux
+lsof -i :8080
+
+# Windows
+netstat -ano | findstr :8080
+```
+
+2. Either stop that process, or point the server at CapSkip's real port with `CAPSKIP_PORT`.
+
+Note that `capskip_status` deliberately reports this as **not** reachable. An earlier version treated any HTTP response as success, which meant it could report a healthy CapSkip seconds before a solve failed against the same port.
+
+---
+
+## "CapSkip rejected the API key"
+
+**Symptom:**
+
+```
+CapSkip rejected the API key. Set CAPSKIP_API_KEY to the key shown in CapSkip settings, or disable key validation there.
+```
+
+**Cause:** API key validation is enabled in CapSkip, and either no key was configured or it does not match.
+
+**Fix**
+
+1. Copy the exact key from CapSkip Settings and set it:
+
+```json
+"env": { "CAPSKIP_API_KEY": "your-actual-key" }
+```
+
+2. Or, for local development only, disable API key validation in CapSkip Settings — any string (including the default `capskip`) is then accepted.
+
+`capskip_status` diagnoses this without spending a solve. It reports `reachable: true` — CapSkip is running, the key is what is wrong — with:
+
+```
+CapSkip is running at 127.0.0.1:8080, 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.
+```
+
+---
+
+## Solve times out
+
+**Symptom:**
+
+```
+The solve did not finish within 300.0s. Raise the timeout parameter, or check CapSkip's own queue.
+```
+
+**Cause:** The captcha is taking longer than the configured budget, or CapSkip is stuck on it.
+
+**Fix**
+
+1. Pass a larger `timeout` on the tool call (capped at 600 seconds — a larger value is rejected outright, not silently clamped):
+
+```json
+{ "sitekey": "...", "url": "...", "timeout": 600 }
+```
+
+2. Or raise the default so you do not have to pass it every time. `CAPSKIP_TIMEOUT` covers `capskip_solve_image_captcha`; `CAPSKIP_RECAPTCHA_TIMEOUT` covers the other three tools. These env-level defaults have their own bound (1–3600s), independent of the 600s per-call cap:
+
+```json
+"env": { "CAPSKIP_RECAPTCHA_TIMEOUT": "600" }
+```
+
+3. Check CapSkip's own queue/log in the desktop app — a solve that never finishes is often stuck there, not waiting on the network.
+
+The timeout error also names the CapSkip captcha id when one was assigned, so a solve that completes just after the deadline can still be read back via `res.php` or any CapSkip SDK.
+
+---
+
+## GeeTest always fails
+
+**Symptom:** `capskip_solve_geetest` fails or times out even though `gt` and `challenge` look correct.
+
+**Cause:** `challenge` is single-use and expires in about a minute. A value copied earlier, cached, or reused across two solves is already dead — this is the most common cause of GeeTest failures.
+
+**Fix:** Fetch `gt` and `challenge` from the target page immediately before calling `capskip_solve_geetest`, and on failure fetch a fresh pair rather than retrying the same one:
+
+```json
+{
+  "gt": "81388ea1fc187e0c335c0a8907ff2625",
+  "challenge": "7cf6a8b1a2c34d5e6f7089abcdef0123",
+  "url": "https://example.com/login"
+}
+```
+
+If the site loads GeeTest from a non-default domain, pass it through as `api_server`, e.g. `"api-na.geetest.com"`.
+
+---
+
+## Turnstile token rejected by the site
+
+**Symptom:** `capskip_solve_turnstile` returns a token, but Cloudflare still blocks the submission.
+
+**Cause:** The token was submitted using a different User-Agent than the one CapSkip used to solve it. Cloudflare binds the token to the solving User-Agent and rejects a mismatch.
+
+**Fix:** Use `userAgent` from the tool result as the `User-Agent` header (or equivalent setting in your browser-automation tool) when you submit `cf-turnstile-response`. If the result has no `userAgent`, CapSkip did not return one for that solve — retry, since resubmitting under an arbitrary User-Agent will not work either.
+
+---
+
+## hCaptcha or FunCaptcha never solves
+
+**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.
+
+hCaptcha is easy to misidentify because it also carries a `data-sitekey`:
+
+```html
+<div class="h-captcha" data-sitekey="10000000-ffff-ffff-ffff-000000000001"></div>
+```
+
+**Fix:** Check the widget's class or script source before choosing a tool.
+
+| Markup | Type | Tool |
+|---|---|---|
+| `class="g-recaptcha"`, `www.google.com/recaptcha/` | reCAPTCHA v2/v3 | `capskip_solve_recaptcha` |
+| `class="cf-turnstile"`, `challenges.cloudflare.com` | Turnstile | `capskip_solve_turnstile` |
+| `gt=` / `challenge=` from a GeeTest init call | GeeTest v3 | `capskip_solve_geetest` |
+| `class="h-captcha"`, `js.hcaptcha.com` | hCaptcha | **not supported** |
+| `funcaptcha` / `arkoselabs.com` | FunCaptcha/Arkose | **not supported** |
+
+The server tells connected models this in its instructions, but a model can still guess wrong from the DOM alone. Retrying will not help — the type is the problem.
+
+---
+
+## reCAPTCHA v3 accepted but the site still blocks
+
+**Symptom:** `capskip_solve_recaptcha` returns a token, the site's own verification accepts it, but the site still treats the visit as suspicious (blocks, challenges, or degrades the experience).
+
+**Cause:** reCAPTCHA v3 is score-based. Google assigns the score from signals CapSkip has no access to — device and browsing history, IP reputation, and so on — and a locally-solved token carries whatever score Google decided. No solver, local or cloud, can raise a score after the token is issued. This is also why there is no `min_score` parameter on `capskip_solve_recaptcha`.
+
+**Fix:** There isn't one at the token level. If the target consistently scores low, that is a signal problem with the requesting environment (IP reputation, browser fingerprint, request pattern), not something a solver call can override.
+
+---
+
+## Still stuck?
+
+1. [CapSkip API docs](https://capskip.com/api-docs/)
+2. [GitHub Issues](https://github.com/capskip/capskip-mcp/issues)
+3. CapSkip support: support@capskip.com
+
+When opening an issue, include:
+
+- Node.js version (`node --version`)
+- `capskip-mcp` version (from `package.json`, or `npx -y capskip-mcp@latest` to confirm you're current)
+- CapSkip port and the captcha type involved
+- The exact tool call and the full error text (redact sitekeys, tokens, and API keys)

package/docs/TUTORIAL.md

@@ -0,0 +1,284 @@
+# CapSkip MCP Server — Complete Tutorial
+
+This tutorial takes you from zero to solving every captcha type CapSkip supports, one page-recognition pattern at a time. Work through it top to bottom, or jump to the section you need.
+
+For each captcha type, four questions in order:
+
+1. **How do I recognize this captcha on a page?**
+2. **What do I read off the page?**
+3. **What call do I make?**
+4. **Where does the answer go?**
+
+**Contents**
+
+1. [Image captcha](#1-image-captcha)
+2. [reCAPTCHA v2](#2-recaptcha-v2)
+3. [reCAPTCHA v2 Invisible](#3-recaptcha-v2-invisible)
+4. [reCAPTCHA v2 Enterprise](#4-recaptcha-v2-enterprise)
+5. [reCAPTCHA v3](#5-recaptcha-v3)
+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)
+
+---
+
+## 1. Image captcha
+
+### How do I recognize this captcha on a page?
+
+A plain `<img>` element showing distorted, wavy, or noisy text, almost always sitting next to a text input for the answer. There is no JavaScript widget, no sitekey, and no site-key attribute to find — the whole captcha is the image.
+
+### What do I read off the page?
+
+The image itself — its `src` URL, or the raw bytes if it is served inline. Nothing else is needed; there is no sitekey or page URL requirement for this tool.
+
+### What call do I make?
+
+```json
+{
+  "image": "https://example.com/captcha.png"
+}
+```
+
+`image` also accepts a local file path, a `data:` URI, or a raw base64 string — the tool auto-detects which form was passed.
+
+### Where does the answer go?
+
+`code` is the recognized text. Type it into the adjacent text input and submit the form.
+
+---
+
+## 2. reCAPTCHA v2
+
+### How do I recognize this captcha on a page?
+
+The classic "I'm not a robot" checkbox: a `<div class="g-recaptcha" data-sitekey="...">`, or a call to `grecaptcha.render(container, { sitekey: '...' })` in the page's scripts. The widget iframe's `src` also carries the sitekey and `size` query parameters.
+
+### What do I read off the page?
+
+The `data-sitekey` attribute (or the `sitekey` field of the JS config object), and the full URL of the page the widget is on.
+
+### What call do I make?
+
+```json
+{
+  "sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
+  "url": "https://example.com/login"
+}
+```
+
+`version` defaults to `v2`, so it can be omitted for a standard checkbox widget.
+
+### Where does the answer go?
+
+`code` is the `g-recaptcha-response` token. reCAPTCHA's own widget normally creates a hidden `textarea` with that `name` for you to populate — set its value to `code`, then submit the form (or invoke the page's `data-callback`, if it uses one, with the token).
+
+---
+
+## 3. reCAPTCHA v2 Invisible
+
+### How do I recognize this captcha on a page?
+
+No visible checkbox. Instead, `data-size="invisible"` on the `.g-recaptcha` div, `grecaptcha.render(..., { size: 'invisible' })` in script, or `size=invisible` in the widget iframe's `src` URL. The captcha typically fires when a form is submitted or a button is clicked, rather than presenting anything to click beforehand.
+
+### What do I read off the page?
+
+The same `data-sitekey` as a standard v2 widget, plus the fact that it is invisible.
+
+### What call do I make?
+
+```json
+{
+  "sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
+  "url": "https://example.com/login",
+  "invisible": true
+}
+```
+
+### Where does the answer go?
+
+Same as standard v2 — `code` goes in the `g-recaptcha-response` field. Because invisible widgets are usually wired to a `data-callback`, you may also need to invoke that callback with the token to unblock the page's own submit logic.
+
+---
+
+## 4. reCAPTCHA v2 Enterprise
+
+### How do I recognize this captcha on a page?
+
+The page loads `https://www.google.com/recaptcha/enterprise.js` instead of the standard `api.js`, or calls `grecaptcha.enterprise.render(...)`. The loader script URL is the reliable signal — sitekey formatting alone does not distinguish Enterprise from standard reCAPTCHA.
+
+### What do I read off the page?
+
+The `data-sitekey` as usual, and the fact that it is served via the Enterprise loader.
+
+### What call do I make?
+
+```json
+{
+  "sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
+  "url": "https://example.com/login",
+  "enterprise": true
+}
+```
+
+`enterprise` works with either `version`, so it also applies to Enterprise v3 (Section 5).
+
+### Where does the answer go?
+
+Same as the non-Enterprise variant of whichever version you set — `g-recaptcha-response` for v2 Enterprise, or wherever the page's own JS reads the resolved token for v3 Enterprise.
+
+---
+
+## 5. reCAPTCHA v3
+
+### How do I recognize this captcha on a page?
+
+No visible widget at all — at most a small badge in a page corner reading "protected by reCAPTCHA". Look in the page's scripts for `<script src=".../api.js?render=SITEKEY">` and a call to `grecaptcha.execute(sitekey, { action: '...' })`.
+
+### What do I read off the page?
+
+The sitekey from the `render=` query parameter (or the first argument to `grecaptcha.execute`), and the exact `action` string passed as `grecaptcha.execute`'s second argument — it must match what the call site sends.
+
+### What call do I make?
+
+```json
+{
+  "sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
+  "url": "https://example.com/login",
+  "version": "v3",
+  "action": "submit"
+}
+```
+
+### Where does the answer go?
+
+v3 has no fixed field name the way v2 does. The page's own JavaScript normally calls `grecaptcha.execute(...).then(token => ...)` and does something specific with the result — sets a hidden input, or sends it via `fetch`/XHR. Read what the page does with its own resolved token and do the same with `code`.
+
+Because the score behind this token is assigned entirely by Google from signals CapSkip cannot see, there is no `min_score` parameter to request a higher one — see [Using a proxy](#9-using-a-proxy) below and [Troubleshooting](TROUBLESHOOTING.md#recaptcha-v3-accepted-but-the-site-still-blocks) if a v3 token is accepted but the site still treats the request as suspicious.
+
+---
+
+## 6. Turnstile widget
+
+### How do I recognize this captcha on a page?
+
+An element with class `cf-turnstile` and a `data-sitekey` attribute, or a call to `turnstile.render(container, { sitekey })`. Rendered inline in a form, usually as a small "Verify you are human" checkbox or spinner.
+
+### What do I read off the page?
+
+`data-sitekey`, the page URL, and `data-action` if the page sets one.
+
+### What call do I make?
+
+```json
+{
+  "sitekey": "0x4AAAAAAA...",
+  "url": "https://example.com"
+}
+```
+
+### Where does the answer go?
+
+`code` goes in a hidden input named `cf-turnstile-response` (Turnstile creates this for you inside the widget). **Submit it with the returned `userAgent` as the request's User-Agent** — Cloudflare binds the token to the solving User-Agent and rejects a mismatch.
+
+---
+
+## 7. Turnstile challenge page
+
+### How do I recognize this captcha on a page?
+
+A full-page Cloudflare interstitial — "Checking your browser...", "Verifying you are human..." — served instead of the page you requested, rather than a widget embedded in a form you're filling out.
+
+### What do I read off the page?
+
+The sitekey as usual, plus `cData` and `chlPageData` values embedded in the page's inline script or a JSON config blob (field names and exact location vary by Cloudflare's challenge version — search the page source for `cData` and `chlPageData`).
+
+### What call do I make?
+
+```json
+{
+  "sitekey": "0x4AAAAAAA...",
+  "url": "https://example.com/challenge",
+  "action": "managed",
+  "cdata": "0=abc123...",
+  "pagedata": "3fH...pagedata"
+}
+```
+
+### Where does the answer go?
+
+Same `cf-turnstile-response` field as the widget case, submitted with the returned `userAgent`. Challenge pages are checked at least as strictly as embedded widgets — a mismatched User-Agent here is the most common way a correct-looking token still gets rejected.
+
+---
+
+## 8. GeeTest v3
+
+### How do I recognize this captcha on a page?
+
+A slide-puzzle widget, typically inside a container whose id or class mentions "geetest", or a call to `initGeetest({ gt, challenge, ... }, callback)` in the page's scripts.
+
+### What do I read off the page?
+
+Unlike a sitekey, `gt` and `challenge` are not static page attributes — the page itself fetches them from an endpoint (often something like `.../register.php` or a `gettype`/`get.php` request) that returns `{"gt": "...", "challenge": "..."}`. Find that request in DevTools → Network, or read the values out of the `initGeetest({ gt, challenge })` call after the page has run it.
+
+**`gt` and `challenge` must be fetched immediately before solving.** `gt` is static per site and can be reused, but `challenge` is single-use and expires in about a minute — a value copied earlier or cached is already dead by the time you call the tool.
+
+### What call do I make?
+
+```json
+{
+  "gt": "81388ea1fc187e0c335c0a8907ff2625",
+  "challenge": "7cf6a8b1a2c34d5e6f7089abcdef0123",
+  "url": "https://example.com/login"
+}
+```
+
+If the site loads GeeTest from a non-default domain, add `api_server`, e.g. `"api-na.geetest.com"`.
+
+### Where does the answer go?
+
+A three-field post-back: `challenge`, `validate`, and `seccode` from the response map to `geetest_challenge`, `geetest_validate`, and `geetest_seccode` respectively, submitted under those exact names exactly as the site's own front-end would. Sending only `validate` is the most common reason an otherwise-correct solve is rejected — all three fields are required.
+
+---
+
+## 9. 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:
+
+```json
+{
+  "sitekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
+  "url": "https://example.com/login",
+  "proxy": { "type": "HTTPS", "uri": "user:pass@1.2.3.4:3128" }
+}
+```
+
+```json
+{
+  "sitekey": "0x4AAAAAAA...",
+  "url": "https://example.com",
+  "proxy": { "type": "HTTP", "uri": "1.2.3.4:3128" }
+}
+```
+
+```json
+{
+  "gt": "81388ea1fc187e0c335c0a8907ff2625",
+  "challenge": "7cf6a8b1a2c34d5e6f7089abcdef0123",
+  "url": "https://example.com/login",
+  "proxy": { "type": "SOCKS5", "uri": "1.2.3.4:1080" }
+}
+```
+
+`type` must be one of `HTTP`, `HTTPS`, `SOCKS5`, or `SOCKS5H` — CapSkip maps only these four, and anything else (including `SOCKS4`) is rejected. `uri` may be a bare `host:port` or carry credentials as `login:password@host:port`.
+
+**`capskip_solve_image_captcha` does not accept a `proxy` argument.** CapSkip does not support proxying image-captcha solves, and passing one is rejected as an unrecognized key rather than silently ignored.
+
+---
+
+### Where to go next
+
+- [API Reference](API_REFERENCE.md) — every tool, parameter, and return shape
+- [Getting Started](GETTING_STARTED.md) — installation and client setup
+- [Troubleshooting](TROUBLESHOOTING.md) — fixes for common errors

package/examples/claude-code.md

@@ -0,0 +1,19 @@
+# Claude Code
+
+Add the server from the command line:
+
+```bash
+claude mcp add capskip -- npx -y capskip-mcp
+```
+
+With a custom port:
+
+```bash
+claude mcp add capskip --env CAPSKIP_PORT=9000 -- npx -y capskip-mcp
+```
+
+Confirm it is connected:
+
+```bash
+claude mcp list
+```