Туча 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/попытка).

Related MCP server: Flightradar24 MCP Server (Cloud Run)

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

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:

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

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

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

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

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

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

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

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

Разработка

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

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