flowchart TB
    subgraph LB["LangChain_bot（自研 Agent）"]
        CLI["CLI 终端"] --> LG["LangGraph Agent"]
        Lark["飞书机器人"] --> LG
        LG --> LLM["LLM（OpenAI 兼容）"]
        LG --> Mem["多轮记忆 MemorySaver"]
        LG --> Builtin["内置工具（自动发现）"]
    end

    subgraph IDE["第三方 AI IDE"]
        Trae["Trae / Cursor / Claude Code"]
    end

    subgraph Server["k8s-mcp-server（本仓库 · FastMCP）"]
        Entry["k8s_server.py<br/>入口：导入即注册"]
        App["app.py<br/>FastMCP 实例（叶子模块）"]
        Tools["Tools/ · 11 个只读工具"]
        Prompts["prompts.py · 排查引导"]
        Resources["resources.py · 集群摘要"]
        Utils["utils/ · 解析 + watch 循环"]
        KC["k8s_client.py<br/>懒加载客户端（单一配置来源）"]
    end

    subgraph Cluster["Kubernetes 集群"]
        API["API Server"]
        Obj["Node / Pod / Event"]
    end

    LG ==>|"MCP 协议<br/>stdio / http"| Entry
    Trae ==>|"MCP 协议<br/>stdio / http"| Entry
    Entry --> App
    App --> Tools
    App --> Prompts
    App --> Resources
    Tools --> Utils
    Tools --> KC
    KC ==>|"kubernetes SDK<br/>（只读查询）"| API
    API --> Obj

├── app.py              # FastMCP 实例（叶子模块，破循环导入）
├── k8s_server.py       # 入口：导入 Tools 即自动注册全部工具
├── k8s_client.py       # K8s 客户端懒加载 + 单一配置来源
├── config.py           # 12-Factor 环境变量配置
├── prompts.py          # @mcp.prompt 引导
├── resources.py        # @mcp.resource 资源
├── Tools/              # 每个工具一个文件，导入即注册
├── utils/              # 纯解析/辅助模块（无 K8s/MCP 依赖）
└── tests/              # 单元测试

# 1. 创建虚拟环境并安装依赖
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

pip install -r requirements.txt

# 2. 运行（HTTP transport，默认 127.0.0.1:8081）
python k8s_server.py

pip install -r requirements-dev.txt
python -m pytest -q

{
  "mcpServers": {
    "k8s-node-server": {
      "url": "http://127.0.0.1:8081/mcp"
    }
  }
}