⚡ go-mcp

<div align="center"> <h3>一个类型安全、直观的 Go SDK，用于 MCP 服务器开发</h3> </div>

<p align="center"> <a href="#-what-is-go-mcp">🤔 什么是 go‑mcp?</a> • <a href="#-features">✨ 特性</a> • <a href="#-quick-start">🏁 快速开始</a> • <a href="#-examples">🔍 示例</a> • <a href="#-supported-features">✅ 支持的特性</a> • <a href="#-contributing">🤝 贡献</a> </p>

---

🤔 什么是 go‑mcp?

go‑mcp 是一个 Go SDK，用于轻松自信地构建 MCP (模型上下文协议) 服务器。它提供了一个类型安全、直观的接口，使服务器开发变得轻而易举。

---

✨ 特性

• 🔒 类型安全 – 代码生成确保您的工具和提示参数是静态类型的，因此错误在编译时而不是运行时被捕获。
• 🧩 简单 & 直观的 API – 一个自然、符合 Go 语言习惯的接口，让您可以快速构建服务器，而无需陡峭的学习曲线。
• 🔌 开发者友好 – 在设计时考虑了 API 的人体工程学，使其易于上手。

---

🏁 快速开始

使用 go‑mcp 创建 MCP 服务器非常简单！

目录结构

以下是一个温度转换 MCP 服务器的示例目录结构：

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

1. 定义 MCP 服务器

首先，创建 cmd/mcpgen/main.go 用于代码生成。运行此文件将自动生成必要的代码。

package main

import (
    "log"
    "os"
    "path/filepath"

    "github.com/ktr0731/go-mcp/codegen"
)

func main() {
    // Create output directory
    outDir := "."
    if err := os.MkdirAll(outDir, 0o755); err != nil {
        log.Fatalf("failed to create output directory: %v", err)
    }

    // Create output file
    f, err := os.Create(filepath.Join(outDir, "mcp.gen.go"))
    if err != nil {
        log.Fatalf("failed to create file: %v", err)
    }
    defer f.Close()

    // Server definition
    def := &codegen.ServerDefinition{
        Capabilities: codegen.ServerCapabilities{
            Tools:   &codegen.ToolCapability{},
            Logging: &codegen.LoggingCapability{},
        },
        Implementation: codegen.Implementation{
            Name:    "Temperature MCP Server",
            Version: "1.0.0",
        },
        // Tool definitions (declared with Go structs)
        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"`
                }{},
            },
        },
    }

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

生成代码：

go run ./cmd/mcpgen

2. 实现 MCP 服务器

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

package main

import (
    "context"
    "fmt"
    "log"
    "math"

    mcp "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 == ConvertTemperatureFromUnitTypeCelsius && toUnit == ConvertTemperatureToUnitTypeFahrenheit:
        // °C → °F: (C × 9/5) + 32
        result = (temperature*9/5 + 32)
    case fromUnit == ConvertTemperatureFromUnitTypeFahrenheit && toUnit == ConvertTemperatureToUnitTypeCelsius:
        // °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)
    }

    // Round to two decimal places
    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

---

🔍 示例

请参阅 examples 目录 和 API 文档 中的完整示例。

---

✅ 支持的特性

• Ping
• 工具
• 提示
• 提示、工具、资源、资源模板
• 资源订阅
• 资源更新通知
• 日志
• 完成
• 取消

🚧 开发中

• 批处理 (JSON‑RPC 2.0)
• 可流式传输的 HTTP 传输
• 进度通知

🚫 未计划

• 动态提示和工具更改

  Go 不太适合动态工具添加。动态添加工具需要在运行时构建工具定义、JSON Schema 和处理程序。虽然生成的代码仍然是类型安全的，但动态添加的组件不是，这迫使大量使用 any 和类型断言，并损害接口一致性。我们将这些用例委托给更适合动态更改的语言（例如 TypeScript）中的 SDK。

  目前大多数已实现的 MCP 服务器仅使用静态定义，并且动态更改似乎还不是主要用例。

---

🤝 贡献

欢迎贡献！请随时提交 pull request。

---

📄 许可证

该项目根据 MIT 许可证获得许可 – 有关详细信息，请参阅 LICENSE 文件。