Metadata-Version: 2.5
Name: captcha-mcp-test
Version: 0.1.1
Summary: MCP server for solving captchas via CapMonster Cloud (test publish)
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: fastmcp
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# captcha-mcp-test

MCP server for solving captchas via [CapMonster Cloud](https://capmonster.cloud). It
is the **solve brain**: it lists supported captcha types, serves CapMonster's docs,
and creates/polls solve tasks against the CapMonster Cloud REST API. It has **no
browser of its own** — pair it with a browser-driving MCP (e.g.
[`mcp-patchright-mainworld`](https://www.npmjs.com/package/mcp-patchright-mainworld))
that does the page work (navigation, interaction, reading the live DOM/network, and
injecting the solved token back into the page).

Two equivalent implementations live in this repo, same tools/behavior:

- **Python** (this directory) — published to PyPI, run with `uvx`.
- **TypeScript** ([`ts/`](ts/)) — published to npm, run with `npx`. See [`ts/README.md`](ts/README.md).

## Quick start (Python / PyPI)

```json
{
  "mcpServers": {
    "capmonster": {
      "command": "uvx",
      "args": ["captcha-mcp-test"],
      "env": { "CM_API_KEY": "YOUR_API_KEY" }
    }
  }
}
```

`uvx` runs the published PyPI package with no local clone needed. See
[`mcp.json`](mcp.json) for a full example that also wires up the `patchright`
companion browser MCP.

For the npm/TypeScript version, see [`ts/README.md`](ts/README.md).

## Configuration

This server only runs over stdio (the transport MCP clients use to launch it as a
subprocess), so there are no HTTP headers to carry a per-request key — set
`CM_API_KEY` in the client's `env` block (see [`mcp.json`](mcp.json)) and every tool
call in that session uses it.

## Tools

- `get_supported_tasks` — list captcha task types CapMonster supports (from the live OpenAPI spec).
- `get_task_parameters(task_type)` — required/optional fields, variant notes, and the solution schema for a task type.
- `get_docs(url, offset, limit, section)` — fetch a CapMonster doc page (`docs.capmonster.cloud`/`api.capmonster.cloud` only), with section-jump and pagination.
- `create_task(task)` — submit a captcha task, returns a `taskId`.
- `get_task_result(task_id)` — poll a task once.
- `get_task_result_wait(task_id, timeout_seconds, poll_interval_seconds)` — poll a task to completion (preferred over driving the loop yourself).
- `get_actual_user_agent()` — fetch a current Windows User-Agent to use as one consistent fingerprint across the browser and the solve task.
- `get_balance()` — CapMonster account balance.

## Workflow

[`capmonster_agent/SKILL.md`](capmonster_agent/SKILL.md) is the step-by-step
procedure for analyzing a captcha-protected page and solving it with this server
paired with a `patchright` (or any stateful browser-automation) MCP.
[`capmonster_agent/PROMPT.md`](capmonster_agent/PROMPT.md) is a copy-paste prompt
that sets an agent up with both servers (Python/PyPI `capmonster` server via `uvx`)
and points it at the skill.
[`capmonster_agent/PROMPT_JS.md`](capmonster_agent/PROMPT_JS.md) is the same prompt
for the TypeScript/npm `capmonster` server, run via `npx`.

## Development

```
python -m venv .venv
.venv\Scripts\activate  # or source .venv/bin/activate on Linux/macOS
pip install -e ".[dev]"
pytest
```
