Skip to content

Development

Welcome! This guide is for developers contributing to MCP Gateway. 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

Page Description
Building Locally How to install dependencies, set up a virtual environment, and run the gateway
Packaging How to build a release, container image, or prebuilt binary
Doctest Coverage Comprehensive doctest coverage implementation and guidelines
DEVELOPING.md Coding standards, commit conventions, and review workflow

πŸ›  Developer Environment

MCP Gateway is built with:

  • Python 3.10+
  • 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

Code style and consistency is enforced via:

make lint          # runs ruff, mypy, black, isort
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/
  • Example payload performance testing under tests/hey/

Use:

make test          # run all tests
make test-unit     # run only unit tests
make test-e2e      # run end-to-end

πŸ” 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 and API are protected by Basic Auth or JWT.

To generate a JWT token:

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

Then test:

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

πŸ“¦ Configuration

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

Use:

cp .env.example .env

Key configs include:

Variable Purpose
DATABASE_URL Database connection
JWT_SECRET_KEY Signing key for JWTs
DEV_MODE=true Enables hot reload and debug
CACHE_TYPE=memory Options: memory, redis, none

🚧 Contribution Tips


βœ… CI/CD

GitHub Actions enforce:

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

CI configs live in .github/workflows/.