# `Туча` aka 2cha

Удалённо доступный MCP-сервер-обёртка над 2Captcha. Решает rotate/image-orientation капчи: один tool `solve_servicepipe_rotate`, Streamable HTTP транспорт.

## Как это работает

`solve_servicepipe_rotate(image)` запускает `TWOCAPTCHA_MCP_PARALLEL_ATTEMPTS` (5) параллельных попыток решения: каждая сабмитит изображение в API 2Captcha (in.php) и поллит ответ (res.php) собственным кодом на httpx. Как только набралось `TWOCAPTCHA_MCP_EARLY_EXIT_SUCCESSES` (4) успеха — поток завершается; финальный угол — агрегат (медиана ±30° отсечение выбросов + среднее) по всем полученным оценкам. Меньше `TWOCAPTCHA_MCP_MIN_SUCCESSES` (3) оценок — ошибка со списком причин.

Неиспользованный «хвост» попыток не отменяется, а автоматически уходит в `reportbad` (возврат средств); у каждой попытки свой лимит `TWOCAPTCHA_MCP_ATTEMPT_TIMEOUT_SEC` (45с), у всего вызова — страховочный дедлайн `TWOCAPTCHA_MCP_SOLVE_DEADLINE_SEC` (54с). Успешные результаты (изображение, агрегат, оценки с ids) дописываются в локальный ndjson-архив.

Стоимость одного вызова — линейно от числа параллельных попыток (~$0.001/попытка).

## Быстрый старт

```bash
make dev                                   # установка в editable-режиме
TWOCAPTCHA_MCP_API_KEY=... make run        # запуск сервера
```

Сервер слушает Streamable HTTP на `http://<TWOCAPTCHA_MCP_HOST>:<TWOCAPTCHA_MCP_PORT>/mcp` (default `0.0.0.0:3000`).

Пример вызова tool:

```json
{"image": "<base64 PNG/JPG/GIF, data-URI префикс допустим>"}
```

Ответ успеха:

```json
{"status": "success", "angle_degrees": 42.5}
```

Ошибка (MCP Tool Result с `isError=True`):

```json
{"status": "error", "error": "...", "suggestions": ["..."]}
```

## Конфигурация

Переменные окружения (см. `.env.example`):

| Переменная | Назначение | Default |
|---|---|---|
| `TWOCAPTCHA_MCP_API_KEY` | API key 2Captcha | обязательная |
| `TWOCAPTCHA_MCP_SERVER` | API server | `2captcha.com` |
| `TWOCAPTCHA_MCP_ATTEMPT_TIMEOUT_SEC` | лимит одной попытки (сабмит + поллинг) | `45` |
| `TWOCAPTCHA_MCP_ATTEMPT_POLLING_INTERVAL_SEC` | интервал polling res.php | `2` |
| `TWOCAPTCHA_MCP_SOLVE_DEADLINE_SEC` | дедлайн всего solve-потока | `54` |
| `TWOCAPTCHA_MCP_HTTP_TIMEOUT_SEC` | лимит одного HTTP-запроса | `15` |
| `TWOCAPTCHA_MCP_HTTP_CONNECT_TIMEOUT_SEC` | таймаут connect/TLS | `10` |
| `TWOCAPTCHA_MCP_PARALLEL_ATTEMPTS` | число параллельных попыток (стоимость ~линейна) | `5` |
| `TWOCAPTCHA_MCP_EARLY_EXIT_SUCCESSES` | ранний выход при стольких успехах | `4` |
| `TWOCAPTCHA_MCP_MIN_SUCCESSES` | минимум оценок для агрегата | `3` |
| `TWOCAPTCHA_MCP_HOST` / `TWOCAPTCHA_MCP_PORT` | адрес HTTP-сервера | `0.0.0.0` / `3000` |
| `TWOCAPTCHA_MCP_DATA_DIR` | каталог ndjson-архива (`""` — выкл.) | `~/.twocaptcha_mcp/` |

Ограничение на пороги: `1 ≤ MIN_SUCCESSES ≤ EARLY_EXIT_SUCCESSES ≤ PARALLEL_ATTEMPTS` (иначе fail-fast при старте).

## Разработка

```bash
make test       # unit-тесты (68)
make test-slow  # реальные вызовы API (тратят баланс!)
make lint       # ruff
make build      # wheel → dist/
make image      # wheel + Docker-образ
```

Архитектурные заметки для контрибьюторов — в [AGENTS.md](AGENTS.md).