feat: implement hgctl agent & mcp add subcommand (#3051)

hgctl/pkg/agent/agent.go

@@ -0,0 +1,46 @@
+// Copyright (c) 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package agent
+
+import (
+	"io"
+
+	"github.com/spf13/cobra"
+	cmdutil "k8s.io/kubectl/pkg/cmd/util"
+)
+
+func NewAgentCmd() *cobra.Command {
+	agentCmd := &cobra.Command{
+		Use:   "agent",
+		Short: "start the interactive agent window",
+		Run: func(cmd *cobra.Command, args []string) {
+			cmdutil.CheckErr(handleAgentInvoke(cmd.OutOrStdout()))
+		},
+	}
+
+	return agentCmd
+}
+
+func handleAgentInvoke(w io.Writer) error {
+
+	return getAgent().Start()
+}
+
+// Sub-Agent1:
+// 1. Parse the url provided by user to MCP server configuration.
+// 2. Publish the parsed MCP Server to Higress
+func addPrequisiteSubAgent() error {
+	return nil
+}

hgctl/pkg/agent/base.go

@@ -0,0 +1,61 @@
+// Copyright (c) 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package agent
+
+import (
+	"fmt"
+	"os"
+)
+
+const (
+	AgentBinaryName  = "claude"
+	BinaryVersion    = "0.1.0"
+	DevVersion       = "dev"
+	NodeLeastVersion = 18
+	AgentInstallCmd  = "npm install -g @anthropic-ai/claude-code"
+	AgentReleasePage = "https://docs.claude.com/en/docs/claude-code/setup"
+)
+
+// set up the core env
+// 1. check if npm is installed
+// 2. check the npm version
+// 3. install hgctl-agent
+func getAgent() *AgenticCore {
+	if !checkAgentInstallStatus() {
+		fmt.Println("⚠️ Prerequisites not satisfied. Exiting...")
+		// exit directly
+		os.Exit(1)
+	}
+
+	return NewAgenticCore()
+}
+
+func checkAgentInstallStatus() bool {
+	// TODO: Support cross-platform:windows
+
+	if !checkNodeInstall() {
+		if err := promptNodeInstall(); err != nil {
+			return false
+		}
+	}
+
+	if !checkAgentInstall() {
+		if err := promptAgentInstall(); err != nil {
+			return false
+		}
+	}
+
+	return true
+}

hgctl/pkg/agent/core.go

@@ -0,0 +1,46 @@
+// Copyright (c) 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package agent
+
+import (
+	"os"
+	"os/exec"
+)
+
+type AgenticCore struct {
+}
+
+func NewAgenticCore() *AgenticCore {
+	return &AgenticCore{}
+}
+
+func (c *AgenticCore) run(args ...string) error {
+	cmd := exec.Command(AgentBinaryName, args...)
+	cmd.Stdin = os.Stdin
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	return cmd.Run()
+
+}
+
+// ------- Initialization  -------
+func (c *AgenticCore) Start() error {
+	return c.run(AgentBinaryName)
+}
+
+// ------- MCP  -------
+func (c *AgenticCore) AddMCPServer(name string, url string) error {
+	return c.run("mcp", "add", "--transport", HTTP, name, url)
+}

hgctl/pkg/agent/mcp.go

@@ -0,0 +1,314 @@
+// Copyright (c) 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package agent
+
+import (
+	"fmt"
+	"io"
+	"net"
+	"net/url"
+	"os"
+	"strings"
+
+	"github.com/alibaba/higress/hgctl/pkg/agent/services"
+	"github.com/fatih/color"
+	"github.com/higress-group/openapi-to-mcpserver/pkg/models"
+	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
+	cmdutil "k8s.io/kubectl/pkg/cmd/util"
+)
+
+type MCPType string
+
+const (
+	HTTP         string = "http"
+	SSE          string = "sse"
+	OPENAPI      string = "openapi"
+	DIRECT_ROUTE string = "DIRECT_ROUTE"
+	OPEN_API     string = "OPEN_API"
+
+	HIGRESS_CONSOLE_URL      = "higress-console-url"
+	HIGRESS_CONSOLE_USER     = "higress-console-user"
+	HIGRESS_CONSOLE_PASSWORD = "higress-console-password"
+)
+
+type MCPAddArg struct {
+	// higress console auth arg
+	baseURL    string
+	hgUser     string
+	hgPassword string
+
+	name      string
+	url       string
+	transport string
+	spec      string
+	scope     string
+	noPublish bool
+	// TODO: support mcp env
+	// env string
+
+}
+
+type MCPAddHandler struct {
+	core *AgenticCore
+	arg  MCPAddArg
+	w    io.Writer
+}
+
+func NewMCPCmd() *cobra.Command {
+	mcpCmd := &cobra.Command{
+		Use:   "mcp",
+		Short: "for the mcp management",
+	}
+
+	mcpCmd.AddCommand(newMCPAddCmd())
+
+	return mcpCmd
+}
+
+func newMCPAddCmd() *cobra.Command {
+	// parameter
+	arg := &MCPAddArg{}
+
+	cmd := &cobra.Command{
+		Use:   "add [name]",
+		Short: "add mcp server including http and openapi",
+		Run: func(cmd *cobra.Command, args []string) {
+			arg.name = args[0]
+			resolveHigressConsoleAuth(arg)
+			cmdutil.CheckErr(handleAddMCP(cmd.OutOrStdout(), *arg))
+			color.Cyan("Tip: Try doing 'kubectl port-forward' and add the server to the agent manually, if MCP Server connection failed")
+		},
+		Args: cobra.ExactArgs(1),
+	}
+
+	cmd.PersistentFlags().StringVarP(&arg.transport, "transport", "t", HTTP, "Determine the MCP Server's Type")
+	cmd.PersistentFlags().StringVarP(&arg.url, "url", "u", "", "MCP server URL")
+	cmd.PersistentFlags().StringVarP(&arg.scope, "scope", "s", "project", `Configuration scope (project or global)`)
+	cmd.PersistentFlags().StringVar(&arg.spec, "spec", "", "Specification of the openapi api")
+	cmd.PersistentFlags().BoolVar(&arg.noPublish, "no-publish", false, "If set then the mcp server will not be plubished to higress")
+
+	flagHigressConsoleAuth(cmd, arg)
+
+	return cmd
+}
+
+func newHanlder(c *AgenticCore, arg MCPAddArg, w io.Writer) *MCPAddHandler {
+	return &MCPAddHandler{c, arg, w}
+}
+
+func (h *MCPAddHandler) validateArg() error {
+	if !h.arg.noPublish {
+		if h.arg.baseURL == "" || h.arg.hgUser == "" || h.arg.hgPassword == "" {
+			fmt.Println("--higress-console-user, --higress-console-url, --higress-console-password must be provided")
+			return fmt.Errorf("invalid args")
+		}
+	}
+	return nil
+
+}
+
+func (h *MCPAddHandler) addHTTPMCP() error {
+	if err := h.core.AddMCPServer(h.arg.name, h.arg.url); err != nil {
+		return fmt.Errorf("mcp add failed: %w", err)
+	}
+
+	if !h.arg.noPublish {
+		return publishToHigress(h.arg, nil)
+	}
+	return nil
+
+}
+
+// hgctl mcp add -t openapi --name test-name --spec openapi.json
+func (h *MCPAddHandler) addOpenAPIMCP() error {
+	// fmt.Printf("get mcp server: %s openapi-spec-file: %s\n", h.arg.name, h.arg.spec)
+	config := h.parseOpenapiSpec()
+
+	// fmt.Printf("get config struct: %v", config)
+
+	// publish to higress
+	if err := publishToHigress(h.arg, config); err != nil {
+		return err
+	}
+
+	// add mcp server to agent
+	gatewayIP, err := GetHigressGatewayServiceIP()
+	if err != nil {
+		color.Red(
+			"failed to add mcp server [%s] while getting higress-gateway ip due to: %v \n You may try to do port-forward and add it to agent manually", h.arg.name, err)
+		return err
+	}
+	mcpURL := fmt.Sprintf("http://%s/mcp-servers/%s", gatewayIP, h.arg.name)
+	return h.core.AddMCPServer(h.arg.name, mcpURL)
+}
+
+func (h *MCPAddHandler) parseOpenapiSpec() *models.MCPConfig {
+	return parseOpenapi2MCP(h.arg)
+}
+
+func handleAddMCP(w io.Writer, arg MCPAddArg) error {
+	client := getAgent()
+	h := newHanlder(client, arg, w)
+	if err := h.validateArg(); err != nil {
+		return err
+	}
+
+	// spec -> OPENAPI
+	// noPublish -> typ
+	switch arg.transport {
+	case HTTP:
+		return h.addHTTPMCP()
+	case OPENAPI:
+		if arg.spec == "" {
+			return fmt.Errorf("--spec is required for openapi type")
+		}
+		if arg.noPublish {
+			return fmt.Errorf("--no-publish is not supported for openapi type")
+		}
+		if arg.url != "" {
+			return fmt.Errorf("--url is not supported for openapi type")
+		}
+		return h.addOpenAPIMCP()
+	default:
+		return fmt.Errorf("unsupported mcp type")
+	}
+}
+
+func publishToHigress(arg MCPAddArg, config *models.MCPConfig) error {
+	// 1. parse the raw http url
+	// 2. add service source
+	// 3. add MCP server request
+	client := services.NewHigressClient(arg.baseURL, arg.hgUser, arg.hgPassword)
+
+	// mcp server's url
+	rawURL := arg.url
+	// DIRECT_ROUTE or OPEN_API
+	mcpType := DIRECT_ROUTE
+
+	if config != nil {
+		// TODO: here use tools's url directly, need to be considered
+		rawURL = config.Tools[0].RequestTemplate.URL
+		mcpType = OPEN_API
+	}
+
+	res, err := url.Parse(rawURL)
+	if err != nil {
+		return err
+	}
+
+	// add service source
+	srvType := ""
+	srvPort := ""
+	srvName := fmt.Sprintf("hgctl-%s", arg.name)
+	srvPath := res.Path
+
+	if ip := net.ParseIP(res.Hostname()); ip == nil {
+		srvType = "dns"
+	} else {
+		srvType = "static"
+	}
+
+	if res.Port() == "" && res.Scheme == "http" {
+		srvPort = "80"
+	} else if res.Port() == "" && res.Scheme == "https" {
+		srvPort = "443"
+	} else {
+		srvPort = res.Port()
+	}
+
+	_, err = services.HandleAddServiceSource(client, map[string]interface{}{
+		"domain":        res.Host,
+		"type":          srvType,
+		"port":          srvPort,
+		"name":          srvName,
+		"domainForEdit": res.Host,
+		"protocol":      res.Scheme,
+	})
+	if err != nil {
+		return err
+	}
+
+	srvField := []map[string]interface{}{{
+		"name":    fmt.Sprintf("%s.%s", srvName, srvType),
+		"port":    srvPort,
+		"version": "1.0",
+		"weight":  100,
+	}}
+
+	// generete mcp server add request body
+	body := map[string]interface{}{
+		"name": arg.name,
+		//   "description": "",
+		"type":               mcpType,
+		"service":            fmt.Sprintf("%s.%s:%s", srvName, srvType, srvPort),
+		"upstreamPathPrefix": srvPath,
+		"services":           srvField,
+	}
+
+	// fmt.Printf("request body: %v", body)
+
+	_, err = services.HandleAddMCPServer(client, body)
+	if err != nil {
+		return err
+	}
+
+	if mcpType == OPEN_API {
+		addMCPToolConfig(client, config, srvField)
+	}
+
+	return nil
+}
+
+func addMCPToolConfig(client *services.HigressClient, config *models.MCPConfig, srvField []map[string]interface{}) {
+	body := map[string]interface{}{
+		"name": config.Server.Name,
+		//	  "description": "",
+		"services":          srvField,
+		"type":              OPEN_API,
+		"rawConfigurations": convertMCPConfigToStr(config),
+		"mcpServerName":     config.Server.Name,
+	}
+
+	_, err := services.HandleAddOpenAPITool(client, body)
+	if err != nil {
+		fmt.Printf("add openapi tools failed: %v\n", err)
+		os.Exit(1)
+	}
+	// fmt.Println("get openapi tools add response: ", string(resp))
+}
+
+func flagHigressConsoleAuth(cmd *cobra.Command, arg *MCPAddArg) {
+	cmd.PersistentFlags().StringVar(&arg.baseURL, HIGRESS_CONSOLE_URL, "", "The BaseURL of higress console")
+	cmd.PersistentFlags().StringVar(&arg.hgUser, HIGRESS_CONSOLE_USER, "", "The username of higress console")
+	cmd.PersistentFlags().StringVarP(&arg.hgPassword, HIGRESS_CONSOLE_PASSWORD, "p", "", "The password of higress console")
+
+	viper.SetEnvKeyReplacer(strings.NewReplacer("-", "_"))
+	viper.AutomaticEnv()
+	// TODO: if higress is installed by hgctl, then try to resolve auth arg in install profile
+}
+
+// resolve from viper
+func resolveHigressConsoleAuth(arg *MCPAddArg) {
+	if arg.baseURL == "" {
+		arg.baseURL = viper.GetString(HIGRESS_CONSOLE_URL)
+	}
+	if arg.hgUser == "" {
+		arg.hgUser = viper.GetString(HIGRESS_CONSOLE_USER)
+	}
+	if arg.hgPassword == "" {
+		arg.hgPassword = viper.GetString(HIGRESS_CONSOLE_PASSWORD)
+	}
+}

hgctl/pkg/agent/services/client.go

@@ -0,0 +1,113 @@
+// Copyright (c) 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package services
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+)
+
+type HigressClient struct {
+	baseURL    string
+	username   string
+	password   string
+	httpClient *http.Client
+}
+
+func NewHigressClient(baseURL, username, password string) *HigressClient {
+	client := &HigressClient{
+		baseURL:  baseURL,
+		username: username,
+		password: password,
+		httpClient: &http.Client{
+			Timeout: 30 * time.Second,
+		},
+	}
+
+	return client
+}
+
+func (c *HigressClient) Get(path string) ([]byte, error) {
+	return c.request("GET", path, nil)
+}
+
+func (c *HigressClient) Post(path string, data interface{}) ([]byte, error) {
+	return c.request("POST", path, data)
+}
+
+func (c *HigressClient) Put(path string, data interface{}) ([]byte, error) {
+	return c.request("PUT", path, data)
+}
+
+func (c *HigressClient) Delete(path string) ([]byte, error) {
+	return c.request("DELETE", path, nil)
+}
+func (c *HigressClient) request(method, path string, data interface{}) ([]byte, error) {
+	url := c.baseURL + path
+
+	var body io.Reader
+	if data != nil {
+		jsonData, err := json.Marshal(data)
+		if err != nil {
+			return nil, fmt.Errorf("failed to marshal request data: %w", err)
+		}
+		body = bytes.NewBuffer(jsonData)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, method, url, body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.SetBasicAuth(c.username, c.password)
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode == 409 {
+		return nil, fmt.Errorf("resource already exists")
+	}
+
+	if resp.StatusCode == 400 {
+		return nil, fmt.Errorf("invalid resource definition")
+	}
+
+	if resp.StatusCode == 500 {
+		return nil, fmt.Errorf("server internal error")
+	}
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("HTTP error %d", resp.StatusCode)
+	}
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response body: %w", err)
+	}
+
+	return respBody, nil
+}

hgctl/pkg/agent/services/service.go

@@ -0,0 +1,129 @@
+// Copyright (c) 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package services
+
+import (
+	"fmt"
+)
+
+func HandleAddServiceSource(client *HigressClient, body interface{}) ([]byte, error) {
+	data, ok := body.(map[string]interface{})
+	// fmt.Printf("request body: %v\n", data)
+	if !ok {
+		return nil, fmt.Errorf("failed to parse request body")
+	}
+	// Validate
+	if _, ok := data["name"]; !ok {
+		return nil, fmt.Errorf("missing required field 'name' in body")
+	}
+	if _, ok := data["type"]; !ok {
+		return nil, fmt.Errorf("missing required field 'type' in body")
+	}
+	if _, ok := data["domain"]; !ok {
+		return nil, fmt.Errorf("missing required field 'domain' in body")
+	}
+	if _, ok := data["port"]; !ok {
+		return nil, fmt.Errorf("missing required field 'port' in body")
+	}
+
+	resp, err := client.Post("/v1/service-sources", data)
+	if err != nil {
+		return nil, fmt.Errorf("failed to add service source: %w", err)
+	}
+	// res := make(map[string]interface{})
+
+	return resp, nil
+}
+
+// add MCP server to higress console, example request body as followed:
+//
+//	{
+//	  "name": "mcp-deepwiki",
+//	  "description": "",
+//	  "type": "DIRECT_ROUTE", // or OPEN_API
+//	  "service": "hgctl-deepwiki.dns:443",
+//	  "upstreamPathPrefix": "/mcp",
+//	  "services": [
+//	    {
+//	      "name": "hgctl-deepwiki.dns",
+//	      "port": 443,
+//	      "version": "1.0",
+//	      "weight": 100
+//	    }
+//	  ]
+//	}
+func HandleAddMCPServer(client *HigressClient, body interface{}) ([]byte, error) {
+	data, ok := body.(map[string]interface{})
+	if !ok {
+		return nil, fmt.Errorf("failed to parse request body")
+	}
+	// Validate
+	if _, ok := data["name"]; !ok {
+		return nil, fmt.Errorf("missing required field 'name' in body")
+	}
+	if _, ok := data["type"]; !ok {
+		return nil, fmt.Errorf("missing required field 'type' in body")
+	}
+	if _, ok := data["service"]; !ok {
+		return nil, fmt.Errorf("missing required field 'service' in body")
+	}
+
+	// if _, ok := data["upstreamPathPrefix"]; !ok {
+	// 	return nil, fmt.Errorf("missing required field 'upstreamPathPrefix' in body")
+	// }
+
+	_, ok = data["services"]
+	if !ok {
+		return nil, fmt.Errorf("missing required field 'port' in body")
+	}
+
+	resp, err := client.Put("/v1/mcpServer", data)
+	if err != nil {
+		return nil, fmt.Errorf("failed to add mcp server: %w", err)
+	}
+
+	return resp, nil
+}
+
+// add OpenAPI MCP tools to higress console, example request body:
+//
+//	{
+//	  "id": null,
+//	  "name": "openapi-name",
+//	  "description": "123",
+//	  "domains": [],
+//	  "services": [
+//	    {
+//	      "name": "kubernetes.default.svc.cluster.local",
+//	      "port": 443,
+//	      "version": null,
+//	      "weight": 100
+//	    }
+//	  ],
+//	  "type": "OPEN_API",
+//	  "consumerAuthInfo": {
+//	    "type": "key-auth",
+//	    "enable": false,
+//	    "allowedConsumers": []
+//	  },
+//	  "rawConfigurations": "", // MCP configuration str
+//	  "dsn": null,
+//	  "dbType": null,
+//	  "upstreamPathPrefix": null,
+//	  "mcpServerName": "openapi-name"
+//	}
+func HandleAddOpenAPITool(client *HigressClient, body interface{}) ([]byte, error) {
+	return client.Put("/v1/mcpServer", body)
+}

hgctl/pkg/agent/types.go

@@ -0,0 +1,134 @@
+// Copyright (c) 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package agent
+
+type Message struct {
+	Role    string `json:"role"`
+	Content string `json:"content"`
+}
+
+type Request struct {
+	Model            string    `json:"model"`
+	Messages         []Message `json:"messages"`
+	FrequencyPenalty float64   `json:"frequency_penalty"`
+	PresencePenalty  float64   `json:"presence_penalty"`
+	Stream           bool      `json:"stream"`
+	Temperature      float64   `json:"temperature"`
+	Topp             int32     `json:"top_p"`
+}
+
+type Choice struct {
+	Index        int     `json:"index"`
+	Message      Message `json:"message"`
+	FinishReason string  `json:"finish_reason"`
+}
+
+type Usage struct {
+	PromptTokens     int `json:"prompt_tokens"`
+	CompletionTokens int `json:"completion_tokens"`
+	TotalTokens      int `json:"total_tokens"`
+}
+
+type Response struct {
+	ID      string   `json:"id"`
+	Choices []Choice `json:"choices"`
+	Created int64    `json:"created"`
+	Model   string   `json:"model"`
+	Object  string   `json:"object"`
+	Usage   Usage    `json:"usage"`
+}
+
+type ToolsParam struct {
+	ToolName    string   `yaml:"toolName"`
+	Path        string   `yaml:"path"`
+	Method      string   `yaml:"method"`
+	ParamName   []string `yaml:"paramName"`
+	Parameter   string   `yaml:"parameter"`
+	Description string   `yaml:"description"`
+}
+
+type Info struct {
+	Title       string `yaml:"title"`
+	Description string `yaml:"description"`
+	Version     string `yaml:"version"`
+}
+
+type Server struct {
+	URL string `yaml:"url"`
+}
+
+type Parameter struct {
+	Name        string `yaml:"name"`
+	In          string `yaml:"in"`
+	Description string `yaml:"description"`
+	Required    bool   `yaml:"required"`
+	Schema      struct {
+		Type    string   `yaml:"type"`
+		Default string   `yaml:"default"`
+		Enum    []string `yaml:"enum"`
+	} `yaml:"schema"`
+}
+
+type Items struct {
+	Type    string `yaml:"type"`
+	Example string `yaml:"example"`
+}
+
+type Property struct {
+	Description string   `yaml:"description"`
+	Type        string   `yaml:"type"`
+	Enum        []string `yaml:"enum,omitempty"`
+	Items       *Items   `yaml:"items,omitempty"`
+	MaxItems    int      `yaml:"maxItems,omitempty"`
+	Example     string   `yaml:"example,omitempty"`
+}
+
+type Schema struct {
+	Type       string              `yaml:"type"`
+	Required   []string            `yaml:"required"`
+	Properties map[string]Property `yaml:"properties"`
+}
+
+type MediaType struct {
+	Schema Schema `yaml:"schema"`
+}
+
+type RequestBody struct {
+	Required bool                 `yaml:"required"`
+	Content  map[string]MediaType `yaml:"content"`
+}
+
+type PathItem struct {
+	Description string      `yaml:"description"`
+	Summary     string      `yaml:"summary"`
+	OperationID string      `yaml:"operationId"`
+	RequestBody RequestBody `yaml:"requestBody"`
+	Parameters  []Parameter `yaml:"parameters"`
+	Deprecated  bool        `yaml:"deprecated"`
+}
+
+type Paths map[string]map[string]PathItem
+
+type Components struct {
+	Schemas map[string]interface{} `yaml:"schemas"`
+}
+
+type API struct {
+	OpenAPI    string     `yaml:"openapi"`
+	Info       Info       `yaml:"info"`
+	Servers    []Server   `yaml:"servers"`
+	Paths      Paths      `yaml:"paths"`
+	Components Components `yaml:"components"`
+}

hgctl/pkg/agent/utils.go

@@ -0,0 +1,455 @@
+// Copyright (c) 2025 Alibaba Group Holding Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package agent
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+
+	"github.com/AlecAivazis/survey/v2"
+	"github.com/braydonk/yaml"
+	"github.com/fatih/color"
+	"github.com/higress-group/openapi-to-mcpserver/pkg/converter"
+	"github.com/higress-group/openapi-to-mcpserver/pkg/models"
+	"github.com/higress-group/openapi-to-mcpserver/pkg/parser"
+	"github.com/manifoldco/promptui"
+	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
+	v1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	k8s "k8s.io/client-go/kubernetes"
+	"k8s.io/client-go/tools/clientcmd"
+)
+
+var binaryName = AgentBinaryName
+
+// ------ cmd related  ------
+func BindFlagToEnv(cmd *cobra.Command, flagName, envName string) {
+	_ = viper.BindPFlag(flagName, cmd.PersistentFlags().Lookup(flagName))
+	_ = viper.BindEnv(flagName, envName)
+}
+
+// ------ Prompt to install prequisite environment  ------
+func checkNodeInstall() bool {
+	cmd := exec.Command("node", "-v")
+	out, err := cmd.Output()
+	if err != nil {
+		return false
+	}
+
+	versionStr := strings.TrimPrefix(strings.TrimSpace(string(out)), "v")
+	parts := strings.Split(versionStr, ".")
+	if len(parts) == 0 {
+		return false
+	}
+
+	major, err := strconv.Atoi(parts[0])
+	if err != nil {
+		return false
+	}
+
+	return major >= NodeLeastVersion
+}
+
+func promptNodeInstall() error {
+	fmt.Println()
+	color.Yellow("⚠️ Node.js is not installed or not found in PATH.")
+	color.Cyan("🔧 Node.js is required to run the agent.")
+	fmt.Println()
+
+	options := []string{
+		"🚀 Install automatically (recommended)",
+		"📖 Exit and show manual installation guide",
+	}
+
+	var ans string
+	prompt := &survey.Select{
+		Message: "How would you like to install Node.js?",
+		Options: options,
+	}
+	if err := survey.AskOne(prompt, &ans); err != nil {
+		return fmt.Errorf("selection error: %w", err)
+	}
+
+	switch ans {
+	case "🚀 Install automatically (recommended)":
+		fmt.Println()
+		color.Green("🚀 Installing Node.js automatically...")
+
+		if err := installNodeAutomatically(); err != nil {
+			color.Red("❌ Installation failed: %v", err)
+			fmt.Println()
+			showNodeManualInstallation()
+			return errors.New("node.js installation failed")
+		}
+
+		color.Green("✅ Node.js installation completed!")
+		fmt.Println()
+		color.Blue("🔍 Verifying installation...")
+
+		if checkNodeInstall() {
+			color.Green("🎉 Node.js is now available!")
+			return nil
+		} else {
+			color.Yellow("⚠️ Node.js installation completed but not found in PATH.")
+			color.Cyan("💡 You may need to restart your terminal or source your shell profile.")
+			return errors.New("node.js installed but not in PATH")
+		}
+
+	case "📖 Exit and show manual installation guide":
+		showNodeManualInstallation()
+		return errors.New("node.js not installed")
+
+	default:
+		return errors.New("invalid selection")
+	}
+}
+
+func installNodeAutomatically() error {
+	switch runtime.GOOS {
+	case "windows":
+		color.Cyan("📦 Please download Node.js installer from https://nodejs.org and run it manually on Windows")
+		return errors.New("automatic installation not supported on Windows yet")
+	case "darwin":
+		// macOS: use brew
+		cmd := exec.Command("brew", "install", "node")
+		cmd.Stdout = os.Stdout
+		cmd.Stderr = os.Stderr
+		return cmd.Run()
+	case "linux":
+		// Linux (Debian/Ubuntu example)
+		cmd := exec.Command("sudo", "apt", "update")
+		cmd.Stdout = os.Stdout
+		cmd.Stderr = os.Stderr
+		if err := cmd.Run(); err != nil {
+			return err
+		}
+		cmd = exec.Command("sudo", "apt", "install", "-y", "nodejs", "npm")
+		cmd.Stdout = os.Stdout
+		cmd.Stderr = os.Stderr
+		return cmd.Run()
+	default:
+		return errors.New("unsupported OS for automatic installation")
+	}
+}
+
+func showNodeManualInstallation() {
+	fmt.Println()
+
+	color.New(color.FgGreen, color.Bold).Println("📖 Manual Node.js Installation Guide")
+	fmt.Println()
+
+	fmt.Println(color.MagentaString("Choose one of the following installation methods:"))
+	fmt.Println()
+
+	color.Cyan("Method 1: Install via package manager")
+	color.Cyan("macOS (brew): brew install node")
+	color.Cyan("Ubuntu/Debian: sudo apt install -y nodejs npm")
+	color.Cyan("Windows: download from https://nodejs.org and run installer")
+	fmt.Println()
+
+	color.Yellow("Method 2: Download from official website")
+	color.Yellow("1. Download Node.js from https://nodejs.org/en/download/")
+	color.Yellow("2. Follow installer instructions and add to PATH if needed")
+	fmt.Println()
+
+	color.Green("✅ Verify Installation")
+	fmt.Println(color.WhiteString("node -v"))
+	fmt.Println(color.WhiteString("npm -v"))
+	fmt.Println()
+
+	color.Cyan("💡 After installation, restart your terminal or source your shell profile.")
+	fmt.Println()
+}
+
+func checkAgentInstall() bool {
+	cmd := exec.Command(binaryName, "--version")
+	if err := cmd.Run(); err != nil {
+		return false
+	}
+	return true
+}
+
+func promptAgentInstall() error {
+	fmt.Println()
+	color.Yellow("⚠️ %s is not installed or not found in PATH.", binaryName)
+	color.Cyan("🔧 %s is required to run the agent.", binaryName)
+	fmt.Println()
+
+	options := []string{
+		"🚀 Install automatically (recommended)",
+		"📖 Exit and show manual installation guide",
+	}
+
+	var ans string
+	prompt := &survey.Select{
+		Message: "How would you like to install " + binaryName + "?",
+		Options: options,
+	}
+	if err := survey.AskOne(prompt, &ans); err != nil {
+		return fmt.Errorf("selection error: %w", err)
+	}
+
+	switch ans {
+	case "🚀 Install automatically (recommended)":
+		fmt.Println()
+		color.Green("🚀 Installing %s automatically...", binaryName)
+
+		if err := installAgentAutomatically(); err != nil {
+			color.Red("❌ Installation failed: %v", err)
+			fmt.Println()
+			showAgentManualInstallation()
+			return errors.New(binaryName + " installation failed")
+		}
+
+		color.Green("✅ %s installation completed!", binaryName)
+		fmt.Println()
+		color.Blue("🔍 Verifying installation...")
+
+		if checkAgentInstall() {
+			color.Green("🎉 %s is now available!", binaryName)
+			return nil
+		} else {
+			color.Yellow("⚠️ %s installed but not found in PATH.", binaryName)
+			color.Cyan("💡 You may need to restart your terminal or source your shell profile.")
+			return errors.New(binaryName + " installed but not in PATH")
+		}
+
+	case "📖 Exit and show manual installation guide":
+		showAgentManualInstallation()
+		return errors.New(binaryName + " not installed")
+
+	default:
+		return errors.New("invalid selection")
+	}
+}
+
+func installAgentAutomatically() error {
+	switch runtime.GOOS {
+	case "windows":
+		cmd := exec.Command("cmd", "/C", AgentInstallCmd)
+		cmd.Stdout = os.Stdout
+		cmd.Stderr = os.Stderr
+		return cmd.Run()
+	case "darwin":
+		cmd := exec.Command("bash", "-c", AgentInstallCmd)
+		cmd.Stdout = os.Stdout
+		cmd.Stderr = os.Stderr
+		return cmd.Run()
+	case "linux":
+		cmd := exec.Command("bash", "-c", AgentInstallCmd)
+		cmd.Stdout = os.Stdout
+		cmd.Stderr = os.Stderr
+		return cmd.Run()
+	default:
+		return errors.New("unsupported OS for automatic installation")
+	}
+}
+
+func showAgentManualInstallation() {
+	fmt.Println()
+	color.New(color.FgGreen, color.Bold).Printf("📖 Manual %s Installation Guide\n", binaryName)
+	fmt.Println()
+
+	fmt.Println(color.MagentaString("Supported Operating Systems: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (WSL/Git for Windows)"))
+	fmt.Println(color.MagentaString("Hardware: 4GB+ RAM"))
+	fmt.Println(color.MagentaString("Software: Node.js 18+"))
+	fmt.Println(color.MagentaString("Network: Internet connection required for authentication and AI processing"))
+	fmt.Println(color.MagentaString("Shell: Works best in Bash, Zsh, or Fish"))
+	fmt.Println()
+
+	color.Cyan("Method 1: Download prebuilt binary")
+	color.Cyan(fmt.Sprintf("1. Go to official release page: %s", AgentReleasePage))
+	fmt.Printf(color.CyanString("2. Download %s for your OS\n"), binaryName)
+	color.Cyan("3. Make it executable and place it in a directory in your PATH")
+	fmt.Println()
+
+	fmt.Println()
+	color.Green("✅ Verify Installation")
+	fmt.Printf(color.WhiteString("%s --version\n"), binaryName)
+	fmt.Println()
+	color.Cyan("💡 After installation, restart your terminal or source your shell profile.")
+	fmt.Println()
+}
+
+// ------ MCP convert utils function  ------
+func parseOpenapi2MCP(arg MCPAddArg) *models.MCPConfig {
+	path := arg.spec
+	serverName := arg.name
+
+	// Create a new parser
+	p := parser.NewParser()
+
+	p.SetValidation(true)
+
+	// Parse the OpenAPI specification
+	err := p.ParseFile(path)
+	if err != nil {
+		fmt.Printf("Error parsing OpenAPI specification: %v\n", err)
+		os.Exit(1)
+	}
+
+	c := converter.NewConverter(p, models.ConvertOptions{
+		ServerName:     serverName,
+		ToolNamePrefix: "",
+		TemplatePath:   "",
+	})
+
+	// Convert the OpenAPI specification to an MCP configuration
+	config, err := c.Convert()
+	if err != nil {
+		fmt.Printf("Error converting OpenAPI specification: %v\n", err)
+		os.Exit(1)
+	}
+
+	return config
+}
+
+func convertMCPConfigToStr(cfg *models.MCPConfig) string {
+	var data []byte
+	var buffer bytes.Buffer
+	encoder := yaml.NewEncoder(&buffer)
+	encoder.SetIndent(2)
+
+	if err := encoder.Encode(cfg); err != nil {
+		fmt.Printf("Error encoding YAML: %v\n", err)
+		os.Exit(1)
+	}
+	data = buffer.Bytes()
+	str := string(data)
+
+	// fmt.Println("Successfully converted OpenAPI specification to MCP Server")
+	// fmt.Printf("Get MCP server config string: %v", str)
+	return str
+
+	// if err != nil {
+	// 	fmt.Printf("Error marshaling MCP configuration: %v\n", err)
+	// 	os.Exit(1)
+	// }
+
+	// err = os.WriteFile(*outputFile, data, 0644)
+	// if err != nil {
+	// 	fmt.Printf("Error writing MCP configuration: %v\n", err)
+	// 	os.Exit(1)
+	// }
+
+}
+
+func GetHigressGatewayServiceIP() (string, error) {
+	color.Cyan("🚀 Adding openapi MCP Server to agent, checking Higress Gateway Pod status...")
+
+	defaultKubeconfig := filepath.Join(os.Getenv("HOME"), ".kube", "config")
+	config, err := clientcmd.BuildConfigFromFlags("", defaultKubeconfig)
+	if err != nil {
+		color.Yellow("⚠️ Failed to load default kubeconfig: %v", err)
+		return promptForServiceKubeSettingsAndRetry()
+	}
+
+	clientset, err := k8s.NewForConfig(config)
+	if err != nil {
+		color.Yellow("⚠️ Failed to create Kubernetes client: %v", err)
+		return promptForServiceKubeSettingsAndRetry()
+	}
+
+	namespace := "higress-system"
+	svc, err := clientset.CoreV1().Services(namespace).Get(context.Background(), "higress-gateway", metav1.GetOptions{})
+	if err != nil || svc == nil {
+		color.Yellow("⚠️ Could not find Higress Gateway Service in namespace '%s'.", namespace)
+		return promptForServiceKubeSettingsAndRetry()
+	}
+
+	ip, err := extractServiceIP(clientset, namespace, svc)
+	if err != nil {
+		return "", err
+	}
+
+	color.Green("✅ Found Higress Gateway Service IP: %s (namespace: %s)", ip, namespace)
+	return ip, nil
+}
+
+// higress-gateway should always be LoadBalancer
+func extractServiceIP(clientset *k8s.Clientset, namespace string, svc *v1.Service) (string, error) {
+	return svc.Spec.ClusterIP, nil
+
+	// // fallback to Pod IP
+	// if len(svc.Spec.Selector) > 0 {
+	// 	selector := metav1.FormatLabelSelector(&metav1.LabelSelector{MatchLabels: svc.Spec.Selector})
+	// 	pods, err := clientset.CoreV1().Pods(namespace).List(context.Background(), metav1.ListOptions{
+	// 		LabelSelector: selector,
+	// 	})
+	// 	if err != nil {
+	// 		return "", fmt.Errorf("failed to list pods for selector: %v", err)
+	// 	}
+	// 	if len(pods.Items) > 0 {
+	// 		return pods.Items[0].Status.PodIP, nil
+	// 	}
+	// }
+
+}
+
+// prompt fallback for user input
+func promptForServiceKubeSettingsAndRetry() (string, error) {
+	color.Cyan("Let's fix it manually 👇")
+
+	kubeconfigPrompt := promptui.Prompt{
+		Label:   "Enter kubeconfig path",
+		Default: filepath.Join(os.Getenv("HOME"), ".kube", "config"),
+	}
+	kubeconfigPath, err := kubeconfigPrompt.Run()
+	if err != nil {
+		return "", fmt.Errorf("aborted: %v", err)
+	}
+
+	nsPrompt := promptui.Prompt{
+		Label:   "Enter Higress namespace",
+		Default: "higress-system",
+	}
+	namespace, err := nsPrompt.Run()
+	if err != nil {
+		return "", err
+	}
+
+	config, err := clientcmd.BuildConfigFromFlags("", kubeconfigPath)
+	if err != nil {
+		return "", fmt.Errorf("failed to load kubeconfig: %v", err)
+	}
+
+	clientset, err := k8s.NewForConfig(config)
+	if err != nil {
+		return "", fmt.Errorf("failed to create kubernetes client: %v", err)
+	}
+
+	svc, err := clientset.CoreV1().Services(namespace).Get(context.Background(), "higress-gateway", metav1.GetOptions{})
+	if err != nil || svc == nil {
+		color.Red("❌ Higress Gateway Service not found in namespace '%s'", namespace)
+		return "", fmt.Errorf("service not found")
+	}
+
+	ip, err := extractServiceIP(clientset, namespace, svc)
+	if err != nil {
+		return "", err
+	}
+
+	color.Green("✅ Found Higress Gateway Service IP: %s (namespace: %s)", ip, namespace)
+	return ip, nil
+}

hgctl/pkg/root.go

@@ -17,6 +17,7 @@ package hgctl
 import (
 	"os"
 
+	"github.com/alibaba/higress/hgctl/pkg/agent"
 	"github.com/alibaba/higress/hgctl/pkg/plugin"
 	"github.com/spf13/cobra"
 )
@@ -42,6 +43,8 @@ func GetRootCommand() *cobra.Command {
 	rootCmd.AddCommand(plugin.NewCommand())
 	rootCmd.AddCommand(newCompletionCmd(os.Stdout))
 	rootCmd.AddCommand(newCodeDebugCmd())
+	rootCmd.AddCommand(agent.NewMCPCmd())
+	rootCmd.AddCommand(agent.NewAgentCmd())
 
 	return rootCmd
 }