Go-MCP

简体中文 | 繁體中文 | Tiếng Việt

🚀 概述

Go-MCP 是一个功能强大的 Go 版本 MCP SDK，实现了模型上下文协议（MCP），以促进外部系统与 AI 应用程序之间的无缝通信。基于 Go 语言的强类型和高性能优势，它提供了一个简洁且符合惯用风格的 API，方便您将外部系统集成到 AI 应用程序中。

✨ 核心特性

• 🔄 完整的协议实现：全面实现 MCP 规范，确保与所有兼容服务的无缝集成
• 🏗️ 优雅的架构设计：采用清晰的三层架构，支持双向通信，确保代码模块化和可扩展性
• 🔌 与 Web 框架的无缝集成：提供符合 MCP 协议的 http.Handler，使开发者能够将 MCP 集成到其服务框架中
• 🛡️ 类型安全：利用 Go 的强类型系统，编写清晰且易于维护的代码
• 📦 简单的部署：受益于 Go 的静态编译特性，无需复杂的依赖管理
• ⚡ 高性能设计：充分利用 Go 的并发能力，在各种场景下保持出色的性能和较低的资源开销

🛠️ 安装

go get github.com/ThinkInAIXYZ/go-mcp

需要 Go 1.18 或更高版本。

🎯 快速入门

客户端示例

package main

import (
	"context"
	"log"

	"github.com/ThinkInAIXYZ/go-mcp/client"
	"github.com/ThinkInAIXYZ/go-mcp/transport"
)

func main() {
	// 创建 SSE 传输客户端
	transportClient, err := transport.NewSSEClientTransport("http://127.0.0.1:8080/sse")
	if err != nil {
		log.Fatalf("创建传输客户端失败: %v", err)
	}

	// 初始化 MCP 客户端
	mcpClient, err := client.NewClient(transportClient)
	if err != nil {
		log.Fatalf("创建 MCP 客户端失败: %v", err)
	}
	defer mcpClient.Close()

	// 获取可用工具
	tools, err := mcpClient.ListTools(context.Background())
	if err != nil {
		log.Fatalf("列出工具失败: %v", err)
	}
	log.Printf("可用工具: %+v", tools)
}

服务器示例

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/ThinkInAIXYZ/go-mcp/protocol"
	"github.com/ThinkInAIXYZ/go-mcp/server"
	"github.com/ThinkInAIXYZ/go-mcp/transport"
)

type TimeRequest struct {
	Timezone string `json:"timezone" description:"时区" required:"true"` // 使用字段标签描述输入模式
}

func main() {
	// 创建 SSE 传输服务器
	transportServer, err := transport.NewSSEServerTransport("127.0.0.1:8080")
	if err != nil {
		log.Fatalf("创建传输服务器失败: %v", err)
	}

	// 初始化 MCP 服务器
	mcpServer, err := server.NewServer(transportServer)
	if err != nil {
		log.Fatalf("创建 MCP 服务器失败: %v", err)
	}
	
	// 可选：全局中间件（可变参数 - 支持多个中间件）
	// mcpServer.Use(
	// 	LoggingMiddleware,
	// 	AuthMiddleware,
	// 	MetricsMiddleware,
	// )

	// 注册时间查询工具
	tool, err := protocol.NewTool("current_time", "获取指定时区的当前时间", TimeRequest{})
	if err != nil {
		log.Fatalf("创建工具失败: %v", err)
		return
	}
	mcpServer.RegisterTool(tool, handleTimeRequest)

	// 启动服务器
	if err = mcpServer.Run(); err != nil {
		log.Fatalf("服务器启动失败: %v", err)
	}
}

func handleTimeRequest(ctx context.Context, req *protocol.CallToolRequest) (*protocol.CallToolResult, error) {
	var timeReq TimeRequest
	if err := protocol.VerifyAndUnmarshal(req.RawArguments, &timeReq); err != nil {
		return nil, err
	}

	loc, err := time.LoadLocation(timeReq.Timezone)
	if err != nil {
		return nil, fmt.Errorf("无效的时区: %v", err)
	}

	return &protocol.CallToolResult{
		Content: []protocol.Content{
			&protocol.TextContent{
				Type: "text",
				Text: time.Now().In(loc).String(),
			},
		},
	}, nil
}

与 Gin 服务器的集成

package main

import (
	"context"
	"log"

	"github.com/ThinkInAIXYZ/go-mcp/protocol"
	"github.com/ThinkInAIXYZ/go-mcp/server"
	"github.com/ThinkInAIXYZ/go-mcp/transport"
	"github.com/gin-gonic/gin"
)

func main() {
	messageEndpointURL := "/message"

	sseTransport, mcpHandler, err := transport.NewSSEServerTransportAndHandler(messageEndpointURL)
	if err != nil {
		log.Panicf("new sse transport and hander with error: %v", err)
	}

	// 新建 MCP 服务器
	mcpServer, _ := server.NewServer(sseTransport)

	// 将工具注册到 mcpServer 中
	// mcpServer.RegisterTool(tool, toolHandler)

	// 启动 MCP 服务器
	go func() {
		mcpServer.Run()
	}()

	defer mcpServer.Shutdown(context.Background())

	r := gin.Default()
	r.GET("/sse", func(ctx *gin.Context) {
		mcpHandler.HandleSSE().ServeHTTP(ctx.Writer, ctx.Request)
	})
	r.POST(messageEndpointURL, func(ctx *gin.Context) {
		mcpHandler.HandleMessage().ServeHTTP(ctx.Writer, ctx.Request)
	})

	if err = r.Run(":8080"); err != nil {
		return
	}
}

参考：更完整的示例

🏗️ 架构设计

Go-MCP 采用优雅的三层架构：

1. 传输层：负责底层通信实现，支持多种传输协议。
2. 协议层：负责 MCP 协议的编码/解码以及数据结构定义。
3. 用户层：提供友好的客户端和服务器 API。

目前支持的传输方式如下：

• HTTP SSE/POST：基于 HTTP 的服务器推送和客户端请求，适用于 Web 场景。
• 可流式 HTTP：支持无状态和有状态两种模式的 HTTP POST/GET 请求，其中有状态模式利用 SSE 进行多消息流式传输，以实现服务器到客户端的通知和请求。
• Stdio：基于标准输入输出流，适用于本地进程间通信。

传输层使用统一的接口抽象，使得添加新的传输方式（如可流式 HTTP、WebSocket、gRPC）变得简单，而不会影响上层代码。

🤝 贡献

我们欢迎任何形式的贡献！详情请参阅 CONTRIBUTING.md。

📄 许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

📞 联系我们

• GitHub Issues：提交问题
• Discord：点击这里加入我们的用户群
• 微信交流群：

✨ 贡献者

感谢所有为本项目做出贡献的开发者！

📈 项目趋势

go-mcp 快速上手指南

go-mcp 是一个基于 Go 语言实现的 Model Context Protocol (MCP) SDK，旨在利用 Go 的强类型和高性能特性，帮助开发者轻松将外部系统集成到 AI 应用中。

环境准备

• 操作系统：支持 Linux、macOS、Windows
• Go 版本：要求 Go 1.18 或更高版本
• 依赖管理：项目使用 Go Modules 进行依赖管理

安装步骤

在您的 Go 项目目录中，执行以下命令安装 go-mcp：

go get github.com/ThinkInAIXYZ/go-mcp

提示：如果下载速度较慢，可配置国内 GOPROXY 加速：

export GOPROXY=https://goproxy.cn,direct

基本使用

go-mcp 支持快速构建 MCP 服务端和客户端。以下是两个最基础的使用示例。

1. 构建 MCP 服务端 (Server)

以下示例创建一个基于 SSE (Server-Sent Events) 传输的服务端，并注册一个查询时间的工具。

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/ThinkInAIXYZ/go-mcp/protocol"
	"github.com/ThinkInAIXYZ/go-mcp/server"
	"github.com/ThinkInAIXYZ/go-mcp/transport"
)

// 定义请求结构体，利用 Tag 描述输入 schema
type TimeRequest struct {
	Timezone string `json:"timezone" description:"timezone" required:"true"`
}

func main() {
	// 创建 SSE 传输服务端
	transportServer, err := transport.NewSSEServerTransport("127.0.0.1:8080")
	if err != nil {
		log.Fatalf("Failed to create transport server: %v", err)
	}

	// 初始化 MCP 服务端
	mcpServer, err := server.NewServer(transportServer)
	if err != nil {
		log.Fatalf("Failed to create MCP server: %v", err)
	}

	// 注册工具：current_time
	tool, err := protocol.NewTool("current_time", "Get current time for specified timezone", TimeRequest{})
	if err != nil {
		log.Fatalf("Failed to create tool: %v", err)
	}
	mcpServer.RegisterTool(tool, handleTimeRequest)

	// 启动服务
	log.Println("Starting MCP server on :8080")
	if err = mcpServer.Run(); err != nil {
		log.Fatalf("Server failed to start: %v", err)
	}
}

// 工具处理函数
func handleTimeRequest(ctx context.Context, req *protocol.CallToolRequest) (*protocol.CallToolResult, error) {
	var timeReq TimeRequest
	// 验证并反序列化参数
	if err := protocol.VerifyAndUnmarshal(req.RawArguments, &timeReq); err != nil {
		return nil, err
	}

	loc, err := time.LoadLocation(timeReq.Timezone)
	if err != nil {
		return nil, fmt.Errorf("invalid timezone: %v", err)
	}

	return &protocol.CallToolResult{
		Content: []protocol.Content{
			&protocol.TextContent{
				Type: "text",
				Text: time.Now().In(loc).String(),
			},
		},
	}, nil
}

2. 构建 MCP 客户端 (Client)

以下示例展示如何连接上述服务端并调用已注册的工具。

package main

import (
	"context"
	"log"

	"github.com/ThinkInAIXYZ/go-mcp/client"
	"github.com/ThinkInAIXYZ/go-mcp/transport"
)

func main() {
	// 创建 SSE 传输客户端
	transportClient, err := transport.NewSSEClientTransport("http://127.0.0.1:8080/sse")
	if err != nil {
		log.Fatalf("Failed to create transport client: %v", err)
	}

	// 初始化 MCP 客户端
	mcpClient, err := client.NewClient(transportClient)
	if err != nil {
		log.Fatalf("Failed to create MCP client: %v", err)
	}
	defer mcpClient.Close()

	// 获取可用工具列表
	tools, err := mcpClient.ListTools(context.Background())
	if err != nil {
		log.Fatalf("Failed to list tools: %v", err)
	}
	log.Printf("Available tools: %+v", tools)
	
	// 此处可继续调用 mcpClient.CallTool(...) 执行具体工具
}

3. 集成 Gin Web 框架 (可选)

如果您需要将 MCP 服务集成到现有的 Gin 项目中，可以使用 NewSSEServerTransportAndHandler：

// 片段示例
sseTransport, mcpHandler, err := transport.NewSSEServerTransportAndHandler("/message")
// ... 初始化 mcpServer ...

r := gin.Default()
// 绑定 SSE 端点
r.GET("/sse", func(ctx *gin.Context) {
	mcpHandler.HandleSSE().ServeHTTP(ctx.Writer, ctx.Request)
})
// 绑定消息端点
r.POST("/message", func(ctx *gin.Context) {
	mcpHandler.HandleMessage().ServeHTTP(ctx.Writer, ctx.Request)
})

r.Run(":8080")