tools

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jan 24, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package tools provides tool registration and integration.

Index

Constants

View Source 
const (
	// DefaultMaxJSONSize is the maximum size for JSON payloads (1MB).
	DefaultMaxJSONSize = 1 * 1024 * 1024
)

MCP-related limits for security.

Variables

View Source 
var ErrToolConflict = errors.New("tool name conflict")

ErrToolConflict is returned when multiple servers provide tools with the same name.

Functions

func DecodeJSONFromReaderSafe 

func DecodeJSONFromReaderSafe(r io.Reader, v any, maxSize int64) error

DecodeJSONFromReaderSafe decodes JSON from a reader with size limits.

func DecodeJSONSafe 

func DecodeJSONSafe(data []byte, v any, maxSize int64) error

DecodeJSONSafe decodes JSON with size limits to prevent memory exhaustion.

Types

type ConflictStrategy 

type ConflictStrategy int

ConflictStrategy defines how to handle tool name conflicts. 

const (
	// ConflictError returns an error on conflict (default).
	ConflictError ConflictStrategy = iota
	// ConflictFirstWins keeps the first tool, ignores later ones.
	ConflictFirstWins
	// ConflictLastWins overwrites with the latest tool (legacy behavior).
	ConflictLastWins
)

type DiscoveryOption 

type DiscoveryOption func(*ToolDiscovery)

DiscoveryOption configures ToolDiscovery.

func WithConflictStrategy 

func WithConflictStrategy(strategy ConflictStrategy) DiscoveryOption

WithConflictStrategy sets the strategy for handling tool name conflicts.

type Error 

type Error struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

Error represents an MCP error.

type Handler 

type Handler func(ctx context.Context, input map[string]any) (any, error)

Handler is a function that handles tool invocations.

func TypedHandler 

func TypedHandler[T any, R any](fn func(ctx context.Context, input T) (R, error)) Handler

TypedHandler creates a type-safe handler from a function. The input type T is automatically deserialized from map[string]any, and the output type R is returned as-is.

Example: 

type GreetInput struct {
    Name string `json:"name"`
}

type GreetOutput struct {
    Message string `json:"message"`
}

handler := TypedHandler(func(ctx context.Context, input GreetInput) (GreetOutput, error) {
    return GreetOutput{Message: "Hello, " + input.Name}, nil
})

type InputValidationError 

type InputValidationError struct {
	Field   string
	Message string
}

InputValidationError represents a validation failure for tool input.

func (*InputValidationError) Error 

func (e *InputValidationError) Error() string

type MCPClient 

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

MCPClient connects to external MCP servers.

func NewMCPClient 

func NewMCPClient(serverURL string, transport MCPTransport) *MCPClient

NewMCPClient creates a new MCP client.

func (*MCPClient) CallTool 

func (c *MCPClient) CallTool(ctx context.Context, name string, args any) (any, error)

CallTool invokes a tool on the remote server.

func (*MCPClient) Close 

func (c *MCPClient) Close() error

Close closes the client connection.

func (*MCPClient) ListTools 

func (c *MCPClient) ListTools(ctx context.Context) ([]*Tool, error)

ListTools fetches available tools from the server.

type MCPRequest 

type MCPRequest struct {
	Method string          `json:"method"`
	Params json.RawMessage `json:"params,omitempty"`
	ID     any             `json:"id,omitempty"`
}

MCPRequest represents an incoming MCP request.

type MCPResponse 

type MCPResponse struct {
	Result any    `json:"result,omitempty"`
	Error  *Error `json:"error,omitempty"`
	ID     any    `json:"id,omitempty"`
}

MCPResponse represents an MCP response.

type MCPServer 

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

MCPServer represents an MCP (Model Context Protocol) server.

func NewMCPServer 

func NewMCPServer(name string, opts ...MCPServerOption) *MCPServer

NewMCPServer creates a new MCP server.

func (*MCPServer) GetResource 

func (s *MCPServer) GetResource(uri string) *Resource

GetResource retrieves a resource by URI.

func (*MCPServer) GetServerInfo 

func (s *MCPServer) GetServerInfo() *ServerInfo

GetServerInfo returns server metadata.

func (*MCPServer) GetTool 

func (s *MCPServer) GetTool(name string) *Tool

GetTool retrieves a tool by name.

func (*MCPServer) HandleRequest 

func (s *MCPServer) HandleRequest(ctx context.Context, req *MCPRequest) *MCPResponse

HandleRequest processes an MCP request.

func (*MCPServer) ListResources 

func (s *MCPServer) ListResources() []*Resource

ListResources returns all registered resources.

func (*MCPServer) ListTools 

func (s *MCPServer) ListTools() []*Tool

ListTools returns all registered tools.

func (*MCPServer) RegisterResource 

func (s *MCPServer) RegisterResource(res *Resource) error

RegisterResource adds a resource.

func (*MCPServer) RegisterTool 

func (s *MCPServer) RegisterTool(tool *Tool) error

RegisterTool adds a tool to the server.

func (*MCPServer) RegisterTools 

func (s *MCPServer) RegisterTools(tools ...*Tool) error

RegisterTools adds multiple tools.

func (*MCPServer) UnregisterTool 

func (s *MCPServer) UnregisterTool(name string)

UnregisterTool removes a tool.

type MCPServerOption 

type MCPServerOption func(*MCPServer)

MCPServerOption configures an MCP server.

func WithMCPDescription 

func WithMCPDescription(desc string) MCPServerOption

WithMCPDescription sets the server description.

func WithMCPMaxJSONSize 

func WithMCPMaxJSONSize(maxSize int64) MCPServerOption

WithMCPMaxJSONSize sets the maximum JSON payload size.

func WithMCPVersion 

func WithMCPVersion(version string) MCPServerOption

WithMCPVersion sets the server version.

func WithProtocolVersion 

func WithProtocolVersion(version string) MCPServerOption

WithProtocolVersion sets the MCP protocol version.

type MCPTransport 

type MCPTransport interface {
	Send(ctx context.Context, req *MCPRequest) (*MCPResponse, error)
	Close() error
}

MCPTransport handles MCP communication.

type Registry 

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

Registry manages tool registration and invocation.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates a new tool registry.

func (*Registry) Get 

func (r *Registry) Get(name string) (*Tool, bool)

Get retrieves a tool by name.

func (*Registry) Invoke 

func (r *Registry) Invoke(ctx context.Context, name string, input map[string]any) (any, error)

Invoke invokes a tool by name.

func (*Registry) List 

func (r *Registry) List() []*Tool

List returns all registered tools.

func (*Registry) Register 

func (r *Registry) Register(tool *Tool) error

Register registers a tool.

func (*Registry) ToMCPFormat 

func (r *Registry) ToMCPFormat() map[string]any

ToMCPFormat converts registered tools to MCP server format. This is a placeholder for MCP server generation.

type Resource 

type Resource struct {
	URI         string         `json:"uri"`
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	MimeType    string         `json:"mimeType,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

Resource represents an MCP resource.

type ServerInfo 

type ServerInfo struct {
	Name         string   `json:"name"`
	Version      string   `json:"version"`
	Description  string   `json:"description,omitempty"`
	Capabilities []string `json:"capabilities"`
}

ServerInfo contains server metadata.

type Tool 

type Tool struct {
	// Name is the tool name.
	Name string

	// Description describes what the tool does.
	Description string

	// InputSchema is the JSON schema for the tool's input.
	InputSchema map[string]any

	// Handler is the function that executes the tool.
	Handler Handler
}

Tool represents a tool available to the AI.

func NewTool 

func NewTool(name, description string, schema map[string]any, handler Handler) *Tool

NewTool creates a new tool.

func TypedTool 

func TypedTool[T any, R any](
	name, description string,
	schema map[string]any,
	fn func(ctx context.Context, input T) (R, error),
) *Tool

TypedTool creates a new tool with a typed handler.

func (*Tool) Invoke 

func (t *Tool) Invoke(ctx context.Context, input map[string]any) (any, error)

Invoke invokes the tool with the given input after validation.

func (*Tool) ValidateInput 

func (t *Tool) ValidateInput(input map[string]any) error

ValidateInput validates input against the tool's InputSchema. Returns nil if validation passes, or an error describing the validation failure.

type ToolDiscovery 

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

ToolDiscovery discovers tools from multiple MCP servers.

func NewToolDiscovery 

func NewToolDiscovery(opts ...DiscoveryOption) *ToolDiscovery

NewToolDiscovery creates a new tool discovery service.

func (*ToolDiscovery) AddServer 

func (d *ToolDiscovery) AddServer(client *MCPClient)

AddServer adds an MCP server to discover tools from.

func (*ToolDiscovery) Close 

func (d *ToolDiscovery) Close() error

Close closes all client connections.

func (*ToolDiscovery) Discover 

func (d *ToolDiscovery) Discover(ctx context.Context) error

Discover fetches tools from all registered servers.

func (*ToolDiscovery) GetToolSource 

func (d *ToolDiscovery) GetToolSource(name string) string

GetToolSource returns the server URL that provided the named tool.

func (*ToolDiscovery) GetTools 

func (d *ToolDiscovery) GetTools() []*Tool

GetTools returns all discovered tools.

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.