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

KAgent Tools - Go 实现版本

本目录包含 KAgent 所有工具的 Go 实现，从原 Python 实现迁移而来。这些工具设计为与模型上下文协议（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 Release
• helm_get: 获取 Helm Release 的相关信息
• helm_upgrade: 升级 Helm Release
• helm_uninstall: 卸载 Helm Release
• helm_install: 安装 Helm Chart
• 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: 推进 Rollout 阶段
• pause_rollout: 暂停 Rollout
• set_rollout_image: 设置 Rollout 使用的镜像
• 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 命令
• mcp_inspect: 回显输入内容并返回请求头，用于 MCP 客户端调试

构建与运行

前置条件

• 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 服务端地址
• 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 服务端地址
• GRAFANA_URL：默认 Grafana 服务端地址
• GRAFANA_API_KEY：默认 Grafana API 密钥

可观测性

MCP 服务端会在可配置的 HTTP 端点（/metrics）暴露 Prometheus 指标。默认情况下，指标端点与 MCP 服务端共用同一端口。如需将指标运行在独立端口，可执行以下命令：

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

暴露的指标列表

服务端同时会暴露标准 Go 运行时与进程指标，包括 goroutine 数量、内存占用、CPU 使用量、文件描述符统计等。

错误处理与调试

工具会返回详细的错误信息，支持 verbose 输出。调试问题时请按以下步骤排查：

1. 确认所需 CLI 工具已安装并已加入系统 PATH 环境变量
2. 校验认证与配置内容（kubeconfig、API 密钥等）
3. 检查到目标服务的网络连通性
4. 查看错误消息以定位具体失败原因

后续增强方向

后续可能的功能优化点：

1. 原生客户端库替换：尽可能使用原生 Go 客户端库替代 CLI 调用
2. 高级文档搜索：为文档查询功能实现完整的向量搜索能力
3. 缓存机制：为高频访问数据添加缓存能力
4. 配置管理增强：优化配置管理与校验能力
5. 并行执行支持：支持关联操作的并行执行

贡献指南

新增工具或修改现有工具时请遵守以下规范：

1. 遵循现有代码结构与命名约定
2. 添加完善的错误处理逻辑
3. 完成符合 MCP 规范的工具注册流程
4. 更新本文档以同步新增工具说明
5. 补充对应的测试用例
6. 确保与现有工具保持向后兼容