---

KAgent Tools - Go Implementation

This directory contains the Go implementation of all KAgent tools, migrated from the original Python implementation. The tools are designed to work with the Model Context Protocol (MCP) server and provide comprehensive Kubernetes, cloud-native, and observability functionality.

Installation

• Bash:

curl -sL https://raw.githubusercontent.com/kagent-dev/tools/refs/heads/main/scripts/install.sh | bash

• Docker:

docker run -it --rm -p 8084:8084 ghcr.io/kagent-dev/kagent/tools:0.0.12

• Kubernetes

helm upgrade -i -n kagent --create-namespace kagent-tools oci://ghcr.io/kagent-dev/tools/helm/kagent-tools --version 0.0.12
helm ls -A

Quickstart Guide

For a quickstart guide on how to run KAgent tools using AgentGateway, please refer to the Quickstart Guide.

Architecture

The Go tools are implemented as a single MCP server that exposes all available tools through the Model Context Protocol (MCP). Built using the official github.com/modelcontextprotocol/go-sdk, the server provides comprehensive Kubernetes, cloud-native, and observability functionality through a unified interface.

MCP SDK Integration

KAgent Tools leverages the official Model Context Protocol SDK:

• Official SDK: Uses github.com/modelcontextprotocol/go-sdk for MCP compliance
• Type Safety: Strongly-typed parameter validation and parsing
• JSON Schema: Automatic schema generation for tool parameters
• Multiple Transports: Support for stdio, HTTP, and SSE transports
• Error Handling: Standardized error responses following MCP specification
• Tool Discovery: Automatic tool registration and capability advertisement

Package Structure

Each tool category is implemented in its own Go package under pkg/ for better organization and maintainability:

pkg/
├── k8s/        # Kubernetes operations
├── helm/       # Helm package management
├── istio/      # Istio service mesh
├── argo/       # Argo Rollouts and ArgoCD
├── cilium/     # Cilium CNI
├── prometheus/ # Prometheus monitoring
└── utils/      # Common utilities

Tool Categories

1. Kubernetes Tools (k8s.go)

Provides comprehensive Kubernetes cluster management functionality:

• kubectl_get: Get Kubernetes resources
• kubectl_describe: Describe Kubernetes resources in detail
• kubectl_logs: Get logs from pods
• kubectl_scale: Scale deployments and replica sets
• kubectl_patch: Patch Kubernetes resources
• kubectl_label: Add/remove labels from resources
• kubectl_annotate: Add/remove annotations from resources
• kubectl_delete: Delete Kubernetes resources
• kubectl_apply: Apply configurations from files or stdin
• kubectl_create: Create resources from files or stdin
• check_service_connectivity: Test service connectivity
• get_events: Get cluster events
• get_api_resources: List available API resources
• get_cluster_configuration: Get cluster configuration
• exec_command: Execute commands in pods
• rollout: Manage deployment rollouts

2. Helm Tools (helm.go)

Provides Helm package manager functionality:

• helm_list: List Helm releases
• helm_get: Get information about Helm releases
• helm_upgrade: Upgrade Helm releases
• helm_uninstall: Uninstall Helm releases
• helm_install: Install Helm charts
• helm_repo_add: Add Helm repositories
• helm_repo_update: Update Helm repositories

3. Istio Tools (istio.go)

Provides Istio service mesh management:

• istio_proxy_status: Get proxy status
• istio_proxy_config: Get proxy configuration
• istio_install: Install Istio
• istio_generate_manifest: Generate Istio manifests
• istio_analyze: Analyze Istio configuration
• istio_version: Get Istio version information
• istio_remote_clusters: Manage remote clusters
• istio_waypoint_list: List waypoint proxies
• istio_waypoint_generate: Generate waypoint proxy configuration
• istio_waypoint_apply: Apply waypoint proxy configuration
• istio_waypoint_delete: Delete waypoint proxies
• istio_waypoint_status: Get waypoint proxy status
• istio_ztunnel_config: Get ztunnel configuration

4. Argo Tools (argo.go)

Provides Argo Rollouts progressive delivery and ArgoCD GitOps functionality:

Argo Rollouts Tools:

• argo_verify_argo_rollouts_controller_install: Verify controller installation
• argo_verify_kubectl_plugin_install: Verify kubectl plugin installation
• argo_rollouts_list: List rollouts or experiments
• argo_promote_rollout: Promote a paused rollout
• argo_pause_rollout: Pause a rollout
• argo_set_rollout_image: Set rollout container image
• argo_verify_gateway_plugin: Verify Gateway API plugin installation
• argo_check_plugin_logs: Check plugin logs

ArgoCD Tools (GitOps):

• argocd_list_applications: List ArgoCD applications with search, limit, and offset
• argocd_get_application: Get ArgoCD application details
• argocd_get_application_resource_tree: Get resource tree for an application
• argocd_get_application_managed_resources: Get managed resources with filtering
• argocd_get_application_workload_logs: Get logs for application workloads
• argocd_get_application_events: Get events for an application
• argocd_get_resource_events: Get events for a specific resource
• argocd_get_resources: Get resource manifests
• argocd_get_resource_actions: Get available actions for a resource
• argocd_create_application: Create a new ArgoCD application (write mode)
• argocd_update_application: Update an ArgoCD application (write mode)
• argocd_delete_application: Delete an ArgoCD application (write mode)
• argocd_sync_application: Sync an ArgoCD application (write mode)
• argocd_run_resource_action: Run an action on a resource (write mode)

Configuration:

• Set ARGOCD_BASE_URL environment variable to ArgoCD server URL (e.g., https://argocd.example.com)
• Set ARGOCD_API_TOKEN environment variable to ArgoCD API token
• Set MCP_READ_ONLY=true to disable write operations (create, update, delete, sync, run_resource_action)

5. Cilium Tools (cilium.go)

Provides Cilium CNI and networking functionality:

• cilium_status_and_version: Get Cilium status and version
• upgrade_cilium: Upgrade Cilium installation
• install_cilium: Install Cilium
• uninstall_cilium: Uninstall Cilium
• connect_to_remote_cluster: Connect to remote clusters
• disconnect_remote_cluster: Disconnect from remote clusters
• list_bgp_peers: List BGP peers
• list_bgp_routes: List BGP routes
• show_cluster_mesh_status: Show cluster mesh status
• show_features_status: Show Cilium features status
• toggle_hubble: Enable/disable Hubble
• toggle_cluster_mesh: Enable/disable cluster mesh

6. Prometheus Tools (prometheus.go)

Provides Prometheus monitoring and alerting functionality:

• prometheus_query: Execute PromQL queries
• prometheus_range_query: Execute PromQL range queries
• prometheus_labels: Get available labels
• prometheus_targets: Get scraping targets and their status

7. Grafana Tools (grafana.go)

Provides Grafana dashboard and alerting management:

• grafana_org_management: Manage Grafana organizations
• grafana_dashboard_management: Manage dashboards
• grafana_alert_management: Manage alerts and alert rules
• grafana_datasource_management: Manage data sources

8. DateTime Tools (datetime.go)

Provides time and date utilities:

• current_date_time: Get current date and time in ISO 8601 format
• format_time: Format timestamps with optional timezone
• parse_time: Parse time strings into RFC3339 format

9. Documentation Tools (docs.go)

Provides documentation query functionality:

• query_documentation: Query documentation for supported products (simplified implementation)
• list_supported_products: List supported products for documentation queries

10. Common Tools (common.go)

Provides general utility functions:

• shell: Execute shell commands

Building and Running

Prerequisites

• Go 1.21 or later
• Access to Kubernetes cluster (for K8s tools)
• Required CLI tools installed:
  • kubectl (for Kubernetes tools)
  • helm (for Helm tools)
  • istioctl (for Istio tools)
  • cilium (for Cilium tools)

Building

go build -o kagent-tools .

Running

# Run with stdio transport (default)
./kagent-tools --stdio

# Run with HTTP transport
./kagent-tools --http --port 8084

# Run with custom kubeconfig
./kagent-tools --stdio --kubeconfig ~/.kube/config

The server supports multiple MCP transports:

• Stdio: For direct integration with MCP clients
• HTTP: For web-based integrations and debugging
• SSE: Server-Sent Events for real-time communication

Testing

go test -v

Tool Implementation Details

Error Handling

All tools implement comprehensive error handling and return appropriate error messages through the MCP protocol. When CLI tools are not available or commands fail, the tools return descriptive error messages.

Authentication and Configuration

Tools respect existing authentication and configuration:

• Kubernetes tools use the default kubeconfig or KUBECONFIG environment variable
• Helm tools use Helm's default configuration
• Prometheus tools accept custom Prometheus server URLs
• Grafana tools support API key and basic authentication

Command Execution

The tools use a common runCommand function that:

• Executes commands with proper error handling
• Captures both stdout and stderr
• Returns formatted output or error messages
• Handles timeouts and cancellation

MCP Integration

All tools are properly integrated with the official MCP SDK:

• Built using github.com/modelcontextprotocol/go-sdk
• Use type-safe parameter parsing with request.RequireString(), request.RequireBool(), etc.
• Return results using mcp.NewToolResultText() or mcp.NewToolResultError()
• Include comprehensive tool descriptions and JSON schema parameter validation
• Support required and optional parameters with proper validation
• Follow MCP specification for error handling and result formatting

Migration from Python

This Go implementation provides feature parity with the original Python tools while offering:

1. Better Performance: Native Go execution without Python interpreter overhead
2. Smaller Binary: Single compiled binary with all tools included
3. Better Resource Usage: Lower memory footprint and faster startup
4. Enhanced Error Handling: More robust error handling and reporting
5. Simplified Deployment: No Python dependencies or virtual environments required

Key Differences from Python Implementation

• Uses native Go clients instead of Python requests/httpx
• Implements simplified documentation query (full vector search would require additional Go libraries)
• Uses Go's native JSON handling instead of Python's json module
• Command execution uses Go's os/exec package instead of Python's subprocess

Configuration

Tools can be configured through environment variables:

• KUBECONFIG: Kubernetes configuration file path
• PROMETHEUS_URL: Default Prometheus server URL (default: http://localhost:9090)
• GRAFANA_URL: Default Grafana server URL
• GRAFANA_API_KEY: Default Grafana API key
• ARGOCD_BASE_URL: ArgoCD server base URL (required for ArgoCD tools)
• ARGOCD_API_TOKEN: ArgoCD API authentication token (required for ArgoCD tools)
• MCP_READ_ONLY: Set to true to disable write operations for ArgoCD tools (default: false)
• LOG_LEVEL: Logging level (debug, info, warn, error)

Example Usage

With MCP Clients

Once connected to an MCP client, you can use natural language to interact with the tools:

"List all pods in the default namespace"
→ Uses kubectl_get tool with resource_type="pods", namespace="default"

"Scale the nginx deployment to 3 replicas"
→ Uses kubectl_scale tool with resource_type="deployment", resource_name="nginx", replicas=3

"Show me the Prometheus query for CPU usage"
→ Uses prometheus_query tool with appropriate PromQL query

"Install the nginx helm chart"
→ Uses helm_install tool with chart="nginx"

Direct HTTP API

When running with HTTP transport, you can also interact directly:

# Check server health
curl http://localhost:8084/health

# Get server metrics
curl http://localhost:8084/metrics

# List available tools
curl -X POST http://localhost:8084/mcp/tools/list \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# Execute a tool
curl -X POST http://localhost:8084/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "datetime_get_current_time",
      "arguments": {}
    },
    "id": 1
  }'

All tool providers (k8s, helm, istio, argo, cilium, prometheus, utils) are fully supported via HTTP transport endpoints /mcp/tools/list and /mcp/tools/call.

Error Handling and Debugging

The tools provide detailed error messages and support verbose output. When debugging issues:

1. Check that required CLI tools are installed and in PATH
2. Verify authentication and configuration (kubeconfig, API keys, etc.)
3. Check network connectivity to target services
4. Review error messages for specific failure details

Future Enhancements

Potential areas for future improvement:

1. Native Client Libraries: Replace CLI calls with native Go client libraries where possible
2. Advanced Documentation Search: Implement full vector search for documentation queries
3. Caching: Add caching for frequently accessed data
4. Metrics and Observability: Add metrics and tracing for tool usage
5. Configuration Management: Enhanced configuration management and validation
6. Parallel Execution: Support for parallel execution of related operations

Contributing

When adding new tools or modifying existing ones:

1. Follow the existing code structure and naming conventions
2. Write tests for all new tools
3. Implement type-safe input validation for all parameters
4. Add comprehensive error handling with structured logging
5. Use the official MCP SDK for all tool registrations
6. Maintain modular package design (tools in pkg/ subdirectories)
7. Update this README with new tool documentation
8. Ensure minimum 80% test coverage
9. Ensure backward compatibility with existing tools

For detailed development guidelines, see:

• DEVELOPMENT.md - Development environment and workflow
• CONTRIBUTION.md - Contribution process and standards