K8stools

🚀 Kubernetes Tools

本项目提供了一系列供智能体使用的 Kubernetes 功能函数。这些函数既可以直接作为工具传递给智能体，也可以部署在 MCP 服务器（已包含）之后使用。以下是一些应用场景：

• 通过 GitHub CoPilot 或 Cursor 与你的 Kubernetes 集群进行交互。
• 构建 智能体 来监控集群或进行根本原因分析。
• 开发自定义的聊天界面。
• 用于非智能体自动化场景。

🚀 快速开始

安装

可以通过以下两种方式安装 k8stools：

• 通过 pip 安装：

pip install k8stools

• 通过 uv 安装：

uv add k8stools

使用示例

直接在智能体中使用

核心工具位于 k8stools.k8s_tools 模块中。以下是在智能体中使用的示例：

from pydantic_ai.agent import Agent
from k8stools.k8s_tools import TOOLS

agent = Agent(
        model="openai:gpt-4.1",
        system_prompt=SYSTEM_PROMPT,
        tools=TOOLS
)

result = agent.run_sync("What is the status of the pods in my cluster?")
print(result.output)

通过 MCP 使用

k8s-mcp-server 脚本为这些工具提供了一个 MCP 服务器。以下是服务器的命令行参数：

usage: k8s-mcp-server [-h] [--transport {streamable-http,stdio}] [--host HOST] [--port PORT]
                      [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--debug]

Run the MCP server.

options:
  -h, --help            show this help message and exit
  --transport {streamable-http,stdio}
                        Transport to use for MCP server [default: stdio]
  --host HOST           Hostname for HTTP service [default: 127.0.0.1]
  --port PORT           Port for HTTP service [default: 8000]
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Log level [default: INFO]
  --debug               Enable debug mode [default: False]

使用 stdio 传输协议

stdio 传输协议最适合与本地编码智能体（如 GitHub CoPilot 或 Cursor）一起使用。它是默认的传输协议，因此可以直接运行 k8s-mcp-server 脚本而无需传递参数。以下是一个 mcp.json 配置示例：

{
   "servers": {
      "k8stools-stdio": {
         "command": "${workspaceFolder}/.venv/bin/k8s-mcp-server",
         "args": [
         ],
         "envFile": "${workspaceFolder}/.envrc"
      }
   }
}

此配置假设：

1. Python 虚拟环境位于 VSCode 工作区根目录下的 .venv 文件夹中。
2. 已将 k8stools 包安装到工作区中。
3. 环境文件 .envrc 包含所需的所有变量。特别是，可能需要设置 KUBECONFIG 指向你的 kubectl 配置文件。

使用可流式传输的 HTTP 传输协议

通过命令行选项 --transport=streamable-http 可以启用 streamable http 传输协议。它将启动一个 HTTP 服务器，监听指定的地址和端口（默认为 127.0.0.1 和 8000）。此传输协议最适合需要远程访问 MCP 服务器的场景。

以下是一个启动服务器并使用 curl 进行工具信息测试的简短示例：

# 启动服务器
 $ k8s-mcp-server --transport=streamable-http
[07/21/25 19:55:13] INFO     Starting with 6 tools on transport streamable-http           mcp_server.py:59
INFO:     Started server process [6649]
INFO:     Waiting for application startup.
INFO     StreamableHTTP session manager started         streamable_http_manager.py:111
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

# 打开另一个终端窗口进行测试
$ curl -v \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{
           "jsonrpc": "2.0",
           "id": 1,
           "method": "tools/list",
           "params": {}
         }' \
     http://127.0.0.1:8000/mcp
*   Trying 127.0.0.1:8000...
* Connected to 127.0.0.1 (127.0.0.1) port 8000
> POST /mcp HTTP/1.1
> Host: 127.0.0.1:8000
> User-Agent: curl/8.7.1
> Content-Type: application/json
> Accept: application/json, text/event-stream
> Content-Length: 120
>
* upload completely sent off: 120 bytes
< HTTP/1.1 200 OK
< date: Tue, 22 Jul 2025 02:56:25 GMT
< server: uvicorn
< cache-control: no-cache, no-transform
< connection: keep-alive
< content-type: text/event-stream
< x-accel-buffering: no
< Transfer-Encoding: chunked
<
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"tools":[.... long text elided ...]}}

✨ 主要特性

设计理念

我们的目标是注重质量而非数量，提供文档完善且类型严格的工具。我们认为这对于智能体有效使用工具至关重要，而不仅仅是简单的演示。

这些工具基于 Kubernetes Python API（https://github.com/kubernetes-client/python）构建，提供了三种类型的工具：

1. 模拟 kubectl 命令输出的工具：例如 get_pod_summaries，其功能等同于 kubectl get pods。这些工具的返回值使用了强类型的 Pydantic 模型。
2. 返回强类型 Pydantic 模型的工具：这些模型尝试与相关的 Kubernetes 客户端类型相匹配（请参阅 https://github.com/kubernetes-client/python/tree/master/kubernetes/docs）。这些模型可能会省略一些较少使用的字段。例如 get_pod_container_statuses。
3. 直接调用 API 返回类的 to_dict() 方法的工具：返回类型为 dict[str,Any]，但我们会在函数的文档字符串中记录字段信息。例如 get_pod_spec。

目前，我们的重点是不修改集群状态的函数，优先考虑监控和根本原因分析的应用场景。当我们添加用于其他场景的工具时，会将它们与只读工具分开，以便你仍然可以构建“安全”的智能体。

模拟工具

在构建智能体时，使用模拟版本的工具进行测试会很有帮助。这些模拟工具不会与真实的集群交互，而是返回静态（但逼真）的值。k8stools.mock_tools 模块就提供了这样的功能。这些数据值是在运行真实的 Minikube 实例并部署 Open Telemetry Demo 应用程序时捕获的。在运行 MCP 服务器时，可以通过 --mock 命令行选项启用模拟工具。

指令文件

GitHub CoPilot 支持 指令 文件，这些文件可以为 CoPilot 编码智能体提供额外的上下文信息。它甚至可以分析你的项目并自动生成一个指令文件。默认情况下，该文件会保存为 .github/copilot-instructions.md。你可以手动添加指令，以自定义智能体对 MCP 工具的使用。以下是本仓库 copilot-instructions.md 中包含的额外内容示例：

MCP 集成

启动服务器：k8s-mcp-server [--transport stdio|streamable-http] 工具通过 mcp_server.py 中的 Tool.from_function() 自动注册。

在回答关于用户 Kubernetes 集群的问题时，请使用此服务器提供的工具，该服务器在 mcp.json 中配置为 k8stools-stdio。在回答这些问题时，还需要考虑以下几点：

• 如果答案包含多个相似的条目，尽可能以表格形式呈现。
• 在提供 Pod 状态时，务必包含 Pod 的状态信息。
• 在提供状态时，使用图标快速显示状态的好坏。
• 如果被问及当前状态，且你在超过一分钟内未运行过请求，请务必再次运行工具以获取最新状态。

📦 安装指南

通过 pip 安装

pip install k8stools

通过 uv 安装

uv add k8stools

📚 详细文档

当前工具

以下是我们定义的工具：

• get_namespaces - 获取命名空间列表，类似于 kubectl get namespace。
• get_node_summaries - 获取节点列表，类似于 kubectl get nodes -o wide。
• get_pod_summaries - 获取 Pod 列表，类似于 kubectl get pods -o wide。
• get_pod_container_statuses - 返回 Pod 中每个容器的状态。
• get_pod_events - 返回 Pod 的事件信息。
• get_pod_spec - 获取指定 Pod 的配置信息。
• get_logs_for_pod_and_container - 获取 Pod 和容器的日志。
• get_deployment_summaries - 获取部署列表，类似于 kubectl get deployments。
• get_service_summaries - 获取服务列表，类似于 kubectl get services。

我们还定义了一组相关的 “print_” 函数，这些函数在调试时很有用：

• print_namespaces
• print_node_summaries
• print_pod_summaries
• print_pod_container_statuses
• print_pod_events
• print_pod_spec
• print_deployment_summaries
• print_service_summaries