go-mcp 开发者指南

1. 项目介绍

go-mcp 是一个由 CSDN 公司开发的、用于构建 MCP（Model Context Protocol）服务器的 Go SDK。它提供了类型安全、直观的接口，使得服务器开发变得简单而自信。这个 SDK 的设计注重 API 的易用性和开发者体验，使得开发者可以快速上手并构建出稳定的服务器。

2. 项目快速启动

创建 MCP 服务器

使用 go-mcp 创建 MCP 服务器非常直接。以下是一个温度转换 MCP 服务器的目录结构示例：

.
├── cmd
│   ├── mcpgen
│   │   └── main.go
│   └── temperature
│       └── main.go
├── mcp.gen.go
└── temperature.go

代码生成

首先，创建 cmd/mcpgen/main.go 用于代码生成。运行这个文件将自动生成所需的代码。

package main

import (
    "log"
    "os"
    "path/filepath"
    "github.com/ktr0731/go-mcp/codegen"
)

func main() {
    // 创建输出目录
    outDir := "."
    if err := os.MkdirAll(outDir, 0o755); err != nil {
        log.Fatalf("failed to create output directory: %v", err)
    }
    // 创建输出文件
    f, err := os.Create(filepath.Join(outDir, "mcp.gen.go"))
    if err != nil {
        log.Fatalf("failed to create file: %v", err)
    }
    defer f.Close()

    // 服务器定义
    def := &codegen.ServerDefinition{
        Capabilities: codegen.ServerCapabilities{
            Tools:    &codegen.ToolCapability{},
            Logging:  &codegen.LoggingCapability{},
        },
        Implementation: codegen.Implementation{
            Name:    "Temperature MCP Server",
            Version: "1.0.0",
        },
        // 工具定义（使用 Go 结构体声明）
        Tools: []codegen.Tool{
            {
                Name:        "convert_temperature",
                Description: "Convert temperature between Celsius and Fahrenheit",
                InputSchema: struct {
                    Temperature float64 `json:"temperature" jsonschema:"description=Temperature value to convert"`
                    FromUnit    string  `json:"from_unit"  jsonschema:"description=Source temperature unit,enum=celsius,enum=fahrenheit"`
                    ToUnit      string  `json:"to_unit"    jsonschema:"description=Target temperature unit,enum=celsius,enum=fahrenheit"`
                }{},
            },
        },
    }

    // 生成代码
    if err := codegen.Generate(f, def, "temperature"); err != nil {
        log.Fatalf("failed to generate code: %v", err)
    }
}

生成代码：

go run ./cmd/mcpgen

实现服务器

接下来，在 cmd/temperature/main.go 中实现服务器逻辑：

package main

import (
    "context"
    "fmt"
    "log"
    "math"
    "github.com/ktr0731/go-mcp"
    "golang.org/x/exp/jsonrpc2"
)

type toolHandler struct{}

func (h *toolHandler) HandleToolConvertTemperature(ctx context.Context, req *ToolConvertTemperatureRequest) (*mcp.CallToolResult, error) {
    temperature := req.Temperature
    fromUnit := req.FromUnit
    toUnit := req.ToUnit

    var result float64
    switch {
    case fromUnit == "celsius" && toUnit == "fahrenheit":
        // °C → °F: (C × 9/5) + 32
        result = (temperature * 9 / 5) + 32
    case fromUnit == "fahrenheit" && toUnit == "celsius":
        // °F → °C: (F − 32) × 5/9
        result = (temperature - 32) * 5 / 9
    case fromUnit == toUnit:
        result = temperature
    default:
        return nil, fmt.Errorf("unsupported conversion: %s to %s", fromUnit, toUnit)
    }

    // 四舍五入到两位小数
    result = math.Round(result*100) / 100
    resultText := fmt.Sprintf("%.2f %s = %.2f %s", temperature, fromUnit, result, toUnit)
    return &mcp.CallToolResult{
        Content: []mcp.CallToolContent{
            mcp.TextContent{
                Text: resultText,
            },
        },
    }, nil
}

func main() {
    handler := NewHandler(&toolHandler{})
    ctx, listener, binder := mcp.NewStdioTransport(context.Background(), handler, nil)
    srv, err := jsonrpc2.Serve(ctx, listener, binder)
    if err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
    srv.Wait()
}

运行服务器：

go run ./cmd/temperature

3. 应用案例和最佳实践

• 代码生成：使用 go-mcp 的代码生成功能可以减少手动编写重复代码的工作量，确保服务器定义的一致性。
• API 设计：在设计工具和接口时，保持 API 的简洁和直观性，以便其他开发者能够快速理解和使用。
• 错误处理：合理处理错误情况，提供清晰的错误信息，帮助调试和问题定位。

4. 典型生态项目

当前，go-mcp 生态系统中的项目主要集中在构建和扩展 MCP 服务器。由于 go-mcp 旨在提供静态定义的服务器，动态工具添加并不是其重点，因此生态项目通常是基于静态定义构建的。开发者可以参考 go-mcp 的示例和文档来创建自己的 MCP 服务器，并根据需要扩展功能。