Руководство разработчика
Сборка и структура репозитория
MCPBox 1.4.0 — самостоятельный Go-модуль с одним React-интерфейсом и одной точкой запуска приложения. Команды сборки приведены в быстром старте.
| Путь | Назначение |
|---|---|
main.go | Сборка единого приложения, создание администратора и admin-команды. |
app/ | Runtime, сетевые настройки, startup hooks и рабочие пути. |
internal/httpapi/ | Базовый API, агрегация MCP, лаунчеры и встроенный интерфейс. |
internal/orchestrator/ | Процессы stdio, инспекция и проверки работоспособности. |
internal/storage/, internal/models/ | Общее хранилище SQLite и модели. |
internal/skills/ | Каталог, импорт, подключения версий, задания и Docker-выполнение Skills. |
internal/cli/ | Обнаружение CLI-каталога и выполнение разрешённых команд. |
internal/rag/ | Извлечение локальных документов и индексы Bleve. |
internal/proauth/, internal/prosso/, internal/prohttp/ | Доступ, OIDC и HTTP-маршруты интеграций. |
internal/proragbox/, internal/prostorage/ | Внешние сервисы и операционное хранилище. |
html/src/ | React/TypeScript-интерфейс и русская/английская локализация. |
Имена pro* сохранены для внутренней совместимости. Текущий бинарник подключает эти функции в main.go; прежняя функция runtime FreeEdition() не описывает полный состав распространяемого приложения.
Административный API
Защищённые запросы используют Authorization: Bearer <session-or-agent-token> на порту панели. GET /api/meta и GET /healthz возвращают публичные метаданные и доступность. Локальный вход: POST /api/pro/login с полями email и password; ответ содержит token сессии.
Основные маршруты (не полная схема API):
| Маршрут | Назначение |
|---|---|
GET /api/projects, POST /api/projects | Список и создание проектов. |
GET /api/catalog/items, POST /api/catalog/sync | Определения Маркета и синхронизация. |
GET /api/packages | Установленные пакеты. |
GET /api/rag/collections, POST /api/rag/collections | Локальные коллекции знаний. |
GET /api/cli, POST /api/cli | Реестр CLI. |
GET /api/cli/catalog, POST /api/cli/catalog/sync | Обнаружение CLI. |
POST /api/cli/catalog/{slug}/apply | Применение просмотренного определения с его revision. |
GET /api/projects/{id}/cli | Связи CLI проекта. |
POST /api/projects/{id}/cli/execute | Административное выполнение CLI. |
GET /api/pro/auth/me | Текущий авторизованный субъект. |
GET /api/pro/users, GET /api/pro/roles | Пользователи и роли. |
GET /api/pro/sessions, GET /api/pro/tokens | Сессии и токены агентов. |
GET /api/pro/storage/runtime-status | Выбранное и активное хранилище, статус fallback. |
GET /api/pro/ragbox/config | Настройки интеграций с маскированными представлениями секретов. |
GET /api/logs, GET /api/logs/metrics | Аудит и метрики. |
Права зависят от метода и маршрута; подробнее в разделе доступа. Успешный вход администратора не авторизует автоматически MCP-подключение проекта.
Транспорт и маршрутизация MCP
POST /mcp/<project-token> без sessionId работает как синхронный HTTP JSON-RPC. GET открывает прежний SSE-процесс с событием endpoint; последующие запросы используют POST с ?sessionId=.... /connect/<project-token> сохраняется как совместимый адрес.
MCPBox сам отвечает на initialize, объединяет tools/list, resources/list, prompts/list и направляет вызовы серверу-источнику. Ошибка отсутствия необязательного list-метода допускается, если сервер явно сообщает, что он не реализован. При совпадении имён используются стабильные псевдонимы. Отключённые серверы исключаются, запросы к приостановленному проекту блокируются.
Bearer/OAuth проекта и проверка необходимости миграции старых проектов выполняются до доступа к его возможностям. Вызовы CLI используют общий исполнитель, который повторно проверяет актуальные связи проекта и список разрешённых операций.
Пример выполнения CLI
Для разрешённой и подключённой к проекту записи Git с ID git:
{ "cli": "git", "command": "log", "args": ["-n", "5"] }Весь набор аргументов должен быть зарегистрирован. Ответ содержит stdout, stderr, exit_code, timed_out, truncated. Ненулевой код процесса — результат выполнения; отказ доступа и ошибка валидации — ошибки API. Ограничения описаны в разделе CLI.
Проверка изменений кода
Выполняйте из репозитория MCPBox:
GOWORK=off go test ./...
npm --prefix html run build
GOWORK=off go build -o MCPBox .Эти команды проверяют код и сборку. При изменениях интеграций отдельно проверяйте реальные MCP-подключения, внешний OIDC, RagBox и базы данных. Сборка релизов: ./build-release.sh host или ./build-release.sh all.
Skills и проверка релизов
API Skills: GET /api/skills, POST /api/skills/import, GET /api/projects/{id}/skills, GET /api/projects/{id}/skill-jobs. Изменение каталога, пакетов и профилей требует pro:admin; создание заданий, загрузка файлов и запуск — pro:write. Полные маршруты и MCP-инструменты: Skills.
GOWORK=off go vet ./...
python3 scripts/check-doc-links.py
# После установки frontend-зависимостей:
./build-release.sh all
python3 scripts/check-release-artifacts.py releaseСборщик создаёт шесть плоских бинарников MCPBox-<os>-<arch> (macos для macOS, .exe для Windows) и SHA256SUMS. GitHub Actions проверяет код и сборки; workflow релизной сборки загружает артефакты, но сам не публикует GitHub Release. Предупреждения dependency audit проверяйте отдельно, даже если job зелёный.