feat: consolidate multiple updates and features for MCP server chart

- Add configurable MCP server chart with SSE/WS/stdio support and optional mcp-proxy
- Add root-level 'unla.enabled' (default true) to gate Unla subchart and registration hooks
- Add optional stdioBridge per server using mcp-proxy, generate SSE endpoint and register accordingly
- Remove outdated NOTES.txt as port-forward note was redundant and potentially confusing
- Default stdioBridge image to ghcr.io/icoretech/mcp-stdio-bridge:latest
- Add TCP readiness/liveness probes on port 3000 for bridge, default bridge tag to v0.1.0
- Update stdioBridge example to v0.2.1 (Node 24 base)
- Normalize and slim examples set, use public bridge v0.2.1, disable register for standalone testing
- Drop flaky python stdio test, keep node SSE, node stdio bridge, python SSE
- Add gateway-register config and job templates
- Add server-specific templates (deployment, HPA, service)
- Update examples with gateway configurations and other improvements
- Update documentation and schema files accordingly

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

Author: masterkain

.github/workflows/mcp-server-e2e.yaml

@@ -0,0 +1,30 @@
+name: mcp-server e2e
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5.0.0
+      - name: Setup kubectl
+        uses: azure/setup-kubectl@v4.0.1
+        with:
+          version: latest
+      - name: Setup Helm
+        uses: azure/setup-helm@v4.3.1
+        with:
+          version: latest
+      - name: Setup kind
+        uses: helm/kind-action@v1.12.0
+        with:
+          version: v0.24.0
+          kubectl_version: v1.30.0
+      - name: Run e2e
+        run: |
+          chmod +x hack/e2e/e2e.sh
+          ./hack/e2e/e2e.sh
+

.github/workflows/release.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5.0.0
         with:
           fetch-depth: 0
 
@@ -24,7 +24,7 @@ jobs:
 
       - name: Install Helm
         id: install
-        uses: azure/setup-helm@v4.3.0
+        uses: azure/setup-helm@v4.3.1
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
 

.github/workflows/test.yml

@@ -7,12 +7,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5.0.0
         with:
           fetch-depth: 0
 
       - name: Set up Helm
-        uses: azure/setup-helm@v4.2.0
+        uses: azure/setup-helm@v4.3.1
 
       - uses: actions/setup-python@v5
         with:
@@ -36,7 +36,7 @@ jobs:
 
       - name: Create kind cluster
         if: steps.list-changed.outputs.changed == 'true'
-        uses: helm/kind-action@v1.10.0
+        uses: helm/kind-action@v1.12.0
 
       - name: Run chart-testing (install)
         if: steps.list-changed.outputs.changed == 'true'

charts/mcp-server/Chart.yaml

@@ -1,6 +1,6 @@
 apiVersion: v2
 name: mcp-server
-description: "Generic MCP server runner for Node (TypeScript) and Python servers. Supports three modes: direct container image, Node (npx), and Python (uvx/pip)."
+description: "Generic MCP server runner for Node (TypeScript) and Python servers. Supports four modes: direct container image, Node (npx), Python (uvx/pip), and OpenAPI (external URL registered in Unla)."
 
 # A chart can be either an 'application' or a 'library' chart.
 #
@@ -15,7 +15,7 @@ type: application
 # This is the chart version. This version number should be incremented each time you make changes
 # to the chart and its templates, including the app version.
 # Versions are expected to follow Semantic Versioning (https://semver.org/)
-version: 0.1.0
+version: 0.1.2
 
 # This is the version number of the application being deployed. This version number should be
 # incremented each time you make changes to the application. Versions are not expected to
@@ -45,3 +45,10 @@ annotations:
     - kind: added
       description: Initial release with image, node (npx) and python (uvx/pip) modes
   artifacthub.io/prerelease: "false"
+
+dependencies:
+  - name: unla
+    version: "0.9.0"
+    repository: "https://amoylab.github.io/unla-helm-charts"
+    # Allow turning the subchart on/off from root values via `unla.enabled`
+    condition: unla.enabled

charts/mcp-server/README.md

@@ -1,53 +1,17 @@
 # mcp-server Helm Chart
 
-Generic runner for Model Context Protocol (MCP) servers on
-Kubernetes.
+Generic runner for Model Context Protocol (MCP) servers on Kubernetes.
+This chart deploys one Deployment/Service per servers[] entry (Node via npx,
+Python via uv tool run, or a pre-built image), and can also register external
+OpenAPI specs without creating Pods. Everything is wired into an Unla MCP
+Gateway (subchart) that exposes a single aggregated endpoint.
 
-This chart supports three modes:
+## Stdio transport (not supported)
 
-- `image`: run a pre-built container image that already includes your MCP
-  server (recommended for production).
-- `node`: run a Node/TypeScript MCP server package via `npx` inside a
-  `node:alpine` container.
-- `python`: run a Python MCP server via `uvx` (or `pip`) inside a `uv`/`python`
-  container.
-
-## Named Servers (Spotlight)
-
-Run many stdio‑based MCP servers behind a single HTTP(SSE) endpoint using the
-built‑in gateway option powered by `mcp-proxy`.
-
-What it is
-
-- One process exposes an SSE endpoint and spawns multiple stdio MCP servers as
-  child processes.
-- Each server is reachable at `/servers/{name}/sse` (a default server can also
-  be exposed at `/sse`).
-
-Why it’s useful
-
-- One Service/Ingress/Gateway for multiple stdio MCP servers.
-- Central place for long‑lived connection tuning (SSE/WS timeouts).
-- Great for internal hubs, demos, or small fleets.
-
-When not to use
-
-- If you need per‑server autoscaling/isolation, prefer multiple Deployments or
-  an external reverse proxy.
-
-How to enable
-
-- Set `transport.type: stdio` and `transport.stdioGateway.enabled: true`.
-- Add entries under `transport.stdioGateway.servers` with `command`/`args`/`env`.
-- Or provide raw JSON via `transport.stdioGateway.namedServersJson`.
-- Use `transport.stdioGateway.preStart` for installing servers (e.g., pip
-  install) or ship a custom image.
-
-Endpoints
-
-- Default: `/sse` (if you spawn a default server after `--`).
-- Named: `/servers/{name}/sse`.
-- Status: `/status`.
+This chart intentionally does not support stdio-only MCP servers. Kubernetes pods are designed for
+long‑lived network services; supervising interactive stdio processes reliably (signals, restarts,
+child lifecycles) is brittle. Pick servers that expose HTTP (SSE) or WebSocket natively. If you must
+translate stdio, run a dedicated gateway outside this chart and route to it with a normal Service.
 
 ## Prerequisites
 
@@ -79,127 +43,42 @@ default values.
 {{ template "chart.valuesSection" . }}
 <!-- markdownlint-enable MD013 -->
 
-## Transports and Exposure
+## Transports and Exposure (via Unla Gateway)
 
 Transports
 
-- `http-sse` (default): stream over a long‑lived HTTP connection.
-- `websocket`: stream over WebSocket.
-- `stdio`: intended for local clients; in Kubernetes it needs a gateway/bridge.
-  This chart offers a stdio gateway mode using `mcp-proxy`.
+- HTTP (SSE/streamable HTTP): long‑lived HTTP connection.
+- WebSocket: use when your server exposes a WS endpoint.
 
-Exposure options
+Exposure is handled by the Unla subchart. Port-forward the gateway Service:
 
-- ClusterIP + port‑forward: simplest local testing.
-- Ingress (e.g., NGINX): add WS upgrade annotations and increase timeouts.
-- Gateway API (HTTPRoute): set `rules.timeouts.request/backendRequest` for
-  long‑lived connections.
+```bash
+kubectl -n <ns> port-forward svc/<release> 8000:5235
+```
 
 Timeout tips
 
 - SSE: raise read/send/proxy timeouts (NGINX `proxy-read-timeout` and
   `proxy-send-timeout` to `3600`).
 - WebSocket: ensure upgrade support (NGINX: `enable-websocket: "true"`).
 
-## Examples
-
-Node mode (npx):
-
-```yaml
-mode: node
-node:
-  image: node:24-alpine
-  package: mcp-remote
-  version: latest
-  args:
-    - https://docs.mcp.cloudflare.com/sse
-    - --port
-    - "3000"
-container:
-  port: 3000
-service:
-  port: 3000
-```
-
-Python mode (uvx):
-
-```yaml
-mode: python
-python:
-  image: ghcr.io/astral-sh/uv:latest
-  package: awslabs.aws-documentation-mcp-server@latest
-  args:
-    - --port
-    - "3000"
-container:
-  port: 3000
-service:
-  port: 3000
-```
+## Dependency Caching (per server)
 
-Stdio gateway with named servers (mcp-proxy):
-
-```yaml
-# Exposes /sse for default server and /servers/{name}/sse for named servers
-mode: python
-python:
-  image: ghcr.io/astral-sh/uv:latest
-  package: awslabs.aws-documentation-mcp-server@latest
-  args:
-    - --port
-    - "3000"
-service:
-  port: 3000
-transport:
-  type: stdio
-  stdioGateway:
-    enabled: true
-    image: ghcr.io/sparfenyuk/mcp-proxy:latest
-    passEnvironment: true
-    allowOrigins: ["*"]
-    preStart:
-      - pip install --no-cache-dir awslabs.aws-documentation-mcp-server awslabs.aws-pricing-mcp-server
-    servers:
-      docs:
-        command: awslabs.aws-documentation-mcp-server
-      pricing:
-        command: awslabs.aws-pricing-mcp-server
-```
-
-WebSocket via NGINX Ingress:
-
-```yaml
-service:
-  port: 3000
-container:
-  port: 3000
-transport:
-  type: websocket
-  http:
-    wsPath: /ws
-ingress:
-  enabled: true
-  className: nginx
-  annotations:
-    nginx.ingress.kubernetes.io/enable-websocket: "true"
-    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
-    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
-  hosts:
-    - host: mcp.example.local
-      paths:
-        - path: /
-          pathType: Prefix
-```
+Enable servers[].cache to persist npm/uv caches between restarts. Set
+servers[].cache.pvc.existingClaim to bind an existing PVC or omit to let the
+chart create one per server.
 
-Example values files are provided under `charts/mcp-server/examples/`:
+## Examples provided under `charts/mcp-server/examples/`
 
-- `node-mcp-remote.yaml`: Node mode using `mcp-remote`.
-- `python-aws-docs.yaml`: Python mode using `awslabs.aws-documentation-mcp-server`.
-- `stdio-gateway-named-servers.yaml`: Stdio gateway with two named servers.
-- `ingress-websocket-nginx.yaml`: WebSocket transport behind NGINX Ingress.
-- `gateway-http.yaml`: Minimal Gateway (Gateway API) to attach HTTPRoutes.
-- `httproute-sse-gatewayapi.yaml`: HTTPRoute with timeouts for SSE/Streamable HTTP.
-- `httproute-websocket-gatewayapi.yaml`: HTTPRoute with timeouts for WebSocket.
+- `node-server-everything.yaml` - Node mode using
+  `@modelcontextprotocol/server-everything` (streamable HTTP pinned to Node 22).
+- `python-aws-pricing.yaml` - Minimal Python mode example running the
+  AWS Pricing MCP server (HTTP/SSE).
+- `python-fastmcp-http.yaml` - Advanced Python mode running the
+  `mcp-server` sample with streamable HTTP arguments.
+ - `openapi.yaml` - Register an external OpenAPI URL with Unla (no Pod created).
+  
+  
 
 Gateway API quickstart:
 

charts/mcp-server/README.md.gotmpl

@@ -0,0 +1,36 @@
+# Example: Microsoft MCP Gateway–centric deployment with two servers in one Pod.
+#
+# Why this example exists
+# - Demonstrates the new gateway-centric architecture: one gateway Pod aggregates
+#   multiple MCP servers that run as sidecar containers in a single Deployment.
+# - Shows two Node HTTP-compatible MCP servers (as most MCP servers are stdio-only).
+# - Uses a public gateway image by default for out-of-the-box local testing. To
+#   switch to Microsoft MCP Gateway, build/push your image and override
+#   gateway.image.repository/tag accordingly.
+# - IMPORTANT: Only use confirmed HTTP-compatible servers. Most MCP servers are stdio-only.
+# - This example uses the same working server twice as reliable HTTP-compatible examples.
+
+# Gateway is provided by the Unla subchart; default ports are used (5235)
+
+# Run two servers in a single Pod
+servers:
+  - name: everything
+    type: node
+    port: 3001
+    node:
+      package: "@modelcontextprotocol/server-everything"
+      version: "latest"
+      args: ["streamableHttp"]
+      # Only the tag should be customized in examples
+      tag: 24-alpine
+
+  - name: everything-alt
+    type: node
+    port: 3002
+    node:
+      package: "@modelcontextprotocol/server-everything"
+      version: "latest"
+      args: ["streamableHttp"]
+      tag: 24-alpine
+
+# No parent Service; the subchart exposes Service named after the release, port 5235