@agents-at-scale/ark 0.1.36 → 0.1.38

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 }}

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

@@ -0,0 +1,80 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "{{ .Values.mcpServerName }}.fullname" . }}
+  labels:
+    {{- include "{{ .Values.mcpServerName }}.labels" . | nindent 4 }}
+spec:
+  {{- if not .Values.autoscaling.enabled }}
+  replicas: {{ .Values.replicaCount }}
+  {{- end }}
+  selector:
+    matchLabels:
+      {{- include "{{ .Values.mcpServerName }}.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      {{- with .Values.podAnnotations }}
+      annotations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      labels:
+        {{- include "{{ .Values.mcpServerName }}.selectorLabels" . | nindent 8 }}
+        {{- with .Values.podLabels }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+    spec:
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      serviceAccountName: {{ include "{{ .Values.mcpServerName }}.serviceAccountName" . }}
+      securityContext:
+        {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      containers:
+        - name: {{ .Chart.Name }}
+          securityContext:
+            {{- toYaml .Values.securityContext | nindent 12 }}
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          ports:
+            - name: http
+              containerPort: 8080
+              protocol: TCP
+          livenessProbe:
+            {{- toYaml .Values.livenessProbe | nindent 12 }}
+          readinessProbe:
+            {{- toYaml .Values.readinessProbe | nindent 12 }}
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          env:
+{{- if .Values.requiresAuth }}
+            - name: AUTH_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.auth.existingSecret | default (include "{{ .Values.mcpServerName }}.fullname" .) }}
+                  key: {{ .Values.auth.existingSecretKey }}
+{{- end }}
+{{- if .Values.hasCustomConfig }}
+            - name: CUSTOM_CONFIG
+              value: {{ .Values.config.customValue | quote }}
+{{- end }}
+          {{- with .Values.volumeMounts }}
+          volumeMounts:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+      {{- with .Values.volumes }}
+      volumes:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}

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

@@ -0,0 +1,32 @@
+{{- if .Values.autoscaling.enabled }}
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: {{ include "{{ .Values.mcpServerName }}.fullname" . }}
+  labels:
+    {{- include "{{ .Values.mcpServerName }}.labels" . | nindent 4 }}
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: {{ include "{{ .Values.mcpServerName }}.fullname" . }}
+  minReplicas: {{ .Values.autoscaling.minReplicas }}
+  maxReplicas: {{ .Values.autoscaling.maxReplicas }}
+  metrics:
+    {{- if .Values.autoscaling.targetCPUUtilizationPercentage }}
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: {{ .Values.autoscaling.targetCPUUtilizationPercentage }}
+    {{- end }}
+    {{- if .Values.autoscaling.targetMemoryUtilizationPercentage }}
+    - type: Resource
+      resource:
+        name: memory
+        target:
+          type: Utilization
+          averageUtilization: {{ .Values.autoscaling.targetMemoryUtilizationPercentage }}
+    {{- end }}
+{{- end }}

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

@@ -0,0 +1,21 @@
+{{- if .Values.mcpServer.create }}
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: MCPServer
+metadata:
+  name: {{ .Values.mcpServer.name | default (include "{{ .Values.mcpServerName }}.fullname" .) }}
+  labels:
+    {{- include "{{ .Values.mcpServerName }}.labels" . | nindent 4 }}
+spec:
+  address:
+    valueFrom:
+      serviceRef:
+        name: {{ include "{{ .Values.mcpServerName }}.fullname" . }}
+        port: http
+        {{- if .Values.mcpServer.path }}
+        path: {{ .Values.mcpServer.path }}
+        {{- end }}
+  transport: sse
+  {{- if .Values.mcpServer.description }}
+  description: {{ .Values.mcpServer.description | quote }}
+  {{- end }}
+{{- end }}

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

@@ -0,0 +1,11 @@
+{{- if and .Values.requiresAuth (not .Values.auth.existingSecret) }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "{{ .Values.mcpServerName }}.fullname" . }}
+  labels:
+    {{- include "{{ .Values.mcpServerName }}.labels" . | nindent 4 }}
+type: Opaque
+data:
+  {{ .Values.auth.existingSecretKey }}: {{ .Values.auth.token | b64enc }}
+{{- end }}

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

@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "{{ .Values.mcpServerName }}.fullname" . }}
+  labels:
+    {{- include "{{ .Values.mcpServerName }}.labels" . | nindent 4 }}
+spec:
+  type: {{ .Values.service.type }}
+  ports:
+    - port: {{ .Values.service.port }}
+      targetPort: {{ .Values.service.targetPort }}
+      protocol: TCP
+      name: http
+  selector:
+    {{- include "{{ .Values.mcpServerName }}.selectorLabels" . | nindent 4 }}

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

@@ -0,0 +1,13 @@
+{{- if .Values.serviceAccount.create -}}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ include "{{ .Values.mcpServerName }}.serviceAccountName" . }}
+  labels:
+    {{- include "{{ .Values.mcpServerName }}.labels" . | nindent 4 }}
+  {{- with .Values.serviceAccount.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+automountServiceAccountToken: {{ .Values.serviceAccount.automount }}
+{{- end }}

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

@@ -0,0 +1,84 @@
+replicaCount: 1
+
+image:
+  repository: {{ .Values.mcpServerName }}
+  pullPolicy: IfNotPresent
+  tag: "latest"
+
+imagePullSecrets: []
+nameOverride: ""
+fullnameOverride: ""
+
+serviceAccount:
+  create: true
+  automount: true
+  annotations: {}
+  name: ""
+
+podAnnotations: {}
+podLabels: {}
+
+podSecurityContext:
+  fsGroup: 2000
+
+securityContext:
+  capabilities:
+    drop:
+    - ALL
+  readOnlyRootFilesystem: true
+  runAsNonRoot: true
+  runAsUser: 1000
+
+service:
+  type: ClusterIP
+  port: 8080
+  targetPort: 8080
+
+resources:
+  limits:
+    cpu: 500m
+    memory: 512Mi
+  requests:
+    cpu: 100m
+    memory: 128Mi
+
+livenessProbe:
+  tcpSocket:
+    port: http
+readinessProbe:
+  tcpSocket:
+    port: http
+
+autoscaling:
+  enabled: false
+  minReplicas: 1
+  maxReplicas: 100
+  targetCPUUtilizationPercentage: 80
+  # targetMemoryUtilizationPercentage: 80
+
+nodeSelector: {}
+
+tolerations: []
+
+affinity: {}
+
+{{- if .Values.requiresAuth }}
+# Authentication configuration
+auth:
+  token: ""
+  existingSecret: ""
+  existingSecretKey: "token"
+{{- end }}
+
+{{- if .Values.hasCustomConfig }}
+# Custom configuration
+config:
+  customValue: ""
+{{- end }}
+
+# MCP Server configuration
+mcpServer:
+  create: true
+  name: ""
+  description: "{{ .Values.description }}"
+  path: "/mcp"

package/templates/mcp-server/example-values.yaml

@@ -0,0 +1,74 @@
+# Example values for {{ .Values.mcpServerName }} MCP Server
+
+replicaCount: 2
+
+image:
+  repository: {{ .Values.mcpServerName }}
+  pullPolicy: Always
+  tag: "v1.0.0"
+
+service:
+  type: ClusterIP
+  port: 8080
+
+resources:
+  limits:
+    cpu: 1000m
+    memory: 1Gi
+  requests:
+    cpu: 250m
+    memory: 256Mi
+
+{{- if .Values.requiresAuth }}
+# Authentication configuration
+auth:
+  token: "your-auth-token-here"
+  # Or use existing secret:
+  # existingSecret: "my-auth-secret"
+  # existingSecretKey: "token"
+{{- end }}
+
+{{- if .Values.hasCustomConfig }}
+# Custom configuration
+config:
+  customValue: "custom-configuration-value"
+{{- end }}
+
+# MCP Server configuration
+mcpServer:
+  create: true
+  name: "{{ .Values.mcpServerName }}-server"
+  description: "{{ .Values.description }}"
+  path: "/mcp"
+
+# Enable autoscaling
+autoscaling:
+  enabled: true
+  minReplicas: 2
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 70
+  targetMemoryUtilizationPercentage: 80
+
+# Node selection
+nodeSelector:
+  kubernetes.io/arch: amd64
+
+# Tolerations
+tolerations:
+  - key: "node-role.kubernetes.io/worker"
+    operator: "Exists"
+    effect: "NoSchedule"
+
+# Affinity rules
+affinity:
+  podAntiAffinity:
+    preferredDuringSchedulingIgnoredDuringExecution:
+    - weight: 100
+      podAffinityTerm:
+        labelSelector:
+          matchExpressions:
+          - key: app.kubernetes.io/name
+            operator: In
+            values:
+            - {{ .Values.mcpServerName }}
+        topologyKey: kubernetes.io/hostname