Go-MCP

Go-MCP 是 Model Context Protocol (MCP) 的 Go 实现。 MCP 是一种用于构建 AI 服务的协议，定义了三个核心原语：Prompts（提示词）、Tools（工具）和 Resources（资源）。

特性

• 完整的 MCP 协议实现
• 类型安全的 API
• 多种传输选项（HTTP、SSE）
• 统一的响应结构
• 分页支持
• 变更通知支持

安装

go get github.com/virgoC0der/go-mcp

快速开始

创建服务器

package main

import (
    "context"
    "log"
    "github.com/virgoC0der/go-mcp"
    "github.com/virgoC0der/go-mcp/internal/types"
)

// 实现 MCPService 接口
type MyService struct {
    // ... 你的服务实现
}

func main() {
    // 创建服务实例
    service := &MyService{}

    // 创建服务器
    server, err := mcp.NewServer(service, &types.ServerOptions{
        Address: ":8080",
        Type:    "sse", // or "http"
    })
    if err != nil {
        log.Fatal(err)
    }

    // 初始化服务器
    ctx := context.Background()
    if err := server.Initialize(ctx, nil); err != nil {
        log.Fatal(err)
    }

    // 启动服务器
    if err := server.Start(); err != nil {
        log.Fatal(err)
    }
}

创建客户端

package main

import (
    "context"
    "log"
    "github.com/virgoC0der/go-mcp"
    "github.com/virgoC0der/go-mcp/internal/types"
)

func main() {
    // 创建客户端
    client, err := mcp.NewClient(&types.ClientOptions{
        ServerAddress: "localhost:8080",
        Type:         "http", // or "sse", "websocket"
        UseJSONRPC: true,
        SubscribeToNotifications: true,
    })
    if err != nil {
        log.Fatal(err)
    }

    // 连接到服务器
    ctx := context.Background()
    if err := client.Connect(ctx); err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    // 获取服务接口
    service := client.Service()

    // 使用服务
    result, err := service.ListPrompts(ctx, "")
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Available prompts: %v", result.Prompts)

    // 获取下一页（如果可用）
    if result.NextCursor != "" {
        nextPage, err := service.ListPrompts(ctx, result.NextCursor)
        if err != nil {
            log.Fatal(err)
        }
        log.Printf("Next page prompts: %v", nextPage.Prompts)
    }
}

响应结构

JSON-RPC 响应

对于 JSON-RPC 端点，响应遵循 JSON-RPC 2.0 规范，并在所有传输层上使用统一的响应处理系统：

type JSONRPCResponse struct {
    JSONRPC string        `json:"jsonrpc"`
    ID      interface{}   `json:"id"`
    Result  interface{}   `json:"result,omitempty"`
    Error   *JSONRPCError `json:"error,omitempty"`
}

type JSONRPCError struct {
    Code    int         `json:"code"`
    Message string      `json:"message"`
    Data    interface{} `json:"data,omitempty"`
}

JSON-RPC 成功响应示例：

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "prompts": [
            {
                "name": "example_prompt",
                "description": "An example prompt"
            }
        ],
        "nextCursor": ""
    }
}

JSON-RPC 错误响应示例：

{
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
        "code": -32602,
        "message": "Invalid params",
        "data": "Missing required parameter: name"
    }
}

该库提供了一个统一的响应处理系统，该系统可在 HTTP、WebSocket 和 stdio 传输层上工作，从而确保一致的错误处理和响应格式。

示例

• Echo Server - 一个简单的 echo 服务器示例
• Weather Service - 一个使用 OpenWeatherMap API 的天气服务示例
• App Launcher - 一个带有 stdio 服务器支持的 macOS 应用程序启动器示例

API 文档

服务器接口

服务器必须实现 types.Server 接口：

type Server interface {
    MCPService
    Initialize(ctx context.Context, options any) error
    Start() error
    Shutdown(ctx context.Context) error
}

MCPService 接口定义了核心功能：

type MCPService interface {
    // ListPrompts 返回可用提示词的列表，支持分页
    ListPrompts(ctx context.Context, cursor string) (*PromptListResult, error)

    // GetPrompt 根据名称检索特定的提示词，带有可选参数
    GetPrompt(ctx context.Context, name string, args map[string]any) (*PromptResult, error)

    // ListTools 返回可用工具的列表，支持分页
    ListTools(ctx context.Context, cursor string) (*ToolListResult, error)

    // CallTool 调用具有参数的特定工具
    CallTool(ctx context.Context, name string, args map[string]any) (*CallToolResult, error)

    // ListResources 返回可用资源的列表，支持分页
    ListResources(ctx context.Context, cursor string) (*ResourceListResult, error)

    // ReadResource 读取特定资源的内容
    ReadResource(ctx context.Context, uri string) (*ResourceContent, error)

    // ListResourceTemplates 返回可用资源模板的列表
    ListResourceTemplates(ctx context.Context) ([]ResourceTemplate, error)

    // SubscribeToResource 订阅特定资源的更改
    SubscribeToResource(ctx context.Context, uri string) error
}

客户端接口

客户端通过 types.Client 接口访问服务：

type Client interface {
    // Connect 建立与服务器的连接
    Connect(ctx context.Context) error

    // Close 终止连接
    Close() error

    // Service 返回底层的 MCPService 接口
    Service() MCPService
}

贡献

欢迎贡献！ 请按照以下步骤操作：

1. Fork 仓库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

许可证

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

更新至 MCP 规范 2025-03-26

此库已更新为支持 Model Context Protocol (MCP) 2025-03-26 规范。 主要更新包括：

新特性

• 完整的 JSON-RPC 支持：实现了符合最新 MCP 规范的 JSON-RPC 2.0 API 端点
• 增强的多模态内容：支持文本、图像、音频和嵌入式资源内容的传输
• 分页支持：所有列表 API 现在都支持基于游标的分页
• 资源模板：支持参数化的资源 URI 模板
• 资源订阅：支持客户端订阅资源更改通知
• 丰富的服务器功能：更精细的服务器功能声明
• 统一的响应处理：跨不同传输层的标准化响应处理

向后兼容性

• 保留了原始 REST API 端点，以确保与旧客户端的兼容性
• 通知系统支持新旧通知格式

使用示例

// 创建服务器
server, err := mcp.NewServer(service, &types.ServerOptions{
    Address: ":8080",
    Capabilities: &types.ServerCapabilities{
        Prompts: &types.PromptCapabilities{
            ListChanged: true,
        },
        Resources: &types.ResourceCapabilities{
            ListChanged: true,
            Subscribe: true,
            Templates: true,
        },
    },
})

// 创建客户端
client, err := mcp.NewClient(&types.ClientOptions{
    ServerAddress: "localhost:8080",
    Type: "http",
    UseJSONRPC: true,
    SubscribeToNotifications: true,
})

// 获取提示词列表（支持分页）
result, err := client.Service().ListPrompts(ctx, "")
// 获取下一页
nextPage, err := client.Service().ListPrompts(ctx, result.NextCursor)

// 订阅资源更改
err := client.Service().SubscribeToResource(ctx, "file:///example.txt")