Developer Onboarding Checklist

✅ Developer Onboarding Checklist

Follow this checklist to set up your development environment, verify all features, and ensure consistent onboarding across ContextForge project.

🐳 VS Code Dev Container (Recommended)

The fastest way to get started is using the VS Code Dev Container, which provides a fully-configured development environment.

???+ check "Prerequisites"

- [ ] **VS Code** with the [Dev Containers extension](https://code.visualstudio.com/docs/devcontainers/containers)
- [ ] **Docker** or **Podman** installed and running locally

???+ check "Setup"

1. Clone and open the repository:
    ```bash
    git clone https://github.com/ibm/mcp-context-forge.git
    cd mcp-context-forge
    code .
    ```

2. VS Code will detect `.devcontainer` and prompt: **"Reopen in Container"**
   (or manually: ++ctrl+shift+p++ → **Dev Containers: Reopen in Container**)

3. First-time build automatically:

    - Installs system packages & Python 3.11
    - Runs `make install-dev` to pull all dependencies
    - Executes tests to verify the toolchain

???+ check "Daily workflow inside container"

```bash
make dev            # Dev server with hot reload (http://localhost:4444)
make test           # Run test suite
make lint           # Run all linters
```

???+ check "GitHub Codespaces (1-click cloud IDE)"

No local Docker? Use Codespaces:

1. Go to the repo → **Code ▸ Codespaces ▸ Create codespace on main**
2. Wait for the container image to build in the cloud
3. Develop using the same workflow above

🛠 Manual Environment Setup

If not using Dev Containers, set up manually:

???+ check "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 + Pyrefly extension
- [ ] Optional: On Windows, install the WSL and Remote Development extensions

???+ check "Python tooling"

- [ ] `pip install --upgrade pip`
- [ ] `uv` and `uvx` installed - [install uv](https://github.com/astral-sh/uv)
- [ ] `.venv` recreated with `make install-dev` (installs runtime + dev extras)

???+ check "Additional tools"

- [ ] `helm` installed for Kubernetes deployments ([Helm install docs](https://helm.sh/docs/intro/install/))
- [ ] Security tools in `$PATH`: `hadolint`, `dockle`, `trivy`, `osv-scanner`

???+ check "Useful VS Code extensions"

- [ ] Python, Pylance
- [ ] YAML, Even Better TOML
- [ ] Docker, Dev Containers (useful on Windows)

???+ check "GitHub setup"

- [ ] GitHub email configured in `git config`
- [ ] See [GitHub config guide](./github.md#16-personal-git-configuration-recommended)

???+ check ".env configuration"

- [ ] Copy `.env.example` to `.env`
- [ ] Set various env variables, such as:

    - `JWT_SECRET_KEY`
    - `BASIC_AUTH_PASSWORD`

🔧 Makefile Targets

???+ check "Local setup"

- [ ] `make check-env` (validates .env is complete)
- [ ] `make install-dev serve`
- [ ] `make smoketest` runs and passes

???+ check "Container builds"

- [ ] Docker: `make docker-prod docker-run-ssl-host compose-up`
- [ ] Podman: `make podman podman-prod podman-run-ssl-host`

???+ check "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

???+ check "Minikube & Helm"

- [ ] `make helm-install minikube-install minikube-start minikube-k8s-apply helm-package helm-deploy`
- [ ] See [minikube deployment](../deployment/minikube.md)

🧪 Testing

???+ check "Code quality"

- [ ] `make lint`, `make lint-web`
- [ ] `make shell-linters-install`, `make shell-lint`
- [ ] `make hadolint` (Dockerfile linting)

???+ check "Python unit tests"

- [ ] `make test` passes all cases
- [ ] `make coverage` generates coverage report

???+ check "UI automation (Playwright)"

- [ ] `playwright install` (one-time browser setup)
- [ ] `pytest tests/playwright/` passes
- [ ] `pytest tests/playwright/ -k admin` validates Admin UI flows

???+ check "Load testing (Locust)"

- [ ] `make testing-up` (containerized Locust + test services)
- [ ] Or run Locust locally: `locust -f tests/loadtest/locustfile.py --host=http://localhost:4444`
- [ ] Access dashboard at http://localhost:8089
- [ ] Verify no errors under moderate load (50-100 users)

???+ check "Frontend linting"

- [ ] `make eslint` - JavaScript linting
- [ ] `make lint-web` - ESLint + HTMLHint + Stylelint
- [ ] `make format-web` - Prettier formatting
- [ ] Note: JS unit tests not yet implemented

🔐 Security

???+ check "Vulnerability scans"

- [ ] Run:
    ```bash
    make hadolint dockle osv-scan trivy pip-audit
    ```

???+ check "SonarQube analysis"

- [ ] `make sonar-up-docker`
- [ ] `make sonar-submit-docker` - ensure no critical violations

🔑 JWT Authentication

???+ check "Generate and use a Bearer token"

- [ ] Export a token with:
    ```bash
    export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key)
    ```

- [ ] Verify authenticated API access:
    ```bash
    curl -k -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" https://localhost:4444/version | jq
    ```

🤖 Client Integration

???+ check "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](../using/index.md))

🧭 API Testing

???+ check "Authentication required"

- [ ] Unauthenticated:
    ```bash
    curl http://localhost:4444/tools
    # -> should return 401 Unauthorized
    ```
- [ ] Authenticated:
    ```bash
    curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/version | jq
    ```

???+ check "Endpoint coverage"

- [ ] Confirm key routes:

    - `/version`
    - `/health`
    - `/tools`
    - `/servers`
    - `/resources`
    - `/prompts`
    - `/gateways`

- [ ] Browse [Redoc docs](http://localhost:4444/redoc)

🖥 Admin UI

???+ check "Login and diagnostics"

- [ ] Navigate to [`/admin`](http://localhost:4444/admin)
- [ ] Log in with Basic Auth credentials from `.env`
- [ ] `/version` shows healthy DB and Redis

???+ check "CRUD verification"

- [ ] Create / edit / delete:

    - Servers
    - Tools
    - Resources
    - Prompts
    - Gateways

- [ ] Toggle active/inactive switches
- [ ] JWT stored in `HttpOnly` cookie, no errors in DevTools Console

???+ check "Metrics"

- [ ] Confirm latency and error rate display under load

📚 Documentation

???+ check "Build and inspect docs"

- [ ] `cd docs && make venv serve`
- [ ] Open http://localhost:8000
- [ ] Confirm:

    - `.pages` ordering
    - nav structure
    - working images
    - Mermaid diagrams

???+ check "Read and understand"

- [ ] `README.md` in root
- [ ] [Official docs site](https://ibm.github.io/mcp-context-forge/)
- [ ] [MkDocs Admonitions guide](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)

✅ Final Review

???+ check "Ready to contribute"

- [ ] All items checked
- [ ] PR description links to this checklist
- [ ] Stuck? Open a [discussion](https://github.com/your-repo/discussions) or issue