FR: Per-catalog-entry resource limits (--cpus / --memory overrides)

[ddullah]

Summary

docker mcp gateway run --cpus and --memory flags currently apply gateway-wide to every spawned MCP server container. We need per-catalog-entry overrides so heterogeneous server workloads can each get appropriate resource caps.

Use case

We operate a 21-server catalog where workload profile varies significantly:

• HEAVY (3 servers — AST parsing of large codebases, bulk cloud-resource enumeration, methodology orchestration loading large content trees): legitimately need ~2 CPU / 2GB
• STANDARD (8 servers — typical API-backed clients): 1 CPU / 1GB is fine
• LIGHT (3 servers — stateless format-conversion / filesystem lookup): 0.5 CPU / 256MB more than enough

With gateway-wide flags, we're forced to choose:

• Cap high enough for HEAVY → LIGHT servers can balloon (21 × 2GB = 42GB ceiling on a workstation)
• Cap tight for LIGHT → HEAVY servers throttle on real workloads

A blanket 1 CPU / 512MB is our current interim. It bounds the runaway worst case (21 × 512MB = ~10.5GB) but starves HEAVY servers on bursts.

Proposed solution

Add a resources block to the catalog entry schema, mirroring Docker Compose syntax:

servers:
  - type: image
    image: tigereye/mcp-ast-grep:latest
    snapshot:
      server:
        name: ast-grep
        resources:
          cpus: "2.0"
          memory: "2g"

Per-entry resources would override gateway-wide flags. If absent, fall back to gateway-wide defaults (existing behavior).

Alternative considered

Pre-spawning containers via a wrapper sidecar and proxying through the gateway. Workable but duplicates lifecycle responsibility; the catalog-level field is cleaner.

Cross-ref

TigerEye Enterprise downstream tracking issue: TE-vsco2 (private). Filed alongside upstream FR per policy of preferring native features over local wrappers.