Skills: каталог и выполнение на сервере

Лицензия MCPBox остаётся Apache-2.0. Сторонние навыки сохраняют собственные лицензии и авторство. Существующие данные SkillBox автоматически не изменяются и не удаляются.

Пользовательский сценарий

1. Откройте Skills в меню. Каталог поддерживает поиск по названию, описанию, автору и фильтр категорий. В бинарник включён начальный снимок каталога; кнопка обновления загружает https://mcpbox.sh/skills.json. Можно указать другой HTTPS URL или загрузить JSON. Ошибка обновления сохраняет предыдущий каталог. Скачанные версии и привязки проектов автоматически не обновляются.
2. Скачайте навык из каталога, импортируйте GitHub-репозиторий с указанием папки навыка или загрузите ZIP. В ZIP файл SKILL.md должен быть в корне либо в явно указанной папке. При импорте команды npx, скрипты и установочные хуки пакета не запускаются.
3. Просмотрите файлы, источник, commit, требования и результаты проверки. Сохраняется весь пакет: SKILL.md, скрипты, справочники, шаблоны и остальные ресурсы. Проверка не доказывает безопасность. Если требования не указаны, они считаются неизвестными.
4. В проекте откройте вкладку Skills, нажмите + и подключите скачанную версию. Один пакет доступен нескольким проектам. Новая версия устанавливается отдельно. Дублирование проекта копирует привязки, но не задания и файлы.
5. Для выполнения скриптов администратор открывает пакет в библиотеке и настраивает профиль: Python, Node.js или Bash, Docker-образ, разрешённые скрипты, таймаут и доступ к сети. Затем сохраняет профиль и нажимает Подготовить окружение. Подготовка скачивает образ и при необходимости устанавливает зависимости в сборочном контейнере: это явное действие, допускающее сеть и выполнение кода сборки зависимостей. При запуске задания зависимости не устанавливаются.
6. Создайте задание в проекте, загрузите входные файлы и запустите разрешённый скрипт. Аргументы задаются JSON-массивом, например ["input.csv", "output.txt"]. Рабочая папка на сервере — /work. Результаты скачиваются из задания. Загрузка разрешена только до первого запуска; для повторного выполнения создайте новое задание.

Серверное окружение

Docker должен быть установлен и запущен на сервере MCPBox. Python и Node.js на хосте не требуются. Каталог и инструкции работают без Docker.

Начальные образы: python:3.12-slim, node:22-bookworm-slim, debian:bookworm-slim для Bash. После подготовки сохраняется неизменяемый ID Docker-образа. Можно указать собственный образ с системными программами, браузером и дополнительными библиотеками.

Python поддерживает установку из requirements-файла .txt; Node.js — из package-lock.json в корне командой npm ci --ignore-scripts. Если необходимы lifecycle-скрипты или другие установочные действия, используйте заранее собранный образ. Изменение профиля сбрасывает готовность окружения. Включение выполнения разрешает его всем проектам, подключившим эту версию навыка.

Контейнер работает без root, с файловой системой только для чтения, без capabilities, с no-new-privileges, ограничениями CPU, памяти, процессов и размера файла. Сеть по умолчанию отключена. Исходный пакет доступен только для чтения в /package; /work содержит только файлы задания. Образы с зависимостями также содержат пакет в /skill: скрипты запускаются оттуда для корректного поиска модулей. Папки проектов хоста, Docker socket и секреты окружения MCPBox не передаются. Аргументы передаются интерпретатору напрямую, без сборки shell-команды. Эти ограничения не превращают сторонний код в доверенный.

Лимиты: 32 МиБ на файл, 128 МиБ на пакет/задание, 2000 файлов, 100 сохранённых заданий на проект, 1–300 секунд на запуск, по 1 МиБ stdout/stderr, 512 МиБ RAM, 1 CPU, 128 процессов. Суммарный размер папки проверяется во время выполнения; это мониторинг, а не файловая квота, поэтому возможно кратковременное превышение. Для освобождения места удаляйте старые задания. Переходы за корень, symlink, специальные файлы и дублирующиеся пути ZIP запрещены. Перед подготовкой и выполнением проверяется хеш пакета.

При таймауте или обрыве запроса MCPBox принудительно удаляет контейнер. Если остановку подтвердить нельзя, задание остаётся заблокированным в состоянии выполнения и файлы не выдаются. Перезапуск MCPBox при работающем Docker восстанавливает незавершённые задания. Сам MCPBox не управляет запуском Docker.

Хранение и перенос

skill_store/ располагается в каталоге данных MCPBox, обычно рядом с БД, независимо от рабочей папки запуска. packages/<id-версии>/ содержит полный пакет; jobs/<id-проекта>/<id-задания>/ — входные и выходные файлы. В SQLite хранятся кэш каталога, метаданные версий, привязки, профили запуска и история заданий. Резервная копия должна включать БД и skill_store. Данные исключены из Git.

Удаление пакета запрещено, пока он подключён к проектам. Удаление проекта убирает привязки и записи заданий, но намеренно сохраняет файлы заданий для восстановления оператором. Неиспользуемые папки удаляются отдельно после проверки резервной копии. Работающее задание блокирует удаление проекта. Для переноса из SkillBox импортируйте экспортированные ZIP-пакеты и явно назначьте проекты. Автоматического объединения БД нет.

Отключение навыка от проекта запрещено, пока в этом проекте есть его задания, включая ещё не запущенные. Дождитесь завершения работающих заданий, скачайте нужные файлы, явно удалите задания и затем отключите навык. Задания, оставшиеся после отключения в старой версии, можно удалить из списка заданий проекта.

Передача через MCP

Инструменты появляются в существующем проектном MCP-подключении после подключения Skills. Проект только со Skills тоже считается готовым к подключению. Применяются существующие token, bearer/OAuth и приостановка проекта.

Инструмент	Назначение
list_skills	Поиск среди подключённых к проекту версий
get_skill	Полный SKILL.md, требования, профиль и список файлов
read_skill_file	Чтение текстового ресурса пакета до 1 МиБ
create_skill_job	Создание серверного задания
upload_skill_file	Передача base64 входного файла до 1 МиБ через MCP
run_skill_script	Запуск разрешённого скрипта в подготовленном окружении
get_skill_job	Статус, вывод и список файлов задания
read_skill_job_file	Скачивание base64 частями до 256 КиБ через offset/limit

Клиент должен передать сами байты документа: локальный путь компьютера пользователя серверу недоступен. Более крупные файлы загружаются в админке, до 32 МиБ на файл. Чат-клиент должен реализовать собственную интеграцию вложений; MCP автоматически не загружает документы пользователя. Клиент/агент также решает, когда вызвать поиск: подключение навыка не гарантирует его автоматического применения каждым клиентом.

Обнаружение инструментов и обновление подключения

Инструменты Skills включаются в tools/list, только пока к проекту подключена хотя бы одна версия навыка. Подсказка initialize о list_skills также отсутствует у проектов без Skills. Одного скачивания пакета недостаточно для появления инструментов в проекте.

После изменения привязок сервер отправляет notifications/tools/list_changed активным MCP SSE-сессиям этого проекта; initialize объявляет tools.listChanged. Повторное сохранение неизменившейся привязки уведомления не создаёт. Клиенты с динамическим обнаружением могут перечитать каталог. Если клиент импортирует или кэширует определения и не слушает уведомления, обновите каталог инструментов подключения либо переподключите его. Вызывать list_skills на каждое сообщение пользователя не требуется.

Если навык виден в MCPBox, но отсутствует в чате, сравните свежий ответ tools/list именно этого endpoint проекта со списком, импортированным клиентом. Проверьте endpoint, listener/порт и запущенный бинарник: другой экземпляр сервера или сохранённый каталог клиента может отличаться от интерфейса. Серверные тесты не подтверждают обновление инструментов стороннего коннектора.

API и права

Чтение требует pro:read. Изменение каталога, пакетов и профилей — pro:admin. Создание заданий, загрузка и запуск используют pro:write; удаление — pro:admin. Разрешение выполнения задаёт администратор, а не аргумент модели.

• GET /api/skills, /api/skills/catalog, /api/skills/runtime
• POST /api/skills/catalog/sync: url либо JSON-объект content
• POST /api/skills/install: catalog_id либо source: { repository, path, ref?, commit? }
• POST /api/skills/import: multipart file и необязательный path
• GET /api/skills/{id}/file?path=SKILL.md
• PUT /api/skills/{id}/profile, POST /api/skills/{id}/prepare, DELETE /api/skills/{id}
• GET /api/projects/{id}/skills; PUT/DELETE /api/projects/{id}/skills/{skill-id}
• GET/POST /api/projects/{id}/skill-jobs; создание принимает skill_id
• GET/DELETE /api/projects/{id}/skill-jobs/{job-id}
• POST …/skill-jobs/{job-id}/files: multipart file
• POST …/skill-jobs/{job-id}/run: script, массив args
• GET …/skill-jobs/{job-id}/file?path=output.txt: скачивание с авторизацией

Сборка центрального каталога

GOWORK=off go run ./cmd/skills-catalog --out skills.json

Сборщик обходит страницы каталога, категорий и навыков https://mcpservers.org/ru/agent-skills, получает репозитории без выполнения установочных команд, фиксирует commit и читает метаданные пакетов из GitHub ZIP. При превышении --max-pages сборка завершается ошибкой вместо публикации неполного результата. Ошибки не перезаписывают предыдущий JSON.

Источник может требовать Cloudflare-проверку. Предусмотрен HTML-экспорт через --html directory.html либо явный список репозиториев:

GOWORK=off go run ./cmd/skills-catalog \
  --repositories https://github.com/anthropics/skills,https://github.com/openai/skills,https://github.com/lllllllama/rigorpilot-skills \
  --out skills.json

GITHUB_TOKEN необязателен и позволяет использовать авторизованные лимиты API. Полученный файл нужно проверить и опубликовать как https://mcpbox.sh/skills.json обычным способом развёртывания сайта. Этот checkout сайт не публикует. Начальный встроенный снимок — internal/skills/catalog_seed.json: 1174 навыка из 29 репозиториев. Его можно пересобрать той же командой для следующей сборки бинарника.

Индексируются корректные пакеты Skills из обнаруженных репозиториев. Наличие в каталоге не означает готовность любого навыка к серверному выполнению: окружение готовится отдельно для установленной версии.

Проверки

GOWORK=off go test ./internal/skills ./internal/httpapi ./internal/storage ./cmd/skills-catalog
MCPBOX_TEST_DOCKER=1 GOWORK=off go test ./internal/skills -run TestRealDockerInputOutput -v
(cd html && npm run build)

При импорте вложенного навыка из GitHub корневые LICENSE/NOTICE репозитория сохраняются в .mcpbox-origin/.

Повторное обновление парсером, сохранённые HTML, кэш и отчёты: инструкция парсера. Редактируемый список источников: catalog/skills-sources.txt. По умолчанию commit определяется через git; для GitHub API используйте --resolve-with api.