feat: add higress api mcp server #2923
Conversation
Tsukilc
requested review from
CH3CHO,
erasernoob,
johnlanni and
rinfx
as code owners
新增 Higress API MCP 服务器功能以支持 AI 路由和提供商管理变更概述
变更文件
💡 小贴士与 lingma-agents 交流的方式📜 直接回复评论
📜 在代码行处标记
📜 在讨论中提问
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #2923 +/- ##
==========================================
+ Coverage 35.91% 43.44% +7.53%
==========================================
Files 69 82 +13
Lines 11576 10917 -659
==========================================
+ Hits 4157 4743 +586
+ Misses 7104 5845 -1259
- Partials 315 329 +14 🚀 New features to boost your workflow:
|
![lingma-agents[bot]](https://avatars.githubusercontent.com/in/1198481?s=60&v=4){kind=small}
There was a problem hiding this comment.
🔎 代码评审报告
🎯 评审意见概览
| 严重度 | 数量 | 说明 |
|---|---|---|
| 🔴 Blocker | 0 | 阻断性问题，需立即修复。例如：系统崩溃、关键功能不可用或严重安全漏洞。 |
| 🟠 Critical | 2 | 严重问题，高优先级修复。例如：核心功能异常或性能瓶颈影响用户体验。 |
| 🟡 Major | 3 | 主要问题，建议修复。例如：非核心功能缺陷或代码维护性较差。 |
| 🟢 Minor | 3 | 次要问题，酬情优化。例如：代码格式不规范或注释缺失。 |
总计: 8 个问题
📋 评审意见详情
💡 代码实现建议
以下是文件级别的代码建议，聚焦于代码的可读性、可维护性和潜在问题。
📖 plugins/golang-filter/mcp-server/servers/higress/higress-api/README.md (1 💬)
- 更新README文档以反映新增功能 (L3)
📖 plugins/golang-filter/mcp-server/servers/higress/higress-api/README_en.md (1 💬)
- 更新英文README文档以反映新增功能 (L3)
🔹 plugins/golang-filter/mcp-server/servers/higress/higress-api/server.go (1 💬)
- 注册AI路由、AI提供商和MCP服务器管理工具 (L70-L72)
🔹 plugins/golang-filter/mcp-server/servers/higress/higress-api/tools/ai_route.go (3 💬)
- 在处理 AI 路由更新时，应避免无意义的类型转换操作，以提升性能和代码清晰度。 (L200-L209)
- 在合并 AI 路由配置时，应确保所有字段都正确处理空值，以避免覆盖默认值或导致意外行为。 (L211-L235)
- 应增强对上游权重总和的校验，以确保配置符合业务逻辑要求。 (L354-L370)
🔹 plugins/golang-filter/mcp-server/servers/higress/higress-api/tools/mcp_server.go (1 💬)
- 查询参数拼接逻辑存在错误，可能导致查询参数格式不正确。 (L124-L133)
🔹 plugins/golang-filter/mcp-server/servers/higress/higress-api/tools/route.go (1 💬)
- 路由工具的查询Schema定义不完整，缺少必要的参数定义。 (L270-L277)
🚀 架构设计建议
以下是对代码架构和设计的综合分析，聚焦于跨文件交互、系统一致性和潜在优化空间。
🔍1. 架构一致性问题：DELETE请求中新增带请求体的DeleteWithBody方法不符合REST规范
在HigressClient中新增的DeleteWithBody方法允许DELETE请求携带请求体，这不符合RESTful API的设计规范。DELETE请求通常不包含请求体，且某些HTTP客户端或代理可能不支持或会忽略DELETE请求中的请求体。这可能导致在不同环境下的行为不一致，影响系统的可移植性和兼容性。建议将需要携带数据的删除操作改为POST或PUT请求，或者通过查询参数传递删除所需的信息。
📌 关键代码
// DeleteWithBody performs a DELETE request with a request body
func (c *HigressClient) DeleteWithBody(path string, data interface{}) ([]byte, error) {
return c.request("DELETE", path, data)
}可能导致API在不同环境下的行为不一致，影响系统的兼容性和可移植性，增加调试和维护成本。
🔍2. 跨文件问题：AI路由和MCP服务器工具中存在重复的配置合并逻辑
在ai_provider.go、ai_route.go和mcp_server.go中都存在类似的配置合并逻辑，用于处理更新操作时将新配置与现有配置合并。这些逻辑重复且复杂，增加了维护成本和出错风险。建议将通用的配置合并逻辑抽象成独立的工具函数，供所有需要的模块复用，以提高代码的一致性和可维护性。
重复的代码逻辑增加了维护成本，容易在多处出现类似的bug，且修改时需要同步多处代码，容易遗漏。
🔍3. 技术债务：工具注册方式缺乏统一的错误处理和日志记录
在RegisterAiProviderTools、RegisterAiRouteTools和RegisterMcpServerTools等函数中，工具的注册过程缺乏统一的错误处理和日志记录机制。当工具注册失败时，系统可能无法及时发现和处理问题，影响系统的稳定性和可维护性。建议在工具注册过程中增加统一的错误处理和日志记录，确保所有注册操作的可靠性和可追踪性。
工具注册失败时难以及时发现，可能导致运行时错误或功能缺失，增加系统调试和维护的难度。
🔍4. 可维护性问题：Swagger内容转换工具中的查询参数拼接逻辑存在错误
在handleListMcpServers函数中，查询参数的拼接逻辑存在错误。多个参数拼接时，除了第一个参数使用'?'外，后续参数应该使用'&'连接，但当前实现中所有参数都可能使用'?'，导致生成的URL格式不正确。这会影响API调用的正确性，建议修复查询参数拼接逻辑，确保生成正确的URL。
📌 关键代码
生成的URL格式不正确可能导致API调用失败，影响功能的正常使用，增加调试和维护成本。
🔍5. 业务逻辑一致性问题：AI路由中上游权重总和校验不完整
在AI路由配置中，上游权重的总和应为100，但在handleUpdateAiRoute函数中缺少对上游权重总和的校验。这可能导致配置不符合业务逻辑要求，影响路由的正确性。建议在处理AI路由更新时，增强对上游权重总和的校验，确保配置符合业务逻辑要求。
📌 关键代码
配置不符合业务逻辑要求可能导致路由行为异常，影响服务的正确性和稳定性。
🔍6. 测试覆盖策略问题：新增的AI路由和MCP服务器管理工具缺乏单元测试
新增的AI路由和MCP服务器管理工具（如ai_provider.go、ai_route.go、mcp_server.go）缺乏相应的单元测试。这些工具涉及复杂的业务逻辑和API调用，没有充分的测试覆盖可能导致潜在的bug和运行时错误。建议为这些新增的工具编写全面的单元测试，确保其功能的正确性和稳定性。
缺乏单元测试可能导致潜在的bug未被及时发现，增加系统运行时错误的风险，影响系统的稳定性和可靠性。
审查详情
📒 文件清单 （9 个文件）
✅ 新增: 3 个文件
📝 变更: 6 个文件
✅ 新增文件:
plugins/golang-filter/mcp-server/servers/higress/higress-api/tools/ai_provider.goplugins/golang-filter/mcp-server/servers/higress/higress-api/tools/ai_route.goplugins/golang-filter/mcp-server/servers/higress/higress-api/tools/mcp_server.go
📝 变更文件:
plugins/golang-filter/mcp-server/servers/higress/client.goplugins/golang-filter/mcp-server/servers/higress/higress-api/README.mdplugins/golang-filter/mcp-server/servers/higress/higress-api/README_en.mdplugins/golang-filter/mcp-server/servers/higress/higress-api/server.goplugins/golang-filter/mcp-server/servers/higress/higress-api/tools/route.goplugins/golang-filter/mcp-server/servers/higress/higress-api/tools/service.go
💡 小贴士
与 lingma-agents 交流的方式
📜 直接回复评论
直接回复本条评论，lingma-agents 将自动处理您的请求。例如：
-
在当前代码中添加详细的注释说明。
-
请详细介绍一下你说的 LRU 改造方案，并使用伪代码加以说明。
📜 在代码行处标记
在文件的特定位置创建评论并 @lingma-agents。例如：
-
@lingma-agents 分析这个方法的性能瓶颈并提供优化建议。
-
@lingma-agents 对这个方法生成优化代码。
📜 在讨论中提问
在任何讨论中 @lingma-agents 来获取帮助。例如：
-
@lingma-agents 请总结上述讨论并提出解决方案。
-
@lingma-agents 请根据讨论内容生成优化代码。
| # Higress API MCP Server | ||
|
|
||
| Higress API MCP Server 提供了 MCP 工具来管理 Higress 路由、服务来源和插件等资源。 | ||
| Higress API MCP Server 提供了 MCP 工具来管理 Higress 路由、服务来源、AI路由、AI提供商、MCP服务器和插件等资源。 |
| # Higress API MCP Server | ||
|
|
||
| Higress API MCP Server provides MCP tools to manage Higress routes, service sources, plugins and other resources. | ||
| Higress API MCP Server provides MCP tools to manage Higress routes, service sources, AI routes, AI providers, MCP servers, plugins and other resources. |
| tools.RegisterAiRouteTools(mcpServer, client) | ||
| tools.RegisterAiProviderTools(mcpServer, client) | ||
| tools.RegisterMcpServerTools(mcpServer, client) |
plugins/golang-filter/mcp-server/servers/higress/higress-api/tools/ai_route.go
Show resolved
Hide resolved
plugins/golang-filter/mcp-server/servers/higress/higress-api/tools/ai_route.go
Show resolved
Hide resolved
| "upstreams": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "object", | ||
| "properties": { | ||
| "provider": {"type": "string", "description": "LLM provider name"}, | ||
| "weight": {"type": "integer", "description": "Weight of the upstream,The sum of upstream weights must be 100"}, | ||
| "modelMapping": { | ||
| "type": "object", | ||
| "additionalProperties": {"type": "string"}, | ||
| "description": "Model mapping" | ||
| } | ||
| }, | ||
| "required": ["provider", "weight"] | ||
| }, | ||
| "description": "Route upstreams" | ||
| }, |
There was a problem hiding this comment.
应增强对上游权重总和的校验，以确保配置符合业务逻辑要求。
🟠 Critical | 🐞 Bugs
📋 问题详情
在 getAddAiRouteSchema 和 getUpdateAiRouteSchema 的 JSON Schema 中，描述了上游权重总和必须为 100，但实际代码中并未实现此校验。若用户配置的权重总和不为 100，可能导致路由行为异常或负载不均。应在添加或更新路由时增加此校验逻辑。
💡 解决方案
建议在 handleAddAiRoute 和 handleUpdateAiRoute 中增加对上游权重总和的校验逻辑，确保其总和为 100。
+ // Validate upstream weights sum to 100
+ totalWeight := 0
+ for _, upstream := range newConfig.Upstreams {
+ totalWeight += upstream.Weight
+ }
+ if totalWeight != 100 {
+ return nil, fmt.Errorf("upstream weights must sum to 100, got %d", totalWeight)
+ }您的反馈对我们很重要！(建议右键在新标签页中打开以下链接)
plugins/golang-filter/mcp-server/servers/higress/higress-api/tools/mcp_server.go
Show resolved
Hide resolved
plugins/golang-filter/mcp-server/servers/higress/higress-api/tools/route.go
Show resolved
Hide resolved
Tsukilc
requested review from
2456868764,
Erica177,
SpecialYang,
Xunzhuo and
wydream
as code owners
|
|
Tsukilc
force-pushed
the
feat/api-ops-mcp-server
branch
from
cfee36a to
df40f1c
Compare
plugins/golang-filter/mcp-server/servers/higress/higress-api/tools/route.go
Outdated
Show resolved
Hide resolved
| username: admin | ||
| password: admin |
There was a problem hiding this comment.
Can we let users provide their credentials at call time through the MCP Client (e.g., Cherry Studio), instead of configuring them on the MCP Server? This would be more secure.
The MCP Server only needs to pass the credentials headers to the backend (Higress Console). We can implement this using middleware. Reference: https://github.com/mark3labs/mcp-go/blob/main/www/docs/pages/transports/http.mdx#custom-endpoints
Extract credentials in middleware and add them to context, then use them in handlers to call backend APIs .
s.AddToolMiddleware(func(next server.ToolHandler) server.ToolHandler {
return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
// Get Authorization header from req.Header
authHeader := req.Header.Get("Authorization")
if authHeader == "" {
return nil, fmt.Errorf("authentication required")
}
// Verify Basic Auth format (optional validation)
if !strings.HasPrefix(authHeader, "Basic ") {
return nil, fmt.Errorf("invalid authorization header")
}
// Store entire Authorization header in context for passthrough
ctx = context.WithValue(ctx, "auth_header", authHeader)
return next(ctx, req)
}
})In your tool handler, extract credentials from context and use them for backend API calls.
func handleListRoutes(client *higress.HigressClient) common.ToolHandlerFunc {
return func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
// Extract Authorization header from context (set by middleware)
authHeader, ok := ctx.Value("auth_header").(string)
if !ok || authHeader == "" {
return nil, fmt.Errorf("authentication required")
}
// Pass auth header directly to client method
respBody, err := client.Get("/v1/routes", authHeader)
......
}
}
| type: higress-ops | ||
| config: | ||
| istiodURL: http://higress-controller.higress-system.svc.cluster.local:15014 # istiod url | ||
| istiodToken: "your token" # 生成方式：kubectl create token higress-gateway -n higress-system --audience istio-ca --duration 87600h |
There was a problem hiding this comment.
We can also let user provide istiodToken in the MCP Client.
openapi-mcp.movopenapi-mcp.mov |
istiod.mov |
ai-route.movai-route.mov |
envoy.movenvoy.mov |
http-bin+response.mov |
plugins/golang-filter/mcp-server/servers/higress/higress-ops/README.md
Outdated
Show resolved
Hide resolved
plugins/golang-filter/mcp-server/servers/higress/higress-ops/README.md
Outdated
Show resolved
Hide resolved
plugins/golang-filter/mcp-server/servers/higress/higress-ops/README_en.md
Outdated
Show resolved
Hide resolved
plugins/golang-filter/mcp-server/servers/higress/higress-ops/README_en.md
Outdated
Show resolved
Hide resolved
Co-authored-by: 澄潭 <[email protected]> Co-authored-by: Se7en <[email protected]>
5 participants
Ⅰ. Describe what this PR did
Integrate the higress api mcp server within higress to expose the api of the higress console as an mcp tool
Ⅲ. Why don't you add test cases (unit test/integration test)?
Manual testing is required.
Ⅳ. Describe how to verify it
refer https://github.com/higress-group/higress-ai-agent/pull/1/files#diff-b08296c17cef8b8fb268a5ad3ba6cac7146b1a319a8c1f23d5900f05c2fb0441