β Developer Onboarding Checklist¶
Follow this checklist to set up your development environment, verify all features, and ensure consistent onboarding across the MCP Gateway project.
π Environment Setup¶
System prerequisites
- Python β₯ 3.11
- Node.js and npm, npx (used for testing with
supergateway
and the HTML/JS Admin UI) - Docker, Docker Compose, and Podman
- Make, GitHub CLI (
gh
),curl
,jq
,openssl
- Optional: Visual Studio Code + Dev Containers extension (or WSL2 if on Windows) + Pyrefly
- Optional: On Windows, install the WSL and Remote Development extensions
Python tooling
-
pip install --upgrade pip
-
uv
anduvx
installed - install uv -
.venv
created withmake venv install install-dev
Additional tools
-
helm
installed for Kubernetes deployments (Helm install docs) - Security tools in
$PATH
:hadolint
,dockle
,trivy
,osv-scanner
Useful VS Code extensions
- Python, Pylance
- YAML, Even Better TOML
- Docker, Dev Containers (useful on Windows)
GitHub setup
- GitHub email configured in
git config
- See GitHub config guide
.env configuration
- Copy
.env.example
to.env
- Set various env variables, such as:
JWT_SECRET_KEY
BASIC_AUTH_PASSWORD
π§ Makefile Targets¶
Local setup
-
make check-env
(validates .env is complete) -
make venv install install-dev serve
-
make smoketest
runs and passes
Container builds
- Docker:
make docker-prod docker-run-ssl-host compose-up
- Podman:
make podman podman-prod podman-run-ssl-host
Packaging
-
make dist verify
builds packages -
make devpi-install devpi-init devpi-start devpi-setup-user devpi-upload devpi-test
- Install and test
mcpgateway
CLI locally
Minikube & Helm
-
make helm-install minikube-install minikube-start minikube-k8s-apply helm-package helm-deploy
- See minikube deployment
π§ͺ Testing¶
Code quality
-
make lint
,make lint-web
-
make shell-linters-install
,make shell-lint
-
make hadolint
(Dockerfile linting)
Unit tests
-
make test
passes all cases
π Security¶
SonarQube analysis
-
make sonar-up-docker
-
make sonar-submit-docker
- ensure no critical violations
π JWT Authentication¶
Generate and use a Bearer token
-
Export a token with:
-
Verify authenticated API access:
π€ Client Integration¶
Run wrapper and test transports
- Run:
python3 -m mcpgateway.wrapper
(stdio support) - Test transports:
- Streamable HTTP
- Server-Sent Events (SSE)
- Optional: Integrate with Claude, Copilot, Continue (usage guide)
π§ API Testing¶
Authentication required
- Unauthenticated:
- Authenticated:
Endpoint coverage
- Confirm key routes:
/version
/health
/tools
/servers
/resources
/prompts
/gateways
- Browse Redoc docs
π₯ Admin UI¶
Login and diagnostics
- Navigate to
/admin
- Log in with Basic Auth credentials from
.env
-
/version
shows healthy DB and Redis
CRUD verification
- Create / edit / delete:
- Servers
- Tools
- Resources
- Prompts
- Gateways
- Toggle active/inactive switches
- JWT stored in
HttpOnly
cookie, no errors in DevTools Console
Metrics
- Confirm latency and error rate display under load
π Documentation¶
Build and inspect docs
-
cd docs && make venv serve
- Open http://localhost:8000
- Confirm:
.pages
ordering- nav structure
- working images
- Mermaid diagrams
Read and understand
-
README.md
in root - Official docs site
- MkDocs Admonitions guide
β Final Review¶
Ready to contribute
- All items checked
- PR description links to this checklist
- Stuck? Open a discussion or issue