Developer guide

Build and repository layout

MCPBox 1.4.0 is a standalone Go module with one React frontend and one application entrypoint. Build commands are in getting started.

Path	Responsibility
main.go	Unified application composition, administrator bootstrap and admin commands.
app/	Runtime, listener configuration, startup hooks and shared runtime paths.
internal/httpapi/	Base API, project MCP aggregation, launchers and embedded UI.
internal/orchestrator/	Managed stdio processes, inspection and health probes.
internal/storage/, internal/models/	Shared SQLite persistence and models.
internal/skills/	Skills catalog, imports, version bindings, jobs and Docker execution.
internal/cli/	CLI catalog discovery and constrained execution.
internal/rag/	Local document extraction and Bleve indexing.
internal/proauth/, internal/prosso/, internal/prohttp/	Access, OIDC and integration HTTP routes.
internal/proragbox/, internal/prostorage/	Optional services and operational storage.
html/src/	React/TypeScript UI and English/Russian localization.

The pro* names remain internal compatibility names. The current executable wires these features in main.go; the legacy FreeEdition() runtime helper does not describe the distributed application's complete behavior.

Administrative API

Protected API calls use Authorization: Bearer <session-or-agent-token> on the admin listener. GET /api/meta and GET /healthz are public metadata/health routes. Local sign-in is POST /api/pro/login with email and password; its response contains a session token.

Selected routes (not a complete API schema):

Route	Purpose
GET /api/projects, POST /api/projects	List/create projects.
GET /api/catalog/items, POST /api/catalog/sync	Market definitions and synchronization.
GET /api/packages	Installed packages.
GET /api/rag/collections, POST /api/rag/collections	Local knowledge collections.
GET /api/cli, POST /api/cli	CLI registry.
GET /api/cli/catalog, POST /api/cli/catalog/sync	CLI discovery.
POST /api/cli/catalog/{slug}/apply	Apply a reviewed definition with its revision.
GET /api/projects/{id}/cli	Project CLI links.
POST /api/projects/{id}/cli/execute	Administrative CLI execution.
GET /api/pro/auth/me	Authenticated principal.
GET /api/pro/users, GET /api/pro/roles	Access records.
GET /api/pro/sessions, GET /api/pro/tokens	Sessions and agent tokens.
GET /api/pro/storage/runtime-status	Desired/active storage and fallback status.
GET /api/pro/ragbox/config	Public integration settings with masked secret previews.
GET /api/logs, GET /api/logs/metrics	Audit and metrics.

Authorization depends on method and route; see access. A successful admin login does not authenticate the project MCP endpoint.

MCP transport and routing

POST /mcp/<project-token> without sessionId uses synchronous HTTP JSON-RPC. GET opens the legacy SSE flow and emits an endpoint event; its follow-up requests use POST with ?sessionId=.... /connect/<project-token> remains a compatibility alias.

MCPBox answers initialize itself, aggregates tools/list, resources/list and prompts/list, and routes subsequent calls to the originating backend. Unsupported optional list methods are tolerated when reported as unimplemented. Name collisions receive stable aliases where needed. Disabled servers are excluded and paused projects are rejected.

Project bearer/OAuth validation and legacy migration gates run before access to project capabilities. CLI calls pass through the shared executor and recheck the current project links and operation allowlist.

CLI execution example

An approved Git entry with slug git, linked to the project, can receive:

{ "cli": "git", "command": "log", "args": ["-n", "5"] }

The entire argument vector must be registered. Results include stdout, stderr, exit_code, timed_out and truncated. A nonzero child exit code is an execution result, while authorization and validation failures are API errors. See CLI for execution boundaries.

Validate code changes

Run from the MCPBox repository:

GOWORK=off go test ./...
npm --prefix html run build
GOWORK=off go build -o MCPBox .

These checks validate code/build behavior. Separately test real client connections, external OIDC, RagBox and database services when changing those integrations. Release builds use ./build-release.sh host or ./build-release.sh all.

Skills and release checks

Skills API includes GET /api/skills, POST /api/skills/import, GET /api/projects/{id}/skills and GET /api/projects/{id}/skill-jobs. Catalog/package/profile changes require pro:admin; job creation, uploads and runs require pro:write. See Skills for complete routes and MCP tools.

GOWORK=off go vet ./...
python3 scripts/check-doc-links.py
# After installing frontend dependencies:
./build-release.sh all
python3 scripts/check-release-artifacts.py release

The builder produces six flat MCPBox-<os>-<arch> binaries (macos for macOS, .exe for Windows) and SHA256SUMS. GitHub Actions checks code and builds; the release-build workflow uploads artifacts but does not publish a GitHub Release itself. Inspect dependency audit findings separately even when the job is green.