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

// 创建一个基础服务器
s := server.NewMCPServer(
    "我的服务器",  // 服务器名称
    "1.0.0",     // 版本
)

// 使用标准输入输出启动服务器
if err := server.ServeStdio(s); err != nil {
    log.Fatalf("服务器错误: %v", err)
}

• 静态（固定 URI）
• 动态（使用 URI 模板）

以下是一个静态资源的简单示例：

// 静态资源示例 - 公开 README 文件
resource := mcp.NewResource(
    "docs://readme",
    "项目 README",
    mcp.WithResourceDescription("项目的 README 文件"), 
    mcp.WithMIMEType("text/markdown"),
)

// 添加资源及其处理器
s.AddResource(resource, func(ctx context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
    content, err := os.ReadFile("README.md")
    if err != nil {
        return nil, err
    }
    
    return []mcp.ResourceContents{
        mcp.TextResourceContents{
            URI:      "docs://readme",
            MIMEType: "text/markdown",
            Text:     string(content),
        },
    }, nil
})

下面是一个使用模板的动态资源示例：

// 动态资源示例 - 根据 ID 获取用户资料
template := mcp.NewResourceTemplate(
    "users://{id}/profile",
    "用户资料",
    mcp.WithTemplateDescription("返回用户个人资料信息"),
    mcp.WithTemplateMIMEType("application/json"),
)

// 添加模板及其处理器
s.AddResourceTemplate(template, func(ctx context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
    // 使用正则匹配从 URI 中提取 ID
    // 服务器会自动将 URI 匹配到模板
    userID := extractIDFromURI(request.Params.URI)
    
    profile, err := getUserProfile(userID)  // 您的数据库/API 调用在此处
    if err != nil {
        return nil, err
    }
    
    return []mcp.ResourceContents{
        mcp.TextResourceContents{
            URI:      request.Params.URI,
            MIMEType: "application/json",
            Text:     profile,
        },
    }, nil
})

这些示例虽然简单，但展示了核心概念。资源可以更加复杂——提供多种内容、集成数据库或外部 API 等。

工具允许 LLM 通过您的服务器执行操作。与资源不同，工具通常用于执行计算并产生副作用。它们类似于 REST API 中的 POST 端点。

任务增强型工具

任务增强型工具以异步方式执行，并通过轮询获取结果。这对于长时间运行的操作非常有用，否则可能会导致阻塞或超时。任务工具支持三种模式：

• TaskSupportForbidden（默认）：该工具不能作为任务调用
• TaskSupportOptional：该工具既可以作为任务调用，也可以同步调用
• TaskSupportRequired：该工具必须作为任务调用

// 示例：需要任务执行的工具
processBatchTool := mcp.NewTool("process_batch",
    mcp.WithDescription("异步处理一批项目"),
    mcp.WithTaskSupport(mcp.TaskSupportRequired),
    mcp.WithArray("items",
        mcp.Description("待处理的项目列表"),
        mcp.WithStringItems(),
        mcp.Required(),
    ),
)

// 任务工具处理器返回 CreateTaskResult 而不是 CallToolResult
s.AddTaskTool(processBatchTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CreateTaskResult, error) {
    items := request.GetStringSlice("items", []string{})
    
    // 长时间运行的工作在此处
    for i, item := range items {
        select {
        case <-ctx.Done():
            // 任务被取消
            return nil, ctx.Err()
        default:
            // 处理项目...
            processItem(item)
        }
    }
    
    // 返回结果——任务 ID 和元数据由服务器管理
    return &mcp.CreateTaskResult{
        Task: mcp.Task{
            // 任务字段（ID、状态等）由服务器填充
        },
    }, nil
})

// 在创建服务器时启用任务功能
s := server.NewMCPServer(
    "任务服务器",
    "1.0.0",
    server.WithTaskCapabilities(
        true, // listTasks：允许客户端列出所有任务
        true, // cancel：允许客户端取消正在运行的任务
        true, // toolCallTasks：为工具启用任务增强功能
    ),
    server.WithMaxConcurrentTasks(10), // 可选：限制同时运行的任务数量
)

任务执行流程：

1. 客户端调用工具并指定任务参数
2. 服务器立即返回任务 ID
3. 工具在后台异步执行
4. 客户端轮询 tasks/result 来获取结果
5. 服务器在任务完成时发送状态通知

对于可选任务工具，同一工具既可以同步调用（不带任务参数），也可以异步调用（带任务参数）：

// 具有可选任务支持的工具
analyzeTool := mcp.NewTool("analyze_data",
    mcp.WithDescription("分析数据——可同步或异步执行"),
    mcp.WithTaskSupport(mcp.TaskSupportOptional),
    mcp.WithString("data", mcp.Required()),
)

// 对于支持两种模式的混合工具，使用 AddTaskTool
s.AddTaskTool(analyzeTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CreateTaskResult, error) {
    // 当作为任务调用时，此处理器运行
    data := request.GetString("data", "")
    result := analyzeData(data)
    
    return &mcp.CreateTaskResult{
        Task: mcp.Task{},
    }, nil
})

// 服务器会自动处理同步和异步调用
// 不带任务参数时：直接执行处理器并立即返回结果
// 带任务参数时：异步执行处理器

限制并发任务数

为防止资源耗尽，您可以限制同时运行的任务数量：

s := server.NewMCPServer(
    "任务服务器",
    "1.0.0",
    server.WithTaskCapabilities(true, true, true),
    server.WithMaxConcurrentTasks(10), // 允许最多 10 个并发任务
)

当达到限制时，新的任务创建请求将失败并返回错误。已完成、失败或已取消的任务不计入限制——只有处于“进行中”状态的任务才会被计算在内。如果未指定 WithMaxConcurrentTasks 或将其设置为 0，则没有并发任务限制。

对于传统的同步工具，它们会立即执行并返回结果：

简单的计算示例：

calculatorTool := mcp.NewTool("calculate",
    mcp.WithDescription("执行基本的算术计算"),
    mcp.WithString("operation",
        mcp.Required(),
        mcp.Description("要执行的算术运算"),
        mcp.Enum("add", "subtract", "multiply", "divide"),
    ),
    mcp.WithNumber("x",
        mcp.Required(),
        mcp.Description("第一个数字"),
    ),
    mcp.WithNumber("y",
        mcp.Required(),
        mcp.Description("第二个数字"),
    ),
)

s.AddTool(calculatorTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    args := request.GetArguments()
    op := args["operation"].(string)
    x := args["x"].(float64)
    y := args["y"].(float64)

    var result float64
    switch op {
    case "add":
        result = x + y
    case "subtract":
        result = x - y
    case "multiply":
        result = x * y
    case "divide":
        if y == 0 {
            return mcp.NewToolResultError("不能除以零"), nil
        }
        result = x / y
    }
    
    return mcp.FormatNumberResult(result), nil
})

HTTP 请求示例：

httpTool := mcp.NewTool("http_request",
    mcp.WithDescription("向外部 API 发送 HTTP 请求"),
    mcp.WithString("method",
        mcp.Required(),
        mcp.Description("要使用的 HTTP 方法"),
        mcp.Enum("GET", "POST", "PUT", "DELETE"),
    ),
    mcp.WithString("url",
        mcp.Required(),
        mcp.Description("发送请求的 URL"),
        mcp.Pattern("^https?://.*"),
    ),
    mcp.WithString("body",
        mcp.Description("请求体（用于 POST/PUT）"),
    ),
)

s.AddTool(httpTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    args := request.GetArguments()
    method := args["method"].(string)
    url := args["url"].(string)
    body := ""
    if b, ok := args["body"].(string); ok {
        body = b
    }

    // 创建并发送请求
    var req *http.Request
    var err error
    if body != "" {
        req, err = http.NewRequest(method, url, strings.NewReader(body))
    } else {
        req, err = http.NewRequest(method, url, nil)
    }
    if err != nil {
        return mcp.NewToolResultErrorFromErr("无法创建请求", err), nil
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return mcp.NewToolResultErrorFromErr("无法执行请求", err), nil
    }
    defer resp.Body.Close()

    // 返回响应
    respBody, err := io.ReadAll(resp.Body)
    if err != nil {
        return mcp.NewToolResultErrorFromErr("无法读取请求响应", err), nil
    }

    return mcp.NewToolResultText(fmt.Sprintf("状态: %d\n正文: %s", resp.StatusCode, string(respBody))), nil
})

工具可用于任何类型的计算或副作用：

• 数据库查询
• 文件操作
• 外部 API 调用
• 计算
• 系统操作

每个工具应：

• 具有清晰的描述
• 验证输入
• 妥善处理错误
• 返回结构化响应
• 使用适当的结果类型

提示词是可重用的模板，可帮助大模型有效地与您的服务器交互。它们就像是编码到您服务器中的“最佳实践”。以下是一些示例：

// 简单的问候提示词
s.AddPrompt(mcp.NewPrompt("greeting",
    mcp.WithPromptDescription("友好的问候提示词"),
    mcp.WithArgument("name",
        mcp.ArgumentDescription("要问候的人的名字"),
    ),
), func(ctx context.Context, request mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
    name := request.Params.Arguments["name"]
    if name == "" {
        name = "朋友"
    }
    
    return mcp.NewGetPromptResult(
        "友好的问候",
        []mcp.PromptMessage{
            mcp.NewPromptMessage(
                mcp.RoleAssistant,
                mcp.NewTextContent(fmt.Sprintf("你好，%s！今天有什么可以帮你的吗？", name)),
            ),
        },
    ), nil
})

// 带嵌入资源的代码审查提示词
s.AddPrompt(mcp.NewPrompt("code_review",
    mcp.WithPromptDescription("代码审查协助"),
    mcp.WithArgument("pr_number",
        mcp.ArgumentDescription("要审查的拉取请求编号"),
        mcp.RequiredArgument(),
    ),
), func(ctx context.Context, request mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
    prNumber := request.Params.Arguments["pr_number"]
    if prNumber == "" {
        return nil, fmt.Errorf("需要提供拉取请求编号")
    }
    
    return mcp.NewGetPromptResult(
        "代码审查协助",
        []mcp.PromptMessage{
            mcp.NewPromptMessage(
                mcp.RoleUser,
                mcp.NewTextContent("请审查这些更改，并提供建设性的反馈。"),
            ),
            mcp.NewPromptMessage(
                mcp.RoleAssistant,
                mcp.NewEmbeddedResource(mcp.ResourceContents{
                    URI: fmt.Sprintf("git://pulls/%s/diff", prNumber),
                    MIMEType: "text/x-diff",
                }),
            ),
        },
    ), nil
})

// 数据库查询构建器提示词
s.AddPrompt(mcp.NewPrompt("query_builder",
    mcp.WithPromptDescription("SQL 查询构建助手"),
    mcp.WithArgument("table",
        mcp.ArgumentDescription("要查询的表名"),
        mcp.RequiredArgument(),
    ),
), func(ctx context.Context, request mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
    tableName := request.Params.Arguments["table"]
    if tableName == "" {
        return nil, fmt.Errorf("需要提供表名")
    }
    
    return mcp.NewGetPromptResult(
        "SQL 查询构建助手",
        []mcp.PromptMessage{
            mcp.NewPromptMessage(
                mcp.RoleUser,
                mcp.NewTextContent("请为提供的模式构建高效且安全的查询。"),
            ),
            mcp.NewPromptMessage(
                mcp.RoleUser,
                mcp.NewEmbeddedResource(mcp.ResourceContents{
                    URI: fmt.Sprintf("db://schema/%s", tableName),
                    MIMEType: "application/json",
                }),
            ),
        },
    ), nil
})

提示词可以包含：

• 系统指令
• 必需参数
• 嵌入式资源
• 多条消息
• 不同的内容类型（文本、图片等）
• 自定义 URI 方案

基本会话处理

// 创建一个支持会话功能的服务器
s := server.NewMCPServer(
    "会话演示",
    "1.0.0",
    server.WithToolCapabilities(true),
)

// 实现自定义的 ClientSession
type MySession struct {
    id           string
    notifChannel chan mcp.JSONRPCNotification
    isInitialized bool
    // 根据应用需求添加自定义字段
}

// 实现 ClientSession 接口
func (s *MySession) SessionID() string {
    return s.id
}

func (s *MySession) NotificationChannel() chan<- mcp.JSONRPCNotification {
    return s.notifChannel
}

func (s *MySession) Initialize() {
    s.isInitialized = true
}

func (s *MySession) Initialized() bool {
    return s.isInitialized
}

// 注册一个会话
session := &MySession{
    id:           "user-123",
    notifChannel: make(chan mcp.JSONRPCNotification, 10),
}
if err := s.RegisterSession(context.Background(), session); err != nil {
    log.Printf("注册会话失败： %v", err)
}

// 向特定客户端发送通知
err := s.SendNotificationToSpecificClient(
    session.SessionID(),
    "notification/update",
    map[string]any{"message": "有新数据可用！"},
)
if err != nil {
    log.Printf("发送通知失败： %v", err)
}

// 使用完毕后注销会话
s.UnregisterSession(context.Background(), session.SessionID())

基于会话的工具

对于更高级的用例，您可以实现 SessionWithTools 接口，以支持基于会话的工具自定义：

// 实现 SessionWithTools 接口，用于支持基于会话的工具
type MyAdvancedSession struct {
    MySession  // 嵌入基础会话
    sessionTools map[string]server.ServerTool
}

// 实现 SessionWithTools 的额外方法
func (s *MyAdvancedSession) GetSessionTools() map[string]server.ServerTool {
    return s.sessionTools
}

func (s *MyAdvancedSession) SetSessionTools(tools map[string]server.ServerTool) {
    s.sessionTools = tools
}

// 创建并注册一个支持工具的会话
advSession := &MyAdvancedSession{
    MySession: MySession{
        id:           "user-456",
        notifChannel: make(chan mcp.JSONRPCNotification, 10),
    },
    sessionTools: make(map[string]server.ServerTool),
}
if err := s.RegisterSession(context.Background(), advSession); err != nil {
    log.Printf("注册会话失败： %v", err)
}

// 添加会话专属工具
userSpecificTool := mcp.NewTool(
    "user_data",
    mcp.WithDescription("访问用户专属数据"),
)
// 可以使用 AddSessionTool（类似于 AddTool）
err := s.AddSessionTool(
    advSession.SessionID(),
    userSpecificTool,
    func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        // 此处理器仅对该特定会话可用
        return mcp.NewToolResultText("针对 " + advSession.SessionID() 的用户专属数据"), nil
    },
)
if err != nil {
    log.Printf("添加会话工具失败： %v", err)
}

// 或者直接使用 AddSessionTools 并传入 ServerTool
/*
err := s.AddSessionTools(
    advSession.SessionID(),
    server.ServerTool{
        Tool: userSpecificTool,
        Handler: func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
            // 此处理器仅对该特定会话可用
            return mcp.NewToolResultText("针对 " + advSession.SessionID() 的用户专属数据"), nil
        },
    },
)
if err != nil {
    log.Printf("添加会话工具失败： %v", err)
}
*/

// 当不再需要时，删除会话专属工具
err = s.DeleteSessionTools(advSession.SessionID(), "user_data")
if err != nil {
    log.Printf("删除会话工具失败： %v", err)
}

工具过滤

您还可以应用过滤器来控制哪些工具对特定会话可见：

// 添加一个工具过滤器，只显示具有特定前缀的工具
s := server.NewMCPServer(
    "工具过滤演示",
    "1.0.0",
    server.WithToolCapabilities(true),
    server.WithToolFilter(func(ctx context.Context, tools []mcp.Tool) []mcp.Tool {
        // 从上下文中获取会话
        session := server.ClientSessionFromContext(ctx)
        if session == null {
            return tools // 如果没有会话，则返回所有工具
        }
        
        // 示例：根据会话 ID 前缀过滤工具
        if strings.HasPrefix(session.SessionID(), "admin-") {
            // 管理员用户可使用所有工具
            return tools
        } else {
            // 普通用户仅能使用带有 "public-" 前缀的工具
            var filteredTools []mcp.Tool
            for _, tool := range tools {
                if strings.HasPrefix(tool.Name, "public-") {
                    filteredTools = append(filteredTools, tool)
                }
            }
            return filteredTools
        }
    }),
)

使用上下文

会话上下文会自动传递给工具和资源处理器：

s.AddTool(mcp.NewTool("session_aware"), func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // 从上下文中获取当前会话
    session := server.ClientSessionFromContext(ctx)
    if session == null {
        return mcp.NewToolResultError("无活动会话"), nil
    }
    
    return mcp.NewToolResultText("你好，会话 " + session.SessionID()), nil
})

// 在使用 HTTP/SSE 服务器的处理器时，需要将包含会话的上下文传递过去
httpHandler := func(w http.ResponseWriter, r *http.Request) {
    // 从某个地方（如 Cookie 或 Header）获取会话
    session := getSessionFromRequest(r)
    
    // 将会话添加到上下文中
    ctx := s.WithContext(r.Context(), session)
    
    // 处理请求时使用此上下文
    // ...
}

type MyPromptCompletionProvider struct{}

func (p *MyPromptCompletionProvider) CompletePromptArgument(
    ctx context.Context,
    promptName string,
    argument mcp.CompleteArgument,
    context mcp.CompleteContext,
) (*mcp.Completion, error) {
    // 示例：为 "code_review" 提供样式建议
    if promptName == "code_review" && argument.Name == "style" {
        styles := []string{"正式", "随意", "技术性", "创意"}
        var suggestions []string
        
        // 根据当前输入进行筛选
        for _, style := range styles {
            if strings.HasPrefix(style, argument.Value) {
                suggestions = append(suggestions, style)
            }
        }
        
        return &mcp.Completion{
            Values: suggestions,
        }, nil
    }
    
    // 对于未处理的情况返回空建议
    return &mcp.Completion{Values: []string{}}, nil
}

type MyResourceCompletionProvider struct{}

func (p *MyResourceCompletionProvider) CompleteResourceArgument(
    ctx context.Context,
    uri string,
    argument mcp.CompleteArgument,
    context mcp.CompleteContext,
) (*mcp.Completion, error) {
    // 示例：提供文件路径补全
    if uri == "file:///{path}" && argument.Name == "path" {
        // 您可以从 context.Arguments 中访问之前已完成的参数
        // context.Arguments 是一个已解析参数的 map[string]string
        
        paths := getMatchingPaths(argument.Value) // 您的自定义逻辑
        
        return &mcp.Completion{
            Values:  paths[:min(len(paths), 100)], // 最多 100 项
            Total:   len(paths),                    // 总共有多少匹配项
            HasMore: len(paths) > 100,              // 是否还有更多结果
        }, nil
    }
    
    return &mcp.Completion{Values: []string{}}, nil
}

// 注册提供者
mcpServer := server.NewMCPServer(
    "my-server",
    "1.0.0",
    server.WithCompletions(),
    server.WithPromptCompletionProvider(&MyPromptCompletionProvider{}),
    server.WithResourceCompletionProvider(&MyResourceCompletionProvider{}),
)

func (p *MyProvider) CompleteResourceArgument(
    ctx context.Context,
    uri string,
    argument mcp.CompleteArgument,
    context mcp.CompleteContext,
) (*mcp.Completion, error) {
    // 访问之前完成的参数
    if previousValue, ok := context.Arguments["previous_arg"]; ok {
        // 根据 previous_arg 的值提供建议
        return getSuggestionsFor(argument.Value, previousValue), nil
    }
    
    return &mcp.Completion{Values: []string{}}, nil
}