ghcr.io/kagent-dev/kagent/tools:0.0.15

KAgent 工具 - Go 实现

本目录包含所有 KAgent 工具的 Go 实现，从原始 Python 实现迁移而来。这些工具旨在与模型上下文协议（Model Context Protocol, MCP）服务器配合使用，提供全面的 Kubernetes、云原生和可观测性功能。

安装

• 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.13

• Kubernetes

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

快速入门指南

有关如何使用 AgentGateway 运行 KAgent 工具的快速入门指南，请参阅 快速入门指南。

架构

Go 工具实现为单个 MCP 服务器，通过 MCP 协议公开所有可用工具。每个工具类别在独立的 Go 文件中实现，以提高组织性和可维护性。

工具类别

1. Kubernetes 工具（k8s.go）

提供全面的 Kubernetes 集群管理功能：

• kubectl_get：获取 Kubernetes 资源
• kubectl_describe：详细描述 Kubernetes 资源
• kubectl_logs：获取 Pod 日志
• kubectl_scale：扩缩容 Deployment 和 ReplicaSet
• kubectl_patch：补丁更新 Kubernetes 资源
• kubectl_label：为资源添加/移除标签
• kubectl_annotate：为资源添加/移除注解
• kubectl_delete：删除 Kubernetes 资源
• kubectl_apply：从文件或标准输入应用配置
• kubectl_create：从文件或标准输入创建资源
• check_service_connectivity：测试服务连通性
• get_events：获取集群事件
• get_api_resources：列出可用的 API 资源
• get_cluster_configuration：获取集群配置
• exec_command：在 Pod 中执行命令
• rollout：管理 Deployment 滚动更新

2. Helm 工具（helm.go）

提供 Helm 包管理器功能：

• helm_list：列出 Helm 发布版本
• helm_get：获取 Helm 发布版本信息
• helm_upgrade：升级 Helm 发布版本
• helm_uninstall：卸载 Helm 发布版本
• helm_install：安装 Helm 图表
• helm_repo_add：添加 Helm 仓库
• helm_repo_update：更新 Helm 仓库

3. Istio 工具（istio.go）

提供 Istio 服务网格管理功能：

• istio_proxy_status：获取代理状态
• istio_proxy_config：获取代理配置
• istio_install：安装 Istio
• istio_generate_manifest：生成 Istio 清单
• istio_analyze：分析 Istio 配置
• istio_version：获取 Istio 版本信息
• istio_remote_clusters：管理远程集群
• istio_waypoint_list：列出 Waypoint 代理
• istio_waypoint_generate：生成 Waypoint 代理配置
• istio_waypoint_apply：应用 Waypoint 代理配置
• istio_waypoint_delete：删除 Waypoint 代理
• istio_waypoint_status：获取 Waypoint 代理状态
• istio_ztunnel_config：获取 ztunnel 配置

4. Argo Rollouts 工具（argo.go）

提供 Argo Rollouts 渐进式交付功能：

• verify_argo_rollouts_controller_install：验证控制器安装
• verify_kubectl_plugin_install：验证 kubectl 插件安装
• promote_rollout：推进滚动更新
• pause_rollout：暂停滚动更新
• set_rollout_image：设置滚动更新镜像
• verify_gateway_plugin：验证 Gateway API 插件
• check_plugin_logs：检查插件安装日志

5. Cilium 工具（cilium.go）

提供 Cilium CNI 和网络功能：

• cilium_status_and_version：获取 Cilium 状态和版本
• upgrade_cilium：升级 Cilium 安装
• install_cilium：安装 Cilium
• uninstall_cilium：卸载 Cilium
• connect_to_remote_cluster：连接到远程集群
• disconnect_remote_cluster：断开与远程集群的连接
• list_bgp_peers：列出 BGP 对等体
• list_bgp_routes：列出 BGP 路由
• show_cluster_mesh_status：显示集群网格状态
• show_features_status：显示 Cilium 功能状态
• toggle_hubble：启用/禁用 Hubble
• toggle_cluster_mesh：启用/禁用集群网格

6. Prometheus 工具（prometheus.go）

提供 Prometheus 监控和告警功能：

• prometheus_query：执行 PromQL 查询
• prometheus_range_query：执行 PromQL 范围查询
• prometheus_labels：获取可用标签
• prometheus_targets：获取抓取目标及其状态

7. Grafana 工具（grafana.go）

提供 Grafana 仪表板和告警管理功能：

• grafana_org_management：管理 Grafana 组织
• grafana_dashboard_management：管理仪表板
• grafana_alert_management：管理告警和告警规则
• grafana_datasource_management：管理数据源

8. 日期时间工具（datetime.go）

提供时间和日期实用工具：

• current_date_time：获取 ISO 8601 格式的当前日期和时间
• format_time：使用可选时区格式化时间戳
• parse_time：将时间字符串解析为 RFC3339 格式

9. 文档工具（docs.go）

提供文档查询功能：

• query_documentation：查询支持产品的文档（简化实现）
• list_supported_products：列出支持文档查询的产品

10. 通用工具（common.go）

提供通用实用函数：

• shell：执行 shell 命令

构建与运行

前提条件

• Go 1.21 或更高版本
• 可访问 Kubernetes 集群（用于 K8s 工具）
• 已安装所需 CLI 工具：
  • kubectl（用于 Kubernetes 工具）
  • helm（用于 Helm 工具）
  • istioctl（用于 Istio 工具）
  • cilium（用于 Cilium 工具）

构建

go build -o kagent-tools .

运行

./kagent-tools

服务器使用 SSE 传输进行 MCP 通信。

CLI 标志

测试

go test -v ./...

工具实现细节

错误处理

所有工具均实现全面的错误处理，并通过 MCP 协议返回适当的错误消息。当 CLI 工具不可用或命令失败时，工具会返回描述性错误消息。

认证与配置

工具遵循现有认证和配置：

• Kubernetes 工具使用默认 kubeconfig 或 KUBECONFIG 环境变量
• Helm 工具使用 Helm 的默认配置
• Prometheus 工具接受自定义 Prometheus 服务器 URL
• Grafana 工具支持 API 密钥和基本认证

命令执行

工具使用通用的 runCommand 函数，该函数：

• 执行命令并进行适当的错误处理
• 捕获标准输出和标准错误
• 返回格式化输出或错误消息
• 处理超时和取消操作

MCP 集成

所有工具均与 MCP 协议正确集成：

• 使用 mcp.ParseString、mcp.ParseBool 等进行正确的参数解析
• 使用 mcp.NewToolResultText 或 mcp.NewToolResultError 返回结果
• 包含全面的工具描述和参数文档
• 支持必填和可选参数

从 Python 迁移

此 Go 实现提供与原始 Python 工具相同的功能，同时具有以下优势：

1. 更好的性能：原生 Go 执行，无 Python 解释器开销
2. 更小的二进制文件：单个编译二进制文件包含所有工具
3. 更优的资源使用：更低的内存占用和更快的启动速度
4. 增强的错误处理：更健壮的错误处理和报告
5. 简化的部署：无需 Python 依赖或虚拟环境

与 Python 实现的主要区别

• 使用原生 Go 客户端而非 Python requests/httpx
• 实现简化的文档查询（完整向量搜索需要额外的 Go 库）
• 使用 Go 原生 JSON 处理而非 Python 的 json 模块
• 命令执行使用 Go 的 os/exec 包而非 Python 的 subprocess

配置

工具可通过环境变量进行配置：

• KUBECONFIG：Kubernetes 配置文件路径
• PROMETHEUS_URL：默认 Prometheus 服务器 URL
• GRAFANA_URL：默认 Grafana 服务器 URL
• GRAFANA_API_KEY：默认 Grafana API 密钥

可观测性

MCP 服务器在可配置的 HTTP 端点（/metrics）上公开 Prometheus 指标。默认情况下，指标端点与 MCP 服务器使用相同的端口。要在单独的端口上运行：

./kagent-tools --port 8084 --metrics-port 9090

公开的指标

还包括标准的 Go 运行时和进程指标（goroutine、内存、CPU、文件描述符等）。

错误处理与调试

工具提供详细的错误消息并支持详细输出。调试问题时：

1. 检查是否安装了所需的 CLI 工具并在 PATH 中
2. 验证认证和配置（kubeconfig、API 密钥等）
3. 检查与目标服务的网络连通性
4. 查看错误消息以获取具体失败详情

未来增强

潜在的未来改进方向：

1. 原生客户端库：在可能的情况下，用原生 Go 客户端库替换 CLI 调用
2. 高级文档搜索：为文档查询实现完整的向量搜索
3. 缓存：为频繁访问的数据添加缓存
4. 配置管理：增强配置管理和验证
5. 并行执行：支持相关操作的并行执行

贡献

添加新工具或修改现有工具时：

1. 遵循现有的代码结构和命名约定
2. 添加全面的错误处理
3. 包含正确的 MCP 工具注册
4. 使用新工具文档更新此 README
5. 添加适当的测试
6. 确保与现有工具的向后兼容性