使用说明

• 项目简介

  • 该仓库实现了一个 MCP（Model Context Protocol）后端服务器，专注于将 Kubernetes 的 Cluster API（CAPI）资源通过 MCP 键值对形式暴露给对话型 AI 客户端。核心能力包括资源访问、工具调用和提示模板的渲染，支持多传输协议，具备会话管理与能力声明等特性。

• 主要功能点

  • MCP 服务器实现与对接：基于 mcp-go 提供的 MCP 服务器框架，注册并暴露一组工具（Tools）、资源（Resources）和 Prompts，供 LLM 客户端调用。
  • 数据与操作能力：通过 pkg/capi 提供的 CAPI 客户端，访问和操作集群、机器、MachineDeployment、MachineSet、节点等资源，以及与多云提供商的整合能力（AWS、Azure、GCP、vSphere 等）的占位实现。
  • 多传输协议支持：标准输入输出（stdio）、服务器端事件（SSE）和流式 HTTP（streamable-http）传输，适配不同部署场景。
  • 自更新能力：内置自更新命令实现（self-update），通过 GitHub Release 检查并替换自身二进制文件。
  • 服务端工具注册：BuildAllTools 构建并注册多种工具（包括集群、机器、节点及各云提供商的工具）以及测试工具，支持按需扩展。
  • 安全性与可扩展性设计：会话上下文、能力声明、日志与优雅关机等机制的实现，便于在生产环境中扩展和集成。

• 安装步骤

  • 克隆代码并进入仓库目录：
    • git clone https://github.com/giantswarm/mcp-capi.git
    • cd mcp-capi
  • 构建服务端：
    • make build
  • 运行服务端（以 SSE 为例）：
    • mcp-capi serve --transport sse --http-addr :8080
  • 自更新（若需要）：
    • mcp-capi self-update

• 服务器配置（MCP 客户端配置需求）

  • MCP 客户端需要知道要连接的 MCP 服务器的启动命令和参数，以及服务器的名称。以下提供准确的配置字段信息，注释说明仅供参考，实际客户端无需包含代码。
  • server_name: mcp-capi
  • command: /path/to/mcp-capi
  • args: [ "serve", "--transport", "sse", "--http-addr", ":8080", "--sse-endpoint", "/events", "--message-endpoint", "/messages" ]
  • 说明：以上命令和参数基于仓库默认实现，默认传输为 stdio，示例中给出 SSE 传输的常用组合。实际部署中请按环境替换为可执行文件路径与端口等参数。

• 基本使用方法

  • 使用命令行启动服务器：
    • mcp-capi serve
    • 或者 mcp-capi serve --transport stdio
  • 常用传输模式：
    • stdio：直接在本地 CLI 与 MCP 客户端交互，便于开发与调试
    • sse：http 端点暴露 SSE 事件流，客户端通过 /events 端点接收
    • streamable-http：http 端点暴露 REST 风格的可流式交互
  • 集成流程概要：
    • 部署前准备：确保本地或目标集群能访问到 Kubernetes API（KUBECONFIG 配置正确），CRD 与 CAPI 相关资源可用
    • 启动服务器：选择合适传输模式启动服务
    • MCP 客户端接入：使用服务器名称、命令和参数配置客户端，建立 JSON-RPC 风格的通信
  • 注意事项：
    • 服务器版本在构建时由构建系统注入，默认是 dev，生产环境请使用自上游 Release 验证的版本
    • CRD 下载、提供商实现等模块为占位示例，实际生产环境需对接真实 Provider CRD 与集群

• 运行与扩展

  • 服务器启动后会注册一组工具（Tools）和资源（Resources），可通过 MCP 客户端查询、调用工具、读取资源、获取 Prompts 等
  • 代码结构提供丰富的扩展点，如新增 Provider、扩展工具和资源实现、增强提示模板等