captchaai-mcp 1.0.0__tar.gz

captchaai_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CaptchaAI (captchaai-developers)
+
+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.

captchaai_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: captchaai-mcp
+Version: 1.0.0
+Summary: Official MCP server for CaptchaAI — expose token-mode CAPTCHA solving to AI agents.
+Keywords: mcp,mcp-server,model-context-protocol,fastmcp,ai-agents,llm,captcha,captchaai,captcha-solver,captcha-solving,captcha-bypass,recaptcha,recaptcha-v2,recaptcha-v3,recaptcha-enterprise,cloudflare-turnstile,turnstile-solver,cloudflare-challenge,geetest,captchafox,friendly-captcha,lemin,automation,web-scraping
+Author: captchaai-developers
+Author-email: captchaai-developers <dev@captchaai.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: captchaai>=1.0.3
+Requires-Dist: fastmcp>=4.1,<5
+Requires-Python: >=3.10
+Project-URL: Homepage, https://captchaai.com/
+Project-URL: Documentation, https://docs.captchaai.com/
+Project-URL: Repository, https://github.com/CaptchaAI/captchaai-mcp
+Project-URL: Issues, https://github.com/CaptchaAI/captchaai-mcp/issues
+Project-URL: Changelog, https://github.com/CaptchaAI/captchaai-mcp/releases
+Description-Content-Type: text/markdown
+
+# CaptchaAI MCP Server
+
+Official Model Context Protocol (MCP) server for [CaptchaAI](https://captchaai.com/), built with [FastMCP](https://gofastmcp.com/) and backed by the official [`captchaai`](https://github.com/CaptchaAI/captchaai-python) Python SDK.
+
+Exposes **token-mode** (pure API, no browser required) tools so AI assistants and automation agents can inspect account capacity, check supported CAPTCHA types, and solve challenges.
+
+- **Website:** https://captchaai.com/
+- **API Documentation:** https://docs.captchaai.com/
+- **MCP Client Integration Guide:** [docs/mcp-integration.md](docs/mcp-integration.md) (Claude Code, OpenAI Codex, Cursor, Claude Desktop, VS Code, Windsurf, Antigravity)
+- **Repository:** https://github.com/CaptchaAI/captchaai-mcp
+
+## Tools
+
+| Tool | Description | API Key Needed |
+|---|---|---|
+| `get_supported_captchas` | List the 8 token-mode CAPTCHA types with required/optional arguments and proxy/UA notes | No |
+| `get_threads` | Get account thread usage (`threads`, `working_threads`, `free_threads`) | Yes |
+| `get_balance` | Get account balance string (`balance`) | Yes |
+| `solve_captcha` | Solve a CAPTCHA in token mode and return `task_id`, `solution`, and `user_agent` | Yes |
+
+## Supported `captcha_type` Values
+
+- `recaptcha_v2` (supports `invisible=True` and `enterprise=True`)
+- `recaptcha_v3` (requires `action`; supports `enterprise=True` and `min_score`)
+- `turnstile`
+- `cloudflare_challenge` (requires `proxy` + `proxytype` (`"HTTP"` or `"HTTPS"`); returns `user_agent`)
+- `geetest` (requires `gt` + `challenge`; returns `{challenge, validate, seccode}`)
+- `captchafox` (requires `proxy` + `proxytype` (`"HTTP"` or `"HTTPS"`); returns `user_agent`)
+- `friendly_captcha`
+- `lemin` (requires `captcha_id` + `div_id`; returns `{answer, challenge_uuid}`)
+
+## Installation
+
+Install directly from PyPI with `pip` or run via `uvx`:
+
+```bash
+pip install captchaai-mcp
+```
+
+Or run from a local clone:
+
+```bash
+git clone https://github.com/CaptchaAI/captchaai-mcp.git
+cd captchaai-mcp
+uv sync
+```
+
+Set your API key:
+
+```bash
+export CAPTCHAAI_API_KEY="YOUR_32_CHAR_API_KEY"
+```
+
+## Running
+
+```bash
+# STDIO (default — for Claude Desktop, Cursor, Windsurf, etc.)
+uvx captchaai-mcp
+# or from source:
+uv run captchaai-mcp
+
+# Streamable HTTP (serves at http://127.0.0.1:8000/mcp)
+uvx captchaai-mcp --transport streamable-http --host 127.0.0.1 --port 8000
+```
+
+> [!NOTE]
+> Prefer `CAPTCHAAI_API_KEY` in the environment over `--api-key` on multi-user hosts so the key is not visible in process listings. When using `--transport streamable-http`, bind to loopback or place it behind an authenticating TLS reverse proxy.
+
+### MCP Client Configuration
+
+See the full **[MCP Client Integration Guide](docs/mcp-integration.md)** for step-by-step setup with **Claude Code**, **OpenAI Codex CLI**, **Cursor**, **Claude Desktop**, **VS Code**, **Windsurf**, and **Antigravity**.
+
+Using `uvx` (recommended):
+
+```json
+{
+  "mcpServers": {
+    "captchaai": {
+      "command": "uvx",
+      "args": ["captchaai-mcp"],
+      "env": {
+        "CAPTCHAAI_API_KEY": "YOUR_32_CHAR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Or from a local checkout:
+
+```json
+{
+  "mcpServers": {
+    "captchaai": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/path/to/captchaai-mcp",
+        "captchaai-mcp"
+      ],
+      "env": {
+        "CAPTCHAAI_API_KEY": "YOUR_32_CHAR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Development & Tests
+
+```bash
+# Run MCP server tests
+uv run pytest -q
+
+# Inspect the MCP server manifest
+uv run fastmcp inspect src/captchaai_mcp/server.py:create_server
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

captchaai_mcp-1.0.0/README.md

@@ -0,0 +1,122 @@
+# CaptchaAI MCP Server
+
+Official Model Context Protocol (MCP) server for [CaptchaAI](https://captchaai.com/), built with [FastMCP](https://gofastmcp.com/) and backed by the official [`captchaai`](https://github.com/CaptchaAI/captchaai-python) Python SDK.
+
+Exposes **token-mode** (pure API, no browser required) tools so AI assistants and automation agents can inspect account capacity, check supported CAPTCHA types, and solve challenges.
+
+- **Website:** https://captchaai.com/
+- **API Documentation:** https://docs.captchaai.com/
+- **MCP Client Integration Guide:** [docs/mcp-integration.md](docs/mcp-integration.md) (Claude Code, OpenAI Codex, Cursor, Claude Desktop, VS Code, Windsurf, Antigravity)
+- **Repository:** https://github.com/CaptchaAI/captchaai-mcp
+
+## Tools
+
+| Tool | Description | API Key Needed |
+|---|---|---|
+| `get_supported_captchas` | List the 8 token-mode CAPTCHA types with required/optional arguments and proxy/UA notes | No |
+| `get_threads` | Get account thread usage (`threads`, `working_threads`, `free_threads`) | Yes |
+| `get_balance` | Get account balance string (`balance`) | Yes |
+| `solve_captcha` | Solve a CAPTCHA in token mode and return `task_id`, `solution`, and `user_agent` | Yes |
+
+## Supported `captcha_type` Values
+
+- `recaptcha_v2` (supports `invisible=True` and `enterprise=True`)
+- `recaptcha_v3` (requires `action`; supports `enterprise=True` and `min_score`)
+- `turnstile`
+- `cloudflare_challenge` (requires `proxy` + `proxytype` (`"HTTP"` or `"HTTPS"`); returns `user_agent`)
+- `geetest` (requires `gt` + `challenge`; returns `{challenge, validate, seccode}`)
+- `captchafox` (requires `proxy` + `proxytype` (`"HTTP"` or `"HTTPS"`); returns `user_agent`)
+- `friendly_captcha`
+- `lemin` (requires `captcha_id` + `div_id`; returns `{answer, challenge_uuid}`)
+
+## Installation
+
+Install directly from PyPI with `pip` or run via `uvx`:
+
+```bash
+pip install captchaai-mcp
+```
+
+Or run from a local clone:
+
+```bash
+git clone https://github.com/CaptchaAI/captchaai-mcp.git
+cd captchaai-mcp
+uv sync
+```
+
+Set your API key:
+
+```bash
+export CAPTCHAAI_API_KEY="YOUR_32_CHAR_API_KEY"
+```
+
+## Running
+
+```bash
+# STDIO (default — for Claude Desktop, Cursor, Windsurf, etc.)
+uvx captchaai-mcp
+# or from source:
+uv run captchaai-mcp
+
+# Streamable HTTP (serves at http://127.0.0.1:8000/mcp)
+uvx captchaai-mcp --transport streamable-http --host 127.0.0.1 --port 8000
+```
+
+> [!NOTE]
+> Prefer `CAPTCHAAI_API_KEY` in the environment over `--api-key` on multi-user hosts so the key is not visible in process listings. When using `--transport streamable-http`, bind to loopback or place it behind an authenticating TLS reverse proxy.
+
+### MCP Client Configuration
+
+See the full **[MCP Client Integration Guide](docs/mcp-integration.md)** for step-by-step setup with **Claude Code**, **OpenAI Codex CLI**, **Cursor**, **Claude Desktop**, **VS Code**, **Windsurf**, and **Antigravity**.
+
+Using `uvx` (recommended):
+
+```json
+{
+  "mcpServers": {
+    "captchaai": {
+      "command": "uvx",
+      "args": ["captchaai-mcp"],
+      "env": {
+        "CAPTCHAAI_API_KEY": "YOUR_32_CHAR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Or from a local checkout:
+
+```json
+{
+  "mcpServers": {
+    "captchaai": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/path/to/captchaai-mcp",
+        "captchaai-mcp"
+      ],
+      "env": {
+        "CAPTCHAAI_API_KEY": "YOUR_32_CHAR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Development & Tests
+
+```bash
+# Run MCP server tests
+uv run pytest -q
+
+# Inspect the MCP server manifest
+uv run fastmcp inspect src/captchaai_mcp/server.py:create_server
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

captchaai_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "captchaai-mcp"
+version = "1.0.0"
+description = "Official MCP server for CaptchaAI — expose token-mode CAPTCHA solving to AI agents."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = [
+    "captchaai>=1.0.3",
+    "fastmcp>=4.1,<5",
+]
+keywords = [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "fastmcp",
+    "ai-agents",
+    "llm",
+    "captcha",
+    "captchaai",
+    "captcha-solver",
+    "captcha-solving",
+    "captcha-bypass",
+    "recaptcha",
+    "recaptcha-v2",
+    "recaptcha-v3",
+    "recaptcha-enterprise",
+    "cloudflare-turnstile",
+    "turnstile-solver",
+    "cloudflare-challenge",
+    "geetest",
+    "captchafox",
+    "friendly-captcha",
+    "lemin",
+    "automation",
+    "web-scraping",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[[project.authors]]
+name = "captchaai-developers"
+email = "dev@captchaai.com"
+
+[project.urls]
+Homepage = "https://captchaai.com/"
+Documentation = "https://docs.captchaai.com/"
+Repository = "https://github.com/CaptchaAI/captchaai-mcp"
+Issues = "https://github.com/CaptchaAI/captchaai-mcp/issues"
+Changelog = "https://github.com/CaptchaAI/captchaai-mcp/releases"
+
+[project.scripts]
+captchaai-mcp = "captchaai_mcp.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+    "pytest-asyncio>=1.4.1.post1",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]

captchaai_mcp-1.0.0/pyproject.toml.orig

@@ -0,0 +1,79 @@
+[project]
+name = "captchaai-mcp"
+version = "1.0.0"
+description = "Official MCP server for CaptchaAI — expose token-mode CAPTCHA solving to AI agents."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "captchaai-developers", email = "dev@captchaai.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "captchaai>=1.0.3",
+    "fastmcp>=4.1,<5",
+]
+keywords = [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "fastmcp",
+    "ai-agents",
+    "llm",
+    "captcha",
+    "captchaai",
+    "captcha-solver",
+    "captcha-solving",
+    "captcha-bypass",
+    "recaptcha",
+    "recaptcha-v2",
+    "recaptcha-v3",
+    "recaptcha-enterprise",
+    "cloudflare-turnstile",
+    "turnstile-solver",
+    "cloudflare-challenge",
+    "geetest",
+    "captchafox",
+    "friendly-captcha",
+    "lemin",
+    "automation",
+    "web-scraping",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://captchaai.com/"
+Documentation = "https://docs.captchaai.com/"
+Repository = "https://github.com/CaptchaAI/captchaai-mcp"
+Issues = "https://github.com/CaptchaAI/captchaai-mcp/issues"
+Changelog = "https://github.com/CaptchaAI/captchaai-mcp/releases"
+
+[project.scripts]
+captchaai-mcp = "captchaai_mcp.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+    "pytest-asyncio>=1.4.1.post1",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]

captchaai_mcp-1.0.0/src/captchaai_mcp/__init__.py

@@ -0,0 +1,9 @@
+"""CaptchaAI MCP server package."""
+
+from __future__ import annotations
+
+from .server import create_server
+
+__version__ = "1.0.0"
+
+__all__ = ["__version__", "create_server"]

captchaai_mcp-1.0.0/src/captchaai_mcp/__main__.py

@@ -0,0 +1,53 @@
+"""CLI entry point for `python -m captchaai_mcp` and the `captchaai-mcp` script."""
+
+from __future__ import annotations
+
+import argparse
+
+from captchaai_mcp.server import create_server
+
+
+def main() -> None:
+    """Parse CLI arguments and run the CaptchaAI MCP server."""
+    parser = argparse.ArgumentParser(
+        description="CaptchaAI MCP Server — expose token-mode captcha solving to AI agents.",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "streamable-http"],
+        default="stdio",
+        help="Transport protocol: stdio (default) or streamable-http.",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host to bind for streamable-http transport (default: 127.0.0.1).",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Port to bind for streamable-http transport (default: 8000).",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=None,
+        help="CaptchaAI API key. Falls back to CAPTCHAAI_API_KEY env var.",
+    )
+    parser.add_argument(
+        "--name",
+        default="captchaai",
+        help="Server name advertised to MCP clients (default: captchaai).",
+    )
+
+    args = parser.parse_args()
+    server = create_server(api_key=args.api_key, name=args.name)
+
+    if args.transport == "stdio":
+        server.run()
+    else:
+        server.run(transport="http", host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

captchaai_mcp-1.0.0/src/captchaai_mcp/catalog.py

@@ -0,0 +1,180 @@
+"""Catalog of supported token-mode CAPTCHA types and SDK call dispatch."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from captchaai import SUPPORTED_PROXY_TYPES, supported_types
+from fastmcp.exceptions import ToolError
+
+_COMMON_ARGS = ("cookies", "user_agent", "proxy", "proxytype")
+_PROXY_ONLY_ARGS = ("proxy", "proxytype")
+_ARG_TO_SDK_KWARG = {
+    "website_url": "url",
+    "website_key": "sitekey",
+}
+
+
+@dataclass(frozen=True)
+class PublicType:
+    """Definition of one public token-mode CAPTCHA type exposed by MCP."""
+
+    sdk_method: str
+    description: str
+    registry_names: tuple[str, ...]
+    required: tuple[str, ...]
+    optional: tuple[str, ...]
+    variants: dict[str, str]
+
+
+CATALOG: dict[str, PublicType] = {
+    "recaptcha_v2": PublicType(
+        sdk_method="recaptcha_v2",
+        description="Google reCAPTCHA v2 checkbox, invisible, or Enterprise.",
+        registry_names=("recaptcha_v2", "recaptcha_v2_invisible", "recaptcha_v2_enterprise"),
+        required=("website_url", "website_key"),
+        optional=("invisible", "enterprise", "action", *_COMMON_ARGS),
+        variants={
+            "invisible": "Invisible reCAPTCHA v2 widget",
+            "enterprise": "reCAPTCHA v2 Enterprise (returns user_agent to reuse)",
+        },
+    ),
+    "recaptcha_v3": PublicType(
+        sdk_method="recaptcha_v3",
+        description="Google reCAPTCHA v3 score-based challenge (standard or Enterprise).",
+        registry_names=("recaptcha_v3", "recaptcha_v3_enterprise"),
+        required=("website_url", "website_key", "action"),
+        optional=("enterprise", "min_score", *_COMMON_ARGS),
+        variants={
+            "enterprise": "reCAPTCHA v3 Enterprise (returns user_agent to reuse)",
+        },
+    ),
+    "turnstile": PublicType(
+        sdk_method="turnstile",
+        description="Cloudflare Turnstile widget.",
+        registry_names=("turnstile",),
+        required=("website_url", "website_key"),
+        optional=_COMMON_ARGS,
+        variants={},
+    ),
+    "cloudflare_challenge": PublicType(
+        sdk_method="cloudflare_challenge",
+        description="Cloudflare interstitial challenge page (returns cf_clearance + user_agent).",
+        registry_names=("cloudflare_challenge",),
+        required=("website_url", "proxy", "proxytype"),
+        optional=("cookies", "user_agent"),
+        variants={},
+    ),
+    "geetest": PublicType(
+        sdk_method="geetest",
+        description="GeeTest v3 slide/puzzle challenge (returns dict with challenge/validate/seccode).",
+        registry_names=("geetest",),
+        required=("website_url", "gt", "challenge"),
+        optional=_COMMON_ARGS,
+        variants={},
+    ),
+    "captchafox": PublicType(
+        sdk_method="captchafox",
+        description="CaptchaFox slider challenge (proxy required; returns user_agent to reuse).",
+        registry_names=("captchafox",),
+        required=("website_url", "website_key", "proxy", "proxytype"),
+        optional=("cookies", "user_agent"),
+        variants={},
+    ),
+    "friendly_captcha": PublicType(
+        sdk_method="friendly_captcha",
+        description="Friendly Captcha proof-of-work challenge.",
+        registry_names=("friendly_captcha",),
+        required=("website_url", "website_key"),
+        optional=("version", *_PROXY_ONLY_ARGS),
+        variants={},
+    ),
+    "lemin": PublicType(
+        sdk_method="lemin",
+        description="Lemin puzzle challenge (returns dict with answer and challenge_uuid).",
+        registry_names=("lemin",),
+        required=("website_url", "captcha_id", "div_id"),
+        optional=("api_server", *_PROXY_ONLY_ARGS),
+        variants={},
+    ),
+}
+
+
+def _is_missing(value: Any) -> bool:
+    return value is None or (isinstance(value, str) and not value.strip())
+
+
+def build_call(captcha_type: str, args: dict[str, Any]) -> tuple[str, dict[str, Any]]:
+    """Validate MCP arguments and build `(sdk_method_name, sdk_kwargs)`.
+
+    Raises ToolError before any network call if `captcha_type` is unknown,
+    required arguments are missing, proxy/proxytype are mismatched, or arguments
+    not supported by the chosen type are supplied.
+    """
+    spec = CATALOG.get(captcha_type)
+    if spec is None:
+        supported = ", ".join(CATALOG)
+        raise ToolError(f"Unknown captcha_type {captcha_type!r}. Supported: {supported}.")
+
+    allowed = set(spec.required) | set(spec.optional)
+
+    # Reject inapplicable arguments rather than silently dropping them, while
+    # skipping default False on boolean flags (SDK defaults to False as well).
+    provided: dict[str, Any] = {}
+    for key, value in args.items():
+        if value is None:
+            continue
+        if key in ("invisible", "enterprise") and value is False:
+            continue
+        provided[key] = value
+
+    inapplicable = sorted(key for key in provided if key not in allowed)
+    if inapplicable:
+        raise ToolError(
+            f"Arguments not supported for {captcha_type!r}: {', '.join(inapplicable)}. "
+            "Call get_supported_captchas() to see valid parameters."
+        )
+
+    missing = [key for key in spec.required if _is_missing(provided.get(key))]
+    if missing:
+        raise ToolError(
+            f"Missing required arguments for {captcha_type!r}: {', '.join(missing)}. "
+            "Call get_supported_captchas() for parameter details."
+        )
+
+    has_proxy = not _is_missing(provided.get("proxy"))
+    has_proxytype = not _is_missing(provided.get("proxytype"))
+    if has_proxy and not has_proxytype:
+        raise ToolError("proxytype is required when proxy is set (HTTP or HTTPS).")
+    if has_proxytype and not has_proxy:
+        raise ToolError("proxy is required when proxytype is set (format: 'user:pass@host:port').")
+    if has_proxytype:
+        normalized_proxytype = str(provided["proxytype"]).strip().upper()
+        if normalized_proxytype not in SUPPORTED_PROXY_TYPES:
+            supported = ", ".join(SUPPORTED_PROXY_TYPES)
+            raise ToolError(
+                f"Unsupported proxytype {provided['proxytype']!r}. Supported values: {supported}."
+            )
+        provided["proxytype"] = normalized_proxytype
+
+    sdk_kwargs = {_ARG_TO_SDK_KWARG.get(key, key): value for key, value in provided.items()}
+    return spec.sdk_method, sdk_kwargs
+
+
+def describe_captchas() -> dict[str, dict[str, Any]]:
+    """Return per-type metadata combining MCP parameters with live SDK registry facts."""
+    sdk_info = supported_types()
+    out: dict[str, dict[str, Any]] = {}
+    for name, spec in CATALOG.items():
+        entries = [sdk_info[reg] for reg in spec.registry_names if reg in sdk_info]
+        out[name] = {
+            "description": spec.description,
+            "required_args": list(spec.required),
+            "optional_args": list(spec.optional),
+            "variants": dict(spec.variants),
+            "requires_proxy": any(item["requires_proxy"] for item in entries),
+            "returns_user_agent": any(item["returns_user_agent"] for item in entries),
+            "supported_proxy_types": list(SUPPORTED_PROXY_TYPES),
+        }
+    return out

captchaai_mcp-1.0.0/src/captchaai_mcp/errors.py

@@ -0,0 +1,38 @@
+"""Map CaptchaAI SDK exceptions to structured FastMCP ToolError instances."""
+
+from __future__ import annotations
+
+from captchaai import (
+    APIError,
+    CaptchaAIError,
+    InvalidKeyError,
+    NetworkError,
+    NoThreadsError,
+    ProxyError,
+    ThreadLimitError,
+    TimeoutError,
+    UnsolvableError,
+    ValidationError,
+)
+from fastmcp.exceptions import ToolError
+
+_HINTS: dict[type[CaptchaAIError], str] = {
+    InvalidKeyError: "Check CAPTCHAAI_API_KEY or --api-key.",
+    ValidationError: "Fix the arguments; see get_supported_captchas().",
+    ThreadLimitError: "All threads busy; check get_threads() and retry later.",
+    NoThreadsError: "Account has no threads; check your plan at captchaai.com.",
+    UnsolvableError: "Workers could not solve it; verify website_key/website_url and retry.",
+    ProxyError: "Proxy failed; check proxy format 'user:pass@host:port' and proxytype.",
+    TimeoutError: "Solve took too long; retry.",
+    NetworkError: "Could not reach CaptchaAI; retry.",
+    APIError: "Unexpected API response.",
+}
+
+
+def to_tool_error(exc: CaptchaAIError) -> ToolError:
+    """Convert a CaptchaAI SDK exception into an agent-readable ToolError."""
+    hint = next((text for cls, text in _HINTS.items() if isinstance(exc, cls)), "")
+    message = f"{type(exc).__name__}: {exc}".rstrip(".")
+    if hint:
+        message = f"{message}. {hint}"
+    return ToolError(message)

captchaai_mcp-1.0.0/src/captchaai_mcp/server.py

@@ -0,0 +1,193 @@
+"""FastMCP server definition, lazy client holder, and token-mode MCP tools."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import Awaitable, Callable
+from typing import Any, Literal, TypeVar
+
+from captchaai import AsyncCaptchaAI, CaptchaAIError
+from fastmcp import Context, FastMCP
+from fastmcp.exceptions import ToolError
+from fastmcp.server.lifespan import lifespan
+
+from captchaai_mcp.catalog import build_call, describe_captchas
+from captchaai_mcp.errors import to_tool_error
+
+_T = TypeVar("_T")
+
+CaptchaTypeLiteral = Literal[
+    "recaptcha_v2",
+    "recaptcha_v3",
+    "turnstile",
+    "cloudflare_challenge",
+    "geetest",
+    "captchafox",
+    "friendly_captcha",
+    "lemin",
+]
+ProxyTypeLiteral = Literal["HTTP", "HTTPS"]
+
+
+class ClientHolder:
+    """Lazily builds and caches one AsyncCaptchaAI instance for the server lifetime."""
+
+    def __init__(self, api_key: str | None) -> None:
+        self._api_key = api_key
+        self._client: AsyncCaptchaAI | None = None
+        self._lock = asyncio.Lock()
+
+    async def get(self) -> AsyncCaptchaAI:
+        """Return the cached AsyncCaptchaAI client, creating it on first use."""
+        async with self._lock:
+            if self._client is None:
+                if not self._api_key:
+                    raise ToolError("CAPTCHAAI_API_KEY is not set (or pass --api-key).")
+                try:
+                    self._client = await AsyncCaptchaAI.create(api_key=self._api_key)
+                except CaptchaAIError as exc:
+                    raise to_tool_error(exc) from exc
+            return self._client
+
+    async def aclose(self) -> None:
+        """Close the cached client if it was created."""
+        if self._client is not None:
+            client = self._client
+            self._client = None
+            await client.aclose()
+
+
+async def _call(ctx: Context, fn: Callable[[AsyncCaptchaAI], Awaitable[_T]]) -> _T:
+    """Retrieve the shared SDK client, run `fn`, and map SDK errors to ToolError."""
+    holder: ClientHolder = ctx.lifespan_context["holder"]
+    client = await holder.get()
+    try:
+        return await fn(client)
+    except CaptchaAIError as exc:
+        raise to_tool_error(exc) from exc
+
+
+def create_server(api_key: str | None = None, name: str = "captchaai") -> FastMCP:
+    """Create and configure the CaptchaAI FastMCP server."""
+    import captchaai_mcp
+
+    resolved_key = api_key if api_key is not None else os.environ.get("CAPTCHAAI_API_KEY")
+    holder = ClientHolder(resolved_key)
+
+    @lifespan
+    async def app_lifespan(server: FastMCP):
+        try:
+            yield {"holder": holder}
+        finally:
+            await holder.aclose()
+
+    mcp = FastMCP(
+        name,
+        version=captchaai_mcp.__version__,
+        lifespan=app_lifespan,
+        mask_error_details=True,
+        instructions=(
+            "CaptchaAI token-mode captcha solving. "
+            "Call get_supported_captchas() first to inspect required and optional parameters per type."
+        ),
+    )
+
+    @mcp.tool(annotations={"readOnlyHint": True, "openWorldHint": True})
+    async def get_threads(ctx: Context) -> dict[str, int]:
+        """Get CaptchaAI thread usage: total threads, active working_threads, and free_threads."""
+        info = await _call(ctx, lambda client: client.threads_info())
+        return {
+            "threads": info["threads"],
+            "working_threads": info["working_threads"],
+            "free_threads": info["threads"] - info["working_threads"],
+        }
+
+    @mcp.tool(annotations={"readOnlyHint": True, "openWorldHint": True})
+    async def get_balance(ctx: Context) -> dict[str, str]:
+        """Get the CaptchaAI account balance as returned by the API."""
+        balance = await _call(ctx, lambda client: client.get_balance())
+        return {"balance": balance}
+
+    @mcp.tool(annotations={"readOnlyHint": True, "idempotentHint": True, "openWorldHint": False})
+    def get_supported_captchas() -> dict[str, dict[str, Any]]:
+        """List all supported token-mode CAPTCHA types with required/optional arguments and capabilities.
+
+        Works without an API key.
+        """
+        return {"captchas": describe_captchas()}
+
+    @mcp.tool(annotations={"readOnlyHint": False, "openWorldHint": True})
+    async def solve_captcha(
+        ctx: Context,
+        captcha_type: CaptchaTypeLiteral,
+        website_url: str,
+        website_key: str | None = None,
+        action: str | None = None,
+        min_score: float | None = None,
+        invisible: bool = False,
+        enterprise: bool = False,
+        gt: str | None = None,
+        challenge: str | None = None,
+        captcha_id: str | None = None,
+        div_id: str | None = None,
+        api_server: str | None = None,
+        version: str | None = None,
+        cookies: str | None = None,
+        user_agent: str | None = None,
+        proxy: str | None = None,
+        proxytype: ProxyTypeLiteral | None = None,
+    ) -> dict[str, Any]:
+        """Solve a CAPTCHA in token mode (no browser) and return the solved token or payload.
+
+        Blocks until solved (typically 10-80s). Call get_supported_captchas() first to check
+        which arguments are required for the chosen captcha_type. When `user_agent` is returned
+        (Enterprise, Cloudflare Challenge, CaptchaFox), reuse it when submitting the token.
+
+        Args:
+            captcha_type: CAPTCHA challenge type (e.g. "recaptcha_v2", "recaptcha_v3", "turnstile").
+            website_url: Full URL of the page containing the CAPTCHA.
+            website_key: Site key (data-sitekey) for reCAPTCHA, Turnstile, CaptchaFox, or Friendly Captcha.
+            action: Action name (required for recaptcha_v3; optional `sa=` for Enterprise v2).
+            min_score: Minimum score threshold (0.0-1.0) for recaptcha_v3.
+            invisible: Enable invisible mode (recaptcha_v2 only).
+            enterprise: Enable Enterprise mode (recaptcha_v2 or recaptcha_v3).
+            gt: GeeTest public `gt` parameter (required for geetest).
+            challenge: GeeTest `challenge` parameter (required for geetest).
+            captcha_id: Lemin captcha identifier (required for lemin).
+            div_id: Lemin target container element ID (required for lemin).
+            api_server: Optional Lemin API server URL.
+            version: Optional Friendly Captcha version string.
+            cookies: Optional cookies forwarded to the solver ("KEY1:Val1;KEY2:Val2;").
+            user_agent: Optional User-Agent string forwarded to the solver.
+            proxy: Proxy string in "user:pass@host:port" format (required for cloudflare_challenge and captchafox).
+            proxytype: Proxy protocol when proxy is set ("HTTP" or "HTTPS").
+        """
+        args: dict[str, Any] = {
+            "website_url": website_url,
+            "website_key": website_key,
+            "action": action,
+            "min_score": min_score,
+            "invisible": invisible,
+            "enterprise": enterprise,
+            "gt": gt,
+            "challenge": challenge,
+            "captcha_id": captcha_id,
+            "div_id": div_id,
+            "api_server": api_server,
+            "version": version,
+            "cookies": cookies,
+            "user_agent": user_agent,
+            "proxy": proxy,
+            "proxytype": proxytype,
+        }
+        method_name, sdk_kwargs = build_call(captcha_type, args)
+        result = await _call(ctx, lambda client: getattr(client, method_name)(**sdk_kwargs))
+        return {
+            "captcha_type": captcha_type,
+            "task_id": result.task_id,
+            "solution": result.solution,
+            "user_agent": result.user_agent,
+        }
+
+    return mcp