aggregator

Documentation

Index

• type Aggregator
  • func New(cfg *Config) (*Aggregator, error)
  • func NewFromFile(path string) (*Aggregator, error)
  • func (a *Aggregator) Backends() *BackendManager
  • func (a *Aggregator) CallTool(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error)
  • func (a *Aggregator) Config() *Config
  • func (a *Aggregator) Namespace() *Namespace
  • func (a *Aggregator) Run(ctx context.Context) error
  • func (a *Aggregator) Start(ctx context.Context) error
  • func (a *Aggregator) Stop() error
  • func (a *Aggregator) ToolCount() int
  • func (a *Aggregator) Tools() []mcp.Tool
• type AggregatorConfig
• type Backend
  • func (b *Backend) CallTool(ctx context.Context, name string, args map[string]any) (*mcp.CallToolResult, error)
  • func (b *Backend) ID() string
  • func (b *Backend) Name() string
  • func (b *Backend) Tools() []*mcp.Tool
• type BackendConfig
• type BackendError
  • func (e *BackendError) Error() string
  • func (e *BackendError) Unwrap() error
• type BackendManager
  • func NewBackendManager(cfg *Config) *BackendManager
  • func (m *BackendManager) Close() error
  • func (m *BackendManager) Connect(ctx context.Context) error
  • func (m *BackendManager) GetBackend(id string) (*Backend, bool)
• type Config
  • func DefaultConfig() *Config
  • func LoadConfig(path string) (*Config, error)
  • func (c *Config) Validate() error
• type ConfigError
  • func (e *ConfigError) Error() string
• type ConnectionConfig
• type Namespace
  • func NewNamespace(separator string) *Namespace
  • func (n *Namespace) AddTools(backendID string, tools []*mcp.Tool, filter *ToolFilterConfig)
  • func (n *Namespace) AllTools() []mcp.Tool
  • func (n *Namespace) Count() int
  • func (n *Namespace) GetTool(namespacedName string) (*NamespacedTool, bool)
• type NamespacedTool
• type RoutingError
  • func (e *RoutingError) Error() string
• type Server
  • func NewServer(cfg *Config, namespace *Namespace, backends *BackendManager) *Server
  • func (s *Server) CallTool(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error)
  • func (s *Server) MCPServer() *mcp.Server
  • func (s *Server) Run(ctx context.Context, transport mcp.Transport) error
• type ToolFilterConfig
• type ToolNotFoundError
  • func (e *ToolNotFoundError) Error() string
• type TransportConfig

Types

type Aggregator

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

Aggregator orchestrates backend connections, namespacing, and the MCP server.

func New

func New(cfg *Config) (*Aggregator, error)

New creates a new Aggregator from configuration.

func NewFromFile

func NewFromFile(path string) (*Aggregator, error)

NewFromFile creates a new Aggregator by loading configuration from a YAML file.

func (*Aggregator) Backends

func (a *Aggregator) Backends() *BackendManager

Backends returns the backend manager for inspection.

func (*Aggregator) CallTool

func (a *Aggregator) CallTool(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error)

CallTool invokes a tool by its namespaced name.

func (*Aggregator) Config

func (a *Aggregator) Config() *Config

Config returns the aggregator configuration.

func (*Aggregator) Namespace

func (a *Aggregator) Namespace() *Namespace

Namespace returns the aggregator's namespace for inspection.

func (*Aggregator) Run

func (a *Aggregator) Run(ctx context.Context) error

Run starts the MCP server on stdio transport.

func (*Aggregator) Start

func (a *Aggregator) Start(ctx context.Context) error

Start initializes connections to all backends and builds the tool namespace. this is where structural enforcement happens: tools are filtered during initialization.

func (*Aggregator) Stop

func (a *Aggregator) Stop() error

Stop gracefully shuts down the aggregator.

func (*Aggregator) ToolCount

func (a *Aggregator) ToolCount() int

ToolCount returns the number of registered tools.

func (*Aggregator) Tools

func (a *Aggregator) Tools() []mcp.Tool

Tools returns all aggregated, namespaced tools.

type AggregatorConfig

type AggregatorConfig struct {
	Name       string
	Version    string
	Separator  string
	Connection ConnectionConfig
}

AggregatorConfig contains settings for the aggregator itself.

type Backend

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

Backend represents a connection to a single backend MCP server.

func (*Backend) CallTool

func (b *Backend) CallTool(ctx context.Context, name string, args map[string]any) (*mcp.CallToolResult, error)

CallTool invokes a tool on this backend.

func (*Backend) ID

func (b *Backend) ID() string

ID returns the backend's identifier.

func (*Backend) Name

func (b *Backend) Name() string

Name returns the backend's human-readable name.

func (*Backend) Tools

func (b *Backend) Tools() []*mcp.Tool

Tools returns the tools available on this backend.

type BackendConfig

type BackendConfig struct {
	ID        string
	Name      string
	Transport TransportConfig
	Tools     ToolFilterConfig
}

BackendConfig defines a single backend MCP server.

type BackendError

type BackendError struct {
	BackendID string
	Op        string
	Err       error
}

BackendError represents an error related to a backend MCP server.

func (*BackendError) Error

func (e *BackendError) Error() string

func (*BackendError) Unwrap

func (e *BackendError) Unwrap() error

type BackendManager

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

BackendManager manages connections to multiple backend MCP servers.

func NewBackendManager

func NewBackendManager(cfg *Config) *BackendManager

NewBackendManager creates a new manager for backend connections.

func (*BackendManager) Close

func (m *BackendManager) Close() error

Close closes all backend connections.

func (*BackendManager) Connect

func (m *BackendManager) Connect(ctx context.Context) error

Connect establishes connections to all configured backends. implements fail-fast: returns error if any backend fails to connect.

func (*BackendManager) GetBackend

func (m *BackendManager) GetBackend(id string) (*Backend, bool)

GetBackend returns a backend by ID.

type Config

type Config struct {
	Aggregator AggregatorConfig
	Backends   []BackendConfig
}

Config represents the top-level aggregator configuration.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a Config with all defaults pre-populated.

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig loads configuration from a YAML file, merging into defaults.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks the configuration for errors.

type ConfigError

type ConfigError struct {
	Field   string
	Message string
}

ConfigError represents a configuration validation error.

func (*ConfigError) Error

func (e *ConfigError) Error() string

type ConnectionConfig

type ConnectionConfig struct {
	ConnectTimeout time.Duration
	CallTimeout    time.Duration
}

ConnectionConfig defines timeout settings.

type Namespace

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

Namespace manages the aggregated tool registry with namespacing.

func NewNamespace

func NewNamespace(separator string) *Namespace

NewNamespace creates a new namespace manager.

func (*Namespace) AddTools

func (n *Namespace) AddTools(backendID string, tools []*mcp.Tool, filter *ToolFilterConfig)

AddTools adds tools from a backend, applying the filter and namespace prefix. this implements structural enforcement: only permitted tools are added.

func (*Namespace) AllTools

func (n *Namespace) AllTools() []mcp.Tool

AllTools returns all registered tools for tools/list response.

func (*Namespace) Count

func (n *Namespace) Count() int

Count returns the number of registered tools.

func (*Namespace) GetTool

func (n *Namespace) GetTool(namespacedName string) (*NamespacedTool, bool)

GetTool looks up a tool by its namespaced name.

type NamespacedTool

type NamespacedTool struct {
	Tool         mcp.Tool
	BackendID    string
	OriginalName string
}

NamespacedTool represents a tool with its namespace information.

type RoutingError

type RoutingError struct {
	ToolName string
	Message  string
}

RoutingError indicates a failure in routing a tool call.

func (*RoutingError) Error

func (e *RoutingError) Error() string

type Server

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

Server wraps an MCP server with aggregation capabilities.

func NewServer

func NewServer(cfg *Config, namespace *Namespace, backends *BackendManager) *Server

NewServer creates a new aggregator MCP server.

func (*Server) CallTool

func (s *Server) CallTool(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error)

CallTool invokes a tool by its namespaced name.

func (*Server) MCPServer

func (s *Server) MCPServer() *mcp.Server

MCPServer returns the underlying MCP server for advanced usage.

func (*Server) Run

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

Run starts the MCP server on the given transport.

type ToolFilterConfig

type ToolFilterConfig struct {
	Mode string
	List []string
}

ToolFilterConfig defines which tools are permitted.

type ToolNotFoundError

type ToolNotFoundError struct {
	Name string
}

ToolNotFoundError indicates a requested tool does not exist.

func (*ToolNotFoundError) Error

func (e *ToolNotFoundError) Error() string

type TransportConfig

type TransportConfig struct {
	Type string
	// stdio transport fields
	Command    string
	Args       []string
	Env        map[string]string
	WorkingDir string
	// zrok transport fields
	ShareToken string
}

TransportConfig specifies how to connect to a backend.