Внешний доступ (CLI и ИИ-клиенты)

Внешний доступ позволяет локальным программам командной строки и ИИ-клиентам с поддержкой MCP управлять скриптами ScriptCat через sctl.

ИИ-клиент ── stdio MCP ──▶ sctl mcp ── локальный API ──▶ sctl serve ── WebSocket ──▶ ScriptCat
CLI ────────────────────────────────────────────────────▲

sctl serve — отдельный локальный демон, который нужно запускать явно. sctl mcp и команды-клиенты не запускают его автоматически. Решение о выдаче исходного кода и выполнении изменений всегда принимается политиками и окном подтверждения ScriptCat; внешняя программа не может одобрить собственный запрос.

Соединение остаётся локальным

sctl слушает только 127.0.0.1 и недоступен из локальной сети или интернета. Расширение подключается к демону, стороны создают долговременный ключ с помощью одноразового кода, а последующие соединения используют взаимную аутентификацию.

1. Установка sctl

sctl поставляется одним исполняемым файлом. Если на странице GitHub Releases опубликован архив для вашей платформы, скачайте и распакуйте его, затем добавьте sctl (sctl.exe в Windows) в PATH.

sctl version

Сейчас ScriptCat требует версию демона не ниже 0.1.0. Обычная сборка из исходников имеет версию 0.0.0-dev и отклоняется расширением. Пока готового релиза нет, разработчикам нужно собирать sctl с корректно заданной версией по инструкции репозитория. Обычный go install ...@latest не следует считать рабочей установкой.

2. Запуск демона и подключение

Подключение выполняется один раз. После него CLI и все MCP-клиенты используют общий доверенный канал между расширением и демоном; отдельное сопряжение каждому клиенту не требуется.

2.1 Выбор каталога данных

Демон, CLI и процесс MCP должны использовать один каталог данных. В нём хранятся долговременный ключ, локальный управляющий токен и журналы. Выберите абсолютный путь, доступный только текущему пользователю:

/absolute/path/to/sctl-data

Передавайте один и тот же аргумент каждому процессу:

sctl --data-dir /absolute/path/to/sctl-data serve
sctl --data-dir /absolute/path/to/sctl-data status
sctl --data-dir /absolute/path/to/sctl-data mcp

Без --data-dir используется стандартный пользовательский каталог платформы. Не размещайте его в репозитории или общей синхронизируемой папке и не передавайте модели ИИ файлы pairing.key и control.token.

2.2 Запуск демона

Запустите команду в терминале и оставьте процесс работающим:

sctl --data-dir /absolute/path/to/sctl-data serve

Адрес по умолчанию — ws://127.0.0.1:8643. Команды connect, status, другие команды CLI и sctl mcp никогда не запускают демон автоматически. Для постоянной работы используйте пользовательский менеджер служб операционной системы.

2.3 Включение и сопряжение в ScriptCat

1. Откройте Настройки → Инструменты → Внешний доступ в ScriptCat и включите переключатель.

2. Убедитесь, что адрес sctl совпадает с демоном; обычно оставьте ws://127.0.0.1:8643.

3. Не останавливая sctl serve, выполните в другом терминале:

   sctl --data-dir /absolute/path/to/sctl-data connect

4. Введите 8-значный код из терминала в диалоге подключения sctl.

5. Проверьте соединение:

   sctl --data-dir /absolute/path/to/sctl-data status

Статус должен сообщить о подключённом расширении и показать версию демона.

Код сопряжения показывается только в терминале

Код выглядит как A1B2-C3D4, действует 2 минуты и используется один раз. Он не передаётся расширению через WebSocket. Не вставляйте его в чат с ИИ, issue, журнал или конфигурацию MCP; после истечения срока снова выполните connect.

3. Разрешения и подтверждение

Возможность	Поведение по умолчанию
Список скриптов и метаданные	Возвращаются сразу
Чтение или поиск исходного кода	Политика чтения исходного кода
Установка, редактирование, включение, отключение или удаление	Политика изменений

Для обеих политик доступны режимы «Требовать подтверждение» (по умолчанию) и «Разрешать напрямую».

При требовании подтверждения запрос открывает страницу в браузере. Его можно отклонить, разрешить один раз или выбрать «Разрешить в этом сеансе». Сеансовое разрешение привязано к скрипту и типу операции и удаляется после перезапуска браузера, перезагрузки расширения или остановки внешнего доступа. Без решения запрос истекает через 5 минут; отключение клиента или Ctrl-C также аннулирует его.

Режим «Разрешать напрямую» пропускает страницу подтверждения. Исходный код может содержать API-ключи, cookie и другие секреты, а изменения непосредственно меняют скрипты — включайте этот режим только осознанно.

4. Использование командной строки

sctl --data-dir <путь> get                         # Список скриптов
sctl --data-dir <путь> get <uuid>                  # Метаданные
sctl --data-dir <путь> get <uuid> -o source        # Весь исходный код
sctl --data-dir <путь> get <uuid> -o source --lines 20-80
sctl --data-dir <путь> grep <uuid> "fetch("         # Буквальный поиск
sctl --data-dir <путь> grep <uuid> "pattern" -E    # Регулярное выражение
sctl --data-dir <путь> install <url|файл>
sctl --data-dir <путь> edit <uuid> --replace OLD --with NEW
sctl --data-dir <путь> enable <uuid>
sctl --data-dir <путь> disable <uuid>
sctl --data-dir <путь> delete <uuid>
sctl --data-dir <путь> status

grep по умолчанию ищет буквальную строку; -E включает регулярные выражения, -i игнорирует регистр, -C N добавляет контекст, а -m N ограничивает число совпадений. Отсутствие совпадений не является ошибкой и возвращает код 0.

edit привязывает правку к содержимому, а не к номеру строки. По умолчанию каждый oldText должен встречаться ровно один раз; --replace-all заменяет все совпадения. Массив {oldText,newText,replaceAll?} можно передать через -f <файл>. Расширению отправляются только правки — предварительно читать или загружать весь исходник не нужно.

Изменения и выдача исходного кода ожидают решения в браузере. Коды завершения CLI:

Код	Значение
0	Запрос одобрен и выполнен либо команда чтения завершилась нормально
1	Пользователь отклонил запрос
2	Запрос истёк, отменён через Ctrl-C или расширение отключилось
3	Другие ошибки: аргументы, соединение, отсутствующий скрипт и т. п.

Все параметры доступны через sctl <команда> --help.

5. Подключение ИИ-клиента (MCP)

Сначала убедитесь, что sctl serve работает, а status показывает подключённое расширение. Затем настройте MCP-клиент на запуск отдельного процесса sctl mcp. В графических клиентах используйте абсолютные пути:

{
  "mcpServers": {
    "scriptcat": {
      "command": "/absolute/path/to/sctl",
      "args": [
        "--data-dir",
        "/absolute/path/to/sctl-data",
        "mcp",
        "--name",
        "my-ai-client"
      ]
    }
  }
}

Многие графические приложения не раскрывают ~, $HOME и выражения оболочки. --name — только метка аудита, а не аутентифицированная личность или граница авторизации. stdout процесса MCP предназначен для кадров протокола; не запускайте sctl через обёртку, печатающую баннер в stdout.

Доступные инструменты:

Инструмент	Назначение	Политика подтверждения
scripts_list	Список скриптов	Нет
scripts_metadata_get	Метаданные одного скрипта	Нет
scripts_source_get	Исходник по uuid и необязательному диапазону строк	Чтение исходника
scripts_source_grep	Поиск по исходнику с возвратом совпавших строк	Чтение исходника
scripts_install_request	Запрос установки	Изменения
scripts_edit_request	Запрос правки с привязкой к содержимому	Изменения
scripts_toggle_request	Запрос включения или отключения	Изменения
scripts_delete_request	Запрос удаления	Изменения

6. Аудит и отзыв доступа

• «Просмотреть журнал аудита» в карточке внешнего доступа открывает отфильтрованную страницу журнала.
• sctl --data-dir <путь> status показывает версию демона, соединение с расширением и недавние события безопасности; -o json возвращает полные события.
• «Остановить внешний доступ» разрывает соединение, удаляет состояние сопряжения расширения и очищает сеансовые разрешения. Для продолжения потребуется новое сопряжение.
• Чтобы отключить только одного ИИ-клиента, удалите sctl из его конфигурации MCP; остальные CLI и клиенты продолжат работать.

7. Устранение неполадок

Демон недоступен

Сначала выполните sctl --data-dir <тот-же-путь> serve. Команды-клиенты не запускают демон автоматически.

Ошибка аутентификации управляющего канала

Убедитесь, что serve, CLI и MCP используют один и тот же абсолютный --data-dir, затем перезапустите MCP-клиент.

Статус сообщает об ошибке соединения

Проверьте, что демон работает, адрес расширения совпадает с ним, а защитное ПО не блокирует 127.0.0.1:8643.

ScriptCat сообщает, что версия sctl устарела

Установите релиз не ниже минимума из sctl version; не используйте сборку 0.0.0-dev без заданной версии.

Команда долго не завершается

Проверьте страницу подтверждения выдачи исходника или изменения в браузере. Ctrl-C аннулирует запрос.

Расположение журналов

Журналы находятся в <data-dir>/logs/. Без --data-dir используются:

Платформа	Каталог журналов
macOS	~/Library/Application Support/sctl/logs/
Windows	%LOCALAPPDATA%\sctl\logs\
Linux	~/.config/sctl/logs/