@agents-at-scale/ark 0.1.37 → 0.1.38

package/templates/mcp-server/Dockerfile

@@ -0,0 +1,133 @@
+{{- if eq .Values.technology "node" }}
+FROM node:22
+
+# Install the MCP server package
+{{- if .Values.packageSource }}
+{{- if eq .Values.packageSource "npm" }}
+RUN npm install -g {{ .Values.packageName }}
+{{- else if eq .Values.packageSource "local" }}
+COPY . /app
+WORKDIR /app
+RUN npm install
+{{- end }}
+{{- else }}
+COPY . /app
+WORKDIR /app
+RUN npm install
+{{- end }}
+
+# Install mcp-proxy for HTTP transport
+RUN npm install -g mcp-proxy
+
+EXPOSE 8080
+
+{{- if eq .Values.packageSource "npm" }}
+ENTRYPOINT [ "/bin/sh", "-c", "mcp-proxy --debug --port 8080 --host 0.0.0.0 --shell \"{{ .Values.packageName }} stdio\"" ]
+{{- else }}
+ENTRYPOINT [ "/bin/sh", "-c", "mcp-proxy --debug --port 8080 --host 0.0.0.0 --shell \"node index.js stdio\"" ]
+{{- end }}
+
+{{- else if eq .Values.technology "deno" }}
+FROM denoland/deno:2.1.8
+
+USER root
+
+# Install Node.js for mcp-proxy
+RUN apt-get update && apt-get install -y \
+    curl \
+    && curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install mcp-proxy
+RUN npm install -g mcp-proxy
+
+{{- if .Values.packageSource }}
+{{- if eq .Values.packageSource "jsr" }}
+RUN deno install --global -A --node-modules-dir=auto {{ .Values.packageName }}
+{{- else if eq .Values.packageSource "local" }}
+COPY . /app
+WORKDIR /app
+{{- end }}
+{{- else }}
+COPY . /app
+WORKDIR /app
+{{- end }}
+
+EXPOSE 8080
+
+{{- if eq .Values.packageSource "jsr" }}
+ENTRYPOINT [ "/bin/bash", "-c", "mcp-proxy --debug --port 8080 --host 0.0.0.0 --shell \"deno run -A --node-modules-dir=auto {{ .Values.packageName }} stdio\"" ]
+{{- else }}
+ENTRYPOINT [ "/bin/bash", "-c", "mcp-proxy --debug --port 8080 --host 0.0.0.0 --shell \"deno run -A index.ts stdio\"" ]
+{{- end }}
+
+{{- else if eq .Values.technology "go" }}
+FROM golang:latest AS go-builder
+{{- if .Values.packageSource }}
+{{- if eq .Values.packageSource "go-install" }}
+RUN go install {{ .Values.packageName }}@latest
+{{- else if eq .Values.packageSource "local" }}
+COPY . /app
+WORKDIR /app
+RUN go build -o {{ .Values.mcpServerName }} .
+{{- end }}
+{{- else }}
+COPY . /app
+WORKDIR /app
+RUN go build -o {{ .Values.mcpServerName }} .
+{{- end }}
+
+FROM node:22
+{{- if eq .Values.packageSource "go-install" }}
+COPY --from=go-builder /go/bin/{{ .Values.packageName }} /usr/local/bin/
+{{- else }}
+COPY --from=go-builder /app/{{ .Values.mcpServerName }} /usr/local/bin/
+{{- end }}
+RUN npm install -g mcp-proxy
+
+EXPOSE 8080
+
+{{- if eq .Values.packageSource "go-install" }}
+ENTRYPOINT [ "/bin/sh", "-c", "mcp-proxy --debug --port 8080 --host 0.0.0.0 --shell \"/usr/local/bin/{{ .Values.packageName }} stdio\"" ]
+{{- else }}
+ENTRYPOINT [ "/bin/sh", "-c", "mcp-proxy --debug --port 8080 --host 0.0.0.0 --shell \"/usr/local/bin/{{ .Values.mcpServerName }} stdio\"" ]
+{{- end }}
+
+{{- else if eq .Values.technology "python" }}
+FROM python:3.11-slim
+
+WORKDIR /app
+
+{{- if .Values.packageSource }}
+{{- if eq .Values.packageSource "pip" }}
+RUN pip install {{ .Values.packageName }}
+{{- else if eq .Values.packageSource "local" }}
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+COPY . .
+{{- end }}
+{{- else }}
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+COPY . .
+{{- end }}
+
+# Install Node.js for mcp-proxy
+RUN apt-get update && apt-get install -y \
+    curl \
+    && curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN npm install -g mcp-proxy
+
+EXPOSE 8080
+
+{{- if eq .Values.packageSource "pip" }}
+ENTRYPOINT [ "/bin/bash", "-c", "mcp-proxy --debug --port 8080 --host 0.0.0.0 --shell \"{{ .Values.packageName }} stdio\"" ]
+{{- else }}
+ENTRYPOINT [ "/bin/bash", "-c", "mcp-proxy --debug --port 8080 --host 0.0.0.0 --shell \"python main.py stdio\"" ]
+{{- end }}
+
+{{- end }}

package/templates/mcp-server/Makefile

@@ -0,0 +1,186 @@
+# {{ .Values.mcpServerName }} MCP Server Makefile
+
+# Variables
+IMAGE_NAME ?= {{ .Values.mcpServerName }}
+IMAGE_TAG ?= latest
+TARGET_CLUSTER ?= auto
+HELM_RELEASE_NAME ?= {{ .Values.mcpServerName }}-mcp
+
+# Docker image build
+.PHONY: build
+build:
+	@echo "Building {{ .Values.mcpServerName }} MCP Server Docker image..."
+	./build.sh $(IMAGE_TAG) $(TARGET_CLUSTER)
+
+{{- if .Values.requiresAuth }}
+# Install using Helm
+.PHONY: install
+install:
+	@echo "Installing {{ .Values.mcpServerName }} MCP Server with Helm..."
+	@if [ -z "$(AUTH_TOKEN)" ]; then \
+		echo "Error: AUTH_TOKEN environment variable is required"; \
+		echo "Usage: make install AUTH_TOKEN=your-auth-token"; \
+		exit 1; \
+	fi
+	helm install $(HELM_RELEASE_NAME) ./chart \
+		--set auth.token="$(AUTH_TOKEN)"
+{{- else }}
+# Install using Helm
+.PHONY: install
+install:
+	@echo "Installing {{ .Values.mcpServerName }} MCP Server with Helm..."
+	helm install $(HELM_RELEASE_NAME) ./chart
+{{- end }}
+
+# Install with values file
+.PHONY: install-with-values
+install-with-values:
+	@echo "Installing {{ .Values.mcpServerName }} MCP Server with values file..."
+	@if [ -z "$(VALUES_FILE)" ]; then \
+		echo "Error: VALUES_FILE is required"; \
+		echo "Usage: make install-with-values VALUES_FILE=example-values.yaml"; \
+		exit 1; \
+	fi
+	helm install $(HELM_RELEASE_NAME) ./chart \
+		--values $(VALUES_FILE)
+
+# Upgrade using Helm
+.PHONY: upgrade
+upgrade:
+	@echo "Upgrading {{ .Values.mcpServerName }} MCP Server with Helm..."
+{{- if .Values.requiresAuth }}
+	@if [ -n "$(AUTH_TOKEN)" ]; then \
+		helm upgrade $(HELM_RELEASE_NAME) ./chart \
+			--set auth.token="$(AUTH_TOKEN)"; \
+	elif [ -n "$(VALUES_FILE)" ]; then \
+		helm upgrade $(HELM_RELEASE_NAME) ./chart \
+			--values $(VALUES_FILE); \
+	else \
+		helm upgrade $(HELM_RELEASE_NAME) ./chart; \
+	fi
+{{- else }}
+	@if [ -n "$(VALUES_FILE)" ]; then \
+		helm upgrade $(HELM_RELEASE_NAME) ./chart \
+			--values $(VALUES_FILE); \
+	else \
+		helm upgrade $(HELM_RELEASE_NAME) ./chart; \
+	fi
+{{- end }}
+
+# Uninstall using Helm
+.PHONY: uninstall
+uninstall:
+	@echo "Uninstalling {{ .Values.mcpServerName }} MCP Server..."
+	helm uninstall $(HELM_RELEASE_NAME)
+
+# Check status
+.PHONY: status
+status:
+	@echo "Checking {{ .Values.mcpServerName }} MCP Server status..."
+	@echo "=== Helm Release Status ==="
+	helm status $(HELM_RELEASE_NAME)
+	@echo ""
+	@echo "=== Pod Status ==="
+	kubectl get pods -l app.kubernetes.io/name={{ .Values.mcpServerName }}
+	@echo ""
+	@echo "=== Service Status ==="
+	kubectl get svc -l app.kubernetes.io/name={{ .Values.mcpServerName }}
+	@echo ""
+	@echo "=== MCP Server Status ==="
+	kubectl get mcpservers -l app.kubernetes.io/name={{ .Values.mcpServerName }}
+
+# Show logs
+.PHONY: logs
+logs:
+	@echo "Showing {{ .Values.mcpServerName }} MCP Server logs..."
+	kubectl logs -l app.kubernetes.io/name={{ .Values.mcpServerName }} --follow
+
+# Deploy examples
+.PHONY: deploy-examples
+deploy-examples:
+	@echo "Deploying example agent and query..."
+	kubectl apply -f examples/
+
+# Clean up examples
+.PHONY: clean-examples
+clean-examples:
+	@echo "Cleaning up example resources..."
+	kubectl delete -f examples/ --ignore-not-found
+
+# Test the MCP server
+.PHONY: test
+test:
+	@echo "Testing {{ .Values.mcpServerName }} MCP Server..."
+{{- if .Values.technology }}
+{{- if eq .Values.technology "node" }}
+	npm test
+{{- else if eq .Values.technology "python" }}
+	python -m pytest
+{{- else if eq .Values.technology "go" }}
+	go test ./...
+{{- else if eq .Values.technology "deno" }}
+	deno test
+{{- end }}
+{{- else }}
+	@echo "No tests configured for this MCP server"
+{{- end }}
+
+# Development server
+.PHONY: dev
+dev:
+	@echo "Starting {{ .Values.mcpServerName }} MCP Server in development mode..."
+{{- if .Values.technology }}
+{{- if eq .Values.technology "node" }}
+	npm run dev
+{{- else if eq .Values.technology "python" }}
+	python main.py
+{{- else if eq .Values.technology "go" }}
+	go run .
+{{- else if eq .Values.technology "deno" }}
+	deno run -A index.ts
+{{- end }}
+{{- else }}
+	@echo "Development mode not configured for this MCP server"
+{{- end }}
+
+# Port forward for local testing
+.PHONY: port-forward
+port-forward:
+	@echo "Port forwarding {{ .Values.mcpServerName }} MCP Server to localhost:8080..."
+	kubectl port-forward svc/$(HELM_RELEASE_NAME) 8080:8080
+
+# Help
+.PHONY: help
+help:
+	@echo "{{ .Values.mcpServerName }} MCP Server Makefile"
+	@echo ""
+	@echo "Available targets:"
+	@echo "  build              Build Docker image"
+	@echo "  install            Install with Helm"
+	@echo "  install-with-values Install with values file"
+	@echo "  upgrade            Upgrade with Helm"
+	@echo "  uninstall          Uninstall from cluster"
+	@echo "  status             Check deployment status"
+	@echo "  logs               Show pod logs"
+	@echo "  deploy-examples    Deploy example resources"
+	@echo "  clean-examples     Clean up example resources"
+	@echo "  test               Run tests"
+	@echo "  dev                Start development server"
+	@echo "  port-forward       Port forward to localhost"
+	@echo "  help               Show this help"
+	@echo ""
+{{- if .Values.requiresAuth }}
+	@echo "Environment variables:"
+	@echo "  AUTH_TOKEN         Authentication token (required for install)"
+	@echo "  VALUES_FILE        Helm values file path"
+	@echo ""
+{{- end }}
+	@echo "Examples:"
+{{- if .Values.requiresAuth }}
+	@echo "  make install AUTH_TOKEN=your-token"
+{{- else }}
+	@echo "  make install"
+{{- end }}
+	@echo "  make install-with-values VALUES_FILE=example-values.yaml"
+	@echo "  make upgrade"
+	@echo "  make status"

package/templates/mcp-server/README.md

@@ -0,0 +1,178 @@
+# {{ .Values.mcpServerName }} MCP Server
+
+{{ .Values.description }}
+
+## Prerequisites
+
+- Kubernetes 1.19+
+- Helm 3.2.0+
+  {{- if .Values.requiresAuth }}
+- Authentication credentials configured
+  {{- end }}
+
+## Installation
+
+### 1. Build the Docker Image
+
+```bash
+cd /path/to/{{ .Values.mcpServerName }}
+docker build -t {{ .Values.mcpServerName }}:latest .
+```
+
+### 2. Install the Helm Chart
+
+```bash
+# Install the MCP server
+helm install {{ .Values.mcpServerName }}-mcp ./chart \
+{{- if .Values.requiresAuth }}
+  --set auth.token="your-auth-token"
+{{- end }}
+{{- if .Values.hasCustomConfig }}
+  --set config.customValue="your-config-value"
+{{- end }}
+
+# Or install with values file
+helm install {{ .Values.mcpServerName }}-mcp ./chart \
+  --values example-values.yaml
+```
+
+### 3. Deploy Agent and Query (Optional)
+
+```bash
+# Deploy the example agent and query that use the MCP server
+kubectl apply -f examples/{{ .Values.mcpServerName }}-agent.yaml
+```
+
+### 4. Verify Installation
+
+```bash
+kubectl get pods -l app.kubernetes.io/name={{ .Values.mcpServerName }}
+kubectl get mcpservers
+kubectl get agents
+kubectl get queries
+```
+
+## Configuration
+
+### Helm Values
+
+| Key                | Type   | Default                         | Description        |
+| ------------------ | ------ | ------------------------------- | ------------------ |
+| `replicaCount`     | int    | `1`                             | Number of replicas |
+| `image.repository` | string | `"{{ .Values.mcpServerName }}"` | Image repository   |
+| `image.tag`        | string | `"latest"`                      | Image tag          |
+| `service.port`     | int    | `8080`                          | Service port       |
+
+{{- if .Values.requiresAuth }}
+| `auth.token` | string | `""` | Authentication token |
+| `auth.existingSecret` | string | `""` | Existing secret name for auth |
+{{- end }}
+{{- if .Values.hasCustomConfig }}
+| `config.customValue` | string | `""` | Custom configuration value |
+{{- end }}
+
+### Environment Variables
+
+{{- if .Values.requiresAuth }}
+
+- `AUTH_TOKEN`: Authentication token for the service
+  {{- end }}
+  {{- if .Values.hasCustomConfig }}
+- `CUSTOM_CONFIG`: Custom configuration for the MCP server
+  {{- end }}
+
+## MCP Tools
+
+The {{ .Values.mcpServerName }} MCP server provides these tools:
+
+{{- range .Values.tools }}
+
+- `{{ .name }}` - {{ .description }}
+  {{- end }}
+
+## Docker Usage
+
+Run the container directly:
+
+```bash
+docker build -t {{ .Values.mcpServerName }} .
+docker run -p 8080:8080 {{ .Values.mcpServerName }}
+```
+
+The server will be available at `http://localhost:8080/mcp`
+
+## Development
+
+### Local Development
+
+1. Install dependencies:
+
+```bash
+{{ .Values.packageManager }} install
+```
+
+2. Run the server:
+
+```bash
+{{ .Values.packageManager }} start
+```
+
+3. Test the MCP server:
+
+```bash
+# Using MCP Inspector or similar tool
+mcp-inspector http://localhost:8080/mcp
+```
+
+### Testing
+
+```bash
+{{ .Values.packageManager }} test
+```
+
+## Architecture
+
+This MCP server is built using:
+
+- **{{ .Values.technology }}**: Core MCP server implementation
+- **mcp-proxy**: HTTP transport layer for the MCP protocol
+- **Kubernetes**: Container orchestration and deployment
+- **Helm**: Package management and configuration
+
+## Examples
+
+See the `examples/` directory for:
+
+- Agent configurations using this MCP server
+- Query examples
+- Integration patterns
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Connection refused**: Check if the service is running and port 8080 is accessible
+2. **Authentication failed**: Verify auth token configuration
+3. **Tool not found**: Ensure the MCP server is properly registered
+
+### Logs
+
+```bash
+# Check pod logs
+kubectl logs -l app.kubernetes.io/name={{ .Values.mcpServerName }}
+
+# Check MCP server registration
+kubectl describe mcpserver {{ .Values.mcpServerName }}
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

package/templates/mcp-server/build.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+
+# {{ .Values.mcpServerName }} MCP Server Build Script
+
+set -e
+
+IMAGE_TAG=${1:-latest}
+TARGET_CLUSTER=${2:-auto}
+IMAGE_NAME="{{ .Values.mcpServerName }}"
+
+echo "Building {{ .Values.mcpServerName }} MCP Server..."
+echo "Image: ${IMAGE_NAME}:${IMAGE_TAG}"
+echo "Target cluster: ${TARGET_CLUSTER}"
+
+# Build the Docker image
+docker build -t ${IMAGE_NAME}:${IMAGE_TAG} .
+
+# Tag and push based on target cluster
+case $TARGET_CLUSTER in
+    "auto")
+        echo "Auto-detecting cluster configuration..."
+        # Try to detect if we're in a local development environment
+        if kubectl config current-context | grep -E "(kind|minikube|docker-desktop)" > /dev/null 2>&1; then
+            echo "Local development cluster detected, loading image locally..."
+            
+            # Load image into kind if available
+            if command -v kind > /dev/null 2>&1 && kind get clusters > /dev/null 2>&1; then
+                echo "Loading image into kind cluster..."
+                kind load docker-image ${IMAGE_NAME}:${IMAGE_TAG}
+            fi
+            
+            # Load image into minikube if available
+            if command -v minikube > /dev/null 2>&1 && minikube status > /dev/null 2>&1; then
+                echo "Loading image into minikube..."
+                minikube image load ${IMAGE_NAME}:${IMAGE_TAG}
+            fi
+        else
+            echo "Remote cluster detected, pushing to registry..."
+            docker push ${IMAGE_NAME}:${IMAGE_TAG}
+        fi
+        ;;
+    "local"|"kind"|"minikube")
+        echo "Loading image into local cluster..."
+        
+        if [[ $TARGET_CLUSTER == "kind" ]] && command -v kind > /dev/null 2>&1; then
+            kind load docker-image ${IMAGE_NAME}:${IMAGE_TAG}
+        elif [[ $TARGET_CLUSTER == "minikube" ]] && command -v minikube > /dev/null 2>&1; then
+            minikube image load ${IMAGE_NAME}:${IMAGE_TAG}
+        else
+            echo "Local cluster tools not available, skipping image load"
+        fi
+        ;;
+    "remote"|"registry")
+        echo "Pushing image to registry..."
+        docker push ${IMAGE_NAME}:${IMAGE_TAG}
+        ;;
+    *)
+        echo "Unknown target cluster: $TARGET_CLUSTER"
+        echo "Valid options: auto, local, kind, minikube, remote, registry"
+        exit 1
+        ;;
+esac
+
+echo "{{ .Values.mcpServerName }} MCP Server build completed successfully!"
+echo ""
+echo "Next steps:"
+echo "1. Install the Helm chart:"
+{{- if .Values.requiresAuth }}
+echo "   make install AUTH_TOKEN=your-auth-token"
+{{- else }}
+echo "   make install"
+{{- end }}
+echo "2. Check the status:"
+echo "   make status"
+echo "3. View logs:"
+echo "   make logs"

package/templates/mcp-server/chart/Chart.yaml

@@ -0,0 +1,22 @@
+apiVersion: v2
+name: {{ .Values.mcpServerName }}
+description: {{ .Values.description }}
+type: application
+version: 0.1.0
+appVersion: "latest"
+keywords:
+  - mcp
+  - {{ .Values.mcpServerName }}
+  - proxy
+  - agent
+{{- if .Values.homeUrl }}
+home: {{ .Values.homeUrl }}
+{{- end }}
+{{- if .Values.sourceUrls }}
+sources:
+{{- range .Values.sourceUrls }}
+  - {{ . }}
+{{- end }}
+{{- end }}
+maintainers:
+  - name: {{ .Values.maintainerName | default "QBAF Team" }}

package/templates/mcp-server/chart/templates/_helpers.tpl

@@ -0,0 +1,62 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "{{ .Values.mcpServerName }}.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "{{ .Values.mcpServerName }}.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "{{ .Values.mcpServerName }}.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "{{ .Values.mcpServerName }}.labels" -}}
+helm.sh/chart: {{ include "{{ .Values.mcpServerName }}.chart" . }}
+{{ include "{{ .Values.mcpServerName }}.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "{{ .Values.mcpServerName }}.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "{{ .Values.mcpServerName }}.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "{{ .Values.mcpServerName }}.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "{{ .Values.mcpServerName }}.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}