MCP 服务器

Golang MCP Server SDK

FreePeak

开发者工具

访问服务器

README

Golang MCP 服务器 SDK

概述

模型上下文协议 (Model Context Protocol) 允许应用程序以标准化的方式为 LLM 提供上下文，将提供上下文的关注点与实际的 LLM 交互分离。这个 Golang SDK 实现了完整的 MCP 规范，使其易于：

构建暴露资源和工具的 MCP 服务器
使用标准传输方式，如 stdio 和服务器发送事件 (SSE)
处理所有 MCP 协议消息和生命周期事件
遵循 Go 最佳实践和清晰的架构原则

注意: 此 SDK 始终更新，以与 spec.modelcontextprotocol.io/latest 的最新 MCP 规范保持一致。

安装

go get github.com/FreePeak/golang-mcp-server-sdk

快速开始

让我们创建一个简单的 MCP 服务器，它暴露一个 echo 工具：

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/FreePeak/golang-mcp-server-sdk/pkg/server"
	"github.com/FreePeak/golang-mcp-server-sdk/pkg/tools"
)

func main() {
	// 创建服务器
	mcpServer := server.NewMCPServer("Echo Server Example", "1.0.0")

	// 创建一个 echo 工具
	echoTool := tools.NewTool("echo",
		tools.WithDescription("Echoes back the input message"),
		tools.WithString("message",
			tools.Description("The message to echo back"),
			tools.Required(),
		),
	)

	// 将工具添加到服务器并添加处理程序
	ctx := context.Background()
	err := mcpServer.AddTool(ctx, echoTool, handleEcho)
	if err != nil {
		log.Fatalf("Error adding tool: %v", err)
	}

	// 启动服务器
	fmt.Println("Starting Echo Server...")
	fmt.Println("Send JSON-RPC messages via stdin to interact with the server.")
	
	// 通过 stdio 提供服务
	if err := mcpServer.ServeStdio(); err != nil {
		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
		os.Exit(1)
	}
}

// Echo 工具处理程序
func handleEcho(ctx context.Context, request server.ToolCallRequest) (interface{}, error) {
	// 提取 message 参数
	message, ok := request.Parameters["message"].(string)
	if !ok {
		return nil, fmt.Errorf("missing or invalid 'message' parameter")
	}

	// 以 MCP 协议期望的格式返回 echo 响应
	return map[string]interface{}{
		"content": []map[string]interface{}{
			{
				"type": "text",
				"text": message,
			},
		},
	}, nil
}

什么是 MCP？

模型上下文协议 (MCP) 是一种标准化协议，允许应用程序以安全有效的方式为 LLM 提供上下文。它将提供上下文和工具的关注点与实际的 LLM 交互分离。 MCP 服务器可以：

通过资源暴露数据（只读数据端点）
通过工具提供功能（可执行函数）
通过 提示词 定义交互模式（可重用模板）
支持各种传输方法（stdio、HTTP/SSE）

核心概念

服务器

MCP 服务器是您与 MCP 协议的核心接口。它处理连接管理、协议合规性和消息路由：

// 创建一个新的 MCP 服务器
mcpServer := server.NewMCPServer("My App", "1.0.0")

工具

工具让 LLM 通过您的服务器执行操作。与资源不同，工具需要执行计算并具有副作用：

// 定义一个计算器工具
calculatorTool := tools.NewTool("calculator",
    tools.WithDescription("Performs basic arithmetic"),
    tools.WithString("operation",
        tools.Description("The operation to perform (add, subtract, multiply, divide)"),
        tools.Required(),
    ),
    tools.WithNumber("a", 
        tools.Description("First number"),
        tools.Required(),
    ),
    tools.WithNumber("b",
        tools.Description("Second number"),
        tools.Required(),
    ),
)

// 将工具添加到服务器并添加处理程序
mcpServer.AddTool(ctx, calculatorTool, handleCalculator)

资源

资源是您向 LLM 暴露数据的方式。它们类似于 REST API 中的 GET 端点 - 它们提供数据，但不应执行重要的计算或具有副作用：

// 创建一个资源 (当前使用内部 API)
resource := &domain.Resource{
    URI:         "sample://hello-world",
    Name:        "Hello World Resource",
    Description: "A sample resource for demonstration purposes",
    MIMEType:    "text/plain",
}

// 注意：资源支持正在公共 API 中更新

提示词

提示词是可重用的模板，可帮助 LLM 有效地与您的服务器交互：

// 创建一个提示词 (当前使用内部 API)
codeReviewPrompt := &domain.Prompt{
    Name:        "review-code",
    Description: "A prompt for code review",
    Template:    "Please review this code:\n\n{{.code}}",
    Parameters: []domain.PromptParameter{
        {
            Name:        "code",
            Description: "The code to review",
            Type:        "string",
            Required:    true,
        },
    },
}

// 注意：提示词支持正在公共 API 中更新

运行你的服务器

Go 中的 MCP 服务器可以根据您的用例连接到不同的传输方式：

stdio

对于命令行工具和直接集成：

// 启动一个 stdio 服务器
if err := mcpServer.ServeStdio(); err != nil {
    fmt.Fprintf(os.Stderr, "Error: %v\n", err)
    os.Exit(1)
}

HTTP with SSE

对于 Web 应用程序，您可以使用服务器发送事件 (SSE) 进行实时通信：

// 配置 HTTP 地址
mcpServer.SetAddress(":8080")

// 启动一个支持 SSE 的 HTTP 服务器
if err := mcpServer.ServeHTTP(); err != nil {
    log.Fatalf("HTTP server error: %v", err)
}

// 为了优雅关闭
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := mcpServer.Shutdown(ctx); err != nil {
    log.Fatalf("Server shutdown error: %v", err)
}

多协议

您还可以同时运行多个协议服务器：

// 配置服务器以同时支持 HTTP 和 stdio
mcpServer := server.NewMCPServer("Multi-Protocol Server", "1.0.0")
mcpServer.SetAddress(":8080")
mcpServer.AddTool(ctx, echoTool, handleEcho)

// 在 goroutine 中启动 HTTP 服务器
go func() {
    if err := mcpServer.ServeHTTP(); err != nil {
        log.Fatalf("HTTP server error: %v", err)
    }
}()

// 在主线程中启动 stdio 服务器
if err := mcpServer.ServeStdio(); err != nil {
    log.Fatalf("Stdio server error: %v", err)
}

测试和调试

为了测试您的 MCP 服务器，您可以使用 MCP Inspector 或直接发送 JSON-RPC 消息：

# 使用 stdio 测试 echo 工具
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo","parameters":{"message":"Hello, World!"}}}' | go run your_server.go

示例

查看 examples 目录以获取完整的示例服务器：

Echo 服务器

examples/echo_server.go 中提供了一个简单的 echo 服务器示例：

# 运行示例
go run examples/echo_server.go

计算器服务器

examples/calculator/ 中提供了一个更高级的计算器示例，它同时具有 HTTP 和 stdio 模式：

# 在 HTTP 模式下运行
go run examples/calculator/main.go --mode http

# 在 stdio 模式下运行
go run examples/calculator/main.go --mode stdio

包结构

SDK 按照清晰的架构原则进行组织：

golang-mcp-server-sdk/
├── pkg/                    # 公共 API (暴露给用户)
│   ├── builder/            # 用于服务器构建的公共构建器模式
│   ├── server/             # 公共服务器实现
│   ├── tools/              # 用于创建 MCP 工具的实用程序
│   └── types/              # 共享类型和接口
├── internal/               # 私有实现细节
├── examples/               # 示例代码片段和用例
└── cmd/                    # 示例 MCP 服务器应用程序

pkg/ 目录包含 SDK 用户应与之交互的所有公开 API。

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

此项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。

📧 支持 & 联系方式

如有问题，请发送电子邮件至 mnhatlinh.doan@gmail.com
直接打开一个 issue：Issue Tracker
如果 Golang MCP Server SDK 对您的工作有所帮助，请考虑支持：