server

package
v1.2.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 20, 2025 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddTool added in v1.2.1 

func AddTool[In, Out any](s *Server, tool *protocol.Tool, handler ToolHandlerFor[In, Out])

AddTool 添加工具和类型安全的工具处理函数到服务器。

这是一个包级函数而非 Server 的方法，因为 Go 不支持方法级别的类型参数。 有关更多信息，请参阅 Go 泛型提案： https://go.googlesource.com/proposal/+/refs/heads/master/design/43651-type-parameters.md#no-parameterized-methods

如果工具的输入 schema 为 nil，它会从 In 类型参数推断设置。类型从 Go 类型推断， 属性描述从 'jsonschema' 结构体标签读取。在内部，SDK 使用 github.com/invopop/jsonschema 包进行推断和验证。In 类型参数必须是 map 或 struct，以便其推断的 JSON Schema 具有 规范要求的 "object" 类型。作为特例，如果 In 类型是 'any'，工具的输入 schema 会设置为空对象 schema 值。

如果工具的输出 schema 为 nil，且 Out 类型不是 'any'，输出 schema 会从 Out 类型 参数推断设置，Out 类型也必须是 map 或 struct。如果 Out 类型是 'any'，则省略输出 schema。

与 Server.AddTool 不同，AddTool 会自动完成许多工作，并强制工具符合 MCP 规范。 详细的自动行为请参阅 ToolHandlerFor 的文档。

示例： 

type Input struct {
    Name string `json:"name" jsonschema:"required,description=用户名称"`
}
type Output struct {
    Greeting string `json:"greeting" jsonschema:"required,description=问候语"`
}

server.AddTool[Input, Output](s, &protocol.Tool{
    Name:        "greet",
    Description: "向用户问候",
}, func(ctx context.Context, req *server.CallToolRequest, input Input) (
    *protocol.CallToolResult, Output, error,
) {
    return nil, Output{Greeting: "你好，" + input.Name}, nil
})

func ErrorResult added in v1.2.1 

func ErrorResult(message string, err error) *protocol.CallToolResult

ErrorResult 创建错误结果

func GetBool added in v1.2.1 

func GetBool(req *CallToolRequest, key string, defaultValue bool) bool

GetBool 从请求参数中获取布尔值

func GetFloat added in v1.2.1 

func GetFloat(req *CallToolRequest, key string, defaultValue float64) float64

GetFloat 从请求参数中获取浮点数值

func GetInt added in v1.2.1 

func GetInt(req *CallToolRequest, key string, defaultValue int) int

GetInt 从请求参数中获取整数值

func GetInt64 added in v1.2.1 

func GetInt64(req *CallToolRequest, key string, defaultValue int64) int64

GetInt64 从请求参数中获取 int64 值

func GetMap added in v1.2.1 

func GetMap(req *CallToolRequest, key string, defaultValue map[string]interface{}) map[string]interface{}

GetMap 从请求参数中获取 map

func GetString added in v1.2.1 

func GetString(req *CallToolRequest, key string, defaultValue string) string

GetString 从请求参数中获取字符串值

func GetStringSlice added in v1.2.1 

func GetStringSlice(req *CallToolRequest, key string, defaultValue []string) []string

GetStringSlice 从请求参数中获取字符串数组

func ImageResult added in v1.2.1 

func ImageResult(data string, mimeType string) *protocol.CallToolResult

ImageResult 创建包含图片的结果

func JSONResult added in v1.2.1 

func JSONResult(data interface{}) (*protocol.CallToolResult, error)

JSONResult 创建包含 JSON 内容的结果

func MustGetBool added in v1.2.1 

func MustGetBool(req *CallToolRequest, key string) (bool, error)

MustGetBool 从请求参数中获取布尔值，如果不存在返回错误

func MustGetInt added in v1.2.1 

func MustGetInt(req *CallToolRequest, key string) (int, error)

MustGetInt 从请求参数中获取整数值，如果不存在返回错误

func MustGetString added in v1.2.1 

func MustGetString(req *CallToolRequest, key string) (string, error)

MustGetString 从请求参数中获取字符串值，如果不存在返回错误

func ResourceResult added in v1.2.1 

func ResourceResult(uri, mimeType, text string) *protocol.CallToolResult

ResourceResult 创建包含嵌入资源的结果

func TextResult added in v1.2.1 

func TextResult(text string) *protocol.CallToolResult

TextResult 创建包含文本内容的结果

Types

type AuthValidator added in v1.2.1 

type AuthValidator interface {
	Validate(authInfo interface{}, tool string) bool
}

AuthValidator 认证验证器接口

type CallToolRequest added in v1.2.0 

type CallToolRequest struct {
	// Session 当前会话
	Session *ServerSession

	// Params 原始参数
	Params *protocol.CallToolParams
}

CallToolRequest 表示工具调用请求,允许工具处理函数发送通知

type Connection added in v1.2.0 

type Connection interface {
	// SendNotification 发送通知到客户端
	SendNotification(ctx context.Context, method string, params interface{}) error

	// SendRequest 发送请求到客户端并等待响应
	SendRequest(ctx context.Context, method string, params interface{}, result interface{}) error

	Close() error

	SessionID() string
}

Connection 表示底层传输连接

type ErrorCode added in v1.2.1 

type ErrorCode string
const (
	// Client Error
	ErrInvalidParams  ErrorCode = "invalid_params"    // Invalid parameter
	ErrNotFound       ErrorCode = "not_found"         // Resource not found
	ErrUnauthorized   ErrorCode = "unauthorized"      // Unauthorized
	ErrForbidden      ErrorCode = "forbidden"         // Access Denied
	ErrConflict       ErrorCode = "conflict"          // Conflict
	ErrTooManyRequest ErrorCode = "too_many_requests" // Too many requests

	// Server error
	ErrInternal       ErrorCode = "internal_error"   // Internal Error
	ErrNotImplemented ErrorCode = "not_implemented"  // Unrealized
	ErrUnavailable    ErrorCode = "unavailable"      // Service Unavailable
	ErrTimeout        ErrorCode = "timeout"          // Timeout
	ErrDependency     ErrorCode = "dependency_error" // Dependency Service Error
)

type ErrorOption added in v1.2.1 

type ErrorOption func(*ToolError)

func WithCause added in v1.2.1 

func WithCause(cause error) ErrorOption

func WithDetail added in v1.2.1 

func WithDetail(key string, value interface{}) ErrorOption

type GetPromptRequest added in v1.2.0 

type GetPromptRequest struct {
	Session *ServerSession
	Params  *protocol.GetPromptParams
}

type MetricsCollector added in v1.2.1 

type MetricsCollector interface {
	RecordToolCall(tool string, duration time.Duration, success bool)
}

MetricsCollector 指标收集器接口

type Middleware added in v1.2.1 

type Middleware func(ToolHandler) ToolHandler

func AuthMiddleware added in v1.2.1 

func AuthMiddleware(validator AuthValidator) Middleware

AuthMiddleware 认证中间件

func LoggingMiddleware added in v1.2.1 

func LoggingMiddleware(logger *slog.Logger) Middleware

LoggingMiddleware 日志中间件

func MetricsMiddleware added in v1.2.1 

func MetricsMiddleware(collector MetricsCollector) Middleware

MetricsMiddleware 指标中间件

func RateLimitMiddleware added in v1.2.1 

func RateLimitMiddleware(limiter RateLimiter) Middleware

RateLimitMiddleware 速率限制中间件

func RecoveryMiddleware added in v1.2.1 

func RecoveryMiddleware() Middleware

RecoveryMiddleware 恢复中间件

func RetryMiddleware added in v1.2.1 

func RetryMiddleware(maxRetries int, shouldRetry func(error) bool) Middleware

RetryMiddleware 重试中间件

func TimeoutMiddleware added in v1.2.1 

func TimeoutMiddleware(timeout time.Duration) Middleware

TimeoutMiddleware 超时中间件

func ValidationMiddleware added in v1.2.1 

func ValidationMiddleware(validator ParamsValidator) Middleware

ValidationMiddleware 参数验证中间件

type ParamsValidator added in v1.2.1 

type ParamsValidator interface {
	Validate(tool string, arguments map[string]any) error
}

type PromptHandler 

type PromptHandler func(ctx context.Context, req *GetPromptRequest) (*protocol.GetPromptResult, error)

type RateLimiter added in v1.2.1 

type RateLimiter interface {
	Allow(tool string) bool
}

RateLimiter 速率限制器接口

type ReadResourceRequest added in v1.2.0 

type ReadResourceRequest struct {
	Session *ServerSession
	Params  *protocol.ReadResourceParams
}

type ResourceHandler 

type ResourceHandler func(ctx context.Context, req *ReadResourceRequest) (*protocol.ReadResourceResult, error)

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server MCP服务器实例, 可以服务一个或多个 MCP 会话

func NewServer 

func NewServer(impl *protocol.ServerInfo, opts *ServerOptions) *Server

func (*Server) AddPrompt added in v1.2.0 

func (s *Server) AddPrompt(p *protocol.Prompt, h PromptHandler)

func (*Server) AddResource added in v1.2.0 

func (s *Server) AddResource(r *protocol.Resource, h ResourceHandler)

func (*Server) AddResourceTemplate added in v1.2.0 

func (s *Server) AddResourceTemplate(t *protocol.ResourceTemplate, h ResourceHandler)

func (*Server) AddTool added in v1.2.0 

func (s *Server) AddTool(t *protocol.Tool, h ToolHandler)

AddTool 添加工具到服务器，或替换同名工具（低级 API）。 Tool 参数在调用后不得修改。

工具的输入 schema 必须非 nil 且类型为 "object"。对于不接受输入的工具， 或接受任何输入的工具，将 [Tool.InputSchema] 设置为 `{"type": "object"}`， 使用你喜欢的库或 `json.RawMessage`。

如果存在 [Tool.OutputSchema]，它也必须类型为 "object"。

当处理函数作为 CallTool 请求的一部分被调用时，req.Params.Arguments 将是 json.RawMessage。

反序列化参数并根据输入 schema 验证它们是调用者的责任。

根据输出 schema（如有）验证结果是调用者的责任。

设置结果的 Content、StructuredContent 和 IsError 字段是调用者的责任。

大多数用户应该使用顶级函数 AddTool，它会处理所有这些责任。

func (*Server) Connect added in v1.2.0 

func (s *Server) Connect(ctx context.Context, t transport.Transport, opts *ServerSessionOptions) (*ServerSession, error)

Connect 通过给定的 transport 连接 MCP 服务器并开始处理消息

它返回一个连接对象,可用于终止连接(使用 Close)或等待客户端终止(使用 Wait)

func (*Server) HandleMessage 

func (s *Server) HandleMessage(ctx context.Context, msg *protocol.JSONRPCMessage) (*protocol.JSONRPCMessage, error)

HandleMessage 实现 SSE Handler 接口 (用于向后兼容)

func (*Server) NotifyResourceUpdated added in v1.2.2 

func (s *Server) NotifyResourceUpdated(uri string)

NotifyResourceUpdated 通知订阅了指定资源的所有会话,该资源已更新 只有之前调用 resources/subscribe 订阅了此 URI 的客户端会收到通知

func (*Server) RemovePrompt added in v1.2.0 

func (s *Server) RemovePrompt(name string)

func (*Server) RemoveResource added in v1.2.0 

func (s *Server) RemoveResource(uri string)

func (*Server) RemoveResourceTemplate added in v1.2.0 

func (s *Server) RemoveResourceTemplate(uriTemplate string)

func (*Server) RemoveTool added in v1.2.0 

func (s *Server) RemoveTool(name string)

func (*Server) Run added in v1.2.0 

func (s *Server) Run(ctx context.Context, t transport.Transport) error

Run 在给定的 transport 上运行服务器 这是一个便捷方法,用于处理单个会话(或一次一个会话)

Run 会阻塞直到客户端终止连接或提供的 context 被取消 如果 context 被取消,Run 会关闭连接

func (*Server) Use added in v1.2.1 

func (s *Server) Use(middleware ...Middleware)

Use 添加中间件到 Server 中间件按添加顺序执行（洋葱模型）

type ServerOptions added in v1.2.0 

type ServerOptions struct {
	// 可选的客户端指令
	Instructions string

	// 初始化处理函数
	InitializedHandler func(context.Context, *ServerSession)

	// 进度通知处理函数
	ProgressNotificationHandler func(context.Context, *ServerSession, *protocol.ProgressNotificationParams)

	// 补全处理函数
	CompletionHandler func(context.Context, *protocol.CompleteRequest) (*protocol.CompleteResult, error)

	// 日志级别设置处理函数
	LoggingSetLevelHandler func(context.Context, *ServerSession, protocol.LoggingLevel) error

	// 资源订阅/取消订阅处理函数
	SubscribeHandler   func(context.Context, *protocol.SubscribeParams) error
	UnsubscribeHandler func(context.Context, *protocol.UnsubscribeParams) error

	// KeepAlive 定义定期 "ping" 请求的间隔
	// 如果对等方未能响应 keepalive 检查发起的 ping,会话将自动关闭
	KeepAlive time.Duration
}

type ServerSession added in v1.2.0 

type ServerSession struct {
	// contains filtered or unexported fields
}

ServerSession 表示一个服务器会话, 每个客户端连接对应一个 ServerSession

func (*ServerSession) Close added in v1.2.0 

func (ss *ServerSession) Close() error

func (*ServerSession) CreateMessage added in v1.2.0 

func (ss *ServerSession) CreateMessage(ctx context.Context, params *protocol.CreateMessageParams) (*protocol.CreateMessageResult, error)

CreateMessage 发送采样请求到客户端

func (*ServerSession) Elicit added in v1.2.0 

func (ss *ServerSession) Elicit(ctx context.Context, params *protocol.ElicitationCreateParams) (*protocol.ElicitationResult, error)

Elicit 发送 elicitation 请求到客户端,请求用户输入

func (*ServerSession) ID added in v1.2.0 

func (ss *ServerSession) ID() string

func (*ServerSession) InitializeParams added in v1.2.0 

func (ss *ServerSession) InitializeParams() *protocol.InitializeParams

InitializeParams 返回初始化参数

func (*ServerSession) ListRoots added in v1.2.0 

func (ss *ServerSession) ListRoots(ctx context.Context) (*protocol.ListRootsResult, error)

ListRoots 列出客户端根目录

func (*ServerSession) Log added in v1.2.0 

func (ss *ServerSession) Log(ctx context.Context, params *protocol.LoggingMessageParams) error

Log 发送日志消息到客户端

func (*ServerSession) NotifyProgress added in v1.2.0 

func (ss *ServerSession) NotifyProgress(ctx context.Context, params *protocol.ProgressNotificationParams) error

NotifyProgress 发送进度通知到客户端

func (*ServerSession) Ping added in v1.2.0 

func (ss *ServerSession) Ping(ctx context.Context) error

Ping 发送 ping 请求到客户端

func (*ServerSession) Wait added in v1.2.0 

func (ss *ServerSession) Wait() error

Wait 等待会话结束, 返回会话结束的错误

type ServerSessionOptions added in v1.2.0 

type ServerSessionOptions struct {
	State *ServerSessionState
	// contains filtered or unexported fields
}

type ServerSessionState added in v1.2.0 

type ServerSessionState struct {
	// InitializeParams 来自 initialize 请求的参数
	InitializeParams *protocol.InitializeParams

	// InitializedParams 来自 notifications/initialized 的参数
	InitializedParams *protocol.InitializedParams

	// LogLevel 日志级别
	LogLevel protocol.LoggingLevel
}

ServerSessionState 会话状态

type ToolError added in v1.2.1 

type ToolError struct {
	Code    ErrorCode
	Message string
	Details map[string]interface{}
	Cause   error
}

func ConflictError added in v1.2.1 

func ConflictError(message string, opts ...ErrorOption) *ToolError

func DependencyError added in v1.2.1 

func DependencyError(service string, err error, opts ...ErrorOption) *ToolError

func ForbiddenError added in v1.2.1 

func ForbiddenError(message string, opts ...ErrorOption) *ToolError

func InternalError added in v1.2.1 

func InternalError(message string, opts ...ErrorOption) *ToolError

func InvalidParamsError added in v1.2.1 

func InvalidParamsError(message string, opts ...ErrorOption) *ToolError

func NewToolError added in v1.2.1 

func NewToolError(code ErrorCode, message string, opts ...ErrorOption) *ToolError

func NotFoundError added in v1.2.1 

func NotFoundError(resource string, opts ...ErrorOption) *ToolError

func NotImplementedError added in v1.2.1 

func NotImplementedError(message string, opts ...ErrorOption) *ToolError

func TimeoutError added in v1.2.1 

func TimeoutError(message string, opts ...ErrorOption) *ToolError

func UnauthorizedError added in v1.2.1 

func UnauthorizedError(message string, opts ...ErrorOption) *ToolError

func UnavailableError added in v1.2.1 

func UnavailableError(message string, opts ...ErrorOption) *ToolError

func (*ToolError) Error added in v1.2.1 

func (e *ToolError) Error() string

Error Implement the error interface

func (*ToolError) ToResult added in v1.2.1 

func (e *ToolError) ToResult() *protocol.CallToolResult

func (*ToolError) Unwrap added in v1.2.1 

func (e *ToolError) Unwrap() error

Unwrap Implement errors.Unwrap

type ToolHandler 

type ToolHandler func(ctx context.Context, req *CallToolRequest) (*protocol.CallToolResult, error)

ToolHandler 工具处理函数 接收 CallToolRequest,可以通过 req.Session 发送通知

type ToolHandlerFor added in v1.2.1 

type ToolHandlerFor[In, Out any] func(
	ctx context.Context,
	req *CallToolRequest,
	input In,
) (result *protocol.CallToolResult, output Out, err error)

ToolHandlerFor 是一个处理 tools/call 请求的类型安全处理函数。

与 ToolHandler 不同，ToolHandlerFor 提供了大量开箱即用的功能， 并强制工具符合 MCP 规范：

  • In 类型为工具提供默认的输入 schema（可在 AddTool 中覆盖）
  • 输入值会自动从 req.Params.Arguments 反序列化
  • 输入值会自动根据其 schema 进行验证，无效输入在到达处理函数前就被拒绝
  • 如果 Out 类型不是 [any]，它会为工具提供默认的输出 schema（同样可覆盖）
  • Out 值用于填充 result.StructuredContent
  • 如果 [CallToolResult.Content] 未设置，它会用输出的 JSON 内容填充
  • 错误结果被视为工具错误而非协议错误，因此会被打包到 CallToolResult.Content 中， 并设置 IsError 标志

因此，大多数用户可以完全忽略 CallToolRequest 参数和 [CallToolResult] 返回值。 实际上，如果你只关心返回输出值或错误，返回 nil CallToolResult 也是允许的。 有效结果会按上述描述自动填充。

使用 AddTool 将 ToolHandlerFor 添加到服务器。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.