afina-mcp

MCP-сервер для Afina — антидетект-браузера. Подключает любой LLM (через MCP-совместимый клиент: Claude Desktop, Claude Code, Cursor, Cline, Continue и др.) к десктопному приложению Afina и даёт LLM возможность управлять аккаунтами, писать/тестировать/запускать RPA-скрипты и модули, ставить задачи с расписанием, работать с прокси/базами/переменными — всё через диалог.

⚠️ Требуется запущенное десктоп-приложение Afina с включённым API key (Settings → API key). MCP-сервер — это бридж к локальному HTTP API Afina на http://127.0.0.1:50778. Без приложения tools будут падать с ECONNREFUSED.

Что умеет

• 👤 Аккаунты (полный CRUD) — list/get/create (с авто-генерацией фингерпринта)/update/soft-delete/hard-delete. Прокси, теги, группы, шумы фингерпринта, экран, startup URLs, per-account настройки.
• 🌐 Управление браузером — старт/стоп профиля, eval_in_browser (JS в контексте страницы), find_clickable/find_input (найти элемент по тексту — селекторы не угадываются вслепую), get_page_text, take_screenshot.
• 🔑 Переменные аккаунта — plain (account.settings) и зашифрованные (account_data_blob): get/set/delete отдельных ключей. Зашифрованные расшифровываются executor'ом перед запуском скрипта.
• ✍️ RPA-скрипты — list/get/create/update/run/stop. LLM генерирует JSON { elements, connections, startElement }, который Afina исполняет тем же executor'ом что и UI-built скрипты. Есть валидатор + автозаполнение label/targetPosition.
• 🧩 RPA-модули (executeModule) — list/get/create/update/resign/delete/hard-delete. Создал модуль → правишь файлы в moduleDirAbs напрямую (Read/Edit/Write хоста) → resign_module (обязательно — иначе executor не запустит).
• ⏰ Задачи и группы задач — полный контроль как из UI: расписание (окно времени суток / часов), повторы, таймауты, лимит параллелизма, отложенный запуск (executeAt с natural-language: "in 5m", "tomorrow 09:00", "2026-05-11 14:30"). run_script_on_accounts — идемпотентный композитный запуск на N аккаунтах.
• 🪵 Логи — чтение лога задачи/запуска по uuid, отслеживание прогресса в реальном времени.
• 🛡 Прокси — проверка (с UDP-тестом для socks5), bulk-аудит, добавление с прогрев-проверкой. Обновляет proxy и per-account proxy_usage кэш.
• 🗄 Базы данных — подключения для RPA-блока database: list/get/create/update/delete/hard-delete (SQLite/Postgres/MySQL/etc).
• 📊 Глобальные переменные (${name} в скриптах) и Keys Catalog — list/create/update/delete.
• 📧 Email (IMAP) — список credentials, включить/выключить мониторинг.

Всего ~67 tools. Полный список с параметрами — docs/TOOLS.md.

Установка

1. Получи API key

В десктопном приложении Afina: Settings → API key. Скопируй.

2. Подключи к MCP-клиенту

Claude Desktop (macOS / Windows)

Открой конфиг:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "afina": {
      "command": "npx",
      "args": ["-y", "afina-mcp"],
      "env": {
        "AFINA_URL": "http://127.0.0.1:50778",
        "AFINA_API_KEY": "<твой ключ>"
      }
    }
  }
}

Перезапусти Claude Desktop. Должна появиться иконка молотка с tools от Afina.

Claude Code (CLI)

claude mcp add afina \
  -e AFINA_API_KEY=<твой ключ> \
  -e AFINA_URL=http://127.0.0.1:50778 \
  -- npx -y afina-mcp

Cursor

.cursor/mcp.json в корне проекта (или ~/.cursor/mcp.json глобально):

{
  "mcpServers": {
    "afina": {
      "command": "npx",
      "args": ["-y", "afina-mcp"],
      "env": { "AFINA_API_KEY": "<твой ключ>" }
    }
  }
}

Cline / Continue / другие

Любой MCP-клиент с stdio-транспортом: command: npx, args: ["-y", "afina-mcp"], env AFINA_API_KEY (+ опц. AFINA_URL).

Конфигурация (env)

| Переменная | Default | Описание | |---|---|---| | AFINA_URL | http://127.0.0.1:50778 | Базовый URL Afina HTTP API. | | AFINA_API_KEY | — (required) | Ключ из Settings → API key. | | AFINA_MCP_EVAL_ENABLED | 1 | Поставь 0 чтобы выключить eval_in_browser (даёт LLM полный JS-доступ к страницам). |

Resources

• afina://docs/rpa-blocks — markdown-каталог всех RPA-блоков с параметрами и JSON-примерами + ПРАВИЛА формата хранения (left/top, targetPosition обязателен, и т.д.). LLM обязан прочитать ЭТО прежде чем писать скрипт.
• afina://docs/script-schema — JSON Schema для script.settings.

Документация

• docs/TOOLS.md — полный справочник всех tools с параметрами.
• docs/PUBLISHING.md — как опубликовать в npm и реестры MCP.
• docs/WHAT_WAS_BUILT.md — что сделано, архитектура, история.
• HTTP API Afina (бэкенд): AfinaTauri/docs/API/README.md в основном репо.

Разработка

npm install
npm run build          # tsc → dist/
npm run dev            # tsc --watch
node dist/index.js     # smoke-тест (запустится на stdio, ждёт MCP-сообщений)

После любого изменения кода — npm run build, потом рестарт MCP-клиента (он перечитает dist/).

Структура:

src/
  index.ts            — entrypoint, регистрация tools + resources
  client.ts           — HTTP-клиент к Afina API (axios + x-api-key)
  resources.ts        — afina://docs/* resources
  blocks-catalog.ts   — каталог RPA-блоков (для rpa-blocks resource)
  block-labels.ts     — мапа type → sidebar.X label
  script-validator.ts — валидация/автофикс script.settings
  tools/
    accounts.ts       — аккаунты CRUD + старт/стоп браузера
    browser.ts        — eval / find / screenshot
    data.ts           — databases / global vars / keys / account vars
    modules.ts        — RPA-модули CRUD + resign
    scripts.ts        — скрипты CRUD + run/stop
    tasks.ts          — задачи и группы задач (+ parseTime helper)
    proxies.ts        — прокси
    emails.ts         — IMAP credentials
    types.ts          — ToolDef interface

Лицензия

MIT.