Cluster Whisperer MCP 服务器

关键词

Model Context ProtocolJSON-RPCLangGraphKubernetesOpenTelemetry

使用说明（简要指南）

  • 项目简介

    • 集成了 MCP 服务器端实现，核心在于为 LLM 客户端（如 Claude Code、Cursor 等 MCP 客户端）提供统一的上下文服务：资源管理、工具注册/执行、以及提示模板的定义与渲染。通过 JSON-RPC 通信，支持多种传输方式（如 STDIO、SSE、WebSocket 等），并具备会话管理与能力声明能力。
    • 提供一个单一的 investigate 工具，包装了用于查询集群信息的 ReAct 风格 Agent；同时通过 REST API 提供实例同步能力的向量数据库同步能力（作为可选补充，供 MCP 客户端使用的场景）。
    • 全链路观测通过 OpenTelemetry 完整追踪，便于在 Datadog/Jaeger 等后端进行追踪、溯源与性能分析。

  • 主要功能点

    • MCP 服务器实现：通过标准化的 JSON-RPC 接口与 MCP 客户端通信，暴露 Investigate 工具来完成对集群的推理与执行。
    • 工具与代理封装：将 LangGraph/LangChain 等代理能力整合为 MCP 工具，并提供追踪上下文、工具执行输入输出的观测信息。
    • 资源/工具/提示模板管理：作为后端服务，托管资源描述、可用工具以及提示模板，支持向 LLM 客户端提供可扩展的上下文服务。
    • 传输协议与拓展性：设计上支持多种传输协议（如 STDIO、SSE、WebSocket 等）以便嵌入到不同框架和运行环境中。
    • 会话与能力声明：具备会话管理、能力声明，以及对外暴露的能力集合，便于 MCP 客户端按需获取信息。
    • 可观测性与追踪：内置 OpenTelemetry 追踪、链路上下文传递、以及可选的 AI 输入/输出内容捕获等特性。

  • 安装与运行

    • 常规安装：在项目根目录执行 npm install，再执行 npm run build 构建后端代码。
    • 运行与调试：构建完成后可直接以 Node.js 运行 dist/mcp-server.js 或通过 MCP 客户端插件（Claude Code/Cursor 等）连接到服务器的 stdio 流。

  • 服务器配置（MCP 客户端所需的连接信息，供客户端配置时参考）

    • 服务器名称：cluster-whisperer
    • 启动命令（command）：node
    • 启动参数（args）：["dist/mcp-server.js"]（需替换为实际部署路径）
    • 环境变量（env，示例注释，不是代码）：
      • ANTHROPIC_API_KEY 等用于调查/推断的密钥（如使用调查代理时需要）
      • VOYAGE_API_KEY（如启用向量数据库知识管道/嵌入）
      • OTEL_TRACING_ENABLED、OTEL_EXPORTER_TYPE、OTEL_EXPORTER_OTLP_ENDPOINT 等用于追踪导出 注：实际客户端配置请以 MCP 客户端文档为准，以上信息用于了解该服务器在客户端的连接方式和必要参数。

  • 基本使用方法

    • 启动服务器：构建后在部署环境中以 Node.js 运行 dist/mcp-server.js，确保相关环境变量就绪。
    • 客户端接入：在支持 MCP 的客户端（如 Claude Code、Cursor 等）中添加一个 MCP 服务器条目，配置名称为 cluster-whisperer，命令与参数对应上述启动信息。
    • 调试与观测：如启用追踪，将看到基于 OpenTelemetry 的跨工具/跨请求的追踪信息，必要时可查看日志/追踪后端的输出。

  • 提示与注意

    • MCP 客户端启动与通信采用标准化 JSON-RPC 协议，服务器端实现应能够接收请求、执行 investigate 工具并返回完整的 JSON-RPC 响应。
    • 根据实际运行环境，可能需要将 STDIO 传输改为其他传输（如 SSE/WebSocket），以适配不同的 MCP 客户端。
    • 如遇到密钥/追踪导出相关问题，请参考仓库里的 tracing 与 optional-deps 配置，确保所需依赖正确安装或以无依赖模式运行。

服务器信息

访问项目