Higress OPS MCP Server 使用说明

项目简介

Higress OPS MCP Server 是一个基于 Model Context Protocol (MCP) 构建的后端服务器，专注于 Higress API 网关的操作和管理。它允许 LLM 客户端通过标准化的 MCP 协议，以自然语言交互的方式，调用预定义的工具来查询 Higress 的配置信息、更新路由规则、管理服务源和服务插件等。该项目旨在为 Higress 提供更智能、更易用的运维管理方式，降低人工操作的复杂性。

主要功能点

资源管理 (Resources): 虽然仓库中没有明确“资源”的概念，但其管理 Higress 的路由、服务源、插件等配置信息可以理解为对 Higress 配置资源的管理和访问。
工具注册和执行 (Tools): 提供了丰富的工具集 (定义在 'tools' 目录下)，例如：
- 路由管理工具 (RouteTools): 用于查询、添加和更新 Higress 路由规则。
- 服务源管理工具 (ServiceSourceTools): 用于查询、添加和更新 Higress 服务源。
- 插件管理工具 (RequestBlockTools, CommonTools): 用于更新和查询 Higress 插件配置，例如请求拦截插件。
Prompt 模板 (Prompts): 虽然没有显式的 Prompt 模板定义，但该 MCP 服务器的设计目标是与 LLM 客户端配合使用，通过工具化的方式响应用户的自然语言指令，可以认为 Prompt 模板的概念体现在客户端如何组织和发送用户请求，并解析服务器返回的结果。
JSON-RPC 通信: 基于 'fastmcp' 库构建，隐式地支持 JSON-RPC 协议，通过 Stdio 传输协议与客户端通信 (如 'client.py' 所示)。
会话管理和能力声明: MCP 服务器负责会话管理 (客户端 'client.py' 中有 session_id 的生成和使用)，并通过注册工具的方式声明自身能力。
工具执行的权限控制: 通过 'SENSITIVE_TOOLS' 列表定义了需要人工确认才能执行的敏感操作，提供了基本的权限控制机制。

安装步骤

克隆仓库:

git clone https://github.com/cr7258/higress-ops-mcp-server.git
cd higress-ops-mcp-server

配置环境变量: 复制 '.env.example' 文件为 '.env'，并根据您的 Higress 环境填写以下环境变量：
- 'HIGRESS_URL': Higress 控制台 API 的 URL，例如 'http://localhost:8001'。
- 'HIGRESS_USERNAME': 用于访问 Higress API 的用户名。
- 'HIGRESS_PASSWORD': 用于访问 Higress API 的密码。
- 'OPENAI_API_KEY' (可选，客户端使用): 如果您想使用 'client.py' 中的 LangChain 客户端示例，需要配置 OpenAI API 密钥。
- 'OPENAI_API_BASE' 和 'MODEL_NAME' (可选，客户端使用): 如果您使用非官方 OpenAI API 或需要指定模型，请配置。

安装 Python 依赖: 虽然仓库中没有明确的 'requirements.txt' 文件，但根据代码推断，您可能需要安装以下 Python 库：

pip install python-dotenv fastmcp langchain_core langchain_openai langgraph mcp requests

建议您根据实际运行情况安装缺少的库。

服务器配置 (MCP 客户端配置)

MCP 客户端 (例如 'client.py') 需要配置以下信息以启动和连接 MCP 服务器。以下是基于 'client.py' 代码生成的服务器配置信息示例 (JSON 格式，用于配置 MCP 客户端，不是直接编辑服务器代码):

{
  "server_name": "higress-mcp-server",  // 服务器名称，可自定义
  "command": "python",                  // 启动服务器的命令，这里是 python
  "args": [                             // 启动服务器命令的参数列表
    "./server.py",                      // 服务器脚本路径
    "--higress-url", "<您的 Higress API URL>", // Higress API URL，例如 "http://localhost:8001"，实际使用时替换为您的 URL 或通过环境变量配置
    "--username", "<您的 Higress 用户名>",    // Higress API 用户名，实际使用时替换为您的用户名或通过环境变量配置
    "--password", "<您的 Higress 密码>"     // Higress API 密码，实际使用时替换为您的密码或通过环境变量配置
  ]
}

参数注释:

'server_name': MCP 服务器的名称，客户端可以用于标识不同的服务器连接。
'command': 启动 MCP 服务器的可执行命令，通常是 'python' 或 'node' 等。
'args': 传递给启动命令的参数列表，用于配置服务器的运行环境和连接信息。
- '"./server.py"': 指定服务器主脚本的路径。
- '"--higress-url"', '"--username"', '"--password"': 用于配置 Higress API 的连接信息，这些参数会传递给 'server.py' 中的 'HigressMCPServer' 类进行初始化。 请务必将 '<您的 Higress API URL>'、'<您的 Higress 用户名>'、'<您的 Higress 密码>' 替换为您的实际值，或者使用环境变量配置。

MCP 客户端如何使用此配置:

MCP 客户端 (例如 LangChain MCP Adapters 或自定义客户端) 需要读取并解析上述 JSON 配置，然后使用 'command' 和 'args' 启动 MCP 服务器进程，并通过 Stdio 或其他指定的传输协议与服务器建立连接，进行后续的 MCP 交互。 'client.py' 示例代码已经展示了如何使用 'StdioServerParameters' 和 'stdio_client' 来启动和连接服务器。

基本使用方法

启动 MCP 客户端: 在克隆的仓库目录下，确保已配置 '.env' 文件，然后运行 'client.py' 客户端程序：
```
uv run client.py
```
或者 (如果未安装 'uv'):
```
python client.py
```
与 Higress OPS MCP Server 交互: 客户端启动后，您可以在命令行中输入自然语言查询，例如：
- '列出所有路由'
- '获取名为 route-example 的路由信息'
- '添加一个新的路由，名称为 test-route，路径为 /test，服务为 seven-test.dns:443'
- '更新路由 route-example 的路径为 /new-test'
用户确认敏感操作: 对于 'SENSITIVE_TOOLS' 列表中定义的操作 (例如 'add_route', 'update_route' 等)，服务器会返回工具调用信息，客户端 (在 'client.py' 的实现中) 会提示用户进行确认。您需要输入 'y' 确认执行，或输入其他内容拒绝执行并提供修改意见。
退出客户端: 在客户端命令行中输入 'quit', 'exit', 或 'q' 即可退出客户端程序。

注意:

本项目主要用于 Higress API 网关的管理和操作，需要您已经部署并运行了 Higress 控制台。
客户端示例 'client.py' 使用了 OpenAI 的模型进行自然语言处理和工具调用，您需要配置 OpenAI API 相关的环境变量才能完整运行客户端示例。您可以根据实际需求替换或修改客户端的 LLM 模型和交互逻辑。
敏感操作需要用户确认的机制旨在提高安全性，实际应用中可以根据需要调整敏感工具列表和权限控制策略。

关键词