tools

package
v0.1.147 Latest Latest
Warning

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

 Go to latest Published: Apr 7, 2026 License: AGPL-3.0, AGPL-3.0-or-later Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// MCPInitTimeout is the timeout for MCP server initialization (includes NPX download time)
	MCPInitTimeout = 120 * time.Second
	// MCPRetryDelay is the delay between retry attempts
	MCPRetryDelay = 2 * time.Second
	// MCPMaxRetries is the maximum number of retry attempts
	MCPMaxRetries = 1
)

Variables

This section is empty.

Functions

func CommandOutputType added in v0.1.133 

func CommandOutputType(toolName, command string) string

CommandOutputType returns the deterministic output type declared in a tool definition, or "" if none is declared. Safe to call from any package; lazily loads and caches the embedded YAML definitions on first call.

func ContextWithSourceViewID added in v0.1.133 

func ContextWithSourceViewID(ctx context.Context, viewID string) context.Context

ContextWithSourceViewID attaches the source view ID to a context for downstream enforcement by view-scoped tools.

func GetRegisteredTools 

func GetRegisteredTools() map[string]Tool

func HasCommandSchema added in v0.1.133 

func HasCommandSchema(toolName, command string) bool

HasCommandSchema returns true if the embedded tool definitions contain a schema for the given tool+command pair. Used to distinguish "no schema at all" from "schema exists but declares no output_type".

func ListAvailableTools 

func ListAvailableTools(toolsFS embed.FS, dir string) ([]string, error)

ListAvailableTools returns the names of tools that have schemas but may or may not have clients

func RegisterTool 

func RegisterTool(t Tool)

func RequiresCredentials 

func RequiresCredentials(name string) bool

RequiresCredentials returns true if the tool needs stored credentials

func SourceViewIDFromContext added in v0.1.133 

func SourceViewIDFromContext(ctx context.Context) string

SourceViewIDFromContext returns the source view ID constraint, or "".

Types

type BackendRepository 

type BackendRepository interface {
	ListWorkspaceTools(ctx context.Context, workspaceId uint) ([]*types.WorkspaceTool, error)
	GetWorkspaceToolByName(ctx context.Context, workspaceId uint, name string) (*types.WorkspaceTool, error)
	GetWorkspaceToolSettings(ctx context.Context, workspaceId uint) (*types.WorkspaceToolSettings, error)
	GetConnection(ctx context.Context, workspaceId uint, memberId uint, integrationType string) (*types.IntegrationConnection, error)
}

BackendRepository is the subset of repository.BackendRepository needed by the resolver

type ClientRegistry 

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

ClientRegistry holds registered tool clients that can be paired with schemas

func NewClientRegistry 

func NewClientRegistry() *ClientRegistry

NewClientRegistry creates a new client registry

func (*ClientRegistry) Get 

func (r *ClientRegistry) Get(name string) (ToolClient, bool)

Get returns a client by name

func (*ClientRegistry) Register 

func (r *ClientRegistry) Register(client ToolClient)

Register adds a self-describing client to the registry using its Name()

func (*ClientRegistry) RegisterAll 

func (r *ClientRegistry) RegisterAll(clients ...ToolClient)

RegisterAll registers multiple clients at once

type CommandDef 

type CommandDef struct {
	Description string
	Params      []*ParamDef
}

CommandDef defines a command within a tool

type CommandSchema 

type CommandSchema struct {
	Description   string         `yaml:"description"`
	Params        []*ParamSchema `yaml:"params,omitempty"`
	OneOfRequired [][]string     `yaml:"one_of_required,omitempty"`
	Internal      bool           `yaml:"internal,omitempty"`
	Write         bool           `yaml:"write,omitempty"`
	OutputType    string         `yaml:"output_type,omitempty"`
}

CommandSchema defines a single command within a tool

func (*CommandSchema) GetFlagParams 

func (c *CommandSchema) GetFlagParams() []*ParamSchema

GetFlagParams returns params that have flags

func (*CommandSchema) GetPositionalParams 

func (c *CommandSchema) GetPositionalParams() []*ParamSchema

GetPositionalParams returns params sorted by position

func (*CommandSchema) HasRequiredArgs added in v0.1.131 

func (c *CommandSchema) HasRequiredArgs(args []string) bool

HasRequiredArgs checks whether the supplied args satisfy every required param and one_of_required group in the schema. Positional args are matched by index; flag args are matched by --flag or -short presence. Returns false for incomplete or malformed calls so they can fail through normal tool error handling.

func (*CommandSchema) ValidateParams 

func (c *CommandSchema) ValidateParams() error

ValidateParams checks that command parameters are well-formed

type ExecutionContext 

type ExecutionContext struct {
	WorkspaceId   uint
	WorkspaceName string
	MemberId      uint
	MemberEmail   string
	Credentials   *types.IntegrationCredentials
	SourceViewID  string
}

ExecutionContext contains identity and credentials for tool execution

type Loader 

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

Loader handles discovering tool schemas and creating providers

func NewLoader 

func NewLoader(clients *ClientRegistry) *Loader

NewLoader creates a new tool loader

func (*Loader) LoadFromBytes 

func (l *Loader) LoadFromBytes(data []byte) (*SchemaProvider, error)

LoadFromBytes loads a single tool from YAML bytes

func (*Loader) LoadFromDir 

func (l *Loader) LoadFromDir(dir string) ([]*SchemaProvider, error)

LoadFromDir loads tool schemas from a filesystem directory

func (*Loader) LoadFromFS 

func (l *Loader) LoadFromFS(toolsFS embed.FS, dir string) ([]*SchemaProvider, error)

LoadFromFS loads tool schemas from an embedded filesystem

func (*Loader) RegisterProviders 

func (l *Loader) RegisterProviders(toolsFS embed.FS, dir string, registry *Registry) error

RegisterProviders loads tools and registers them with a provider registry

type LocalToolProvider added in v0.1.60 

type LocalToolProvider interface {
	LocalCommand() string
}

LocalToolProvider is an optional interface for tools that execute locally inside the sandbox rather than proxying through the gateway. The FUSE layer serves a wrapper script for these tools instead of the gRPC shim.

type MCPCapabilities 

type MCPCapabilities struct {
	Tools     *MCPToolsCapability     `json:"tools,omitempty"`
	Resources *MCPResourcesCapability `json:"resources,omitempty"`
	Prompts   *MCPPromptsCapability   `json:"prompts,omitempty"`
}

MCPCapabilities describes what the MCP server supports

type MCPClient 

type MCPClient interface {
	Name() string
	Start(ctx context.Context) error
	ListTools(ctx context.Context) ([]MCPToolInfo, error)
	CallTool(ctx context.Context, name string, args map[string]any) (MCPToolResult, error)
	Tools() []MCPToolInfo
	ServerInfo() *MCPServerInfo
	Close() error
}

MCPClient is the interface for MCP server clients (both stdio and remote).

type MCPContent 

type MCPContent struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
}

MCPContent represents content in a tool result

type MCPManager 

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

MCPManager manages MCP server clients and their lifecycle

func NewMCPManager 

func NewMCPManager() *MCPManager

NewMCPManager creates a new MCP manager

func (*MCPManager) Clients 

func (m *MCPManager) Clients() []MCPClient

Clients returns the list of active MCP clients

func (*MCPManager) Close 

func (m *MCPManager) Close() error

Close shuts down all MCP clients

func (*MCPManager) LoadServers 

func (m *MCPManager) LoadServers(config map[string]types.MCPServerConfig, registry *Registry) error

LoadServers starts MCP servers from config and registers their tools

type MCPPromptsCapability 

type MCPPromptsCapability struct {
	ListChanged bool `json:"listChanged,omitempty"`
}

MCPPromptsCapability indicates prompts support

type MCPPropertySchema 

type MCPPropertySchema struct {
	Type        string                       `json:"type"`
	Description string                       `json:"description,omitempty"`
	Items       *MCPPropertySchema           `json:"items,omitempty"`      // For arrays
	Properties  map[string]MCPPropertySchema `json:"properties,omitempty"` // For objects
}

MCPPropertySchema represents a property in the tool schema

type MCPRemoteClient 

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

MCPRemoteClient manages communication with a remote MCP server via HTTP/SSE. It implements the JSON-RPC 2.0 protocol used by MCP over HTTP transport. Supports both SSE transport and Streamable HTTP transport.

func NewMCPRemoteClient 

func NewMCPRemoteClient(name string, config types.MCPServerConfig) *MCPRemoteClient

NewMCPRemoteClient creates a new HTTP/SSE-based MCP client for the given server configuration. The connection is not established until Start() is called.

func (*MCPRemoteClient) CallTool 

func (c *MCPRemoteClient) CallTool(ctx context.Context, name string, args map[string]any) (MCPToolResult, error)

CallTool invokes a tool on the MCP server. Implements MCPToolExecutor interface.

func (*MCPRemoteClient) Close 

func (c *MCPRemoteClient) Close() error

Close shuts down the MCP client and closes the SSE connection

func (*MCPRemoteClient) ListTools 

func (c *MCPRemoteClient) ListTools(ctx context.Context) ([]MCPToolInfo, error)

ListTools fetches the list of available tools from the server

func (*MCPRemoteClient) Name 

func (c *MCPRemoteClient) Name() string

Name returns the server name

func (*MCPRemoteClient) ServerInfo 

func (c *MCPRemoteClient) ServerInfo() *MCPServerInfo

ServerInfo returns the server information from initialization

func (*MCPRemoteClient) Start 

func (c *MCPRemoteClient) Start(ctx context.Context) error

Start connects to the remote MCP server and initializes the connection. Supports both SSE transport (default) and Streamable HTTP transport.

func (*MCPRemoteClient) Tools 

func (c *MCPRemoteClient) Tools() []MCPToolInfo

Tools returns the cached list of tools

type MCPResourcesCapability 

type MCPResourcesCapability struct {
	Subscribe   bool `json:"subscribe,omitempty"`
	ListChanged bool `json:"listChanged,omitempty"`
}

MCPResourcesCapability indicates resources support

type MCPServerInfo 

type MCPServerInfo struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

MCPServerInfo contains server identification from initialization

type MCPServerProvider 

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

MCPServerProvider implements ToolProvider for an entire MCP server. The server becomes a single binary, with each tool as a subcommand. Usage: /tools/<server> <tool> [args...]

func NewMCPServerProvider 

func NewMCPServerProvider(serverName string, executor MCPToolExecutor) *MCPServerProvider

NewMCPServerProvider creates a new provider for an MCP server

func (*MCPServerProvider) AddTool 

func (p *MCPServerProvider) AddTool(name, description string, inputSchema json.RawMessage)

AddTool registers a tool with this server provider

func (*MCPServerProvider) Execute 

func (p *MCPServerProvider) Execute(ctx context.Context, args []string, stdout, stderr io.Writer) error

Execute runs an MCP tool as a subcommand

func (*MCPServerProvider) ExecuteWithContext 

func (p *MCPServerProvider) ExecuteWithContext(ctx context.Context, execCtx *ExecutionContext, args []string, stdout, stderr io.Writer) error

ExecuteWithContext runs an MCP tool with execution context

func (*MCPServerProvider) HasTool 

func (p *MCPServerProvider) HasTool(name string) bool

HasTool checks if a tool exists in this server

func (*MCPServerProvider) Help 

func (p *MCPServerProvider) Help() string

Help returns usage information listing all available tools as subcommands

func (*MCPServerProvider) Name 

func (p *MCPServerProvider) Name() string

Name returns the server name (used as the binary name in /tools/)

func (*MCPServerProvider) ToolCount 

func (p *MCPServerProvider) ToolCount() int

ToolCount returns the number of tools in this server

type MCPServerTool 

type MCPServerTool struct {
	Name        string
	Description string
	InputSchema json.RawMessage
}

MCPServerTool represents a single tool within an MCP server

type MCPStdioClient 

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

MCPStdioClient manages communication with an MCP server process via stdio. It implements the JSON-RPC 2.0 protocol used by MCP.

func NewMCPStdioClient 

func NewMCPStdioClient(name string, config types.MCPServerConfig) *MCPStdioClient

NewMCPStdioClient creates a new stdio-based MCP client for the given server configuration. The server process is not started until Start() is called.

func (*MCPStdioClient) CallTool 

func (c *MCPStdioClient) CallTool(ctx context.Context, name string, args map[string]any) (MCPToolResult, error)

CallTool invokes a tool on the MCP server. Implements MCPToolExecutor interface.

func (*MCPStdioClient) Close 

func (c *MCPStdioClient) Close() error

Close shuts down the MCP client and terminates the server process

func (*MCPStdioClient) ListTools 

func (c *MCPStdioClient) ListTools(ctx context.Context) ([]MCPToolInfo, error)

ListTools fetches the list of available tools from the server

func (*MCPStdioClient) Name 

func (c *MCPStdioClient) Name() string

Name returns the server name

func (*MCPStdioClient) ServerInfo 

func (c *MCPStdioClient) ServerInfo() *MCPServerInfo

ServerInfo returns the server information from initialization

func (*MCPStdioClient) Start 

func (c *MCPStdioClient) Start(ctx context.Context) error

Start launches the MCP server process and initializes the connection.

func (*MCPStdioClient) Tools 

func (c *MCPStdioClient) Tools() []MCPToolInfo

Tools returns the cached list of tools

type MCPToolExecutor 

type MCPToolExecutor interface {
	CallTool(ctx context.Context, name string, args map[string]any) (MCPToolResult, error)
}

MCPToolExecutor is the interface for executing MCP tool calls. Implemented by MCPClient.

type MCPToolInfo 

type MCPToolInfo struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	InputSchema json.RawMessage `json:"inputSchema"`
}

MCPToolInfo represents a tool exposed by an MCP server

type MCPToolResult 

type MCPToolResult struct {
	Content []MCPContent `json:"content"`
	IsError bool         `json:"isError,omitempty"`
}

MCPToolResult represents the result of an MCP tool call

type MCPToolSchema 

type MCPToolSchema struct {
	Type       string                       `json:"type"`
	Properties map[string]MCPPropertySchema `json:"properties,omitempty"`
	Required   []string                     `json:"required,omitempty"`
}

MCPToolSchema represents the input schema for an MCP tool (JSON Schema subset)

type MCPToolsCapability 

type MCPToolsCapability struct {
	ListChanged bool `json:"listChanged,omitempty"`
}

MCPToolsCapability indicates tools support

type ParamDef 

type ParamDef struct {
	Name        string
	Type        string // string, int, bool, float
	Required    bool
	Position    *int   // positional arg index (nil = flag only)
	Short       string // short flag (e.g., "-n")
	Flag        string // long flag (e.g., "--limit")
	Default     any
	Description string
}

ParamDef defines a parameter for a command

type ParamSchema 

type ParamSchema struct {
	Name        string `yaml:"name"`
	Type        string `yaml:"type"`                  // string, int, bool, float
	Required    bool   `yaml:"required,omitempty"`    // default false
	Position    *int   `yaml:"position,omitempty"`    // positional arg index (nil = flag only)
	Short       string `yaml:"short,omitempty"`       // short flag (e.g., "-n")
	Flag        string `yaml:"flag,omitempty"`        // long flag (e.g., "--limit")
	Default     any    `yaml:"default,omitempty"`     // default value
	Description string `yaml:"description,omitempty"` // help text
}

ParamSchema defines a parameter for a command

type Registry 

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

Registry manages registered tool providers

func NewRegistry 

func NewRegistry() *Registry

func (*Registry) Get 

func (r *Registry) Get(name string) ToolProvider

func (*Registry) GetCommandSchema added in v0.1.131 

func (r *Registry) GetCommandSchema(toolName, command string) *CommandSchema

GetCommandSchema returns the schema for a specific tool command, or nil.

func (*Registry) Has 

func (r *Registry) Has(name string) bool

func (*Registry) IsValidWriteCommand added in v0.1.131 

func (r *Registry) IsValidWriteCommand(toolName string, args []string) bool

IsValidWriteCommand returns true if the tool+subcommand is marked write in its schema AND the supplied args satisfy all required params. Invalid calls (missing args, --help probes) pass through ungated so the tool returns a proper error and the agent self-corrects.

func (*Registry) List 

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

func (*Registry) Register 

func (r *Registry) Register(p ToolProvider)

func (*Registry) RegisterSchema added in v0.1.131 

func (r *Registry) RegisterSchema(name string, schema *ToolSchema)

type SchemaProvider 

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

SchemaProvider wraps a ToolClient with a schema to create a ToolProvider. It handles argument parsing, validation, and help generation.

func NewSchemaProvider 

func NewSchemaProvider(schema *ToolSchema, client ToolClient) *SchemaProvider

NewSchemaProvider creates a new schema-driven provider

func (*SchemaProvider) Execute 

func (p *SchemaProvider) Execute(ctx context.Context, args []string, stdout, stderr io.Writer) error

Execute parses arguments and delegates to the client (without credentials)

func (*SchemaProvider) ExecuteWithContext 

func (p *SchemaProvider) ExecuteWithContext(ctx context.Context, execCtx *ExecutionContext, args []string, stdout, stderr io.Writer) error

ExecuteWithContext parses arguments and delegates to the client with credentials

func (*SchemaProvider) Help 

func (p *SchemaProvider) Help() string

Help generates help text from the schema

func (*SchemaProvider) LocalCommand added in v0.1.60 

func (p *SchemaProvider) LocalCommand() string

LocalCommand implements LocalToolProvider.

func (*SchemaProvider) Name 

func (p *SchemaProvider) Name() string

Name returns the tool name from the schema

type Tool 

type Tool interface {
	Name() string
	Description() string
	Commands() map[string]*CommandDef
	Execute(ctx context.Context, execCtx *ExecutionContext, command string, args map[string]any, stdout, stderr io.Writer) error
}

Tool is the unified interface for tool implementations.

func GetRegisteredTool 

func GetRegisteredTool(name string) (Tool, bool)

type ToolAdapter 

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

ToolAdapter wraps a Tool to implement ToolProvider

func (*ToolAdapter) Execute 

func (a *ToolAdapter) Execute(ctx context.Context, args []string, stdout, stderr io.Writer) error

func (*ToolAdapter) ExecuteWithContext 

func (a *ToolAdapter) ExecuteWithContext(ctx context.Context, execCtx *ExecutionContext, args []string, stdout, stderr io.Writer) error

func (*ToolAdapter) Help 

func (a *ToolAdapter) Help() string

func (*ToolAdapter) Name 

func (a *ToolAdapter) Name() string

type ToolClient 

type ToolClient interface {
	Name() types.IntegrationName
	Execute(ctx context.Context, command string, args map[string]any, creds *types.IntegrationCredentials, stdout, stderr io.Writer) error
}

ToolClient is implemented by tool backends

type ToolProvider 

type ToolProvider interface {
	Name() string
	Help() string
	Execute(ctx context.Context, args []string, stdout, stderr io.Writer) error
	ExecuteWithContext(ctx context.Context, execCtx *ExecutionContext, args []string, stdout, stderr io.Writer) error
}

ToolProvider defines the interface for tool implementations

func NewToolAdapter 

func NewToolAdapter(t Tool) ToolProvider

type ToolSchema 

type ToolSchema struct {
	Name         string                    `yaml:"name"`
	Description  string                    `yaml:"description"`
	Icon         string                    `yaml:"icon,omitempty"`
	LocalCommand string                    `yaml:"local_command,omitempty"`
	Commands     map[string]*CommandSchema `yaml:"commands"`
}

ToolSchema defines the structure of a tool definition YAML file

func DiscoverSchemas 

func DiscoverSchemas(dir string) ([]*ToolSchema, error)

DiscoverSchemas finds all .yaml files in a directory and loads them

func LoadSchema 

func LoadSchema(path string) (*ToolSchema, error)

LoadSchema loads a tool schema from a YAML file

func ParseSchema 

func ParseSchema(data []byte) (*ToolSchema, error)

ParseSchema parses a tool schema from YAML bytes

func (*ToolSchema) Validate 

func (s *ToolSchema) Validate() error

Validate checks that the schema is well-formed

type WorkspaceToolResolver 

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

WorkspaceToolResolver provides workspace-aware tool resolution. It merges global tools with workspace-specific tools and enforces per-workspace enable/disable settings.

func NewWorkspaceToolResolver 

func NewWorkspaceToolResolver(globalRegistry *Registry, backend BackendRepository) *WorkspaceToolResolver

NewWorkspaceToolResolver creates a new resolver

func (*WorkspaceToolResolver) Close 

func (r *WorkspaceToolResolver) Close() error

Close shuts down all cached MCP clients

func (*WorkspaceToolResolver) Get 

func (r *WorkspaceToolResolver) Get(ctx context.Context, name string) (ToolProvider, error)

Get returns a ToolProvider for the given tool name, checking both global and workspace-specific tools. Returns nil if disabled or not found.

func (*WorkspaceToolResolver) Has 

func (r *WorkspaceToolResolver) Has(ctx context.Context, name string) bool

Has checks if a tool exists (in global or workspace scope)

func (*WorkspaceToolResolver) Invalidate 

func (r *WorkspaceToolResolver) Invalidate(workspaceId uint, toolName string)

Invalidate removes cached clients for a workspace tool

func (*WorkspaceToolResolver) InvalidateWorkspace 

func (r *WorkspaceToolResolver) InvalidateWorkspace(workspaceId uint)

InvalidateWorkspace removes all cached clients for a workspace

func (*WorkspaceToolResolver) IsGlobal 

func (r *WorkspaceToolResolver) IsGlobal(name string) bool

IsGlobal returns true if the tool is from the global registry

func (*WorkspaceToolResolver) List 

func (r *WorkspaceToolResolver) List(ctx context.Context) ([]types.ResolvedTool, error)

List returns all tools available to the workspace (global + workspace-specific), filtered by workspace tool settings

func (*WorkspaceToolResolver) ListEnabled 

func (r *WorkspaceToolResolver) ListEnabled(ctx context.Context) ([]types.ResolvedTool, error)

ListEnabled returns only enabled tools for the workspace

Source Files

View all Source files

Directories

Path Synopsis
Package builtin contains self-registering tool implementations.
 Package builtin contains self-registering tool implementations.

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.