feat(mcp): add list-plugin-instances tool for AI Agent (#3038)

plugins/golang-filter/mcp-server/servers/higress/higress-api/README.md

@@ -17,6 +17,7 @@ Higress API MCP Server 提供了 MCP 工具来管理 Higress 路由、服务来
 - `update-service-source`: 更新服务来源
 
 ### 插件管理
+- `list-plugin-instances`: 列出特定作用域下的所有插件实例（支持全局、域名、服务、路由级别）
 - `get-plugin`: 获取插件配置
 - `delete-plugin`: 删除插件
 - `update-request-block-plugin`: 更新 request-block 插件配置

plugins/golang-filter/mcp-server/servers/higress/higress-api/README_en.md

@@ -17,6 +17,7 @@ Higress API MCP Server provides MCP tools to manage Higress routes, service sour
 - `update-service-source`: Update service source
 
 ### Plugin Management
+- `list-plugin-instances`: List all plugin instances for a specific scope (supports global, domain, service, and route levels)
 - `get-plugin`: Get plugin configuration
 - `delete-plugin`: Delete plugin
 - `update-request-block-plugin`: Update request block configuration

plugins/golang-filter/mcp-server/servers/higress/higress-api/tools/plugins/common.go

@@ -12,6 +12,12 @@ import (
 
 // RegisterCommonPluginTools registers all common plugin management tools
 func RegisterCommonPluginTools(mcpServer *common.MCPServer, client *higress.HigressClient) {
+	// List plugin instances for a specific scope
+	mcpServer.AddTool(
+		mcp.NewToolWithRawSchema("list-plugin-instances", "List all plugin instances for a specific scope (e.g., a route, domain, or service)", getListPluginInstancesSchema()),
+		handleListPluginInstances(client),
+	)
+
 	// Get plugin configuration
 	mcpServer.AddTool(
 		mcp.NewToolWithRawSchema("get-plugin", "Get configuration for a specific plugin", getPluginConfigSchema()),
@@ -25,6 +31,61 @@ func RegisterCommonPluginTools(mcpServer *common.MCPServer, client *higress.Higr
 	)
 }
 
+func handleListPluginInstances(client *higress.HigressClient) common.ToolHandlerFunc {
+	return func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+		arguments := request.Params.Arguments
+
+		// Parse required parameters
+		scope, ok := arguments["scope"].(string)
+		if !ok {
+			return nil, fmt.Errorf("missing or invalid 'scope' argument")
+		}
+
+		if !IsValidScope(scope) {
+			return nil, fmt.Errorf("invalid scope '%s', must be one of: %v", scope, ValidScopes)
+		}
+
+		// Parse resource_name (required for non-global scopes)
+		var resourceName string
+		if scope != ScopeGlobal {
+			resourceName, ok = arguments["resource_name"].(string)
+			if !ok || resourceName == "" {
+				return nil, fmt.Errorf("'resource_name' is required for scope '%s'", scope)
+			}
+		}
+
+		// Build API path and make request
+		// The API endpoint for listing all plugin instances at a specific scope
+		var path string
+		switch scope {
+		case ScopeGlobal:
+			path = "/v1/global/plugin-instances"
+		case ScopeDomain:
+			path = fmt.Sprintf("/v1/domains/%s/plugin-instances", resourceName)
+		case ScopeService:
+			path = fmt.Sprintf("/v1/services/%s/plugin-instances", resourceName)
+		case ScopeRoute:
+			path = fmt.Sprintf("/v1/routes/%s/plugin-instances", resourceName)
+		default:
+			path = "/v1/global/plugin-instances"
+		}
+
+		respBody, err := client.Get(path)
+		if err != nil {
+			return nil, fmt.Errorf("failed to list plugin instances at scope '%s': %w", scope, err)
+		}
+
+		return &mcp.CallToolResult{
+			Content: []mcp.Content{
+				mcp.TextContent{
+					Type: "text",
+					Text: string(respBody),
+				},
+			},
+		}, nil
+	}
+}
+
 func handleGetPluginConfig(client *higress.HigressClient) common.ToolHandlerFunc {
 	return func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 		arguments := request.Params.Arguments
@@ -117,6 +178,25 @@ func handleDeletePluginConfig(client *higress.HigressClient) common.ToolHandlerF
 	}
 }
 
+func getListPluginInstancesSchema() json.RawMessage {
+	return json.RawMessage(`{
+		"type": "object",
+		"properties": {
+			"scope": {
+				"type": "string",
+				"enum": ["GLOBAL", "DOMAIN", "SERVICE", "ROUTE"],
+				"description": "The scope at which to list plugin instances"
+			},
+			"resource_name": {
+				"type": "string",
+				"description": "The name of the resource (required for DOMAIN, SERVICE, ROUTE scopes). For example, the route name, domain name, or service name"
+			}
+		},
+		"required": ["scope"],
+		"additionalProperties": false
+	}`)
+}
+
 func getPluginConfigSchema() json.RawMessage {
 	return json.RawMessage(`{
 		"type": "object",