Building Locally¶

Follow these instructions to set up your development environment, build the gateway from source, and run it interactively.

🧩 Prerequisites¶

• Python ≥ 3.11
• make
• (Optional) Docker or Podman for container builds

🔧 One-Liner Setup (Recommended)¶

make venv install-dev serve

This will:

1. Create a virtual environment in .venv/
2. Install Python dependencies (including dev extras)
3. Run the gateway using Gunicorn

🐍 Manual Python Setup¶

If you need to bypass the Makefile, use uv directly — the project's dev dependency group is defined via PEP 735 ([dependency-groups]), so the traditional pip install -e ".[dev]" form does not apply:

uv venv .venv
source .venv/bin/activate
uv pip install --group dev '.[plugins]'

This installs:

• Core app dependencies
• Dev dependencies (pytest, coverage, mypy, bandit, etc.)
• Plugin framework extras

Formatters and linters (ruff, black, isort, pylint, vulture, interrogate, radon, yamllint, tomlcheck) are not installed into the venv — they are invoked on demand through the Makefile targets (make ruff, make black, make isort, make pylint, make vulture, make interrogate, make radon, make yamllint, make tomllint), which fetch pinned versions via uv tool run.

🚀 Running the App¶

You can run the gateway with:

make serve         # production-mode (Gunicorn) on http://localhost:4444
make dev           # hot-reload (Uvicorn) on http://localhost:8000
make run           # executes ./run.sh with your current .env settings
RELOAD=true make run   # enable auto-reload via run.sh (same as ./run.sh --reload)
./run.sh --help    # view all supported flags

Use make dev during development for auto-reload on port 8000.

🔄 Live Reload Tips¶

When relying on run.sh, set RELOAD=true (or pass --reload) and DEV_MODE=true in your .env so settings match.

Also set:

DEBUG=true
LOG_LEVEL=debug

🧪 Test It¶

curl http://localhost:4444/health
curl http://localhost:4444/tools

You should see [] or registered tools (once added).

🎨 Frontend Tooling¶

The Admin UI uses plain JavaScript (not TypeScript). Frontend tooling requires Node.js:

npm install        # install frontend dev dependencies

Building the Admin UI Bundle¶

The Admin UI JavaScript is bundled with Vite. The bundle is not committed to the repository — it must be built locally. make install-dev invokes make build-ui automatically, and the step is required: without a bundle, /admin will fail to load at runtime with No bundle-*.js found. Rebuild after any changes to files under mcpgateway/admin_ui/.

Node.js is a prerequisite. If npm is missing, make build-ui (and therefore make install-dev) fails fast rather than leaving a broken install. Install Node.js from https://nodejs.org before running setup.

make build-ui          # build mcpgateway/static/bundle-<hash>.js (requires npm)

If you genuinely do not need the Admin UI (for example, a headless API-only deployment where MCPGATEWAY_UI_ENABLED=false), bypass the step with:

SKIP_UI_BUILD=1 make install-dev

Or build manually:

npm ci                 # install dependencies from lockfile (falls back to `npm install` if lockfile absent)
npm run vite:build     # produce mcpgateway/static/bundle-<hash>.js

The server reads mcpgateway/static/.vite/manifest.json at startup to locate the hashed bundle filename.

For iterative development you can use watch mode:

npx vite build --watch

Linting & Formatting¶

make eslint        # lint JavaScript with ESLint
make lint-web      # ESLint + HTMLHint + Stylelint
make format-web    # format with Prettier

Frontend Stack¶

UI Testing¶

# Playwright (UI automation)
playwright install              # one-time browser setup
pytest tests/playwright/        # run UI tests

# Locust (load testing)
locust -f tests/loadtest/locustfile.py --host=http://localhost:4444

Note: JavaScript unit tests are not yet implemented. Testing efforts focus on the Python backend (pytest) and UI automation (Playwright).

Air-Gapped Mode (Local Development)¶

To test the Admin UI without CDN dependencies:

# Download vendor libraries to mcpgateway/static/vendor/
./scripts/download-cdn-assets.sh

# Run with air-gapped mode
MCPGATEWAY_UI_AIRGAPPED=true make dev

This downloads Alpine.js, Tailwind, CodeMirror, Chart.js, and Font Awesome for fully offline UI operation. HTMX is bundled via npm/Vite and included in the main JS bundle. See Admin UI - Air-Gapped Mode for details.