• mcp协议理解
• mcp server生产级部署方案
  • 如何支持集群部署
  • 如何和hertz结合。
  • 如何支持header中加k/v
• Agent如何集成MCP

StreamableHttp 介绍

• 标准同步模式：Content-Type: application/json，立即返回完整响应
• 流式模式：Content-Type: text/event-stream，当需要发送通知时升级为SSE流。

• 【客户端】根据response content_type自动识别SSE，如果是sse则将流式结果全部处理完成之后在封装成mcp.ToolCallResul

业务接口是一个SSE 流式接口如何封装成一个Tool

2.3.3 Stdio Server

使用场景

1. 命令行工具

• CLI 实用程序，可被 LLM 调用
• 本地开发和测试 MCP 实现
• 系统管理工具

• IDE 插件和文本编辑器扩展
• 本地生产力工具
• 文件系统浏览器

• 父进程管理 MCP 服务器
• 进程级隔离和安全性
• 单用户场景

搭建Stdio Server

客户端使用Stdio Server

2.5 集成hertz

使用 hertz最新版本提供的工具类adaptor.HertzHandler 来集成MCP Server。

2.5.1 Streamable Http Server + Hertz

• 提示词
  // 提示词 const ( // 构建专门用于工具判断的提示词 toolDetectionPrompt = ` ## 任务 你是一个AI的助手，可以调用工具解决问题。你需要根据用户的问题、历史对话和工具执行结果，给出完整、友好的回答。如果需要多轮调用工具才能完成任务，请继续调用，直到可以给出最终答案 ## 可用的工具包括： - calculate: 执行数学乘积 { "need_tool": true, "tool_name": "calculate", "server_path": "./mcp-server", "desc": "执行数学运算（加、减、乘、除）", "parameters": { "left_param": "左值", "right_param": "右值" } } ## LLM输出样式 请确保只返回 JSON，不要添加任何其他解释,分为如下两个场景: - 如果需要调用工具，请以以下 JSON 格式回复： { "need_tool": true, "tool_name": "calculate", "parameters": { "left_param": "左值", "right_param": "右值" } } - 如果不需要调用工具或有最终答案，请以下 JSON 格式回复，其中result表示LLM最终的结果： { "need_tool": false, "result": "xx" } ## 工具返回结果遵循JSON-RPC 2.0协议协议 比如调用calculate工具返回结果为： { "jsonrpc": "2.0", "result": { "content": [{ "type": "text", "text": "{ \"value\": 2 }" }] } } ` )

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53

  // 提示词 const (    // 构建专门用于工具判断的提示词    toolDetectionPrompt = ` ## 任务 你是一个AI的助手，可以调用工具解决问题。你需要根据用户的问题、历史对话和工具执行结果，给出完整、友好的回答。如果需要多轮调用工具才能完成任务，请继续调用，直到可以给出最终答案   ## 可用的工具包括： - calculate: 执行数学乘积 {     "need_tool": true,     "tool_name": "calculate",     "server_path": "./mcp-server",     "desc": "执行数学运算（加、减、乘、除）",     "parameters": {         "left_param": "左值",         "right_param": "右值"     } }     ## LLM输出样式 请确保只返回 JSON，不要添加任何其他解释,分为如下两个场景: - 如果需要调用工具，请以以下 JSON 格式回复： {     "need_tool": true,     "tool_name": "calculate",     "parameters": {         "left_param": "左值",         "right_param": "右值"     } }   - 如果不需要调用工具或有最终答案，请以下 JSON 格式回复，其中result表示LLM最终的结果： {     "need_tool": false,     "result": "xx" }   ## 工具返回结果遵循JSON-RPC 2.0协议协议 比如调用calculate工具返回结果为： {    "jsonrpc": "2.0",    "result": {       "content": [{          "type": "text",          "text": "{ \"value\": 2 }"       }]    } } `   )

• • 执行流程
    / 消息角色常量 const ( RoleSystem = "system" // 系统指令和提示 RoleUser = "user" // 用户输入 RoleAssistant = "assistant" // AI 助手的回复 RoleTool = "tool" // 工具执行结果 ) // McpAgentExecute 功能包括：根据LLM获取 工具name和参数 ；执行MCP工具； 根据工具返回内容构建Context // userQuery := "请计算 135 乘以 28 等于多少？然后告诉我结果的平方是多少？" func McpAgentExecute(userQuery string) { // 1. 如果需要工具，则调用相应的工具 conversationHistory := []doubao.DoubaoMessage{} conversationHistory = append(conversationHistory, doubao.DoubaoMessage{Role: RoleSystem, Content: toolDetectionPrompt}, doubao.DoubaoMessage{Role: RoleUser, Content: userQuery}, ) // 2.设置一个最大循环次数，避免无限制循环 maxIterations := 5 for iteration := 0; iteration < maxIterations; iteration++ { logs.Info("===== 第%v轮对话历史=======", iteration+1) toolCall, err := callLLM(conversationHistory) if err != nil { log.Printf("工具判断失败: %v", err) break } if toolCall.NeedTool { toolResult, err := callMcpTool(toolCall) if err != nil { log.Printf("调用工具失败: %v", err) break } else { log.Printf("工具执行结果: %v", toolResult) // 将工具结果添加到对话历史. 这里遇到一个问题，如果设置role为tool，LLM返回就会报错了 conversationHistory = append(conversationHistory, doubao.DoubaoMessage{Role: RoleUser, Content: "工具执行结果: " + toolResult}, ) } } else { logs.Info("最终结果: %s", toolCall.Result) break } } logs.Info("===== 最终对话历史=======") time.Sleep(1 * time.Second) } // callLLM 调用LLM: 识别工具 func callLLM(conversationHistory []doubao.DoubaoMessage) (ToolCall, error) { // 调用豆包 API response, err := doubao.ChatSync(context.Background(), conversationHistory) // 尝试解析 JSON toolCall := ToolCall{} if err != nil { toolCall.NeedTool = false return toolCall, fmt.Errorf("调用豆包 API 失败: %v", err) } if len(response.Choices) == 0 { toolCall.NeedTool = false return toolCall, errors.New("response.Choices为空") } // 解析模型回复 reply := response.Choices[0].Message.Content if err := json.Unmarshal([]byte(reply), &toolCall); err != nil { // 如果无法解析为 JSON，假设不需要工具 log.Printf("无法解析模型回复为 JSON: %v, 回复内容: %s", err, reply) toolCall.NeedTool = false return toolCall, errors.New("无法解析模型回复") } return toolCall, nil } func callMcpTool(toolCall ToolCall) (string, error) { leftParam := toolCall.Parameters["left_param"].(string) rightParam := toolCall.Parameters["right_param"].(string) left, _ := strconv.ParseInt(leftParam, 10, 64) right, _ := strconv.ParseInt(rightParam, 10, 64) value := left * right valuleResult := map[string]interface{}{ "value": value, } valueStr, _ := json.Marshal(valuleResult) cItem := []ContentItem{{ Type: "text", Text: string(valueStr), }, } toolResult := &ToolResult{ JSONRPC: "2.0", Result: ResponseResult{ Content: cItem, }, } toolResultStr, _ := json.Marshal(toolResult) return string(toolResultStr), nil } // 工具调用结构 type ToolCall struct { NeedTool bool `json:"need_tool"` ToolName string `json:"tool_name"` Description string `json:"description"` Parameters map[string]interface{} `json:"parameters"` ServerPath string `json:"server_path"` Result string `json:"result"` } type ToolResult struct { JSONRPC string `json:"jsonrpc"` // JSON-RPC版本，固定为"2.0" ID int `json:"id"` // 请求ID，与请求中的ID对应 Result ResponseResult `json:"result"` // 响应结果 } // ResponseResult 表示响应中的result字段 type ResponseResult struct { Content []ContentItem `json:"content"` // 内容数组 } // ContentItem 表示content数组中的每个元素 type ContentItem struct { Type string `json:"type"` // 内容类型，如"text" Text string `json:"text"` // 内容文本，这里是一个JSON字符串 }

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141

    / 消息角色常量 const (    RoleSystem    = "system"    // 系统指令和提示    RoleUser      = "user"      // 用户输入    RoleAssistant = "assistant" // AI 助手的回复    RoleTool      = "tool"      // 工具执行结果 )       // McpAgentExecute 功能包括：根据LLM获取 工具name和参数 ；执行MCP工具； 根据工具返回内容构建Context // userQuery := "请计算 135 乘以 28 等于多少？然后告诉我结果的平方是多少？" func McpAgentExecute(userQuery string) {      // 1. 如果需要工具，则调用相应的工具    conversationHistory := []doubao.DoubaoMessage{}    conversationHistory = append(conversationHistory,       doubao.DoubaoMessage{Role: RoleSystem, Content: toolDetectionPrompt},       doubao.DoubaoMessage{Role: RoleUser, Content: userQuery},    )      // 2.设置一个最大循环次数，避免无限制循环    maxIterations := 5    for iteration := 0; iteration < maxIterations; iteration++ {       logs.Info("===== 第%v轮对话历史=======", iteration+1)       toolCall, err := callLLM(conversationHistory)       if err != nil {          log.Printf("工具判断失败: %v", err)          break       }       if toolCall.NeedTool {          toolResult, err := callMcpTool(toolCall)          if err != nil {             log.Printf("调用工具失败: %v", err)             break          } else {             log.Printf("工具执行结果: %v", toolResult)             // 将工具结果添加到对话历史. 这里遇到一个问题，如果设置role为tool，LLM返回就会报错了             conversationHistory = append(conversationHistory,                doubao.DoubaoMessage{Role: RoleUser, Content: "工具执行结果: " + toolResult},             )          }       } else {          logs.Info("最终结果: %s", toolCall.Result)          break       }      }      logs.Info("===== 最终对话历史=======")    time.Sleep(1 * time.Second)   }   // callLLM 调用LLM: 识别工具 func callLLM(conversationHistory []doubao.DoubaoMessage) (ToolCall, error) {      // 调用豆包 API    response, err := doubao.ChatSync(context.Background(), conversationHistory)    // 尝试解析 JSON    toolCall := ToolCall{}      if err != nil {       toolCall.NeedTool = false       return toolCall, fmt.Errorf("调用豆包 API 失败: %v", err)    }      if len(response.Choices) == 0 {       toolCall.NeedTool = false       return toolCall, errors.New("response.Choices为空")    }      // 解析模型回复    reply := response.Choices[0].Message.Content      if err := json.Unmarshal([]byte(reply), &toolCall); err != nil {       // 如果无法解析为 JSON，假设不需要工具       log.Printf("无法解析模型回复为 JSON: %v, 回复内容: %s", err, reply)       toolCall.NeedTool = false       return toolCall, errors.New("无法解析模型回复")    }      return toolCall, nil }   func callMcpTool(toolCall ToolCall) (string, error) {    leftParam := toolCall.Parameters["left_param"].(string)    rightParam := toolCall.Parameters["right_param"].(string)      left, _ := strconv.ParseInt(leftParam, 10, 64)    right, _ := strconv.ParseInt(rightParam, 10, 64)      value := left * right      valuleResult := map[string]interface{}{       "value": value,    }    valueStr, _ := json.Marshal(valuleResult)    cItem := []ContentItem{{       Type: "text",       Text: string(valueStr),    },    }    toolResult := &ToolResult{       JSONRPC: "2.0",       Result: ResponseResult{          Content: cItem,       },    }      toolResultStr, _ := json.Marshal(toolResult)    return string(toolResultStr), nil }   // 工具调用结构 type ToolCall struct {    NeedTool    bool                   `json:"need_tool"`    ToolName    string                 `json:"tool_name"`    Description string                 `json:"description"`    Parameters  map[string]interface{} `json:"parameters"`    ServerPath  string                 `json:"server_path"`    Result      string                 `json:"result"` }   type ToolResult struct {    JSONRPC string         `json:"jsonrpc"` // JSON-RPC版本，固定为"2.0"    ID      int            `json:"id"`      // 请求ID，与请求中的ID对应    Result  ResponseResult `json:"result"`  // 响应结果   }   // ResponseResult 表示响应中的result字段 type ResponseResult struct {    Content []ContentItem `json:"content"` // 内容数组 }   // ContentItem 表示content数组中的每个元素 type ContentItem struct {    Type string `json:"type"` // 内容类型，如"text"    Text string `json:"text"` // 内容文本，这里是一个JSON字符串 }

  • • 调用豆包接口，可以参考方舟平台demo封装下如下
      // ChatSync 同步接口 func ChatSync(ctx context.Context, messages []DoubaoMessage) (*DoubaoResponse, error) { // 定义请求的URL url := domain + chat_url // 定义请求体 requestBody := DoubaoRequest{ Model: model_id, Messages: messages, } // 将请求体转换为JSON格式 jsonBody, err := json.Marshal(requestBody) if err != nil { logs.CtxError(ctx, "json.Marshal:%v", err) return nil, err } // 创建HTTP请求 req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonBody)) if err != nil { logs.CtxError(ctx, "NewRequest:%v", err) return nil, err } // 设置请求头 req.Header.Set("Content-Type", "application/json") req.Header.Set("Authorization", "Bearer "+api_key) // 发送HTTP请求 client := &http.Client{} resp, err := client.Do(req) if err != nil { logs.CtxError(ctx, "Response:%v", err) return nil, err } defer resp.Body.Close() // 读取响应 doubResponse := &DoubaoResponse{} err = json.NewDecoder(resp.Body).Decode(doubResponse) if err != nil { logs.CtxError(ctx, "Response:%v", err) return nil, err } // 打印响应 logs.CtxInfo(ctx, "Response:%v", doubResponse) // 提取响应中的内容 return doubResponse, nil } type DoubaoResponse struct { Choices []struct { Message DoubaoMessage `json:"message"` FinishReason string `json:"finish_reason"` } `json:"choices"` } // 定义与豆包 API 交互所需的数据结构 type DoubaoMessage struct { Role string `json:"role"` Content string `json:"content"` } type DoubaoRequest struct { Model string `json:"model"` // 例如 "doubao-1-5-pro-256k" Messages []DoubaoMessage `json:"messages"` Stream bool `json:"stream"` }

      1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71

      // ChatSync 同步接口 func ChatSync(ctx context.Context, messages []DoubaoMessage) (*DoubaoResponse, error) {    // 定义请求的URL    url := domain + chat_url      // 定义请求体    requestBody := DoubaoRequest{       Model:    model_id,       Messages: messages,    }      // 将请求体转换为JSON格式    jsonBody, err := json.Marshal(requestBody)    if err != nil {       logs.CtxError(ctx, "json.Marshal:%v", err)       return nil, err    }      // 创建HTTP请求    req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonBody))    if err != nil {       logs.CtxError(ctx, "NewRequest:%v", err)       return nil, err    }      // 设置请求头    req.Header.Set("Content-Type", "application/json")    req.Header.Set("Authorization", "Bearer "+api_key)      // 发送HTTP请求    client := &http.Client{}    resp, err := client.Do(req)    if err != nil {       logs.CtxError(ctx, "Response:%v", err)       return nil, err    }    defer resp.Body.Close()      // 读取响应    doubResponse := &DoubaoResponse{}    err = json.NewDecoder(resp.Body).Decode(doubResponse)    if err != nil {       logs.CtxError(ctx, "Response:%v", err)       return nil, err    }      // 打印响应    logs.CtxInfo(ctx, "Response:%v", doubResponse)      // 提取响应中的内容    return doubResponse, nil }   type DoubaoResponse struct {    Choices []struct {       Message      DoubaoMessage `json:"message"`       FinishReason string        `json:"finish_reason"`    } `json:"choices"` }   // 定义与豆包 API 交互所需的数据结构 type DoubaoMessage struct {    Role    string `json:"role"`    Content string `json:"content"` }   type DoubaoRequest struct {    Model    string          `json:"model"` // 例如 "doubao-1-5-pro-256k"    Messages []DoubaoMessage `json:"messages"`    Stream   bool            `json:"stream"` }

    • • 测试: