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