使用说明

项目简介

Troubleshoot MCP Server 是一款基于 Model Context Protocol (MCP) 构建的服务器应用，旨在使 AI 模型能够与 Kubernetes 支持包进行交互，从而实现智能化的 Kubernetes 集群分析和故障排除。该服务器允许 AI 模型访问 Kubernetes 集群的诊断信息，执行 'kubectl' 命令，并浏览支持包内的文件，为 AI 驱动的 Kubernetes 管理工具提供强大的后端支持。

主要功能点

支持包管理: 初始化和管理 Kubernetes 支持包，方便 AI 模型访问集群数据。
Kubectl 命令执行: 允许 AI 模型安全地执行 'kubectl' 命令，直接与支持包内的 API Server 交互。
文件浏览: 提供文件系统浏览能力，使 AI 模型能够查看和搜索支持包内的文件内容。
安全认证: 基于 Token 的安全认证机制，保障对支持包的访问安全。
容器化部署: 支持 Docker 容器化部署，方便快捷地部署和运行 MCP 服务器。

安装步骤

Docker 部署 (推荐)
- 确保已安装 Docker。
- 执行仓库提供的 'build.sh' 脚本构建 Docker 镜像：
```
./scripts/build.sh
```
- 使用 'run.sh' 脚本运行服务器，指定支持包存储路径和访问 Token：
```
./scripts/run.sh /path/to/bundles your-token
```
  请将 '/path/to/bundles' 替换为本地存储支持包的路径，'your-token' 替换为您设置的访问 Token。

手动安装

确保已安装 Python 3.11 或更高版本。

创建虚拟环境并激活：

./scripts/setup_env.sh

或手动创建：

uv venv -p python3.13 .venv
source .venv/bin/activate

安装项目依赖：

uv pip install -e ".[dev]"

设置访问 Token 环境变量：

export SBCTL_TOKEN=your-token

运行 MCP 服务器：

python -m mcp_server_troubleshoot

服务器配置

MCP 客户端需要配置以下 JSON 格式的服务器连接信息，以便与 Troubleshoot MCP Server 建立连接。请根据您的实际部署情况修改以下参数。

{
  "serverName": "troubleshoot-mcp-server",
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "-v",
    "${HOME}/bundles:/data/bundles",
    // 将 '${HOME}/bundles' 替换为 MCP 客户端本地存储支持包的路径，
    // 确保此路径与 MCP 服务器的 '/path/to/bundles' 路径对应。
    "-e",
    "SBCTL_TOKEN=${SBCTL_TOKEN}",
    // 将 '${SBCTL_TOKEN}' 替换为访问 MCP 服务器时使用的 Token，
    // 此 Token 需要与 MCP 服务器启动时设置的 Token 一致。
    "mcp-server-troubleshoot:latest"
    //  'mcp-server-troubleshoot:latest' 是 Docker 镜像名称，
    // 请根据实际构建的镜像名称进行调整。
  ]
}

基本使用方法

AI 模型可以通过 JSON-RPC 协议与 Troubleshoot MCP Server 进行通信。以下是一些基本操作示例：

列出文件: 请求服务器列出支持包根目录下的文件和目录：

{
  "name": "list_files",
  "input": {
    "path": "/",
    "recursive": false
  }
}

读取文件内容: 请求服务器读取指定文件的内容：

{
  "name": "read_file",
  "input": {
    "path": "/kubernetes/pods/pod-definition.yaml"
  }
}

执行 kubectl 命令: 请求服务器执行 'kubectl get pods' 命令：

{
  "name": "kubectl",
  "input": {
    "command": "get pods"
  }
}

AI 模型需要根据 MCP 协议规范构造 JSON-RPC 请求，并发送到 MCP 服务器的 JSON-RPC 端点。服务器会处理请求并返回 JSON-RPC 响应。详细的 API 文档请参考仓库中的 'docs/api_reference.md'。

Troubleshoot MCP Server

使用说明

服务器信息