What You'll Find Here

Development

Welcome! This guide is for developers contributing to ContextForge. Whether you're fixing bugs, adding features, or extending federation or protocol support, this doc will help you get up and running quickly and consistently.

🧰 What You'll Find Here

🛠 Developer Environment

ContextForge is built with:

• Python 3.11+
• FastAPI + SQLAlchemy (async) + Pydantic Settings
• HTMX, Alpine.js, TailwindCSS for the Admin UI

Development tools:

• Linters: ruff, mypy, black, isort
• Testing: pytest, httpx
• Serving: uvicorn, gunicorn

Frontend tools (Admin UI):

• Linters: ESLint, Stylelint, HTMLHint, Biome
• Formatting: Prettier
• Security: Retire.js (vulnerability scanning)

Code style and consistency is enforced via:

make lint          # runs ruff, mypy, black, isort
make lint-web      # runs ESLint, HTMLHint, Stylelint
make pre-commit    # runs pre-commit hooks on staged files

As well as GitHub Actions code scanning.

🧪 Testing

Test coverage includes:

• Unit tests under tests/unit/
• Integration tests under tests/integration/
• End-to-end tests under tests/e2e/
• UI automation under tests/playwright/ (Playwright)
• Load testing under tests/loadtest/ (Locust)
• Example payload performance testing under tests/hey/

Use:

make test                        # run full suite
pytest tests/unit/               # run only unit tests
pytest tests/e2e/                # run end-to-end scenarios
pytest tests/playwright/         # run UI automation tests
locust -f tests/loadtest/locustfile.py --host=http://localhost:4444  # load testing

Note: JavaScript unit tests are not yet implemented; frontend testing relies on Playwright for UI automation.

Database Performance Testing

make dev-query-log         # start server with query logging
make query-log-tail        # watch query log in real-time
make query-log-analyze     # analyze logs for N+1 patterns
make test-db-perf          # run N+1 detection tests

See Database Performance for details.

🔍 Linting and Hooks

CI will fail your PR if code does not pass lint checks.

You should manually run:

make lint
make pre-commit

Enable hooks with:

pre-commit install

🐳 Containers

Build and run with Podman or Docker:

make podman            # build production image
make podman-run-ssl    # run with self-signed TLS at https://localhost:4444

🔐 Authentication

Admin UI uses email/password authentication (PLATFORM_ADMIN_EMAIL/PASSWORD). API endpoints require JWT tokens (Basic Auth is disabled by default).

To generate a JWT token:

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key)
echo $MCPGATEWAY_BEARER_TOKEN

Then test:

curl -sX GET \
  -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  http://localhost:4444/tools | jq

📦 Configuration

Edit .env or set environment variables. A complete list is documented in the Configuration Reference.

Use:

cp .env.example .env

Key configs include:

🚧 Contribution Tips

• Pick a good first issue
• Read the CONTRIBUTING.md
• Fork, branch, commit with purpose
• Submit PRs against main with clear titles and linked issues

✅ CI/CD

GitHub Actions enforce:

• CodeQL security scanning
• Pre-commit linting
• Dependency audits
• Docker image builds

CI configs live in .github/workflows/.