capsolver-mcp 0.1.0__tar.gz

capsolver_mcp-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution
+dist/
+build/
+*.egg-info/
+*.egg
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+.cursor/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+
+# Environment
+.env
+.env.local
+.python-version
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db

capsolver_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning where practical. Public releases are
+tagged in Git as `vX.Y.Z` and published to PyPI with the same version.
+
+## [0.1.0] - 2026-09-01
+
+### Added
+
+- Initial public release of `capsolver-mcp`.
+- MCP server exposing CapSolver captcha-solving tools.
+- Support for stdio, SSE, and streamable HTTP transports.
+- Optional browser-based tools behind the `browser` extra.
+- Client configuration guide for Claude Desktop, Claude Code, Cursor,
+  Windsurf, Cline, and remote HTTP clients.
+- `capsolver-mcp` CLI entry point.
+

capsolver_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing
+
+Thank you for your interest in `capsolver-mcp`.
+
+This repository is maintained by the CapSolver team. Issues and pull requests
+are welcome when they are focused on bugs, documentation, compatibility, or
+small improvements to the public MCP server surface.
+
+## Before You Start
+
+- Search existing issues before opening a new one.
+- Open an issue before starting a large change or adding support for a new MCP
+  client.
+- Do not include real API keys, cookies, private URLs, MCP client configs,
+  prompts, tool traces, or customer data in issues, tests, examples, or
+  screenshots.
+- Keep examples token-mode focused and use placeholder credentials.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+```
+
+If you do not use `uv`, install the development dependencies from
+`requirements-dev.txt` and run the equivalent commands with Python.
+
+## Pull Requests
+
+Pull requests should include:
+
+- A clear description of the change.
+- Tests or a short explanation of why tests are not needed.
+- Documentation updates for user-facing behavior.
+
+Maintainers may close changes that are outside the public MCP server scope or
+require private service-side details.
+

capsolver_mcp-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-2026 capsolver-ai
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

capsolver_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: capsolver-mcp
+Version: 0.1.0
+Summary: MCP Server for CapSolver — expose captcha-solving capabilities to AI agents via Model Context Protocol.
+Project-URL: Homepage, https://capsolver.com
+Project-URL: Repository, https://github.com/capsolver-ai/mcp-capsolver
+Project-URL: Issues, https://github.com/capsolver-ai/mcp-capsolver/issues
+Project-URL: Documentation, https://github.com/capsolver-ai/mcp-capsolver/blob/main/docs/mcp-integration.md
+Project-URL: Changelog, https://github.com/capsolver-ai/mcp-capsolver/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/capsolver-ai/mcp-capsolver/blob/main/SECURITY.md
+Author-email: capsolver-ai <dev@capsolver.ai>
+License-Expression: ISC
+License-File: LICENSE
+Keywords: ai-agent,capsolver,captcha,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: capsolver-core>=0.1.0
+Requires-Dist: mcp<2,>=1.0.0
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == 'browser'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# capsolver-mcp
+
+MCP Server for [CapSolver](https://capsolver.com) — expose captcha-solving capabilities to AI agents via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+See the [capsolver-ai](https://github.com/capsolver-ai/capsolver-ai) hub repo for integration examples and the full documentation.
+
+For detailed MCP client setup (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, and more), see [docs/mcp-integration.md](docs/mcp-integration.md).
+
+## Install
+
+```bash
+pip install capsolver-mcp
+pip install capsolver-mcp[browser]   # with Playwright support (for detect/solve_on_page)
+```
+
+All tools read the API key from the environment:
+
+```bash
+# bash / zsh
+export CAPSOLVER_API_KEY="your-capsolver-api-key"
+
+# PowerShell
+$env:CAPSOLVER_API_KEY = "your-capsolver-api-key"
+
+# cmd
+set CAPSOLVER_API_KEY=your-capsolver-api-key
+```
+
+## Usage
+
+### CLI
+
+```bash
+# stdio (default — for local MCP clients like Claude Desktop)
+capsolver-mcp
+
+# SSE (for remote / HTTP access)
+capsolver-mcp --transport sse --host 0.0.0.0 --port 8000
+
+# Streamable HTTP (MCP 2025-03-26 spec)
+capsolver-mcp --transport streamable-http --host 0.0.0.0 --port 8000
+```
+
+#### CLI options
+
+```
+capsolver-mcp [OPTIONS]
+
+  --transport {stdio,sse,streamable-http}
+                              Transport protocol (default: stdio)
+  --host HOST                 Bind host for SSE/HTTP transports (default: 127.0.0.1)
+  --port PORT                 Bind port for SSE/HTTP transports (default: 8000)
+  --api-key KEY               API key (fallback: CAPSOLVER_API_KEY env)
+  --name NAME                 Server name (default: capsolver)
+```
+
+### Programmatic
+
+```python
+from capsolver_mcp.server import create_server
+
+server = create_server(
+    api_key="your-key",       # or set CAPSOLVER_API_KEY env var
+    server_name="capsolver",  # name advertised to MCP clients
+    host="127.0.0.1",         # bind host for SSE / HTTP transports
+    port=8000,                # bind port for SSE / HTTP transports
+)
+server.run(transport="sse")   # or "stdio" or "streamable-http"
+```
+
+> **Note:** `host` and `port` are constructor parameters on `create_server()`
+> (forwarded to `FastMCP`), matching the MCP Python SDK 1.x API.
+
+## Configure in Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "capsolver": {
+      "command": "capsolver-mcp",
+      "env": {
+        "CAPSOLVER_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+## Available tools
+
+| Tool | Browser? | Description |
+|---|---|---|
+| `solve_captcha` | No | Solve a captcha by type + site params (token mode) |
+| `detect_captchas` | Yes | Scan a page URL and list present captcha types |
+| `solve_on_page` | Yes | Detect + solve + autofill all captchas on a page |
+| `get_balance` | No | Check account balance and packages |
+| `get_supported_captchas` | No | List all supported captcha types and handlers |
+
+Browser-based tools (`detect_captchas`, `solve_on_page`) require the `browser` extra:
+
+```bash
+pip install capsolver-mcp[browser]
+playwright install chromium
+```
+
+## Development
+
+```bash
+git clone https://github.com/capsolver-ai/mcp-capsolver.git
+cd mcp-capsolver
+uv sync --all-extras          # or: pip install -r requirements-dev.txt
+uv run pytest                 # run tests
+uv run ruff check src tests   # lint
+```
+
+## License
+
+ISC

capsolver_mcp-0.1.0/PUBLISHING.md

@@ -0,0 +1,118 @@
+# Publishing
+
+Release target: `capsolver-mcp` version `0.1.0`, prepared for public release on
+2026-09-01.
+
+This checklist is for maintainers syncing the prepared public files to the
+official open-source repository, testing the package on TestPyPI, and then
+publishing the final package to PyPI.
+
+Publish `capsolver-core==0.1.0` first. This package depends on
+`capsolver-core>=0.1.0`.
+
+## Preconditions
+
+- The source is the prepared public copy, not a private development checkout.
+- `capsolver-core==0.1.0` has already passed TestPyPI testing before this
+  package is tested.
+- `capsolver-core==0.1.0` is already available on PyPI before this package is
+  formally published.
+- `pyproject.toml` has `version = "0.1.0"`.
+- `CHANGELOG.md` has `## [0.1.0] - 2026-09-01`.
+- `README.md`, `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`, and `SUPPORT.md`
+  are present.
+- Documentation examples use placeholder credentials only.
+- The tree does not contain `.git`, `.venv`, `uv.lock`, caches, local path
+  overrides, real API keys, browser profiles, MCP client configs with secrets,
+  prompts, tool traces, or private service data.
+
+## Sync to the Official Open-Source Repository
+
+Copy this directory into the official `mcp-capsolver` public repository working
+tree, then review the diff before committing.
+
+```bash
+git status
+git diff
+git add .
+git commit -m "Release v0.1.0"
+git status
+```
+
+Do not tag until the build, TestPyPI upload, and install test have passed.
+
+## Verify Locally
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+```
+
+## Build and Check
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+Inspect the source distribution and wheel before upload. Confirm that no
+private files, local paths, secrets, browser profiles, caches, MCP client
+configs with secrets, prompts, tool traces, or test output are included.
+
+## TestPyPI Test Release
+
+Upload the exact distribution files to TestPyPI first.
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+Install from TestPyPI in a clean environment and smoke-test the CLI import path.
+Use PyPI as an extra index so normal third-party dependencies can still resolve.
+
+```bash
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ capsolver-mcp==0.1.0
+python -c "import capsolver_mcp; print(capsolver_mcp.__version__)"
+capsolver-mcp --help
+```
+
+PyPI and TestPyPI distributions cannot be overwritten. If the test upload is
+wrong, fix the issue and publish a new version.
+
+## Formal PyPI Release
+
+After TestPyPI passes and `capsolver-core==0.1.0` is available from PyPI, upload
+the same checked distribution files to PyPI.
+
+```bash
+python -m twine upload dist/*
+```
+
+Then verify installation from PyPI.
+
+```bash
+python -m pip install capsolver-mcp==0.1.0
+python -c "import capsolver_mcp; print(capsolver_mcp.__version__)"
+capsolver-mcp --help
+```
+
+## Tag and GitHub Release
+
+When the PyPI release is verified, create the release tag and push it from the
+official public repository.
+
+```bash
+git tag v0.1.0
+git push origin main
+git push origin v0.1.0
+```
+
+Create a GitHub Release for `v0.1.0` using the `CHANGELOG.md` entry.
+
+Prefer PyPI Trusted Publishing from the official public GitHub repository for
+future releases. If manual upload is used, use a project-scoped PyPI API token
+instead of an account password.
+

capsolver_mcp-0.1.0/README.md

@@ -0,0 +1,120 @@
+# capsolver-mcp
+
+MCP Server for [CapSolver](https://capsolver.com) — expose captcha-solving capabilities to AI agents via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+See the [capsolver-ai](https://github.com/capsolver-ai/capsolver-ai) hub repo for integration examples and the full documentation.
+
+For detailed MCP client setup (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, and more), see [docs/mcp-integration.md](docs/mcp-integration.md).
+
+## Install
+
+```bash
+pip install capsolver-mcp
+pip install capsolver-mcp[browser]   # with Playwright support (for detect/solve_on_page)
+```
+
+All tools read the API key from the environment:
+
+```bash
+# bash / zsh
+export CAPSOLVER_API_KEY="your-capsolver-api-key"
+
+# PowerShell
+$env:CAPSOLVER_API_KEY = "your-capsolver-api-key"
+
+# cmd
+set CAPSOLVER_API_KEY=your-capsolver-api-key
+```
+
+## Usage
+
+### CLI
+
+```bash
+# stdio (default — for local MCP clients like Claude Desktop)
+capsolver-mcp
+
+# SSE (for remote / HTTP access)
+capsolver-mcp --transport sse --host 0.0.0.0 --port 8000
+
+# Streamable HTTP (MCP 2025-03-26 spec)
+capsolver-mcp --transport streamable-http --host 0.0.0.0 --port 8000
+```
+
+#### CLI options
+
+```
+capsolver-mcp [OPTIONS]
+
+  --transport {stdio,sse,streamable-http}
+                              Transport protocol (default: stdio)
+  --host HOST                 Bind host for SSE/HTTP transports (default: 127.0.0.1)
+  --port PORT                 Bind port for SSE/HTTP transports (default: 8000)
+  --api-key KEY               API key (fallback: CAPSOLVER_API_KEY env)
+  --name NAME                 Server name (default: capsolver)
+```
+
+### Programmatic
+
+```python
+from capsolver_mcp.server import create_server
+
+server = create_server(
+    api_key="your-key",       # or set CAPSOLVER_API_KEY env var
+    server_name="capsolver",  # name advertised to MCP clients
+    host="127.0.0.1",         # bind host for SSE / HTTP transports
+    port=8000,                # bind port for SSE / HTTP transports
+)
+server.run(transport="sse")   # or "stdio" or "streamable-http"
+```
+
+> **Note:** `host` and `port` are constructor parameters on `create_server()`
+> (forwarded to `FastMCP`), matching the MCP Python SDK 1.x API.
+
+## Configure in Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "capsolver": {
+      "command": "capsolver-mcp",
+      "env": {
+        "CAPSOLVER_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+## Available tools
+
+| Tool | Browser? | Description |
+|---|---|---|
+| `solve_captcha` | No | Solve a captcha by type + site params (token mode) |
+| `detect_captchas` | Yes | Scan a page URL and list present captcha types |
+| `solve_on_page` | Yes | Detect + solve + autofill all captchas on a page |
+| `get_balance` | No | Check account balance and packages |
+| `get_supported_captchas` | No | List all supported captcha types and handlers |
+
+Browser-based tools (`detect_captchas`, `solve_on_page`) require the `browser` extra:
+
+```bash
+pip install capsolver-mcp[browser]
+playwright install chromium
+```
+
+## Development
+
+```bash
+git clone https://github.com/capsolver-ai/mcp-capsolver.git
+cd mcp-capsolver
+uv sync --all-extras          # or: pip install -r requirements-dev.txt
+uv run pytest                 # run tests
+uv run ruff check src tests   # lint
+```
+
+## License
+
+ISC

capsolver_mcp-0.1.0/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are provided for the latest public release line.
+
+| Version | Supported |
+| ------- | --------- |
+| 0.1.x   | Yes       |
+
+## Reporting a Vulnerability
+
+Please do not open public issues for vulnerabilities, leaked credentials, or
+reports that include private target URLs, API keys, MCP client configuration,
+tool traces, or customer data.
+
+Report security issues by emailing `dev@capsolver.ai` with:
+
+- The affected package and version.
+- A concise description of the issue.
+- Reproduction steps or a minimal proof of concept.
+- The impact you believe the issue has.
+
+We will acknowledge valid reports as soon as possible and coordinate a fix or
+mitigation before public disclosure.
+
+## Handling API Keys and MCP Configuration
+
+Never commit real `CAPSOLVER_API_KEY` values, MCP client configs containing
+secrets, browser profiles, cookies, or captured tokens. Documentation examples
+must use placeholder values only.
+

capsolver_mcp-0.1.0/SUPPORT.md

@@ -0,0 +1,25 @@
+# Support
+
+Use the right channel for the type of help you need.
+
+## Package Bugs and Documentation
+
+Open a GitHub issue for:
+
+- Installation problems.
+- Runtime errors in this package.
+- Documentation mistakes.
+- Compatibility issues with supported Python versions, MCP clients, or optional
+  browser tooling.
+
+Include the package version, Python version, operating system, MCP client name
+and version, transport mode, and a minimal reproduction when possible.
+
+## CapSolver Account or API Service Issues
+
+For account access, billing, API key, balance, or service availability issues,
+use the support options available from `https://capsolver.com`.
+
+Do not post API keys, account identifiers, cookies, browser profiles, MCP client
+configuration with secrets, or target site credentials in public issues.
+