make venv install serve

make install-dev # Install development dependencies, ex: linters and test harness
make lint          # optional: run style checks (ruff, mypy, etc.)

make podman            # build production image
make podman-run-ssl    # run at https://localhost:4444

python -m mcpgateway.utils.create_jwt_token \
       -u admin \
       -e 10080 | tee token.txt   # 7 days (minutes)

export MCPGATEWAY_BEARER_TOKEN=$(cat token.txt)

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

make venv install          # create .venv + install deps
make serve                 # gunicorn on :4444

uv venv && source .venv/bin/activate
uv pip install -e .[dev]

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

uv pip install psycopg2-binary   # dev convenience
# or
uv pip install psycopg2          # production build

docker run --name mcp-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_DB=mcp \
  -p 5432:5432 -d postgres

 make serve               # Run production Gunicorn server on
 make serve-ssl           # Run Gunicorn behind HTTPS on :4444 (uses ./certs)

make dev
# or
./run.sh --reload --log debug --workers 2

uvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444 --workers 4

# Generate a JWT token using JWT_SECRET_KEY and export it as MCPGATEWAY_BEARER_TOKEN
export MCPGATEWAY_BEARER_TOKEN=$(JWT_SECRET_KEY=my-test-key python3 mcpgateway/utils/create_jwt_token.py)

# Use the JWT token in an API call
curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools

# ── Required ─────────────────────────────────────────────
IBMCLOUD_REGION=us-south
IBMCLOUD_RESOURCE_GROUP=default
IBMCLOUD_PROJECT=my-codeengine-project
IBMCLOUD_CODE_ENGINE_APP=mcpgateway
IBMCLOUD_IMAGE_NAME=us.icr.io/myspace/mcpgateway:latest
IBMCLOUD_IMG_PROD=mcpgateway/mcpgateway
IBMCLOUD_API_KEY=your_api_key_here   # Optional – omit to use interactive `ibmcloud login --sso`

# ── Optional overrides (sensible defaults provided) ──────
IBMCLOUD_CPU=1                       # vCPUs for the app
IBMCLOUD_MEMORY=4G                   # Memory allocation
IBMCLOUD_REGISTRY_SECRET=my-regcred  # Name of the Container Registry secret

make ibmcloud-check-env
make ibmcloud-cli-install
make ibmcloud-login
make ibmcloud-ce-login
make ibmcloud-tag
make ibmcloud-push
make ibmcloud-deploy
make ibmcloud-ce-status
make ibmcloud-ce-logs

# Initialize MCP session
curl -X POST -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{
           "protocol_version":"2025-03-26",
           "capabilities":{},
           "client_info":{"name":"MyClient","version":"1.0.0"}
         }' \
     http://localhost:4444/protocol/initialize

# Ping (JSON-RPC style)
curl -X POST -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"ping"}' \
     http://localhost:4444/protocol/ping

# Completion for prompt/resource arguments
curl -X POST -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{
           "ref":{"type":"ref/prompt","name":"example_prompt"},
           "argument":{"name":"topic","value":"py"}
         }' \
     http://localhost:4444/protocol/completion/complete

# Sampling (streaming)
curl -N -X POST -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{
           "messages":[{"role":"user","content":{"type":"text","text":"Hello"}}],
           "maxTokens":16
         }' \
     http://localhost:4444/protocol/sampling/createMessage

# Generic JSON-RPC calls (tools, gateways, roots, etc.)
curl -X POST -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"list_tools"}' \
     http://localhost:4444/rpc

# Register a new tool
curl -X POST -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{
           "name":"clock_tool",
           "url":"http://localhost:9000/rpc",
           "description":"Returns current time",
           "input_schema":{
             "type":"object",
             "properties":{"timezone":{"type":"string"}},
             "required":[]
           }
         }' \
     http://localhost:4444/tools

# List tools
curl -u admin:changeme http://localhost:4444/tools

# Get tool by ID
curl -u admin:changeme http://localhost:4444/tools/1

# Update tool
curl -X PUT -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{ "description":"Updated desc" }' \
     http://localhost:4444/tools/1

# Toggle active status
curl -X POST -u admin:changeme \
     http://localhost:4444/tools/1/toggle?activate=false

# Delete tool
curl -X DELETE -u admin:changeme http://localhost:4444/tools/1

# Register a peer gateway
curl -X POST -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{"name":"peer_gateway","url":"http://peer:4444"}' \
     http://localhost:4444/gateways

# List gateways
curl -u admin:changeme http://localhost:4444/gateways

# Get gateway by ID
curl -u admin:changeme http://localhost:4444/gateways/1

# Update gateway
curl -X PUT -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{"description":"New description"}' \
     http://localhost:4444/gateways/1

# Toggle active status
curl -X POST -u admin:changeme \
     http://localhost:4444/gateways/1/toggle?activate=false

# Delete gateway
curl -X DELETE -u admin:changeme http://localhost:4444/gateways/1

# Register resource
curl -X POST -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{
           "uri":"config://app/settings",
           "name":"App Settings",
           "content":"key=value"
         }' \
     http://localhost:4444/resources

# List resources
curl -u admin:changeme http://localhost:4444/resources

# Read a resource
curl -u admin:changeme http://localhost:4444/resources/config://app/settings

# Update resource
curl -X PUT -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{"content":"new=value"}' \
     http://localhost:4444/resources/config://app/settings

# Delete resource
curl -X DELETE -u admin:changeme http://localhost:4444/resources/config://app/settings

# Subscribe to updates (SSE)
curl -N -u admin:changeme http://localhost:4444/resources/subscribe/config://app/settings

# Create prompt template
curl -X POST -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{
           "name":"greet",
           "template":"Hello, {{ user }}!",
           "argument_schema":{
             "type":"object",
             "properties":{"user":{"type":"string"}},
             "required":["user"]
           }
         }' \
     http://localhost:4444/prompts

# List prompts
curl -u admin:changeme http://localhost:4444/prompts

# Get prompt (with args)
curl -X POST -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{"user":"Alice"}' \
     http://localhost:4444/prompts/greet

# Get prompt (no args)
curl -u admin:changeme http://localhost:4444/prompts/greet

# Update prompt
curl -X PUT -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{"template":"Hi, {{ user }}!"}' \
     http://localhost:4444/prompts/greet

# Toggle active
curl -X POST -u admin:changeme \
     http://localhost:4444/prompts/5/toggle?activate=false

# Delete prompt
curl -X DELETE -u admin:changeme http://localhost:4444/prompts/greet

# List roots
curl -u admin:changeme http://localhost:4444/roots

# Add root
curl -X POST -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{"uri":"/data","name":"Data Root"}' \
     http://localhost:4444/roots

# Remove root
curl -X DELETE -u admin:changeme http://localhost:4444/roots/%2Fdata

# Subscribe to root changes (SSE)
curl -N -u admin:changeme http://localhost:4444/roots/changes

# List servers
curl -u admin:changeme http://localhost:4444/servers

# Get server
curl -u admin:changeme http://localhost:4444/servers/1

# Create server
curl -X POST -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{"name":"db","description":"Database"}' \
     http://localhost:4444/servers

# Update server
curl -X PUT -u admin:changeme \
     -H "Content-Type: application/json" \
     -d '{"description":"Updated"}' \
     http://localhost:4444/servers/1

# Toggle active
curl -X POST -u admin:changeme \
     http://localhost:4444/servers/1/toggle?activate=false

# Get aggregated metrics
curl -u admin:changeme http://localhost:4444/metrics

# Reset metrics (all or per-entity)
curl -X POST -u admin:changeme http://localhost:4444/metrics/reset
curl -X POST -u admin:changeme http://localhost:4444/metrics/reset?entity=tool&id=1

# SSE: all events
curl -N -u admin:changeme http://localhost:4444/events

# WebSocket
wscat -c ws://localhost:4444/ws \
      -H "Authorization: Basic $(echo -n admin:changeme|base64)"

# Health check
curl http://localhost:4444/health

uvicorn sample_tool.clock_tool:app --host 0.0.0.0 --port 9000

curl -X POST -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"get_time","params":{"timezone":"UTC"}}' \
     http://localhost:9000/rpc

make tests           # Run unit tests
make lint            # Run lint tools

.
├── Containerfile               # OCI image build for Docker and Podman
├── DEVELOPING.md               # Contributor guidelines, workflows, and style guide
├── dictionary.dic              # Custom dictionary for spell-checker and linters
├── gunicorn.config.py          # Production Gunicorn settings (workers, logging, timeouts)
├── LICENSE                     # Apache License 2.0
├── Makefile                    # Development & deployment targets: venv, install, tests, serve, podman, etc.
├── mcp.db                      # Default SQLite database file (auto-created on first run)
├── mcpgateway                  # ← main application package
│   ├── __init__.py             # Package metadata and version constant
│   ├── admin.py                # FastAPI routers and controllers for the Admin UI
│   ├── cache
│   │   ├── __init__.py         # Cache package initializer
│   │   └── resource_cache.py   # In-memory LRU+TTL cache implementation for resources
│   ├── config.py               # Pydantic Settings loader (env, .env parsing)
│   ├── db.py                   # SQLAlchemy ORM models, engine setup, and migrations
│   ├── federation
│   │   ├── __init__.py         # Federation package initializer
│   │   ├── discovery.py        # Peer gateway discovery (mDNS, explicit lists)
│   │   ├── forward.py          # RPC forwarding logic to peer gateways
│   │   └── manager.py          # Federation orchestration, health checks, capability aggregation
│   ├── handlers
│   │   ├── __init__.py         # Handlers package initializer
│   │   └── sampling.py         # MCP streaming sampling request handler
│   ├── main.py                 # FastAPI app factory, startup/shutdown events
│   ├── schemas.py              # Shared Pydantic DTOs for requests and responses
│   ├── services
│   │   ├── __init__.py         # Services package initializer
│   │   ├── completion_service.py  # Prompt and resource argument completion logic
│   │   ├── gateway_service.py     # Peer gateway registration and management
│   │   ├── logging_service.py     # Central logging helpers and middleware
│   │   ├── prompt_service.py      # Prompt template CRUD, validation, rendering
│   │   ├── resource_service.py    # Resource registration, retrieval, templates, subscriptions
│   │   ├── root_service.py        # File-system root registry and subscriptions
│   │   ├── server_service.py      # Server registry, health monitoring
│   │   └── tool_service.py        # Tool registration, invocation, metrics
│   ├── static                  # Tailwind CSS, JavaScript and other static assets for Admin UI
│   ├── templates
│   │   └── admin.html          # HTMX/Alpine.js Admin UI HTML template
│   ├── static
│   │   ├── admin.js            # JS functions for Admin UI
│   │   ├── admin.css           # Styles for Admin UI
│   ├── transports
│   │   ├── __init__.py         # Transports package initializer
│   │   ├── base.py             # Abstract Transport interface (connect, send, receive)
│   │   ├── sse_transport.py    # Server-Sent Events transport implementation
│   │   ├── stdio_transport.py  # stdio transport for subprocess embedding
│   │   └── websocket_transport.py  # WebSocket transport with ping/pong support
│   ├── types.py                # Core enums, type aliases, shared data classes
│   ├── utils
│   │   ├── create_jwt_token.py    # CLI & library for JWT generation and inspection
│   │   └── verify_credentials.py  # FastAPI deps for Basic and JWT authentication
│   └── validation
│       ├── __init__.py            # Validation package initializer
│       └── jsonrpc.py             # JSON-RPC 2.0 request and response validation
├── os_deps.sh                   # Script to install system-level dependencies
├── pdm.lock                     # PDM dependency lockfile
├── pyproject.toml               # Poetry/PDM configuration, dependencies, lint rules
├── run-gunicorn.sh              # Opinionated Gunicorn startup script
├── run.sh                       # Uvicorn shortcut script with argument parsing
├── TESTING.md                   # Testing strategy, fixtures and guidelines
├── test_readme.py               # CI check to ensure README stays in sync
└── tests
    ├── conftest.py              # Shared fixtures and pytest setup
    ├── e2e                      # End-to-end test scenarios
    ├── integration              # API-level integration tests
    └── unit                     # Pure unit tests for business logic

🐍 MCP CONTEXT FORGE  (An enterprise-ready Model Context Protocol Gateway)
🔧 SYSTEM-LEVEL DEPENDENCIES (DEV BUILD ONLY)
os-deps              - Install Graphviz, Pandoc, Trivy, SCC used for dev docs generation and security scan
🌱 VIRTUAL ENVIRONMENT & INSTALLATION
venv                 - Create a fresh virtual environment with uv & friends
activate             - Activate the virtual environment in the current shell
install              - Install project into the venv
install-dev          - Install project (incl. dev deps) into the venv
update               - Update all installed deps inside the venv
check-env            - Verify all required env vars in .env are present
▶️ SERVE & TESTING
serve                - Run production Gunicorn server on :4444
certs                - Generate self-signed TLS cert & key in ./certs (won't overwrite)
serve-ssl            - Run Gunicorn behind HTTPS on :4444 (uses ./certs)
dev                  - Run fast-reload dev server (uvicorn)
run                  - Execute helper script ./run.sh
test                 - Run unit tests with pytest
test-curl            - Smoke-test API endpoints with curl script
pytest-examples      - Run README / examples through pytest-examples
clean                - Remove caches, build artefacts, virtualenv, docs, certs, coverage, SBOM, etc.
📊 COVERAGE & METRICS
coverage             - Run tests with coverage, emit md/HTML/XML + badge
pip-licenses         - Produce dependency license inventory (markdown)
scc                  - Quick LoC/complexity snapshot with scc
scc-report           - Generate HTML LoC & per-file metrics with scc
📚 DOCUMENTATION & SBOM
docs                 - Build docs (graphviz + handsdown + images + SBOM)
images               - Generate architecture & dependency diagrams
🔍 LINTING & STATIC ANALYSIS
lint                 - Run the full linting suite (see targets below)
black                - Reformat code with black
autoflake            - Remove unused imports / variables with autoflake
isort                - Organise & sort imports with isort
flake8               - PEP-8 style & logical errors
pylint               - Pylint static analysis
mypy                 - Static type-checking with mypy
bandit               - Security scan with bandit
pydocstyle           - Docstring style checker
pycodestyle          - Simple PEP-8 checker
pre-commit           - Run all configured pre-commit hooks
ruff                 - Ruff linter + formatter
ty                   - Ty type checker from astral
pyright              - Static type-checking with Pyright
radon                - Code complexity & maintainability metrics
pyroma               - Validate packaging metadata
importchecker        - Detect orphaned imports
spellcheck           - Spell-check the codebase
fawltydeps           - Detect undeclared / unused deps
wily                 - Maintainability report
pyre                 - Static analysis with Facebook Pyre
depend               - List dependencies in ≈requirements format
snakeviz             - Profile & visualise with snakeviz
pstats               - Generate PNG call-graph from cProfile stats
spellcheck-sort      - Sort local spellcheck dictionary
tox                  - Run tox across multi-Python versions
sbom                 - Produce a CycloneDX SBOM and vulnerability scan
pytype               - Flow-sensitive type checker
check-manifest       - Verify sdist/wheel completeness
🕸️  WEBPAGE LINTERS & STATIC ANALYSIS (HTML/CSS/JS lint + security scans + formatting)
install-web-linters  - Install HTMLHint, Stylelint, ESLint, Retire.js & Prettier via npm
lint-web             - Run HTMLHint, Stylelint, ESLint, Retire.js and npm audit
format-web           - Format HTML, CSS & JS files with Prettier
📡 SONARQUBE ANALYSIS
sonar-deps-podman    - Install podman-compose + supporting tools
sonar-deps-docker    - Install docker-compose + supporting tools
sonar-up-podman      - Launch SonarQube with podman-compose
sonar-up-docker      - Launch SonarQube with docker-compose
sonar-submit-docker  - Run containerised Sonar Scanner CLI with Docker
sonar-submit-podman  - Run containerised Sonar Scanner CLI with Podman
pysonar-scanner      - Run scan with Python wrapper (pysonar-scanner)
sonar-info           - How to create a token & which env vars to export
🛡️ SECURITY & PACKAGE SCANNING
trivy                - Scan container image for CVEs (HIGH/CRIT). Needs podman socket enabled
dockle               - Lint the built container image via tarball (no daemon/socket needed)
hadolint             - Lint Containerfile/Dockerfile(s) with hadolint
pip-audit            - Audit Python dependencies for published CVEs
📦 DEPENDENCY MANAGEMENT
deps-update          - Run update-deps.py to update all dependencies in pyproject.toml and docs/requirements.txt
containerfile-update - Update base image in Containerfile to latest tag
🦭 PODMAN CONTAINER BUILD & RUN
podman-dev           - Build development container image
podman               - Build production container image
podman-run           - Run the container on HTTP  (port 4444)
podman-run-shell     - Run the container on HTTP  (port 4444) and start a shell
podman-run-ssl       - Run the container on HTTPS (port 4444, self-signed)
podman-stop          - Stop & remove the container
podman-test          - Quick curl smoke-test against the container
podman-logs          - Follow container logs (⌃C to quit)
podman-stats         - Show container resource stats (if supported)
podman-top           - Show live top-level process info in container
podman-shell         - Open an interactive shell inside the Podman container
🐋 DOCKER BUILD & RUN
docker-dev           - Build development Docker image
docker               - Build production Docker image
docker-run           - Run the container on HTTP  (port 4444)
docker-run-ssl       - Run the container on HTTPS (port 4444, self-signed)
docker-stop          - Stop & remove the container
docker-test          - Quick curl smoke-test against the container
docker-logs          - Follow container logs (⌃C to quit)
docker-stats         - Show container resource usage stats (non-streaming)
docker-top           - Show top-level process info in Docker container
docker-shell         - Open an interactive shell inside the Docker container
☁️ IBM CLOUD CODE ENGINE
ibmcloud-check-env          - Verify all required IBM Cloud env vars are set
ibmcloud-cli-install        - Auto-install IBM Cloud CLI + required plugins (OS auto-detected)
ibmcloud-login              - Login to IBM Cloud CLI using IBMCLOUD_API_KEY (--sso)
ibmcloud-ce-login           - Set Code Engine target project and region
ibmcloud-list-containers    - List deployed Code Engine apps
ibmcloud-tag                - Tag container image for IBM Container Registry
ibmcloud-push               - Push image to IBM Container Registry
ibmcloud-deploy             - Deploy (or update) container image in Code Engine
ibmcloud-ce-logs            - Stream logs for the deployed application
ibmcloud-ce-status          - Get deployment status
ibmcloud-ce-rm              - Delete the Code Engine application