使用说明（Markdown）

• 项目简介

  • K8s Doctor MCP 服务器是一套基于 MCP 的后端服务，能向 MCP 客户端提供 Kubernetes 集群诊断、日志分析、资源检测等能力。通过注册多个 MCP 工具（如 diagnose-pod、analyze-logs、full-diagnosis 等），实现对资源、工具和提示模板的标准化管理与执行。

• 主要功能点

  • 资源及数据访问：通过 Kubernetes API 获取命名空间、Pod、事件、节点等信息。
  • 工具注册与执行：提供诊断 Pod、CrashLoopBackoff 分析、日志分析、资源检查、集群健康等多种工具，并输出易于阅读的文本化结果。
  • Prompt/模板渲染：将诊断结果整理为结构化的文本报告，支持后续的 LLM 交互使用。
  • 会话与缓存：内置简单缓存以提升查询效率，支持多种传输方式（如 Stdio、WebSocket、SSE 等，实际运行时依赖 MCP SDK 的传输实现）。
  • 安全与只读操作：通过 Kubernetes API 的只读调用实现诊断，不修改集群状态。

• 安装步骤

  1. 安装 Node.js 18 及以上环境。
  2. 将代码克隆到本地并进入项目目录。
  3. 安装依赖并构建：执行 npm install；执行 npm run build。
  4. 启动 MCP 服务器：在支持 MCP 客户端发现和连接的环境中运行 dist/index.js（通过：node dist/index.js，或在打包后通过 npx/可执行方式启动）。运行后服务器会对外提供 MCP 接入点，用于 MCP 客户端连接并发起请求。

• 服务器配置（MCP 客户端需要的启动信息，JSON 格式，包含 serverName、command、args 等）

  • 说明：以下字段用于 MCP 客户端在本地或远程启动并连接到 MCP 服务器。serverName 必须与服务器注册时的名称一致；command 与 args 指定启动 MCP 服务器的执行命令及参数（客户端不需要该配置文本本身，但用于正确启动服务器环境）。
  • 示例配置（注释性说明在括号中，不作为代码块呈现）： { "serverName": "k8s-doctor", "command": "node", "args": ["/path/to/your/project/dist/index.js"], "version": "1.0.0", "description": "K8s Doctor MCP 服务器，用于向 MCP 客户端提供 Kubernetes 集群诊断、资源与工具执行能力" }
  • 注解
    • serverName：服务器在 MCP 客户端中的标识，需与代码中创建时的名称一致（本仓库中为 k8s-doctor）。
    • command：启动命令，常见为 node。
    • args：启动命令的参数，指向构建产物的入口文件（dist/index.js）。
    • version/description：可选字段，用于描述服务器版本与用途，便于管理与运维。
  • MCP 客户端不需要对服务器配置进行修改，只需正确配置上述启动信息以建立连接。

• 基本使用方法

  • 启动后，MCP 客户端通过 MCP 协议向服务器发起请求，调用如 diagnose-pod、analyze-logs、full-diagnosis 等工具。
  • MCP 客户端可以将问题以自然语言形式传入，服务器将返回带结构的文本报告，便于嵌入到对话或进一步的 LLM 处理。
  • 常见交互场景包括：诊断指定 Pod、分析日志、获取集群健康概览、列出命名空间/ Pod 等辅助信息。