MCP-сервер и набор навыков — документация Vflin

Для ИИ-агента, который ведёт Vflin по MCP. Это метод (результат 4 в AGENT_TOOLING_STRATEGY.md (internal: docs/20-control-plane/AGENT_TOOLING_STRATEGY.md)) — порядок работы, правила безопасности и идиомы, — чтобы агент пользовался инструментами хорошо, а не выдумывал процедуры и не спотыкался о шлюз опасности. Самого списка инструментов здесь нет (он бы разошёлся): вызовите tools/list и получите живой достоверный набор (описание каждого инструмента несёт его уровень опасности, требуемый режим и — для долгих операций — инструмент статуса, который надо опрашивать). Установка и настройка под каждого клиента: crates/vflin-mcp/README.md (internal: crates/vflin-mcp/README.md).

Что такое Vflin

Операционная система браузерных профилей: антидетект-профили (подписанные зашифрованные блобы), запускаемые на браузерном ядре, с автоматизацией (скрипты и графы, группы задач, расписания, наборы данных), синхронизацией и хабом. Каждый инструмент — тонкая обёртка один к одному над Local API (ADR-0003): чего не может CLI vflin, того не можете и вы.

Метод: Audit → Plan → Act

Audit — сначала читайте, потом пишите. system.health, profile.list, automation.script.list, automation.run.list — только чтение (зелёные), их можно звать свободно. Узнайте id, прежде чем что-то с ними делать.
Plan — назовите те несколько изменяющих вызовов, которые собираетесь сделать. Изменяющие инструменты вызываются явно, а не как побочный эффект чтения.
Act — сделайте изменение, затем проверьте (перечитайте или опросите). Не считайте, что получилось; смотрите на конверт.

Безопасность: режим сессии и уровни опасности

У каждого инструмента есть уровень опасности (в его описании в tools/list), и он работает под режимом сессии (VFLIN_MCP_MODE, задаёт оператор): read-only < normal < trusted.

опасность	нужен режим	примеры
зелёный (только чтение)	`read-only`	`system.health`, `.list`, `.get`, `*.status`
жёлтый (изменяющий)	`normal`	`profile.create`, `profile.start`, `automation.run.start`, `cloud.push`
красный (опасный)	`trusted`	`profile.cdp.attach`, `profile.session.set` / `clear`, `cloud.twofa.disable`, `cloud.devices.revoke` (A90)

Инструменту выше режима сессии отказывают до любого вызова демона — isError:true и nextSteps, который говорит оператору, какой VFLIN_MCP_MODE поставить. Не повторяйте тот же вызов: попросите оператора поднять режим или возьмите вариант только для чтения. initialize сразу сообщает действующий режим.
Считайте отказ сигналом политики, а не временной ошибкой.

Где находится демон (установленный продукт, A88)

vflin-mcp читает файл обнаружения Local API $VFLIN_HOME/local-api.json, иначе ~/.vflin/local-api.json — тот же корень, который пишет демон и читают оболочка и CLI; %LOCALAPPDATA%\VFlin не использует ничто. Установленный продукт кладёт сервер рядом с приложением: %LOCALAPPDATA%\VFlin Antikflin-mcp.exe — именно на него указывает поле command в записи mcpServers MCP-клиента (этой папки нет в PATH). Сам демон запускает приложение при старте, и он остаётся работать после закрытия окна; если ни один демон не отвечает, приложение (или vflind.exe из той же папки) запускает его — MCP-сервер демон не запускает никогда.

Как получить CDP на профиле (A89)

Не ищите порт: по умолчанию его нет. Запустите профиль, затем vflin_profile_cdp_attach (нужен VFLIN_MCP_MODE=trusted — попросите оператора; тот же вызов не повторяйте) и ведите возвращённый wsEndpoint своим CDP-клиентом; он обслуживает одного клиента и истекает — по окончании вызовите vflin_profile_cdp_detach. Профиль, в подробностях которого сказано cdpTransport: port, публикует свой порт каждому локальному процессу; читайте brokered:false как этот факт, а не как удобство.

Облачный аккаунт (A90)

Всё, что делает кабинет на сайте, здесь — инструмент: vflin_cloud_account_get (зелёный), смена пароля и подключение двухэтапной проверки (жёлтые, power) и два красных — vflin_cloud_twofa_disable и vflin_cloud_devices_revoke, — которым отказывают до любого вызова демона ниже VFLIN_MCP_MODE=trusted (измерено: отказ называет инструмент, его уровень и режим). Секрет подключения возвращается ОДИН раз и никогда не пишется в журнал; неверный код — это TOTP_INVALID от облака. Отозванное устройство выпадает из списка сразу; токен доступа, который у него уже есть, живёт ещё не больше 15 минут (контракт сервера) — не читайте всё ещё отвечающее устройство как «не отозванное». Отозвать ЭТО устройство можно, и демон выходит сам (signedOutHere). vflin_cloud_compare — то чтение, которое стоит сделать перед push или pull: same, localNewer, cloudNewer, diverged, localOnly — без блокировки и без скачивания. Адрес облака — это настройка (vflin_settings_set {cloudUrl}); VFLIN_CLOUD_URL в окружении демона её перекрывает, и settings.get об этом говорит (cloudUrlSource: env).

Опрашивайте, не блокируйтесь

Долгие инструменты (например, automation.run.start, automation.taskgroup.run) сразу возвращают id и ставят работу в очередь. В их результате summary/nextSteps называют инструмент статуса, который надо опрашивать (например, automation.run.status с {id}). Опрашивайте его до конечного состояния (succeeded/failed) — никогда не считайте, что уже готово, и никогда не занимайте оператора ожиданием. В описании инструмента в tools/list помечено, что он долгий.

Как читать результаты

Каждый результат — это JSON в текстовом блоке: { "summary": …, "envelope": { ok, data } } при успехе или { "summary": …, "ok": false, "error": …, "nextSteps"? : … } при неудаче (isError:true). Читайте сначала summary, затем data за подробностями.

Что делать при неудаче (подсказки `nextSteps`)

При исправимой ошибке результат несёт nextSteps, привязанный к коду демона:

код	что значит	что делать
`NOT_FOUND`	такого id нет	вызовите соответствующий `*.list` и возьмите верный id
`LOCKED`	криптосессия заперта	сначала `session.unlock`, затем повторите
`LOCKED_REMOTE`	профиль держит другое устройство	посмотрите статус его синхронизационной блокировки, затем повторите
`UNAUTHENTICATED`	нет аутентификации в облаке или в сессии	сначала `cloud.login` (или `session.unlock`)
`POLICY_DENIED`	политика демона отказала	нужен более высокий режим политики
`TOTP_REQUIRED`/`TOTP_INVALID`	нужна 2FA	вызовите снова с актуальным `totpCode`
`STALE`/`CONFLICT`	это изменило другое устройство	заберите свежее (pull/refresh), затем повторите

Рецепты (живые имена инструментов — в `tools/list`)

Выполнить скрипт на одном профиле: profile.list → automation.script.list → automation.run.start (id) → опрашивайте automation.run.status до конечного состояния → читайте выводы (automation.run.artifact, если есть).
Разослать скрипт по N профилям: automation.taskgroup.run с id профилей (id) → опрашивайте automation.taskgroup.get, пока каждый запуск не станет конечным.
Создать и запустить профиль: profile.create → profile.start (возвращает эндпоинт CDP).

Жёсткие правила

Никогда не выдумывайте инструмент — существует только то, что вернул tools/list.
Никогда не повторяйте отказ политики: поднимайте режим или меняйте подход.
Никогда не блокируйтесь на долгой операции — опрашивайте её инструмент статуса.
Профиль в состоянии RUNNING никогда не синхронизируется; демон это соблюдает — не боритесь с ним.