server

package
v0.0.0-...-5dfb09d Latest Latest
Warning

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

 Go to latest Published: Jan 28, 2026 License: Apache-2.0 Imports: 12 Imported by: 6

Documentation

Overview

Package server contains the *protocol-level* abstractions that make up the “server side” of the Model Context Protocol (MCP).

The MCP specification itself calls this role “server”. Within the code we expose a Handler interface (plus DefaultHandler) to emphasise that this component handles already-decoded JSON-RPC requests, while a separate transport layer (in another module) is responsible for listening on HTTP, stdio, WebSockets, etc.

A Handler typically embeds DefaultHandler and selectively overrides the Operations it needs. The package is intentionally transport-agnostic so it can be reused by different listener implementations.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrSamplingNotSupported is returned when the client doesn't support sampling
	ErrSamplingNotSupported = errors.New("client does not support sampling")
	// ErrElicitationNotSupported is returned when the client doesn't support elicitation
	ErrElicitationNotSupported = errors.New("client does not support elicitation")
)

Functions

func RegisterResource 

func RegisterResource[I any](registry *Registry, resource schema.Resource, handler func(ctx context.Context, uri string) (*schema.ReadResourceResult, *jsonrpc.Error))

RegisterResource registers a resource using a typed handler that returns a Go struct. The struct will be JSON-marshaled into the ReadResourceResult.Contents field.

func RegisterTool 

func RegisterTool[I any, O any](registry *Registry, name, description string, handler func(ctx context.Context, input I) (*schema.CallToolResult, *jsonrpc.Error)) error

RegisterTool derives JSON schemas from the generic I/O types and registers the tool.

Types

type DefaultHandler 

type DefaultHandler struct {
	Notifier           transport.Notifier
	Logger             logger.Logger
	Client             client.Operations
	ClientInitialize   *schema.InitializeRequestParams
	Subscription       *syncmap.Map[string, bool]
	ServerCapabilities *schema.ServerCapabilities
	// Configuration for listChanged capabilities
	ToolsListChanged     *bool
	ResourcesListChanged *bool
	PromptsListChanged   *bool
	*Registry
}

DefaultHandler provides default implementations for server-side methods. You can embed this in your own Handler and register tools/resources via its helper methods.

func NewDefaultHandler 

func NewDefaultHandler(notifier transport.Notifier, logger logger.Logger, client client.Operations) *DefaultHandler

NewDefaultHandler creates a new DefaultHandler with initialized registries. You can then call RegisterResource, RegisterTool, etc., on it before running the server.

func (*DefaultHandler) CallTool 

func (d *DefaultHandler) CallTool(ctx context.Context, jRequest *jsonrpc.TypedRequest[*schema.CallToolRequest]) (*schema.CallToolResult, *jsonrpc.Error)

CallTool returns method-not-found by default.

func (*DefaultHandler) CanElicit 

func (d *DefaultHandler) CanElicit() bool

CanElicit checks if the client supports elicitation

func (*DefaultHandler) CanSample 

func (d *DefaultHandler) CanSample() bool

CanSample checks if the client supports sampling

func (*DefaultHandler) Complete 

func (d *DefaultHandler) Complete(ctx context.Context, jRequest *jsonrpc.TypedRequest[*schema.CompleteRequest]) (*schema.CompleteResult, *jsonrpc.Error)

Complete returns method-not-found by default.

func (*DefaultHandler) GetElicitationCapability 

func (d *DefaultHandler) GetElicitationCapability() *schema.ElicitationCapability

GetElicitationCapability returns the client's elicitation capability if available

func (*DefaultHandler) GetPrompt 

func (d *DefaultHandler) GetPrompt(ctx context.Context, jRequest *jsonrpc.TypedRequest[*schema.GetPromptRequest]) (*schema.GetPromptResult, *jsonrpc.Error)

GetPrompt returns the result of a prompt call.

func (*DefaultHandler) GetSamplingCapability 

func (d *DefaultHandler) GetSamplingCapability() *schema.SamplingCapability

GetSamplingCapability returns the client's sampling capability if available

func (*DefaultHandler) Implements 

func (d *DefaultHandler) Implements(method string) bool

Implements returns true for supported methods.

func (*DefaultHandler) Initialize 

func (d *DefaultHandler) Initialize(ctx context.Context, init *schema.InitializeRequestParams, result *schema.InitializeResult)

Initialize stores the initialization parameters.

func (*DefaultHandler) ListPrompts 

func (d *DefaultHandler) ListPrompts(ctx context.Context, jRequest *jsonrpc.TypedRequest[*schema.ListPromptsRequest]) (*schema.ListPromptsResult, *jsonrpc.Error)

ListPrompts lists all registered prompts on this DefaultHandler.

func (*DefaultHandler) ListResourceTemplates 

func (d *DefaultHandler) ListResourceTemplates(ctx context.Context, request *jsonrpc.TypedRequest[*schema.ListResourceTemplatesRequest]) (*schema.ListResourceTemplatesResult, *jsonrpc.Error)

ListResourceTemplates returns method-not-found by default.

func (*DefaultHandler) ListResources 

func (d *DefaultHandler) ListResources(ctx context.Context, request *jsonrpc.TypedRequest[*schema.ListResourcesRequest]) (*schema.ListResourcesResult, *jsonrpc.Error)

ListResources returns method-not-found by default.

func (*DefaultHandler) ListTools 

func (d *DefaultHandler) ListTools(ctx context.Context, jRequest *jsonrpc.TypedRequest[*schema.ListToolsRequest]) (*schema.ListToolsResult, *jsonrpc.Error)

ListTools returns method-not-found by default.

func (*DefaultHandler) OnNotification 

func (d *DefaultHandler) OnNotification(ctx context.Context, notification *jsonrpc.Notification)

OnNotification is a no-op by default.

func (*DefaultHandler) ReadResource 

func (d *DefaultHandler) ReadResource(ctx context.Context, jRequest *jsonrpc.TypedRequest[*schema.ReadResourceRequest]) (*schema.ReadResourceResult, *jsonrpc.Error)

ReadResource returns method-not-found by default.

func (*DefaultHandler) Subscribe 

func (d *DefaultHandler) Subscribe(ctx context.Context, jRequest *jsonrpc.TypedRequest[*schema.SubscribeRequest]) (*schema.SubscribeResult, *jsonrpc.Error)

Subscribe adds the URI to the subscription map.

func (*DefaultHandler) SupportsElicitationMode 

func (d *DefaultHandler) SupportsElicitationMode(mode string) bool

SupportsElicitationMode checks if the client supports the specified mode

func (*DefaultHandler) Unsubscribe 

func (d *DefaultHandler) Unsubscribe(ctx context.Context, jRequest *jsonrpc.TypedRequest[*schema.UnsubscribeRequest]) (*schema.UnsubscribeResult, *jsonrpc.Error)

Unsubscribe removes the URI from the subscription map.

type Handler 

type Handler interface {
	Operations

	OnNotification(ctx context.Context, notification *jsonrpc.Notification)

	// Implements checks if the method is implemented.
	Implements(method string) bool
}

Handler represents a protocol implementer.

type NewHandler 

type NewHandler func(ctx context.Context, notifier transport.Notifier, logger logger.Logger, client client.Operations) (Handler, error)

NewHandler creates new handler implementer.

func WithDefaultHandler 

func WithDefaultHandler(ctx context.Context, options ...Option) NewHandler

type Operations 

type Operations interface {
	Initialize(ctx context.Context, init *schema.InitializeRequestParams, result *schema.InitializeResult)

	ListResources(ctx context.Context, request *jsonrpc.TypedRequest[*schema.ListResourcesRequest]) (*schema.ListResourcesResult, *jsonrpc.Error)

	ListResourceTemplates(ctx context.Context, request *jsonrpc.TypedRequest[*schema.ListResourceTemplatesRequest]) (*schema.ListResourceTemplatesResult, *jsonrpc.Error)

	ReadResource(ctx context.Context, request *jsonrpc.TypedRequest[*schema.ReadResourceRequest]) (*schema.ReadResourceResult, *jsonrpc.Error)

	Subscribe(ctx context.Context, request *jsonrpc.TypedRequest[*schema.SubscribeRequest]) (*schema.SubscribeResult, *jsonrpc.Error)

	Unsubscribe(ctx context.Context, request *jsonrpc.TypedRequest[*schema.UnsubscribeRequest]) (*schema.UnsubscribeResult, *jsonrpc.Error)

	ListTools(ctx context.Context, request *jsonrpc.TypedRequest[*schema.ListToolsRequest]) (*schema.ListToolsResult, *jsonrpc.Error)

	CallTool(ctx context.Context, request *jsonrpc.TypedRequest[*schema.CallToolRequest]) (*schema.CallToolResult, *jsonrpc.Error)

	ListPrompts(ctx context.Context, request *jsonrpc.TypedRequest[*schema.ListPromptsRequest]) (*schema.ListPromptsResult, *jsonrpc.Error)

	GetPrompt(ctx context.Context, request *jsonrpc.TypedRequest[*schema.GetPromptRequest]) (*schema.GetPromptResult, *jsonrpc.Error)

	Complete(ctx context.Context, request *jsonrpc.TypedRequest[*schema.CompleteRequest]) (*schema.CompleteResult, *jsonrpc.Error)
}

Operations lists all JSON-RPC methods that an MCP handler may implement.

type Option 

type Option func(server *DefaultHandler) error

Option can be supplied to WithDefaultHandler to mutate the handler before use.

type PromptEntry 

type PromptEntry struct {
	Handler PromptHandlerFunc
	Prompt  *schema.Prompt
}

PromptEntry holds a handler with its metadata.

type PromptHandlerFunc 

type PromptHandlerFunc func(ctx context.Context, request *schema.GetPromptRequestParams) (*schema.GetPromptResult, *jsonrpc.Error)

PromptHandlerFunc defines a function to handle a prompt call.

type Prompts 

type Prompts []*PromptEntry

Prompts is a collection of PromptEntry.

type Registry 

type Registry struct {
	ToolRegistry             *syncmap.Map[string, *ToolEntry]
	ResourceRegistry         *syncmap.Map[string, *ResourceEntry]
	ResourceTemplateRegistry *syncmap.Map[string, *ResourceTemplateEntry]
	Prompts                  *syncmap.Map[string, *PromptEntry]
	Methods                  *syncmap.Map[string, bool]
}

Registry holds registered tools, resources, prompts, etc. for a handler instance.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates and initialises an empty Registry.

func (*Registry) ListRegisteredResourceTemplates 

func (d *Registry) ListRegisteredResourceTemplates() []schema.ResourceTemplate

ListRegisteredResourceTemplates returns metadata for all registered resource templates on this handler.

func (*Registry) ListRegisteredResources 

func (d *Registry) ListRegisteredResources() []schema.Resource

ListRegisteredResources returns metadata for all registered resources on this handler.

func (*Registry) ListRegisteredTools 

func (d *Registry) ListRegisteredTools() []schema.Tool

ListRegisteredTools returns metadata for all registered tools.

func (*Registry) RegisterPrompts 

func (d *Registry) RegisterPrompts(prompt *schema.Prompt, handler PromptHandlerFunc)

RegisterPrompts registers a prompt on this handler.

func (*Registry) RegisterResource 

func (d *Registry) RegisterResource(resource schema.Resource, handler ResourceHandlerFunc)

RegisterResource registers a resource with metadata and handler on this handler.

func (*Registry) RegisterResourceTemplate 

func (d *Registry) RegisterResourceTemplate(template schema.ResourceTemplate, handler ResourceHandlerFunc)

RegisterResourceTemplate registers a resource template on this handler.

func (*Registry) RegisterTool 

func (d *Registry) RegisterTool(entry *ToolEntry)

RegisterTool adds a prepared ToolEntry to the registry.

func (*Registry) RegisterToolWithSchema 

func (d *Registry) RegisterToolWithSchema(name, description string, inputSchema schema.ToolInputSchema, outputSchema *schema.ToolOutputSchema, handler ToolHandlerFunc)

RegisterToolWithSchema registers a tool with an explicit JSON schema.

type ResourceEntry 

type ResourceEntry struct {
	Handler  ResourceHandlerFunc
	Metadata schema.Resource
}

ResourceEntry holds a handler with its metadata.

type ResourceHandlerFunc 

type ResourceHandlerFunc func(ctx context.Context, request *schema.ReadResourceRequest) (*schema.ReadResourceResult, *jsonrpc.Error)

ResourceHandlerFunc defines a function to handle a resource read.

type ResourceTemplateEntry 

type ResourceTemplateEntry struct {
	Metadata schema.ResourceTemplate
	Handler  ResourceHandlerFunc
}

ResourceTemplateEntry holds metadata for a resource template.

type ToolEntry 

type ToolEntry struct {
	Handler  ToolHandlerFunc
	Metadata schema.Tool
}

ToolEntry holds a handler together with its public metadata.

type ToolHandlerFunc 

type ToolHandlerFunc func(ctx context.Context, request *schema.CallToolRequest) (*schema.CallToolResult, *jsonrpc.Error)

ToolHandlerFunc defines a function to handle a tool call.

type Tools 

type Tools []*ToolEntry

Tools is a collection of ToolEntry

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.