GFast开发MCP服务器之mark3labs/mcp-go库接入（一）

kocie2025-04-30 9:47

这将是一个系列文章，我们将从简到繁开发一套基于GFast框架下MCP服务工具

github.com/mark3labs/mcp-go介绍

github.com/mark3labs/mcp-go 是一个基于 Go 语言实现的 Model Context Protocol (MCP) 的开源项目，旨在为大语言模型（LLM）与外部系统的交互提供标准化协议支持。以下是综合搜索结果的关键信息：

1. 项目功能与定位

  • 该项目实现了 MCP 协议的完整规范，提供 客户端和服务端能力，用于 LLM 与数据资源、工具的集成。例如，支持通过标准化方式暴露资源、提示词和工具，便于 LLM 调用外部 API 或执行操作。
  • 目前支持 stdio 和 SSE（Server-Sent Events） 作为传输协议，未来可能扩展其他通信方式（如 WebSocket 或 gRPC）。

2. 技术特点

  • Go 语言优势：与 Python 或 TypeScript 实现的 MCP SDK 相比，Go 版本强调强类型检查、高并发性能和简易部署，适合生产环境的高可靠性需求。
  • 模块化设计：分层架构（传输层、协议层、用户层）确保扩展性和维护性，开发者可自定义传输方式或协议扩展。

3. 与其他 MCP 实现的对比

  • ThinkInAI 的 Go-MCP（另一个 Go 实现）更注重生态建设（如 Marketplace 和工具链），而 mark3labs/mcp-go 目前功能更聚焦于协议基础实现。
  • Python/TypeScript SDK 动态语言的灵活性更高，但长期维护成本可能更高。

4. 安全与维护状态

  • 根据 GitHub 页面，该项目 未设置安全策略文件（SECURITY.md），且无公开的安全公告，需注意潜在风险。
  • 项目活跃度未明确提及，但代码示例和协议支持显示其具备实际可用性。

总结

mark3labs/mcp-go 是一个轻量级的 MCP 协议 Go 实现，适合需要高性能、强类型支持的 LLM 集成场景。若需更完整的生态工具（如服务发现、调试面板），可参考 ThinkInAI 的 Go-MCP 项目。建议进一步查阅其 GitHub 仓库的文档和示例以评估适用性。

MCP Server 的业务能力

Request Method 发起方 响应方 描述
initialized Client Server 初始化会话
tools-list Client Server 发现可用的工具
tools/call Client Server 调用工具
resources/list Client Server 发现可用的资源
resources/read Client Server 获取资源内容
resources/templates Client Server 发现可用的参数化资源
resources/subscribe Client Server 订阅特定资源，监听其变化事件
prompts/list Client Server 发现可用的提示词
prompts/get Client Server 获取特定提示词
roots/list Server Client 列出服务器有权访问的客户端文件系统根节点（暴露目录和文件）
sampling/create Server Client 启用服务器的 AI 生成能力（ sampling creation ）

一、简单的MCP服务器demo实现(stdio方式)

go 复制代码 
package main

import (
	"context" "errors" "fmt" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" ) func main() { // 创建MCP服务器 s := server.NewMCPServer( "Demo 🚀", // 服务器名称 "1.0.0", // 服务器版本 ) // 添加工具 tool := mcp.NewTool("hello_world", // 工具名称 mcp.WithDescription("Say hello to someone"), // 工具描述 mcp.WithString("name", // 参数名称 mcp.Required(), // 参数是必需的 mcp.Description("Name of the person to greet"), // 参数描述 ), ) // 为工具添加处理器 s.AddTool(tool, helloHandler) // 启动标准输入输出服务器 if err := server.ServeStdio(s); err != nil { fmt.Printf("Server error: %v\n", err) // 打印服务器错误 } } func helloHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { // 从请求参数中获取名字参数，并断言为字符串类型 name, ok := request.Params.Arguments["name"].(string) if !ok { // 如果断言失败，返回错误 return nil, errors.New("name must be a string") } // 返回包含问候语的结果 return mcp.NewToolResultText(fmt.Sprintf("Hello, %s!", name)), nil }

这段代码实现了一个简单的 MCP（Model Context Protocol）服务器，它通过标准输入/输出（stdio）与客户端交互，提供了一个名为 hello_world 的工具，用于向指定的人打招呼。以下是详细解析：

1. 核心功能

  • 工具注册：服务器注册了一个工具 hello_world，接收一个字符串参数 name，返回问候语。
  • 标准输入/输出通信：通过 stdio 与客户端交互（适合命令行或管道调用）。
  • 错误处理：验证参数类型，返回明确的错误信息。

2. 代码逐层解析

(1) 初始化 MCP 服务器

go 复制代码 
s := server.NewMCPServer( "Demo 🚀", // 服务器名称（显示标识） "1.0.0", // 服务器版本 )
  • 创建一个 MCP 服务器实例，指定名称和版本（用于元信息标识）。

(2) 定义工具 hello_world

go 复制代码 
tool := mcp.NewTool("hello_world", mcp.WithDescription("Say hello to someone"), // 工具功能描述 mcp.WithString("name", // 参数名 mcp.Required(), // 参数必填 mcp.Description("Name of the person to greet"), // 参数描述 ), )
  • 工具名称：hello_world。
  • 参数配置：
    • name：字符串类型，必填字段，描述为"Name of the person to greet"。
  • 通过 mcp.WithString 和链式方法声明参数约束。

(3) 注册工具处理器

go 复制代码 
s.AddTool(tool, helloHandler)
  • 将工具 hello_world 绑定到处理函数 helloHandler。

(4) 启动服务器

go 复制代码 
server.ServeStdio(s)
  • 启动标准输入/输出模式，监听来自客户端的请求。

(5) 工具处理函数 helloHandler

go 复制代码 
func helloHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { name, ok := request.Params.Arguments["name"].(string) // 获取参数 if !ok { return nil, errors.New("name must be a string") // 类型检查 } return mcp.NewToolResultText(fmt.Sprintf("Hello, %s!", name)), nil // 返回结果 }
  • 参数提取：从 request.Params.Arguments 中获取 name 参数，并验证是否为字符串。
  • 错误处理：若类型不符，返回错误。
  • 结果生成：使用 mcp.NewToolResultText 封装文本响应。

3. 数据流示例

客户端请求（JSON 输入）

json 复制代码 
{
  "tool": "hello_world", "params": { "arguments": { "name": "Alice" } } }

服务器响应

json 复制代码 
{
  "result": {
    "text": "Hello, Alice!" } }

错误场景（非字符串参数）

json 复制代码 
{
  "tool": "hello_world", "params": { "arguments": { "name": 123 } } }

响应错误：

text 复制代码 
name must be a string

4. 关键设计点

  1. 工具化架构
    • 每个功能（如问候）封装为独立工具，通过名称调用，支持灵活扩展。
  2. 强类型校验
    • 使用 Go 的类型断言确保参数合法性。
  3. 标准化协议
    • 输入/输出遵循 MCP 格式，兼容不同客户端（如 CLI、Web 前端）。
  4. 轻量级通信
    • stdio 模式无需网络依赖，适合集成到脚本或管道。

5. 如何运行？

  1. 编译服务器：

    bash 复制代码 
    $ go build -v -o server

  2. 再启动 mcp inspetor：（通过标准输入）：

    bash 复制代码 
    $ npx -y @modelcontextprotocol/inspector ./server

  3. 运行结果：

    点击connect:

    连接后可以列出相关工具，此时显示hello_world,可以进行run tool测试

二、简单的MCP服务器demo实现(同时支持stdio和SSE方式)

go 复制代码 
package main

import (
	"context" "encoding/json" "flag" "fmt" "io" "log" "net/http" "os" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" ) // authKey 是用于在context中存储认证令牌的自定义键类型 type authKey struct{} // withAuthKey 将认证令牌添加到context中 // ctx: 原始context // auth: 要存储的认证令牌 // 返回: 包含令牌的新context func withAuthKey(ctx context.Context, auth string) context.Context { return context.WithValue(ctx, authKey{}, auth) } // authFromRequest 从HTTP请求头中提取认证令牌并存入context // ctx: 原始context // r: HTTP请求对象 // 返回: 包含认证令牌的新context func authFromRequest(ctx context.Context, r *http.Request) context.Context { return withAuthKey(ctx, r.Header.Get("Authorization")) } // authFromEnv 从环境变量中提取认证令牌并存入context // ctx: 原始context // 返回: 包含认证令牌的新context func authFromEnv(ctx context.Context) context.Context { return withAuthKey(ctx, os.Getenv("API_KEY")) } // tokenFromContext 从context中提取认证令牌 // ctx: 包含令牌的context // 返回: 令牌字符串或错误(如果令牌不存在或类型不符) // 注意: 此方法不关心令牌来源(HTTP头或环境变量)，统一通过context获取 func tokenFromContext(ctx context.Context) (string, error) { auth, ok := ctx.Value(authKey{}).(string) if !ok { return "", fmt.Errorf("missing auth") } return auth, nil } // response 定义httpbin.org返回的数据结构 type response struct { Args map[string]interface{} `json:"args"` // 请求参数 Headers map[string]string `json:"headers"` // 请求头 } // makeRequest 向httpbin.org发起带认证的GET请求 // ctx: context对象(用于超时控制等) // message: 要发送的消息(会作为查询参数) // token: 认证令牌(会添加到请求头) // 返回: 响应数据或错误 func makeRequest(ctx context.Context, message, token string) (*response, error) { // 创建HTTP请求 req, err := http.NewRequestWithContext(ctx, "GET", "https://httpbin.org/anything", nil) if err != nil { return nil, fmt.Errorf("创建请求失败: %w", err) } // 设置认证头 req.Header.Set("Authorization", token) // 添加查询参数 query := req.URL.Query() query.Add("message", message) req.URL.RawQuery = query.Encode() // 发送请求 resp, err := http.DefaultClient.Do(req) if err != nil { return nil, fmt.Errorf("请求失败: %w", err) } defer resp.Body.Close() // 读取响应体 body, err := io.ReadAll(resp.Body) if err != nil { return nil, fmt.Errorf("读取响应失败: %w", err) } // 解析JSON响应 var r *response if err := json.Unmarshal(body, &r); err != nil { return nil, fmt.Errorf("解析JSON失败: %w", err) } return r, nil } // handleMakeAuthenticatedRequestTool 认证请求工具的处理函数 // ctx: 包含认证令牌的context // request: MCP工具调用请求 // 返回: 工具调用结果或错误 func handleMakeAuthenticatedRequestTool( ctx context.Context, request mcp.CallToolRequest, ) (*mcp.CallToolResult, error) { // 从请求参数中获取message参数 message, ok := request.Params.Arguments["message"].(string) if !ok { return nil, fmt.Errorf("缺少message参数或参数类型错误") } // 从context中提取认证令牌 token, err := tokenFromContext(ctx) if err != nil { return nil, fmt.Errorf("获取认证令牌失败: %w", err) } // 发起带认证的请求 resp, err := makeRequest(ctx, message, token) if err != nil { return nil, fmt.Errorf("执行请求失败: %w", err) } // 返回格式化后的响应 return mcp.NewToolResultText(fmt.Sprintf("%+v", resp)), nil } // MCPServer 封装MCP服务器的结构体 type MCPServer struct { server *server.MCPServer } // NewMCPServer 创建并配置MCP服务器实例 // 返回: 初始化好的MCPServer指针 func NewMCPServer() *MCPServer { // 创建基础服务器实例 mcpServer := server.NewMCPServer( "example-server", // 服务器名称 "1.0.0", // 服务器版本 server.WithResourceCapabilities(true, true), // 启用资源能力 server.WithPromptCapabilities(true), // 启用提示词能力 server.WithToolCapabilities(true), // 启用工具能力 ) // 注册认证请求工具 mcpServer.AddTool(mcp.NewTool("make_authenticated_request", mcp.WithDescription("执行带认证的HTTP请求"), // 工具描述 mcp.WithString("message", // 字符串参数 mcp.Description("要发送的消息内容"), // 参数描述 mcp.Required(), // 必填参数 ), ), handleMakeAuthenticatedRequestTool) return &MCPServer{ server: mcpServer, } } // ServeSSE 启动SSE模式的服务 // addr: 监听地址(如"localhost:8080") // 返回: SSEServer实例 func (s *MCPServer) ServeSSE(addr string) *server.SSEServer { return server.NewSSEServer(s.server, server.WithBaseURL(fmt.Sprintf("http://%s", addr)), // 基础URL server.WithSSEContextFunc(authFromRequest), // 使用请求头认证 ) } // ServeStdio 启动标准输入输出模式的服务 // 返回: 错误信息(如果有) func (s *MCPServer) ServeStdio() error { return server.ServeStdio(s.server, server.WithStdioContextFunc(authFromEnv), // 使用环境变量认证 ) } func main() { // 解析命令行参数 var transport string flag.StringVar(&transport, "t", "stdio", "传输协议类型(stdio或sse)") flag.StringVar(&transport, "transport", "stdio", "传输协议类型(stdio或sse)") flag.Parse() // 创建服务器实例 s := NewMCPServer() // 根据参数启动对应模式 switch transport { case "stdio": // 标准输入输出模式 if err := s.ServeStdio(); err != nil { log.Fatalf("服务器错误: %v", err) } case "sse": // SSE服务器模式 sseServer := s.ServeSSE("localhost:8080") log.Printf("SSE服务启动，监听 :8080 端口") if err := sseServer.Start(":8080"); err != nil { log.Fatalf("服务器错误: %v", err) } default: log.Fatalf("无效的传输协议: %s。必须是'stdio'或'sse'", transport) } }

这段代码实现了一个基于 MCP（Model Context Protocol） 的服务器，支持通过 SSE（Server-Sent Events） 或 标准输入/输出（stdio） 两种方式与客户端交互。以下是代码的详细解析：

1. 核心功能

  • 认证管理：从 HTTP 请求头或环境变量中提取认证令牌（Authorization），并通过上下文（context.Context）传递。
  • 工具调用：注册一个名为 make_authenticated_request 的工具，用于向外部 API（httpbin.org）发送带认证的请求。
  • 多传输协议支持：支持 SSE 和 stdio 两种通信方式（通过命令行参数切换）。

2. 代码结构解析

(1) 认证管理

  • authKey 类型：自定义的上下文键，用于存储认证令牌。
  • withAuthKey：将令牌注入上下文。
  • authFromRequest：从 HTTP 请求头提取 Authorization 字段并存入上下文。
  • authFromEnv：从环境变量 API_KEY 中读取令牌并存入上下文。
  • tokenFromContext：从上下文中提取令牌，供工具函数使用。

(2) 工具实现

  • makeRequest 函数：向 httpbin.org/anything 发送 GET 请求，附带认证令牌和查询参数 message，返回响应数据。
  • handleMakeAuthenticatedRequestTool：MCP 工具的核心逻辑：
    • 从请求参数中提取 message。
    • 从上下文中获取认证令牌。
    • 调用 makeRequest 发送请求，返回格式化后的响应。

(3) MCP 服务器配置

  • NewMCPServer：初始化 MCP 服务器：
    • 设置服务器名称和版本。
    • 启用资源、提示词和工具能力。
    • 注册工具 make_authenticated_request，绑定处理函数 handleMakeAuthenticatedRequestTool。
  • ServeSSE：启动 SSE 服务器，绑定认证函数 authFromRequest。
  • ServeStdio：启动 stdio 模式，从环境变量获取认证令牌。

(4) 主函数

  • 通过命令行参数 -t 选择传输协议（stdio 或 sse）。
    • stdio 模式：直接通过标准输入/输出交互（适合 CLI 或管道调用）。
    • sse 模式：启动 HTTP 服务（默认端口 8080），通过 SSE 协议通信。

3. 关键逻辑流程

  1. 客户端发起请求：
    • 若为 SSE 模式，HTTP 请求头需包含 Authorization。
    • 若为 stdio 模式，需设置环境变量 API_KEY。
  2. 认证令牌传递：
    • 服务器通过 authFromRequest 或 authFromEnv 提取令牌，存入上下文。
  3. 工具调用：
    • 客户端发送 MCP 格式的请求，指定工具名 make_authenticated_request 和参数 message。
    • 服务器调用 handleMakeAuthenticatedRequestTool，从上下文中获取令牌并发送到 httpbin.org。
  4. 返回结果：
    • 工具将 httpbin.org 的响应封装为 MCP 格式返回给客户端。

4. 示例用法

(1) SSE 模式

bash 复制代码 
# 启动服务器
go run main.go -t sse

# 客户端请求示例（使用 curl）
curl -N -H "Accept: text/event-stream" \  -H "Authorization: Bearer YOUR_TOKEN" \  -X POST \  -d '{"tool":"make_authenticated_request", "params":{"arguments":{"message":"hello"}}}' \  http://localhost:8080/mcp

(2) Stdio 模式

bash 复制代码 
# 设置环境变量并启动
export API_KEY="YOUR_TOKEN" go run main.go -t stdio # 通过标准输入发送请求（示例 JSON） echo '{"tool":"make_authenticated_request", "params":{"arguments":{"message":"hello"}}}' | go run main.go

5. 如何运行？

  1. 启动SSE服务器：

    bash 复制代码 
    $ go run sse.go -t sse

  2. 再启动 mcp inspetor：：

    bash 复制代码 
    $ npx -y @modelcontextprotocol/inspector

  3. 运行结果：

    连接后可以列出相关工具，此时显示make_authenticated_request,可以进行run tool测试

三、GFast 集成

在实际开发中，很多公司内部的业务有自己的框架，集成了许许多多的独特功能。总不能为了使用 MCP 重写一套 Web 框架，此时就需要使用到 mark3labs/mcp-go 集成到 Web 框架下。因GFast使用的是GoFrame框架，下面以 GoFrame 框架为例：

go 复制代码 
package main

import (
	"context" "errors" "fmt" "github.com/gogf/gf/v2/frame/g" "github.com/gogf/gf/v2/net/ghttp" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" ) func helloHandler2(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { // 从请求参数中获取名字参数，并断言为字符串类型 name, ok := request.Params.Arguments["name"].(string) if !ok { // 如果断言失败，返回错误 return nil, errors.New("name must be a string") } // 返回包含问候语的结果 return mcp.NewToolResultText(fmt.Sprintf("Hello, %s!", name)), nil } func main() { // 创建一个新的 MCPServer 实例（假设这是 SSEServer 所需的） mcpServer := server.NewMCPServer("gf-mcp-server", "1.0.0") // 根据你的实际代码调整 // mcpServer 新加Tool、Resource、Prompt // 添加工具 tool := mcp.NewTool("hello_world", // 工具名称 mcp.WithDescription("Say hello to someone"), // 工具描述 mcp.WithString("name", // 参数名称 mcp.Required(), // 参数是必需的 mcp.Description("Name of the person to greet"), // 参数描述 ), ) // 为工具添加处理器 mcpServer.AddTool(tool, helloHandler2) // 创建一个新的 SSEServer 实例，并传入 MCPServer sseServer := server.NewSSEServer(mcpServer) s := g.Server() // 将 SSEServer 的 SSE 端点和处理函数集成到 GoFrame 路由中 s.BindHandler(sseServer.CompleteSsePath(), func(r *ghttp.Request) { sseServer.ServeHTTP(r.Response.Writer, r.Request) }) // 将 SSEServer 的消息端点和处理函数集成到 GoFrame 路由中 s.BindHandler(sseServer.CompleteMessagePath(), func(r *ghttp.Request) { sseServer.ServeHTTP(r.Response.Writer, r.Request) }) s.SetPort(8000) s.Run() }

运行

  1. 启动SSE服务器：

    bash 复制代码 
    $ go run main.go

    此时MCPServer 请求响应将被GoFrame接管，并绑定如下路由：

  2. 再启动 mcp inspetor：：

    bash 复制代码 
    $ npx -y @modelcontextprotocol/inspector

  3. 运行结果：

    连接后可以列出相关工具，此时显示hello_world工具,可以进行run tool测试

热门推荐
01KGG转MP3工具|非KGM文件|解密音频02从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑03西电B测-计算机网络综合实验(含验收问题)04Coze扣子平台完整体验和实践（附国内和国际版对比）05YOLOv8入门 | 重要性能衡量指标、训练结果评价及分析及影响mAP的因素【发论文关注的指标】06DeepSeek各版本说明与优缺点分析07Python基于Flask的豆瓣电影数据分析可视化系统（附源码，文档说明）08yolov8，yolo11，yolo12 服务器训练到部署全流程 笔记09我决定放弃搞 Java 了10【VIsion Master】机器视觉软件二次开发（C#版本）学习笔记