server

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Dec 7, 2025 License: Apache-2.0 Imports: 10 Imported by: 11

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

This section is empty.

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 added in v0.4.0 

type DefaultHandler struct {
	Notifier           transport.Notifier
	Logger             logger.Logger
	Client             client.Operations
	ClientInitialize   *schema.InitializeRequestParams
	Subscription       *syncmap.Map[string, bool]
	ServerCapabilities *schema.ServerCapabilities
	*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 added in v0.4.0 

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 added in v0.4.0 

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) Complete added in v0.4.0 

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) GetPrompt added in v0.4.0 

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) Implements added in v0.4.0 

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

Implements returns true for supported methods.

func (*DefaultHandler) Initialize added in v0.4.0 

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

Initialize stores the initialization parameters.

func (*DefaultHandler) ListPrompts added in v0.4.0 

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 added in v0.4.0 

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 added in v0.4.0 

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 added in v0.4.0 

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 added in v0.4.0 

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

OnNotification is a no-op by default.

func (*DefaultHandler) ReadResource added in v0.4.0 

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 added in v0.4.0 

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) Unsubscribe added in v0.4.0 

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 added in v0.4.0 

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 added in v0.4.0 

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

NewHandler creates new handler implementer.

func WithDefaultHandler added in v0.4.0 

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 added in v0.3.2 

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

PromptEntry holds a handler with its metadata.

type PromptHandlerFunc added in v0.3.2 

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

PromptHandlerFunc defines a function to handle a prompt call.

type Prompts added in v0.3.3 

type Prompts []*PromptEntry

Prompts is a collection of PromptEntry.

type Registry added in v0.3.3 

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 added in v0.3.4 

func NewRegistry() *Registry

NewRegistry creates and initialises an empty Registry.

func (*Registry) ListRegisteredResourceTemplates added in v0.3.3 

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

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

func (*Registry) ListRegisteredResources added in v0.3.3 

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

ListRegisteredResources returns metadata for all registered resources on this handler.

func (*Registry) ListRegisteredTools added in v0.3.3 

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

ListRegisteredTools returns metadata for all registered tools.

func (*Registry) RegisterPrompts added in v0.3.3 

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

RegisterPrompts registers a prompt on this handler.

func (*Registry) RegisterResource added in v0.3.3 

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

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

func (*Registry) RegisterResourceTemplate added in v0.3.3 

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

RegisterResourceTemplate registers a resource template on this handler.

func (*Registry) RegisterTool added in v0.3.4 

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

RegisterTool adds a prepared ToolEntry to the registry.

func (*Registry) RegisterToolWithSchema added in v0.3.3 

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 added in v0.3.3 

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.