@agents-at-scale/ark 0.1.36 → 0.1.38

package/templates/marketplace/agents/.keep

@@ -0,0 +1,29 @@
+# Agents Directory
+
+This directory contains reusable agent definitions that can be shared across projects.
+
+## Structure
+
+Each agent should be in its own file or subdirectory (complex agents) with:
+
+- agent.yaml (the main agent definition)
+- README.md (documentation)
+- examples/ (optional usage examples)
+
+## Naming Convention
+
+Use descriptive names that indicate the agent's purpose:
+
+- data-analyst/
+- code-reviewer/
+- security-scanner/
+- documentation-writer/
+
+## Contributing
+
+When contributing an agent:
+
+1. Ensure it follows the Ark agent specification
+2. Include comprehensive documentation
+3. Provide usage examples
+4. Test with multiple models when possible

package/templates/marketplace/docs/.keep

@@ -0,0 +1,19 @@
+# Documentation Directory
+
+Documentation for the marketplace and its components.
+
+## Structure
+
+- contributing.md - Guidelines for contributors
+- component-specs/ - Specifications for different component types
+- best-practices/ - Development and usage best practices
+- tutorials/ - Step-by-step guides
+- api/ - API documentation
+
+## Documentation Standards
+
+1. Use clear, concise language
+2. Include code examples
+3. Keep documentation up-to-date
+4. Follow markdown conventions
+5. Include diagrams where helpful

package/templates/marketplace/mcp-servers/.keep

@@ -0,0 +1,32 @@
+# MCP Servers Directory
+
+This directory contains Model Context Protocol (MCP) server configurations and implementations.
+
+## Structure
+
+Each MCP server should be in its own subdirectory with:
+
+- mcp-server.yaml (server configuration)
+- src/ (source code if custom implementation)
+- Dockerfile (if containerized)
+- README.md (documentation)
+- examples/ (usage examples)
+
+## Naming Convention
+
+Use descriptive names that indicate the server's purpose:
+
+- file-system-server/
+- database-server/
+- api-gateway-server/
+- knowledge-base-server/
+
+## Contributing
+
+When contributing an MCP server:
+
+1. Follow MCP protocol specifications
+2. Include security configurations
+3. Document all available tools/resources
+4. Provide integration examples
+5. Include monitoring and logging setup

package/templates/marketplace/models/.keep

@@ -0,0 +1,23 @@
+# Models Directory
+
+This directory contains model configurations for different AI providers and use cases.
+
+## Structure
+Each model configuration should be:
+- provider-specific directories (openai/, anthropic/, etc.)
+- model-specific YAML files within each directory
+- README.md documenting capabilities and limitations
+
+## Naming Convention
+Use provider and model names:
+- openai/gpt-4.yaml
+- anthropic/claude-3-sonnet.yaml
+- azure/gpt-4-32k.yaml
+- local/llama2-7b.yaml
+
+## Contributing
+When contributing a model configuration:
+1. Include provider-specific settings
+2. Document token limits and capabilities
+3. Specify recommended use cases
+4. Include cost considerations if applicable

package/templates/marketplace/projects/.keep

@@ -0,0 +1,43 @@
+# Projects Directory
+
+This directory contains complete, reusable Ark projects that demonstrate comprehensive use cases and multi-component solutions.
+
+## Purpose
+
+- **Full Project Templates**: Complete Ark project structures with multiple agents, teams, models, and tools working together
+- **End-to-End Solutions**: Real-world scenarios that showcase complex workflows and integrations
+- **Reference Implementations**: Best practices for structuring large-scale Ark deployments
+
+## Structure Guidelines
+
+Each project should include:
+
+- **Complete project structure**: All necessary YAML configurations
+- **README.md**: Detailed setup instructions, use case description, and architecture overview
+- **Documentation**: Architecture diagrams, workflow explanations, and deployment guides
+- **Examples**: Sample queries and expected outputs
+- **Dependencies**: Clear list of required models, tools, and external services
+
+## Naming Convention
+
+Use descriptive names that indicate the use case:
+
+- `customer-support-workflow/` - Multi-agent customer service system
+- `research-assistant-pipeline/` - Academic research and analysis workflow
+- `content-generation-studio/` - Creative content production system
+
+## Project Requirements
+
+- Each project must be self-contained and deployable
+- Include comprehensive documentation
+- Provide clear setup and configuration instructions
+- Include sample data or test cases where applicable
+- Follow Ark best practices for resource organization
+
+## Examples
+
+- Multi-agent workflows with specialized roles
+- Integration with external APIs and services
+- Complex data processing pipelines
+- Cross-functional team collaboration scenarios
+- Industry-specific solution templates

package/templates/marketplace/queries/.keep

@@ -0,0 +1,25 @@
+# Queries Directory
+
+This directory contains reusable query templates for common use cases.
+
+## Structure
+Each query should be in its own file or subdirectory:
+- query-name.yaml (simple queries)
+- complex-query/ (for queries with multiple files)
+  - query.yaml
+  - README.md
+  - examples/
+
+## Naming Convention
+Use descriptive names that indicate the query's purpose:
+- code-analysis.yaml
+- data-transformation.yaml
+- security-audit.yaml
+- document-summarization.yaml
+
+## Contributing
+When contributing a query:
+1. Make it parameterizable where possible
+2. Include clear documentation of expected inputs
+3. Provide example outputs
+4. Specify compatible agents/teams

package/templates/marketplace/teams/.keep

@@ -0,0 +1,29 @@
+# Teams Directory
+
+This directory contains reusable team configurations for multi-agent workflows.
+
+## Structure
+
+Each team should be in its own file (simple) or subdirectory (complex) with:
+
+- team.yaml (the main team definition)
+- README.md (documentation describing the workflow)
+- examples/ (optional usage examples)
+
+## Naming Convention
+
+Use descriptive names that indicate the team's workflow:
+
+- code-review-team/
+- data-pipeline-team/
+- content-creation-team/
+- security-audit-team/
+
+## Contributing
+
+When contributing a team:
+
+1. Document the team's workflow and strategy
+2. Explain when to use this team configuration
+3. Include examples of typical inputs and outputs
+4. Test the team configuration thoroughly

package/templates/marketplace/tools/.keep

@@ -0,0 +1,32 @@
+# Tools Directory
+
+This directory contains reusable tool definitions for extending agent capabilities.
+
+## Structure
+
+Each tool should be in its own subdirectory with:
+
+- tool.yaml (the main tool definition)
+- src/ (source code if applicable)
+- Dockerfile (if containerized)
+- README.md (documentation)
+- examples/ (usage examples)
+
+## Naming Convention
+
+Use descriptive names that indicate the tool's function:
+
+- file-processor/
+- database-connector/
+- api-client/
+- data-validator/
+
+## Contributing
+
+When contributing a tool:
+
+1. Follow the Ark tool specification
+2. Include comprehensive documentation
+3. Provide usage examples
+4. Ensure proper error handling
+5. Include security considerations

package/templates/marketplace/tools/examples/.keep

@@ -0,0 +1,17 @@
+# Tool Examples Directory
+
+This directory contains example tool implementations that can serve as templates.
+
+Examples should demonstrate:
+
+- Best practices for tool development
+- Common patterns and use cases
+- Integration with different agent types
+- Error handling and logging
+
+Each example should include:
+
+- Complete source code
+- Documentation
+- Build instructions
+- Testing guidelines

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"