Skip to content

ADR-0020: Multi-Format Packaging Strategy

  • Status: Accepted
  • Date: 2025-10-27
  • Deciders: Core Engineering Team

Context

ContextForge supports diverse deployment scenarios with different packaging requirements:

  • Developers need easy installation for local development (pip install)
  • Serverless platforms (Lambda, Cloud Run) need container images or deployment packages
  • Kubernetes/OpenShift operators need Helm charts with configurable values
  • Edge deployments need lightweight static binaries
  • CI/CD pipelines need multi-arch container images
  • Enterprise users need signed releases with SBOM and provenance

Each deployment target has different constraints: - PyPI packages work for Python environments - Container images work for Kubernetes, serverless containers - Helm charts simplify Kubernetes deployments - Static binaries work for edge devices without Python runtime - Multi-arch support needed for amd64 (x86_64) and arm64 (Apple Silicon, AWS Graviton)

Decision

We will package ContextForge in multiple formats to support all deployment scenarios:

1. PyPI Packages (Python Distribution)

Core packages: - mcp-contextforge-gateway - Core gateway application - mcp-contextforge-gateway-ui - Admin UI (installs as plugin) - mcp-contextforge-translate - Protocol bridge utility - mcp-contextforge-wrapper - MCP client wrapper - mcp-contextforge-reverse-proxy - NAT traversal proxy

Plugin packages: - mcp-contextforge-plugin-framework - Plugin framework - Individual plugins: mcp-contextforge-plugin-{name} (40+ packages) - Meta package: mcp-contextforge-plugins-all (installs all plugins)

MCP Server packages: - Individual servers: mcp-server-{name} (Python servers) - Rust plugin wheels with PyO3 (cross-compiled for amd64/arm64)

Installation: 

# Core gateway
pip install mcp-contextforge-gateway

# With all plugins
pip install mcp-contextforge-gateway mcp-contextforge-plugins-all

# Standalone utility
pip install mcp-contextforge-translate

2. Container Images (Docker/Podman)

Images hosted on GitHub Container Registry (ghcr.io): - ghcr.io/contextforge-org/mcp-gateway:latest - Core gateway - ghcr.io/contextforge-org/mcp-gateway-ui:latest - Gateway + UI - ghcr.io/contextforge-org/translate:latest - Translate utility - ghcr.io/contextforge-org/wrapper:latest - Wrapper utility - ghcr.io/contextforge-org/reverse-proxy:latest - Reverse proxy - Per-server images: ghcr.io/contextforge-org/mcp-server-{name}:latest

Multi-arch support: - linux/amd64 (x86_64) - Standard Intel/AMD servers - linux/arm64 (aarch64) - Apple Silicon, AWS Graviton, Raspberry Pi

Image features: - Minimal base images (Alpine Linux where possible) - Non-root user for security - Health check endpoints configured - Multi-stage builds for smaller images - Signed with cosign (keyless OIDC) - SBOM included (Syft, SPDX format)

Usage: 

# Run core gateway
docker run -p 4444:4444 ghcr.io/contextforge-org/mcp-gateway:latest

# Run on ARM64 (Apple Silicon)
docker run --platform linux/arm64 ghcr.io/contextforge-org/mcp-gateway:latest

3. Helm Charts (Kubernetes Deployment)

Chart repository: - OCI registry: oci://ghcr.io/contextforge-org/helm-charts/mcp-stack - Artifact Hub: Public listing for discoverability

Chart features: - Configurable resource limits and requests - Horizontal Pod Autoscaler (HPA) support - PostgreSQL and Redis dependencies (optional) - Ingress configuration (nginx, Traefik, Istio) - ConfigMap for environment variables - Secrets management integration - Pod disruption budgets - Network policies - Service mesh compatibility (Istio, Linkerd)

Installation: 

# Add Helm repo
helm repo add contextforge oci://ghcr.io/contextforge-org/helm-charts

# Install with default values
helm install mcp-stack contextforge/mcp-stack

# Install with custom values (production)
helm install mcp-stack contextforge/mcp-stack \
  -f production-values.yaml \
  --set replicaCount=5 \
  --set hpa.enabled=true

4. Static Binaries (Go/Rust Servers)

Binary targets: - Go servers: Cross-compiled Go executables (5-15 MB) - Rust servers: Static Rust binaries (3-10 MB) - Platforms: linux-amd64, linux-arm64, darwin-amd64, darwin-arm64, windows-amd64

Distribution: - GitHub Releases with checksums - Signed with GPG and cosign - SLSA Build Level 3 provenance

Usage: 

# Download and run Go server
curl -LO https://github.com/contextforge-org/mcp-servers-go/releases/download/v1.0.0/mcp-server-time-linux-amd64
chmod +x mcp-server-time-linux-amd64
./mcp-server-time-linux-amd64 --port 9000

Consequences

Positive

  • 🎯 Right tool for the job - Each deployment gets optimal packaging format
  • 🐍 Easy development - pip install for local development
  • 🐳 Cloud-native - Container images for Kubernetes, serverless
  • ☸️ Simplified K8s - Helm charts with best practices and HPA
  • 🚀 Edge deployments - Static binaries for minimal environments
  • 🌍 Multi-arch support - Works on x86_64 and ARM64 (Apple Silicon, Graviton)
  • 🔒 Supply chain security - Signed releases, SBOM, provenance

Negative

  • 🔧 Maintenance overhead - Multiple build pipelines and release processes
  • 📦 Storage costs - Container images and binaries consume registry space
  • 🔄 Version synchronization - Must keep package versions aligned
  • 📚 Documentation - Need installation guides for each format

Neutral

  • 🏗️ CI/CD complexity - GitHub Actions workflows per format
  • 📊 Metrics - Track downloads per format to understand usage

Package Matrix

Format Core Gateway Utilities Plugins MCP Servers Helm Use Case
PyPI ✅ Yes ✅ Yes ✅ Yes ✅ Python only ❌ No Local dev, pip install
Containers ✅ Yes ✅ Yes ✅ Bundled ✅ All languages ❌ No K8s, serverless, Docker
Helm ✅ Yes ✅ Optional ✅ Optional ✅ Optional ✅ Yes Kubernetes production
Binaries ❌ No ⚠️ Future ❌ No ✅ Go/Rust only ❌ No Edge, embedded systems

Multi-Arch Build Strategy

Container images: 

# Build multi-arch image with BuildKit
docker buildx build --platform linux/amd64,linux/arm64 \
  -t ghcr.io/contextforge-org/mcp-gateway:latest \
  --push .

Python wheels (Rust plugins): 

# Cross-compile Rust plugin for multiple architectures
cargo build --release --target x86_64-unknown-linux-gnu
cargo build --release --target aarch64-unknown-linux-gnu
maturin build --release --target x86_64-unknown-linux-gnu
maturin build --release --target aarch64-unknown-linux-gnu

Go binaries: 

# Cross-compile Go server
GOOS=linux GOARCH=amd64 go build -o mcp-server-time-linux-amd64
GOOS=linux GOARCH=arm64 go build -o mcp-server-time-linux-arm64
GOOS=darwin GOARCH=arm64 go build -o mcp-server-time-darwin-arm64

Supply Chain Security

All releases include: 1. Digital signatures - GPG signed tags and releases 2. Container signing - cosign with keyless OIDC (Sigstore) 3. SBOM - Software Bill of Materials (Syft, SPDX format) 4. Provenance - SLSA Build Level 3 attestation 5. Vulnerability scanning - Trivy and Grype in CI/CD 6. Checksums - SHA256 for all binary artifacts

Verification: 

# Verify container signature
cosign verify ghcr.io/contextforge-org/mcp-gateway:latest

# Verify binary checksum
sha256sum -c checksums.txt

Alternatives Considered

Option Why Not
PyPI only Doesn't work for Go/Rust servers, inconvenient for Kubernetes
Containers only Poor developer experience, overkill for pip install
Single monolithic package Too large, includes unnecessary dependencies
OS-specific packages (deb, rpm) Narrow distribution, doesn't work for all platforms
Snap/Flatpak Limited adoption, primarily for desktop apps

Status

This decision is implemented. All formats are available through respective registries.

References