registry

package
v0.26.0-rc.1 Latest Latest
Warning

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

 Go to latest Published: Dec 16, 2025 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MCPMethodInitialize             = "initialize"
	MCPMethodToolsList              = "tools/list"
	MCPMethodToolsCall              = "tools/call"
	MCPMethodResourcesList          = "resources/list"
	MCPMethodResourcesRead          = "resources/read"
	MCPMethodResourcesTemplatesList = "resources/templates/list"
	MCPMethodPromptsList            = "prompts/list"
	MCPMethodPromptsGet             = "prompts/get"
)

MCP method constants for use with ForMCPRequest.

Variables

This section is empty.

Functions

This section is empty.

Types

type Builder 

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

Builder builds a Registry with the specified configuration. Use NewBuilder to create a builder, chain configuration methods, then call Build() to create the final Registry.

Example: 

reg := NewBuilder().
    SetTools(tools).
    SetResources(resources).
    SetPrompts(prompts).
    WithDeprecatedAliases(aliases).
    WithReadOnly(true).
    WithToolsets([]string{"repos", "issues"}).
    WithFeatureChecker(checker).
    WithFilter(myFilter).
    Build()

func NewBuilder 

func NewBuilder() *Builder

NewBuilder creates a new Builder.

func (*Builder) Build 

func (b *Builder) Build() *Registry

Build creates the final Registry with all configuration applied. This processes toolset filtering, tool name resolution, and sets up the registry for use. The returned Registry is ready for use with AvailableTools(), RegisterAll(), etc.

func (*Builder) SetPrompts 

func (b *Builder) SetPrompts(prompts []ServerPrompt) *Builder

SetPrompts sets the prompts for the registry. Returns self for chaining.

func (*Builder) SetResources 

func (b *Builder) SetResources(resources []ServerResourceTemplate) *Builder

SetResources sets the resource templates for the registry. Returns self for chaining.

func (*Builder) SetTools 

func (b *Builder) SetTools(tools []ServerTool) *Builder

SetTools sets the tools for the registry. Returns self for chaining.

func (*Builder) WithDeprecatedAliases 

func (b *Builder) WithDeprecatedAliases(aliases map[string]string) *Builder

WithDeprecatedAliases adds deprecated tool name aliases that map to canonical names. Returns self for chaining.

func (*Builder) WithFeatureChecker 

func (b *Builder) WithFeatureChecker(checker FeatureFlagChecker) *Builder

WithFeatureChecker sets the feature flag checker function. The checker receives a context (for actor extraction) and feature flag name, returns (enabled, error). If error occurs, it will be logged and treated as false. If checker is nil, all feature flag checks return false. Returns self for chaining.

func (*Builder) WithFilter 

func (b *Builder) WithFilter(filter ToolFilter) *Builder

WithFilter adds a filter function that will be applied to all tools. Multiple filters can be added and are evaluated in order. If any filter returns false or an error, the tool is excluded. Returns self for chaining.

func (*Builder) WithReadOnly 

func (b *Builder) WithReadOnly(readOnly bool) *Builder

WithReadOnly sets whether only read-only tools should be available. When true, write tools are filtered out. Returns self for chaining.

func (*Builder) WithTools 

func (b *Builder) WithTools(toolNames []string) *Builder

WithTools specifies additional tools that bypass toolset filtering. These tools are additive - they will be included even if their toolset is not enabled. Read-only filtering still applies to these tools. Deprecated tool aliases are automatically resolved to their canonical names during Build(). Returns self for chaining.

func (*Builder) WithToolsets 

func (b *Builder) WithToolsets(toolsetIDs []string) *Builder

WithToolsets specifies which toolsets should be enabled. Special keywords:

  • "all": enables all toolsets
  • "default": expands to toolsets marked with Default: true in their metadata

Input strings are trimmed of whitespace and duplicates are removed. Pass nil to use default toolsets. Pass an empty slice to disable all toolsets (useful for dynamic toolsets mode where tools are enabled on demand). Returns self for chaining.

type FeatureFlagChecker 

type FeatureFlagChecker func(ctx context.Context, flagName string) (bool, error)

FeatureFlagChecker is a function that checks if a feature flag is enabled. The context can be used to extract actor/user information for flag evaluation. Returns (enabled, error). If error occurs, the caller should log and treat as false.

type HandlerFunc 

type HandlerFunc func(deps any) mcp.ToolHandler

HandlerFunc is a function that takes dependencies and returns an MCP tool handler. This allows tools to be defined statically while their handlers are generated on-demand with the appropriate dependencies. The deps parameter is typed as `any` to avoid circular dependencies - callers should define their own typed dependencies struct and type-assert as needed.

type Registry 

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

Registry holds a collection of tools, resources, and prompts with filtering applied. Create a Registry using Builder: 

reg := NewBuilder().
    SetTools(tools).
    WithReadOnly(true).
    WithToolsets([]string{"repos"}).
    Build()

The Registry is configured at build time and provides:

  • Filtered access to tools/resources/prompts via Available* methods
  • Deterministic ordering for documentation generation
  • Lazy dependency injection during registration via RegisterAll()
  • Runtime toolset enabling for dynamic toolsets mode

func (*Registry) AllTools 

func (r *Registry) AllTools() []ServerTool

AllTools returns all tools without any filtering, sorted deterministically.

func (*Registry) AvailablePrompts 

func (r *Registry) AvailablePrompts(ctx context.Context) []ServerPrompt

AvailablePrompts returns prompts that pass all current filters, sorted deterministically by toolset ID, then prompt name. The context is used for feature flag evaluation.

func (*Registry) AvailableResourceTemplates 

func (r *Registry) AvailableResourceTemplates(ctx context.Context) []ServerResourceTemplate

AvailableResourceTemplates returns resource templates that pass all current filters, sorted deterministically by toolset ID, then template name. The context is used for feature flag evaluation.

func (*Registry) AvailableTools 

func (r *Registry) AvailableTools(ctx context.Context) []ServerTool

AvailableTools returns the tools that pass all current filters, sorted deterministically by toolset ID, then tool name. The context is used for feature flag evaluation.

func (*Registry) AvailableToolsets 

func (r *Registry) AvailableToolsets(exclude ...ToolsetID) []ToolsetMetadata

AvailableToolsets returns the unique toolsets that have tools, in sorted order. This is the ordered intersection of toolsets with reality - only toolsets that actually contain tools are returned, sorted by toolset ID. Optional exclude parameter filters out specific toolset IDs from the result.

func (*Registry) DefaultToolsetIDs 

func (r *Registry) DefaultToolsetIDs() []ToolsetID

DefaultToolsetIDs returns the IDs of toolsets marked as Default in their metadata. The IDs are returned in sorted order for deterministic output.

func (*Registry) EnableToolset 

func (r *Registry) EnableToolset(toolsetID ToolsetID)

EnableToolset marks a toolset as enabled in this group. This is used by dynamic toolset management to track which toolsets have been enabled.

func (*Registry) EnabledToolsetIDs 

func (r *Registry) EnabledToolsetIDs() []ToolsetID

EnabledToolsetIDs returns the list of enabled toolset IDs based on current filters. Returns all toolset IDs if no filter is set.

func (*Registry) FilteredTools 

func (r *Registry) FilteredTools(ctx context.Context) ([]ServerTool, error)

FilteredTools returns tools filtered by the Enabled function and builder filters. This provides an explicit API for accessing filtered tools, currently implemented as an alias for AvailableTools.

The error return is currently always nil but is included for future extensibility. Library consumers (e.g., remote server implementations) may need to surface recoverable filter errors rather than silently logging them. Having the error return in the API now avoids breaking changes later.

The context is used for Enabled function evaluation and builder filter checks.

func (*Registry) FindToolByName 

func (r *Registry) FindToolByName(toolName string) (*ServerTool, ToolsetID, error)

FindToolByName searches all tools for one matching the given name. Returns the tool, its toolset ID, and an error if not found. This searches ALL tools regardless of filters.

func (*Registry) ForMCPRequest 

func (r *Registry) ForMCPRequest(method string, itemName string) *Registry

ForMCPRequest returns a Registry optimized for a specific MCP request. This is designed for servers that create a new instance per request (like the remote server), allowing them to only register the items needed for that specific request rather than all ~90 tools.

Parameters:

  • method: The MCP method being called (use MCP* constants)
  • itemName: Name of specific item for call/get methods (tool name, resource URI, or prompt name)

Returns a new Registry containing only the items relevant to the request:

  • MCPMethodInitialize: Empty (capabilities are set via ServerOptions, not registration)
  • MCPMethodToolsList: All available tools (no resources/prompts)
  • MCPMethodToolsCall: Only the named tool
  • MCPMethodResourcesList, MCPMethodResourcesTemplatesList: All available resources (no tools/prompts)
  • MCPMethodResourcesRead: Only the named resource template
  • MCPMethodPromptsList: All available prompts (no tools/resources)
  • MCPMethodPromptsGet: Only the named prompt
  • Unknown methods: Empty (no items registered)

All existing filters (read-only, toolsets, etc.) still apply to the returned items.

func (*Registry) HasToolset 

func (r *Registry) HasToolset(toolsetID ToolsetID) bool

HasToolset checks if any tool/resource/prompt belongs to the given toolset.

func (*Registry) IsToolsetEnabled 

func (r *Registry) IsToolsetEnabled(toolsetID ToolsetID) bool

IsToolsetEnabled checks if a toolset is currently enabled based on filters.

func (*Registry) RegisterAll 

func (r *Registry) RegisterAll(ctx context.Context, s *mcp.Server, deps any)

RegisterAll registers all available tools, resources, and prompts with the server. The context is used for feature flag evaluation.

func (*Registry) RegisterPrompts 

func (r *Registry) RegisterPrompts(ctx context.Context, s *mcp.Server)

RegisterPrompts registers all available prompts with the server. The context is used for feature flag evaluation.

func (*Registry) RegisterResourceTemplates 

func (r *Registry) RegisterResourceTemplates(ctx context.Context, s *mcp.Server, deps any)

RegisterResourceTemplates registers all available resource templates with the server. The context is used for feature flag evaluation.

func (*Registry) RegisterTools 

func (r *Registry) RegisterTools(ctx context.Context, s *mcp.Server, deps any)

RegisterTools registers all available tools with the server using the provided dependencies. The context is used for feature flag evaluation.

func (*Registry) ResolveToolAliases 

func (r *Registry) ResolveToolAliases(toolNames []string) (resolved []string, aliasesUsed map[string]string)

ResolveToolAliases resolves deprecated tool aliases to their canonical names. It logs a warning to stderr for each deprecated alias that is resolved. Returns:

  • resolved: tool names with aliases replaced by canonical names
  • aliasesUsed: map of oldName → newName for each alias that was resolved

func (*Registry) ToolsForToolset 

func (r *Registry) ToolsForToolset(toolsetID ToolsetID) []ServerTool

ToolsForToolset returns all tools belonging to a specific toolset. This method bypasses the toolset enabled filter (for dynamic toolset registration), but still respects the read-only filter.

func (*Registry) ToolsetDescriptions 

func (r *Registry) ToolsetDescriptions() map[ToolsetID]string

ToolsetDescriptions returns a map of toolset ID to description for all toolsets.

func (*Registry) ToolsetIDs 

func (r *Registry) ToolsetIDs() []ToolsetID

ToolsetIDs returns a sorted list of unique toolset IDs from all tools in this group.

func (*Registry) UnrecognizedToolsets 

func (r *Registry) UnrecognizedToolsets() []string

UnrecognizedToolsets returns toolset IDs that were passed to WithToolsets but don't match any registered toolsets. This is useful for warning users about typos.

type ResourceHandlerFunc 

type ResourceHandlerFunc func(deps any) mcp.ResourceHandler

ResourceHandlerFunc is a function that takes dependencies and returns an MCP resource handler. This allows resources to be defined statically while their handlers are generated on-demand with the appropriate dependencies.

type ServerPrompt 

type ServerPrompt struct {
	Prompt  mcp.Prompt
	Handler mcp.PromptHandler
	// Toolset identifies which toolset this prompt belongs to
	Toolset ToolsetMetadata
	// FeatureFlagEnable specifies a feature flag that must be enabled for this prompt
	// to be available. If set and the flag is not enabled, the prompt is omitted.
	FeatureFlagEnable string
	// FeatureFlagDisable specifies a feature flag that, when enabled, causes this prompt
	// to be omitted. Used to disable prompts when a feature flag is on.
	FeatureFlagDisable string
}

ServerPrompt pairs a prompt with its toolset metadata.

func NewServerPrompt 

func NewServerPrompt(toolset ToolsetMetadata, prompt mcp.Prompt, handler mcp.PromptHandler) ServerPrompt

NewServerPrompt creates a new ServerPrompt with toolset metadata.

type ServerResourceTemplate 

type ServerResourceTemplate struct {
	Template mcp.ResourceTemplate
	// HandlerFunc generates the handler when given dependencies.
	// This allows resources to be passed around without handlers being set up,
	// and handlers are only created when needed.
	HandlerFunc ResourceHandlerFunc
	// Toolset identifies which toolset this resource belongs to
	Toolset ToolsetMetadata
	// FeatureFlagEnable specifies a feature flag that must be enabled for this resource
	// to be available. If set and the flag is not enabled, the resource is omitted.
	FeatureFlagEnable string
	// FeatureFlagDisable specifies a feature flag that, when enabled, causes this resource
	// to be omitted. Used to disable resources when a feature flag is on.
	FeatureFlagDisable string
}

ServerResourceTemplate pairs a resource template with its toolset metadata.

func NewServerResourceTemplate 

func NewServerResourceTemplate(toolset ToolsetMetadata, resourceTemplate mcp.ResourceTemplate, handlerFn ResourceHandlerFunc) ServerResourceTemplate

NewServerResourceTemplate creates a new ServerResourceTemplate with toolset metadata.

func (*ServerResourceTemplate) Handler 

func (sr *ServerResourceTemplate) Handler(deps any) mcp.ResourceHandler

Handler returns a resource handler by calling HandlerFunc with the given dependencies. Panics if HandlerFunc is nil - all resources should have handlers.

func (*ServerResourceTemplate) HasHandler 

func (sr *ServerResourceTemplate) HasHandler() bool

HasHandler returns true if this resource has a handler function.

type ServerTool 

type ServerTool struct {
	// Tool is the MCP tool definition containing name, description, schema, etc.
	Tool mcp.Tool

	// Toolset contains metadata about which toolset this tool belongs to.
	Toolset ToolsetMetadata

	// HandlerFunc generates the handler when given dependencies.
	// This allows tools to be passed around without handlers being set up,
	// and handlers are only created when needed.
	HandlerFunc HandlerFunc

	// FeatureFlagEnable specifies a feature flag that must be enabled for this tool
	// to be available. If set and the flag is not enabled, the tool is omitted.
	FeatureFlagEnable string

	// FeatureFlagDisable specifies a feature flag that, when enabled, causes this tool
	// to be omitted. Used to disable tools when a feature flag is on.
	FeatureFlagDisable string

	// Enabled is an optional function called at build/filter time to determine
	// if this tool should be available. If nil, the tool is considered enabled
	// (subject to FeatureFlagEnable/FeatureFlagDisable checks).
	// The context carries request-scoped information for the consumer to use.
	// Returns (enabled, error). On error, the tool should be treated as disabled.
	Enabled func(ctx context.Context) (bool, error)
}

ServerTool represents an MCP tool with metadata and a handler generator function. The tool definition is static, while the handler is generated on-demand when the tool is registered with a server. Tools are now self-describing with their toolset membership and read-only status derived from the Tool.Annotations.ReadOnlyHint field.

func NewServerTool 

func NewServerTool[In any, Out any](tool mcp.Tool, toolset ToolsetMetadata, handlerFn func(deps any) mcp.ToolHandlerFor[In, Out]) ServerTool

NewServerTool creates a ServerTool from a tool definition, toolset metadata, and a typed handler function. The handler function takes dependencies (as any) and returns a typed handler. Callers should type-assert deps to their typed dependencies struct.

func NewServerToolFromHandler 

func NewServerToolFromHandler(tool mcp.Tool, toolset ToolsetMetadata, handlerFn func(deps any) mcp.ToolHandler) ServerTool

NewServerToolFromHandler creates a ServerTool from a tool definition, toolset metadata, and a raw handler function. Use this when you have a handler that already conforms to mcp.ToolHandler.

func (*ServerTool) Handler 

func (st *ServerTool) Handler(deps any) mcp.ToolHandler

Handler returns a tool handler by calling HandlerFunc with the given dependencies. Panics if HandlerFunc is nil - all tools should have handlers.

func (*ServerTool) HasHandler 

func (st *ServerTool) HasHandler() bool

HasHandler returns true if this tool has a handler function.

func (*ServerTool) IsReadOnly 

func (st *ServerTool) IsReadOnly() bool

IsReadOnly returns true if this tool is marked as read-only via annotations.

func (*ServerTool) RegisterFunc 

func (st *ServerTool) RegisterFunc(s *mcp.Server, deps any)

RegisterFunc registers the tool with the server using the provided dependencies. Panics if the tool has no handler - all tools should have handlers.

type ToolDoesNotExistError 

type ToolDoesNotExistError struct {
	Name string
}

ToolDoesNotExistError is returned when a tool is not found.

func NewToolDoesNotExistError 

func NewToolDoesNotExistError(name string) *ToolDoesNotExistError

NewToolDoesNotExistError creates a new ToolDoesNotExistError.

func (*ToolDoesNotExistError) Error 

func (e *ToolDoesNotExistError) Error() string

type ToolFilter 

type ToolFilter func(ctx context.Context, tool *ServerTool) (bool, error)

ToolFilter is a function that determines if a tool should be included. Returns true if the tool should be included, false to exclude it.

type ToolsetDoesNotExistError 

type ToolsetDoesNotExistError struct {
	Name string
}

ToolsetDoesNotExistError is returned when a toolset is not found.

func NewToolsetDoesNotExistError 

func NewToolsetDoesNotExistError(name string) *ToolsetDoesNotExistError

NewToolsetDoesNotExistError creates a new ToolsetDoesNotExistError.

func (*ToolsetDoesNotExistError) Error 

func (e *ToolsetDoesNotExistError) Error() string

func (*ToolsetDoesNotExistError) Is 

func (e *ToolsetDoesNotExistError) Is(target error) bool

type ToolsetID 

type ToolsetID string

ToolsetID is a unique identifier for a toolset. Using a distinct type provides compile-time type safety.

type ToolsetMetadata 

type ToolsetMetadata struct {
	// ID is the unique identifier for the toolset (e.g., "repos", "issues")
	ID ToolsetID
	// Description provides a human-readable description of the toolset
	Description string
	// Default indicates this toolset should be enabled by default
	Default bool
}

ToolsetMetadata contains metadata about the toolset a tool belongs to.

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.