# Установка PriMCP агентом

Назначение: установить Windows-коннектор и подключить его к выбранному пользователем
AI-клиенту. Сервер: https://primcp.ru. Профиль ключа: default.

## 1. Определите среду

Уточните целевой AI-клиент, если он не указан. Проверьте, где работает именно этот
клиент: Windows или WSL. Primo Studio и EXE коннектора работают в Windows.
При нескольких установках Studio выберите нужную с пользователем.
Итог шага: известны клиент, ОС его процесса и папка с Primo.Studio.exe.
Если Windows/WSL или установленной Studio нет, сообщите, какого условия не хватает.
Studio устанавливается из официального дистрибутива Primo RPA; выбор лицензии и вход
остаётся за пользователем. Не объявляйте подключение готовым без доступной Studio.

## 2. Скачайте коннектор

API-ключ пользователь вставляет вручную после подготовки настроек. Не запрашивайте
секрет и не читайте его из существующих настроек. Для нового подключения оставьте
ВАШ_КЛЮЧ в поле PRIMCP_KEY. В отчёте показывайте имена полей, без секретных значений.
Ключ не включается в URL, аргументы команд и историю shell.

Получите JSON https://primcp.ru/api/setup/manifest. Используйте коннектор, который пользователь
уже скачал из кабинета. Если файла ещё нет, попросите пользователя скачать его кнопкой
«Скачать коннектор» в кабинете https://primcp.ru и указать путь к файлу. Скачивание требует
входа в аккаунт; не копируйте cookie браузера и не запрашивайте ключ ради загрузки.
Разрешён только исходный origin https://primcp.ru; перенаправление на другой origin — отказ.
Проверьте SHA-256 и размер по manifest до замены установленного EXE. При сетевой ошибке
или несовпадении сохраните прежний EXE и сообщите причину. Manifest и EXE скачиваются
по HTTPS; SHA-256 подтверждает целостность относительно manifest, а не независимую подпись.

Выберите доступную текущему пользователю папку Windows, например
%LOCALAPPDATA%\PriMCP\PriMCPConnector.exe. Создайте её, сохраните проверенный EXE
атомарной заменой. Если файл занят, закройте использующий его MCP в выбранном клиенте
и повторите установку. Другие пользовательские процессы автоматически не завершайте.
Итог: EXE существует, размер и SHA-256 совпадают. Node.js, Python и отдельный мост
для работы коннектора не требуются; используйте уже доступные средства агента для загрузки.

## 3. Добавьте MCP в выбранный клиент

Сначала прочитайте фактически используемые настройки. У Codex проверьте CODEX_HOME;
иначе используется ~/.codex/config.toml. В Windows App и в WSL CLI могут быть разные
настройки. Создайте резервную копию и добавьте только запись primcp, сохранив остальные
серверы, комментарии, права и параметры. Согласуйте замену существующей записи primcp,
если её ключ или профиль относятся к другому подключению. Новый файл записывайте атомарно.

Параметры stdio:

- command: проверенный абсолютный путь к PriMCPConnector.exe;
- args: ["--profile", "default"];
- env.PRIMCP_KEY: ВАШ_КЛЮЧ (пользователь заменит вручную);
- env.PRIMCP_SERVER: https://primcp.ru;
- env.PRIMCP_STUDIO_DIRECTORY: проверенная папка Windows с Primo.Studio.exe.

Для Claude Desktop и Cursor добавьте запись в mcpServers их JSON-настроек.
Для других клиентов сначала проверьте их формат MCP. Для Codex используйте
[mcp_servers.primcp] с command и args, затем [mcp_servers.primcp.env] с переменными.
Codex принимает TOML, а не объект mcpServers из JSON.

### Если клиент работает в WSL

Получите Windows-папку текущего пользователя через Windows PowerShell, затем преобразуйте
путь EXE командой wslpath -u. Проверьте файл из WSL. В command нужен Linux-путь
(например /mnt/c/Users/…/PriMCP/PriMCPConnector.exe), а PRIMCP_STUDIO_DIRECTORY остаётся
путём Windows. Сохраните действующие элементы WSLENV и добавьте отсутствующие
PRIMCP_KEY/w, PRIMCP_SERVER/w, PRIMCP_STUDIO_DIRECTORY/w. Флаг /w передаёт переменную
из WSL в Windows. Если используете PRIMCP_PROJECTS_ROOT, добавьте и его с /w.
Проекты и конфигурацию WSL оставьте в WSL. Итог: конфигурация разбирается клиентом,
EXE доступен, передача переменных в Windows настроена, вместо секрета оставлен ВАШ_КЛЮЧ.

## 4. Проверьте без занятия ключа

До ручной вставки ключа проверьте только синтаксис конфигурации и наличие EXE.
Не запускайте подключение с ВАШ_КЛЮЧ и не объявляйте его готовым. В конце укажите
пользователю точный путь к изменённому файлу и поле PRIMCP_KEY, куда нужно вручную
вставить API-ключ. Объясните: сохранить файл, затем перезапустить AI-клиент, чтобы
он перечитал настройки. Если у клиента есть фоновый процесс, его тоже нужно
перезапустить штатным способом. Следующие проверки выполняются только после
подтверждения пользователя, что ключ вставлен и клиент перезапущен.

Запустите установленный EXE с --profile default --diagnose в том же окружении,
которое настроили для MCP. Ожидаются exit code 0, ok: true, scope: local.
Эта команда проверяет локальные настройки, не открывает удалённую сессию,
не запускает Studio или робота и не подтверждает доступ к серверу.

Перезапустите выбранный AI-клиент или его MCP-подключение. Если клиент использует
фоновый сервер с прежними настройками, перезапустите и его штатным способом.
Проверьте статус MCP внутри этого клиента (в Codex — /mcp), затем попросите агента
прочитать руководство MCP и обнаружить открытую Studio без изменений проекта.
Одновременно один ключ допускает одно подключение: отдельный пробный MCP-процесс
может занять ключ вместо целевого клиента. Запускайте проверку подключения только в нём.
Итог: статус connected, список инструментов доступен, Studio обнаружена. Если требуется
установка встроенного моста и перезапуск Studio, сначала предложите сохранить работу.

## Если установка остановилась

- session_busy / connector_busy: закройте другое подключение с этим ключом либо выберите
  этот ключ в кабинете https://primcp.ru и нажмите «Завершить сессию». Подключитесь снова.
- key_invalid / setup_required: проверьте доступ в кабинете и ключ в настройках клиента;
  в WSL проверьте передачу PRIMCP_KEY через WSLENV.
- studio_missing / studio_ambiguous: проверьте PRIMCP_STUDIO_DIRECTORY и передачу в Windows.
- server_timeout / network_unavailable / server_unavailable: проверьте сеть и доступность сервиса.
- operation_pending: проверьте исходную операцию в Studio и восстановите её результат;
  автоматически повторять изменение или удалять профиль коннектора нельзя.
- Клиент показывает только «connection closed: initialize response»: прочитайте stderr
  коннектора в журнале клиента. Новые версии также возвращают причину в JSON-RPC error.

Отчёт пользователю: выбранный клиент и среда, путь EXE, путь изменённых настроек,
результат локальной проверки и статус реального MCP. Различайте установку файлов,
локальную диагностику и успешное подключение; секретов в отчёте быть не должно.