tool

package
v0.0.0-...-5b49586 Latest Latest
Warning

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

 Go to latest Published: Apr 1, 2026 License: Apache-2.0 Imports: 55 Imported by: 0

Documentation

Overview

Package tool defines the interface for tools that can be executed by the upstream service.

Package tool is a generated GoMock package.

Index

Constants

View Source 
const (

	// Summary: Indicates that an upstream service failed its readiness or liveness health check and should not receive traffic.
	// Parameters: None
	// Returns: None
	// Errors: None
	// Side Effects: None
	HealthStatusUnhealthy = "unhealthy"
)

Variables

View Source 
var ErrToolNotFound = errors.New("unknown tool")

ErrToolNotFound is returned when a requested tool cannot be found.

Summary: Represents a ErrToolNotFound.

Functions

func CalculateConfigHash 

func CalculateConfigHash(t *configv1.ToolDefinition) (string, error)

CalculateConfigHash computes the SHA256 hash of a configuration tool definition.

Summary: Calculates hash for configuration tool.

Parameters:

  • t: *configv1.ToolDefinition. The tool definition to hash.

Returns:

  • string: The hex-encoded SHA256 hash.
  • error: An error if marshaling fails.

func CalculateHash 

func CalculateHash(t *v1.Tool) (string, error)

CalculateHash computes the SHA256 hash of a runtime tool definition.

Summary: Calculates hash for runtime tool.

Parameters:

  • t: *v1.Tool. The tool to hash.

Returns:

  • string: The hex-encoded SHA256 hash.
  • error: An error if marshaling fails.

func ConvertMCPToolToProto 

func ConvertMCPToolToProto(tool *mcp.Tool) (*pb.Tool, error)

ConvertMCPToolToProto transforms an *mcp.Tool, which uses a flexible schema representation, into a protobuf-defined *pb.Tool with a structured input schema. This is used to standardize tool definitions within the system.

Parameters:

  • tool: *mcp.Tool. The MCP tool definition to convert.

Returns:

  • *pb.Tool: The corresponding protobuf tool definition.
  • error: An error if conversion fails (e.g. invalid schema).

Summary: Executes ConvertMCPToolToProto operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func ConvertMcpFieldsToInputSchemaProperties 

func ConvertMcpFieldsToInputSchemaProperties(fields []*protobufparser.McpField) (*structpb.Struct, error)

ConvertMcpFieldsToInputSchemaProperties converts a slice of McpField, which represent fields from a protobuf message, into a structpb.Struct that can be used as the `properties` field in a JSON schema.

Parameters:

  • fields: []*protobufparser.McpField. The list of fields to convert.

Returns:

  • *structpb.Struct: A struct representing the properties JSON schema.
  • error: An error if conversion fails.

Summary: Executes ConvertMcpFieldsToInputSchemaProperties operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func ConvertProtoToMCPTool 

func ConvertProtoToMCPTool(pbTool *pb.Tool) (*mcp.Tool, error)

ConvertProtoToMCPTool transforms a protobuf-defined *pb.Tool into an *mcp.Tool. This is the reverse of convertMCPToolToProto and is used when exposing internally defined tools to the outside world.

Parameters:

  • pbTool: *pb.Tool. The protobuf tool definition to convert.

Returns:

  • *mcp.Tool: The corresponding MCP tool definition.
  • error: An error if conversion fails.

Summary: Executes ConvertProtoToMCPTool operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func ConvertToolDefinitionToProto 

func ConvertToolDefinitionToProto(toolDef *configv1.ToolDefinition, inputSchema, outputSchema *structpb.Struct) (*pb.Tool, error)

ConvertToolDefinitionToProto transforms a *configv1.ToolDefinition into a *pb.Tool.

Parameters:

  • toolDef: *configv1.ToolDefinition. The tool definition from configuration.
  • inputSchema: *structpb.Struct. The input schema for the tool.
  • outputSchema: *structpb.Struct. The output schema for the tool.

Returns:

  • *pb.Tool: The protobuf tool definition.
  • error: An error if conversion fails.

Summary: Executes ConvertToolDefinitionToProto operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func EvaluateCallPolicy 

func EvaluateCallPolicy(policies []*configv1.CallPolicy, toolName, callID string, arguments []byte) (bool, error)

EvaluateCallPolicy checks if a call should be allowed based on the policies.

Summary: Evaluates call policies against a tool execution.

If arguments is nil, it performs a static check (ignoring rules with argument_regex). It returns true if the call is allowed, false otherwise.

Parameters:

  • policies: []*configv1.CallPolicy. The list of policies to evaluate.
  • toolName: string. The name of the tool being called.
  • callID: string. The unique ID of the call.
  • arguments: []byte. The arguments of the call (can be nil).

Returns:

  • bool: True if the call is allowed, false otherwise.
  • error: An error if evaluation fails.

func EvaluateCompiledCallPolicy 

func EvaluateCompiledCallPolicy(policies []*CompiledCallPolicy, toolName, callID string, arguments []byte) (bool, error)

EvaluateCompiledCallPolicy checks if a call should be allowed based on the compiled policies.

Summary: Evaluates compiled call policies.

Parameters:

  • policies: []*CompiledCallPolicy. The list of compiled policies to evaluate.
  • toolName: string. The name of the tool being called.
  • callID: string. The unique ID of the call.
  • arguments: []byte. The arguments of the call (can be nil).

Returns:

  • bool: True if the call is allowed, false otherwise.
  • error: An error if evaluation fails.

func GetFullyQualifiedToolName 

func GetFullyQualifiedToolName(serviceID, methodName string) string

GetFullyQualifiedToolName constructs a fully qualified tool name from a service ID and a method name.

Summary: Constructs a fully qualified tool name.

Parameters:

  • serviceID: string. The unique identifier of the service.
  • methodName: string. The name of the tool/method within the service.

Returns:

  • string: The combined, fully qualified tool name.

func GetJSONSchemaForScalarType 

func GetJSONSchemaForScalarType(scalarType, description string) (*jsonschema.Schema, error)

GetJSONSchemaForScalarType maps a protobuf scalar type (e.g., "TYPE_STRING", "TYPE_INT32") to its corresponding JSON schema type ("string", "integer"). It is a helper function for building JSON schemas from protobuf definitions.

Parameters:

  • scalarType: string. The protobuf scalar type name.
  • description: string. The description for the schema.

Returns:

  • *jsonschema.Schema: The generated JSON schema.
  • error: An error if the scalar type is unsupported.

Summary: Retrieves GetJSONSchemaForScalarType operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func NewContextWithCacheControl 

func NewContextWithCacheControl(ctx context.Context, cc *CacheControl) context.Context

NewContextWithCacheControl creates a new context with the given CacheControl.

Summary: Embeds CacheControl into the context.

Parameters:

  • ctx: context.Context. The context to extend.
  • cc: *CacheControl. The CacheControl instance to embed.

Returns:

  • context.Context: A new context containing the CacheControl.

func NewContextWithSampler deprecated 

func NewContextWithSampler(ctx context.Context, s Sampler) context.Context

NewContextWithSampler creates a new context with the given Sampler.

Summary: Injects Sampler into context.

Deprecated: Use NewContextWithSession instead.

Parameters:

  • ctx: context.Context. The parent context.
  • s: Sampler. The sampler to inject.

Returns:

  • context.Context: The new context.

func NewContextWithSession 

func NewContextWithSession(ctx context.Context, s Session) context.Context

NewContextWithSession creates a new context with the given Session.

Summary: Injects Session into context.

Parameters:

  • ctx: context.Context. The parent context.
  • s: Session. The session to inject.

Returns:

  • context.Context: The new context.

func NewContextWithTool 

func NewContextWithTool(ctx context.Context, t Tool) context.Context

Summary: Injects an active Tool instance into a context, enabling downstream consumers or middleware to dynamically access tool metadata during request propagation.

Parameters:

  • ctx: context.Context. The context to extend.
  • t: Tool. The tool instance to embed in the context.

Returns:

  • context.Context: A new context containing the tool.

func ParseToolName 

func ParseToolName(toolName string) (namespace string, tool string, err error)

ParseToolName deconstructs a fully qualified tool name into its namespace (service ID) and the bare tool name.

Summary: Parses a fully qualified tool name.

Parameters:

  • toolName: string. The fully qualified tool name to parse.

Returns:

  • namespace: string. The service ID/namespace.
  • tool: string. The bare tool name.
  • err: error. An error if the tool name is invalid.

func SanitizeJSONSchema 

func SanitizeJSONSchema(schema any) (*structpb.Struct, error)

SanitizeJSONSchema attempts to fix common schema issues that cause strict MCP clients to fail. It takes a raw map[string]interface{} (or compatible) and returns a *structpb.Struct. This function does NOT modify the input schema.

Summary: Sanitizes and converts a JSON schema into a Struct protobuf.

Parameters:

  • schema: any. The input schema (typically map[string]interface{}).

Returns:

  • *structpb.Struct: The sanitized schema as a protobuf Struct.
  • error: An error if deep copying or processing fails.

Errors:

  • Returns error if deep copy fails or recursion limit exceeded.

Side Effects:

  • Performs a deep copy of the input schema.

func ShouldExport 

func ShouldExport(name string, policy *configv1.ExportPolicy) bool

ShouldExport determines whether a named item (tool, prompt, or resource) should be exported.

Summary: Checks if an item should be exported based on policy.

Parameters:

  • name: string. The name of the item.
  • policy: *configv1.ExportPolicy. The export policy to evaluate.

Returns:

  • bool: True if the item should be exported, false otherwise.

func VerifyConfigIntegrity 

func VerifyConfigIntegrity(t *configv1.ToolDefinition) error

VerifyConfigIntegrity checks if the config tool definition matches its expected hash.

Summary: Verifies configuration tool integrity.

Parameters:

  • t: *configv1.ToolDefinition. The tool definition to verify.

Returns:

  • error: An error if integrity check fails.

func VerifyIntegrity 

func VerifyIntegrity(t *v1.Tool) error

VerifyIntegrity checks if the tool definition matches its expected hash.

Summary: Verifies runtime tool integrity.

Parameters:

  • t: *v1.Tool. The tool to verify.

Returns:

  • error: An error if integrity check fails.

Types

type Action 

type Action int

Action defines the decision made by a pre-call hook.

Summary: Enumeration of possible hook actions. 

const (
	// ActionAllow indicates that the action is allowed to proceed.
	//
	// Summary: Allow action.
	ActionAllow Action = 0
	// ActionDeny indicates that the action is denied and should be blocked.
	//
	// Summary: Deny action.
	ActionDeny Action = 1
	// ActionSaveCache indicates that the result should be saved to the cache.
	//
	// Summary: Save to cache action.
	ActionSaveCache Action = 2
	// ActionDeleteCache indicates that the associated cache entry should be invalidated.
	//
	// Summary: Delete from cache action.
	ActionDeleteCache Action = 3
)

type CacheControl 

type CacheControl struct {
	Action Action
}

CacheControl is a mutable struct to pass cache control instructions via context.

Summary: Context-based cache control instructions.

func GetCacheControl 

func GetCacheControl(ctx context.Context) (*CacheControl, bool)

Summary: Extracts embedded caching policies from the current request scope, allowing middleware to conditionally mutate standard caching behaviors.

Parameters:

  • ctx: context.Context. The context to search.

Returns:

  • *CacheControl: The CacheControl instance if found.
  • bool: True if CacheControl exists, false otherwise.

type Callable 

type Callable interface {
	// Call executes the callable with the given request.
	//
	// Parameters:
	//   - ctx: The context for the request.
	//   - req: The execution request details.
	//
	// Returns:
	//   - any: The result of the execution.
	//   - error: An error if the operation fails.
	Call(ctx context.Context, req *ExecutionRequest) (any, error)
}

Summary: Establishes a contract for executable entities capable of synchronously processing context-aware requests and returning generic structural responses. Parameters: None Returns: None Errors: None Side Effects: None

type CallableTool 

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

CallableTool implements the Tool interface for a tool that is executed by a Callable.

Summary: Represents a CallableTool.

func NewCallableTool 

func NewCallableTool(toolDef *configv1.ToolDefinition, serviceConfig *configv1.UpstreamServiceConfig, callable Callable, inputSchema, outputSchema *structpb.Struct) (*CallableTool, error)

NewCallableTool creates a new CallableTool.

Summary: Creates a new tool that wraps a Callable interface.

Parameters:

  • toolDef: *configv1.ToolDefinition. The definition of the tool.
  • serviceConfig: *configv1.UpstreamServiceConfig. The configuration of the service the tool belongs to.
  • callable: Callable. The callable implementation for execution.
  • inputSchema: *structpb.Struct. The input schema for the tool.
  • outputSchema: *structpb.Struct. The output schema for the tool.

Returns:

  • *CallableTool: A pointer to the created CallableTool.
  • error: An error if creation fails.

func (*CallableTool) Callable 

func (t *CallableTool) Callable() Callable

Callable returns the underlying Callable of the tool.

Summary: Retrieves the underlying Callable interface.

Returns:

  • Callable: The underlying callable.

func (*CallableTool) Execute 

func (t *CallableTool) Execute(ctx context.Context, req *ExecutionRequest) (any, error)

Execute handles the execution of the tool.

Summary: Executes the underlying callable.

Parameters:

  • ctx: context.Context. The context for the request.
  • req: *ExecutionRequest. The request object containing parameters.

Returns:

  • any: The result of the execution.
  • error: An error if the operation fails.

func (CallableTool) GetCacheConfig 

func (t CallableTool) GetCacheConfig() *configv1.CacheConfig

GetCacheConfig returns the cache configuration for the tool.

Summary: Retrieves the cache configuration for the tool.

Parameters:

  • None.

Returns:

  • *configv1.CacheConfig: Always returns nil for baseTool.

Errors:

  • None.

Side Effects:

  • None.

func (*CallableTool) IsStreaming 

func (t *CallableTool) IsStreaming() bool

IsStreaming returns true if the underlying callable supports streaming.

Summary: Checks if the tool supports streaming execution.

Returns:

  • bool: True if streaming is supported.

func (CallableTool) MCPTool 

func (t CallableTool) MCPTool() *mcp.Tool

MCPTool returns the MCP tool definition.

Summary: Retrieves the MCP-compliant tool definition.

Returns:

  • *mcp.Tool: The MCP tool definition.

Side Effects:

  • Lazily converts the proto definition to MCP format on first call.

func (*CallableTool) StreamExecute 

func (t *CallableTool) StreamExecute(ctx context.Context, req *ExecutionRequest) (<-chan any, error)

StreamExecute handles the streaming execution of the tool.

Summary: Executes the underlying callable in streaming mode.

Parameters:

  • ctx: context.Context. The context for the request.
  • req: *ExecutionRequest. The request object containing parameters.

Returns:

  • <-chan any: A channel that emits streaming results.
  • error: An error if the operation fails or streaming is not supported.

func (CallableTool) Tool 

func (t CallableTool) Tool() *v1.Tool

Tool returns the protobuf definition of the tool.

Summary: Retrieves the protobuf definition.

Returns:

  • *v1.Tool: The protobuf tool definition.

type CommandTool 

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

CommandTool implements the Tool interface for a tool that is executed as a local command-line process.

Summary: Tool implementation for command-line services (via executor).

It maps tool inputs to command-line arguments and environment variables.

func (*CommandTool) Execute 

func (t *CommandTool) Execute(ctx context.Context, req *ExecutionRequest) (any, error)

Execute handles the execution of the command-line tool.

Summary: Executes the command-line tool via executor.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

Errors:

  • Returns an error if initialization failed.
  • Returns an error if policy evaluation blocks the execution.
  • Returns an error if argument substitution or validation fails.
  • Returns an error if shell injection is detected.
  • Returns an error if the command execution fails.

Side Effects:

  • Executes a local command line process, potentially in a container.

func (*CommandTool) GetCacheConfig 

func (t *CommandTool) GetCacheConfig() *configv1.CacheConfig

GetCacheConfig returns the cache configuration for the command-line tool.

Returns:

  • *configv1.CacheConfig: The cache configuration, if any.

Summary: Retrieves GetCacheConfig operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func (*CommandTool) IsStreaming 

func (t *CommandTool) IsStreaming() bool

Execute handles the execution of the command-line tool.

Summary: Executes the command-line tool via executor.

It constructs a command with arguments and environment variables derived from the tool inputs, runs the command, and returns its output.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

Side Effects:

  • Executes a subprocess (potentially inside a container).
  • Consumes system resources.
  • Logs execution details.

IsStreaming returns true if the tool supports streaming.

Summary: Checks if the tool supports streaming execution.

Returns:

  • bool: True if streaming is supported.

func (*CommandTool) MCPTool 

func (t *CommandTool) MCPTool() *mcp.Tool

MCPTool returns the MCP-compliant tool definition.

It lazily converts the internal protobuf definition to the MCP format on first access.

Returns:

  • *mcp.Tool: The MCP tool definition.

Summary: Executes MCPTool operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func (*CommandTool) StreamExecute 

func (t *CommandTool) StreamExecute(ctx context.Context, req *ExecutionRequest) (<-chan any, error)

StreamExecute executes the tool in streaming mode.

Summary: Executes the tool in streaming mode.

Parameters:

  • ctx: context.Context. The context for the request.
  • req: *ExecutionRequest. The request object containing parameters.

Returns:

  • <-chan any: A channel that emits streaming results.
  • error: An error if the operation fails or streaming is not supported.

func (*CommandTool) Tool 

func (t *CommandTool) Tool() *v1.Tool

Tool returns the protobuf definition of the command-line tool.

Returns:

  • *v1.Tool: The underlying protobuf definition.

Summary: Executes Tool operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

type CompiledCallPolicy 

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

CompiledCallPolicy holds a compiled version of a call policy.

Summary: Represents a pre-compiled call policy for efficient evaluation.

func CompileCallPolicies 

func CompileCallPolicies(policies []*configv1.CallPolicy) ([]*CompiledCallPolicy, error)

CompileCallPolicies compiles a list of call policies into an efficient runtime format.

Summary: Compiles call policies for runtime usage.

Parameters:

  • policies: []*configv1.CallPolicy. The list of policies to compile.

Returns:

  • []*CompiledCallPolicy: The compiled policies.
  • error: An error if compilation fails (e.g., invalid regex).

func NewCompiledCallPolicy 

func NewCompiledCallPolicy(policy *configv1.CallPolicy) (*CompiledCallPolicy, error)

NewCompiledCallPolicy compiles a single call policy.

Summary: Compiles a single call policy.

Parameters:

  • policy: *configv1.CallPolicy. The policy to compile.

Returns:

  • *CompiledCallPolicy: The compiled policy.
  • error: An error if compilation fails.

type ExecutionFunc 

type ExecutionFunc func(ctx context.Context, req *ExecutionRequest) (any, error)

Summary: Defines the functional signature for middleware execution nodes, allowing request interception, augmentation, or short-circuiting before reaching the core tool logic.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The request payload.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

type ExecutionMiddleware 

type ExecutionMiddleware interface {
	// Execute performs the middleware logic wrapping the next handler in the chain.
	//
	// Summary: Executes middleware logic.
	//
	// Parameters:
	//   - ctx (context.Context): The context for the execution.
	//   - req (*ExecutionRequest): The execution request.
	//   - next (ExecutionFunc): The next handler in the chain.
	//
	// Returns:
	//   - any: The result of the execution.
	//   - error: An error if execution fails.
	Execute(ctx context.Context, req *ExecutionRequest, next ExecutionFunc) (any, error)
}

ExecutionMiddleware defines the interface for middleware that intercepts tool execution.

Summary: Interface for tool execution middleware.

type ExecutionRequest 

type ExecutionRequest struct {
	// ToolName is the name of the tool to be executed.
	ToolName string `json:"name"`
	// ToolInputs is the raw JSON message of the tool inputs. It is used by
	// tools that need to unmarshal the inputs into a specific struct.
	ToolInputs stdjson.RawMessage `json:"toolInputs"`
	// Arguments is a map of the tool inputs. It is used by tools that need to
	// access the inputs as a map.
	Arguments map[string]interface{} `json:"arguments"`
	// DryRun indicates whether the tool should be executed in dry-run mode.
	// In dry-run mode, the tool should validate inputs and return a preview
	// of the execution without performing any side effects.
	DryRun bool `json:"dryRun"`
	// Tool is the resolved tool instance. Populated internally to avoid re-lookup.
	Tool Tool `json:"-"`
}

Summary: Represents a structured invocation request for a specific tool, containing dynamic arguments and optional dry-run contexts required for safe execution. Parameters: None Returns: None Errors: None Side Effects: None

type GRPCTool 

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

GRPCTool implements the Tool interface for a tool that is exposed via a gRPC endpoint.

Summary: Tool implementation for gRPC services.

It handles the marshalling of JSON inputs to protobuf messages and invoking the gRPC method.

func NewGRPCTool 

func NewGRPCTool(tool *v1.Tool, poolManager *pool.Manager, serviceID string, method protoreflect.MethodDescriptor, callDefinition *configv1.GrpcCallDefinition, resilienceConfig *configv1.ResilienceConfig, policies []*configv1.CallPolicy, callID string) *GRPCTool

NewGRPCTool creates a new GRPCTool instance.

Summary: Initializes a new GRPCTool.

Parameters:

  • tool: *v1.Tool. The protobuf definition of the tool.
  • poolManager: *pool.Manager. The connection pool manager for gRPC connections.
  • serviceID: string. The identifier for the service.
  • method: protoreflect.MethodDescriptor. The gRPC method descriptor.
  • callDefinition: *configv1.GrpcCallDefinition. The configuration for the gRPC call.
  • resilienceConfig: *configv1.ResilienceConfig. The resilience configuration.
  • policies: []*configv1.CallPolicy. The security policies.
  • callID: string. The unique identifier for the call.

Returns:

  • *GRPCTool: The initialized GRPCTool.

func (*GRPCTool) Execute 

func (t *GRPCTool) Execute(ctx context.Context, req *ExecutionRequest) (any, error)

Execute handles the execution of the gRPC tool.

Summary: Executes the gRPC tool call.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

Errors:

  • Returns an error if the grpc pool is not found.
  • Returns an error if getting a client from the pool fails.
  • Returns an error if unmarshalling the tool inputs fails.
  • Returns an error if the grpc method invocation fails.

Side Effects:

  • Makes a gRPC call to the upstream service.

func (*GRPCTool) GetCacheConfig 

func (t *GRPCTool) GetCacheConfig() *configv1.CacheConfig

GetCacheConfig returns the cache configuration for the gRPC tool.

Returns:

  • *configv1.CacheConfig: The cache configuration, if any.

Summary: Retrieves GetCacheConfig operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func (*GRPCTool) IsStreaming 

func (t *GRPCTool) IsStreaming() bool

Execute handles the execution of the gRPC tool.

Summary: Executes the gRPC tool call.

It retrieves a client from the pool, unmarshals the JSON input into a protobuf request message, invokes the gRPC method, and marshals the protobuf response back to JSON.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • any: The execution result (usually a map or JSON string).
  • error: An error if execution fails.

Side Effects:

  • Makes a gRPC call to the upstream service.
  • Updates metrics (latency, success/error counts).
  • Logs execution details.

IsStreaming returns true if the tool supports streaming.

Summary: Checks if the tool supports streaming execution.

Returns:

  • bool: True if streaming is supported.

func (*GRPCTool) MCPTool 

func (t *GRPCTool) MCPTool() *mcp.Tool

MCPTool returns the MCP-compliant tool definition.

It lazily converts the internal protobuf definition to the MCP format on first access.

Returns:

  • *mcp.Tool: The MCP tool definition.

Summary: Executes MCPTool operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func (*GRPCTool) StreamExecute 

func (t *GRPCTool) StreamExecute(ctx context.Context, req *ExecutionRequest) (<-chan any, error)

StreamExecute executes the tool in streaming mode.

Summary: Executes the tool in streaming mode.

Parameters:

  • ctx: context.Context. The context for the request.
  • req: *ExecutionRequest. The request object containing parameters.

Returns:

  • <-chan any: A channel that emits streaming results.
  • error: An error if the operation fails or streaming is not supported.

func (*GRPCTool) Tool 

func (t *GRPCTool) Tool() *v1.Tool

Tool returns the protobuf definition of the gRPC tool.

Returns:

  • *v1.Tool: The underlying protobuf definition.

Summary: Executes Tool operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

type HTTPTool 

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

HTTPTool implements the Tool interface for a tool exposed via an HTTP endpoint.

Summary: Tool implementation for HTTP services.

It constructs and sends an HTTP request based on the tool definition and input, handling parameter mapping, authentication, and transformations.

func NewHTTPTool 

func NewHTTPTool(tool *v1.Tool, poolManager *pool.Manager, serviceID string, authenticator auth.UpstreamAuthenticator, callDefinition *configv1.HttpCallDefinition, cfg *configv1.ResilienceConfig, policies []*configv1.CallPolicy, callID string) *HTTPTool

NewHTTPTool creates a new HTTPTool instance.

Summary: Initializes a new HTTPTool.

Parameters:

  • tool: *v1.Tool. The protobuf definition of the tool.
  • poolManager: *pool.Manager. The connection pool manager for HTTP connections.
  • serviceID: string. The identifier for the service.
  • authenticator: auth.UpstreamAuthenticator. The authenticator for upstream requests.
  • callDefinition: *configv1.HttpCallDefinition. The configuration for the HTTP call.
  • cfg: *configv1.ResilienceConfig. The resilience configuration.
  • policies: []*configv1.CallPolicy. The security policies for the call.
  • callID: string. The unique identifier for the call.

Returns:

  • *HTTPTool: The initialized HTTPTool.

func (*HTTPTool) Execute 

func (t *HTTPTool) Execute(ctx context.Context, req *ExecutionRequest) (any, error)

Execute handles the execution of the HTTP tool.

Summary: Executes the HTTP tool call.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

Errors:

  • Returns an error if policy evaluation fails or blocks execution.
  • Returns an error if the http pool is not found.
  • Returns an error if getting a client from the pool fails.
  • Returns an error if input validation or body preparation fails.
  • Returns an error if the HTTP request fails.

Side Effects:

  • Makes an HTTP request to the upstream service.

func (*HTTPTool) GetCacheConfig 

func (t *HTTPTool) GetCacheConfig() *configv1.CacheConfig

GetCacheConfig returns the cache configuration for the HTTP tool.

Returns:

  • *configv1.CacheConfig: The cache configuration, if any.

Summary: Retrieves GetCacheConfig operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func (*HTTPTool) IsStreaming 

func (t *HTTPTool) IsStreaming() bool

Execute handles the execution of the HTTP tool.

Summary: Executes the HTTP tool call.

It builds an HTTP request by mapping input parameters to the path, query, and body, applies any configured transformations, sends the request, and processes the response.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

Side Effects:

  • Makes an HTTP request to the upstream service.
  • Updates metrics.
  • Logs execution details.

IsStreaming returns true if the tool supports streaming.

Summary: Checks if the tool supports streaming execution.

Returns:

  • bool: True if streaming is supported.

func (*HTTPTool) MCPTool 

func (t *HTTPTool) MCPTool() *mcp.Tool

MCPTool returns the MCP-compliant tool definition.

It lazily converts the internal protobuf definition to the MCP format on first access.

Returns:

  • *mcp.Tool: The MCP tool definition.

Summary: Executes MCPTool operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func (*HTTPTool) StreamExecute 

func (t *HTTPTool) StreamExecute(ctx context.Context, req *ExecutionRequest) (<-chan any, error)

StreamExecute executes the tool in streaming mode.

Summary: Executes the tool in streaming mode.

Parameters:

  • ctx: context.Context. The context for the request.
  • req: *ExecutionRequest. The request object containing parameters.

Returns:

  • <-chan any: A channel that emits streaming results.
  • error: An error if the operation fails or streaming is not supported.

func (*HTTPTool) Tool 

func (t *HTTPTool) Tool() *v1.Tool

Tool returns the protobuf definition of the HTTP tool.

Returns:

  • *v1.Tool: The underlying protobuf definition.

Summary: Executes Tool operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

type LocalCommandTool 

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

LocalCommandTool implements the Tool interface for a tool that is executed as a local command-line process.

Summary: Tool implementation for local command-line services.

It maps tool inputs to command-line arguments and environment variables.

func (*LocalCommandTool) Execute 

func (t *LocalCommandTool) Execute(ctx context.Context, req *ExecutionRequest) (any, error)

Execute handles the execution of the command-line tool.

Summary: Executes the local command-line tool.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

Errors:

  • Returns an error if initialization failed.
  • Returns an error if policy evaluation blocks the execution.
  • Returns an error if argument substitution or validation fails.
  • Returns an error if shell injection is detected.
  • Returns an error if the command execution fails.

Side Effects:

  • Executes a local command line process.

func (*LocalCommandTool) GetCacheConfig 

func (t *LocalCommandTool) GetCacheConfig() *configv1.CacheConfig

GetCacheConfig returns the cache configuration for the command-line tool.

Returns:

  • *configv1.CacheConfig: The cache configuration, if any.

Summary: Retrieves GetCacheConfig operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func (*LocalCommandTool) IsStreaming 

func (t *LocalCommandTool) IsStreaming() bool

Execute handles the execution of the command-line tool.

Summary: Executes the local command-line tool.

It constructs a command with arguments and environment variables derived from the tool inputs, runs the command, and returns its output.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

Side Effects:

  • Executes a subprocess on the local system.
  • Consumes system resources (CPU, memory).
  • Logs execution details.

IsStreaming returns true if the tool supports streaming.

Summary: Checks if the tool supports streaming execution.

Returns:

  • bool: True if streaming is supported.

func (*LocalCommandTool) MCPTool 

func (t *LocalCommandTool) MCPTool() *mcp.Tool

MCPTool returns the MCP-compliant tool definition.

It lazily converts the internal protobuf definition to the MCP format on first access.

Returns:

  • *mcp.Tool: The MCP tool definition.

Summary: Executes MCPTool operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func (*LocalCommandTool) StreamExecute 

func (t *LocalCommandTool) StreamExecute(ctx context.Context, req *ExecutionRequest) (<-chan any, error)

StreamExecute executes the tool in streaming mode.

Summary: Executes the tool in streaming mode.

Parameters:

  • ctx: context.Context. The context for the request.
  • req: *ExecutionRequest. The request object containing parameters.

Returns:

  • <-chan any: A channel that emits streaming results.
  • error: An error if the operation fails or streaming is not supported.

func (*LocalCommandTool) Tool 

func (t *LocalCommandTool) Tool() *v1.Tool

Tool returns the protobuf definition of the command-line tool.

Returns:

  • *v1.Tool: The underlying protobuf definition.

Summary: Executes Tool operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

type MCPServerProvider 

type MCPServerProvider interface {
	// Server returns the underlying MCP server instance.
	//
	// Summary: Retrieves the MCP server instance.
	//
	// Returns:
	//   - *mcp.Server: The MCP server instance.
	Server() *mcp.Server
}

MCPServerProvider defines an interface for components that can provide an instance of an *mcp.Server.

Summary: Interface for providing an MCP server instance.

This interface is used to decouple the Manager from the concrete server implementation, avoiding circular dependencies.

type MCPTool 

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

MCPTool implements the Tool interface for a tool that is exposed via another MCP-compliant service.

Summary: Tool implementation for proxying to MCP services.

It acts as a proxy, forwarding the tool call to the downstream MCP service.

func NewMCPTool 

func NewMCPTool(tool *v1.Tool, client client.MCPClient, callDefinition *configv1.MCPCallDefinition) *MCPTool

NewMCPTool creates a new MCPTool instance.

Summary: Initializes a new MCPTool.

Parameters:

  • tool: *v1.Tool. The protobuf definition of the tool.
  • client: client.MCPClient. The MCP client for downstream communication.
  • callDefinition: *configv1.MCPCallDefinition. The configuration for the MCP call.

Returns:

  • *MCPTool: The initialized MCPTool.

func (*MCPTool) Execute 

func (t *MCPTool) Execute(ctx context.Context, req *ExecutionRequest) (any, error)

Execute handles the execution of the MCP tool.

Summary: Executes the MCP tool call.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

Errors:

  • Returns an error if initialization failed.
  • Returns an error if unmarshalling tool inputs fails.
  • Returns an error if the transformation webhook fails.
  • Returns an error if calling the tool on the downstream MCP service fails.
  • Returns an error if output parsing or transformation fails.

Side Effects:

  • Makes a call to a downstream MCP service.

func (*MCPTool) GetCacheConfig 

func (t *MCPTool) GetCacheConfig() *configv1.CacheConfig

GetCacheConfig returns the cache configuration for the MCP tool.

Returns:

  • *configv1.CacheConfig: The cache configuration, if any.

Summary: Retrieves GetCacheConfig operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func (*MCPTool) IsStreaming 

func (t *MCPTool) IsStreaming() bool

Execute handles the execution of the MCP tool.

Summary: Executes the MCP tool call.

It forwards the tool call, including its name and arguments, to the downstream MCP service using the configured client and applies any necessary transformations to the request and response.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

Side Effects:

  • Makes an MCP call to the upstream service.
  • Logs execution details.

IsStreaming returns true if the tool supports streaming.

Summary: Checks if the tool supports streaming execution.

Returns:

  • bool: True if streaming is supported.

func (*MCPTool) MCPTool 

func (t *MCPTool) MCPTool() *mcp.Tool

MCPTool returns the MCP-compliant tool definition.

It lazily converts the internal protobuf definition to the MCP format on first access.

Returns:

  • *mcp.Tool: The MCP tool definition.

Summary: Executes MCPTool operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func (*MCPTool) StreamExecute 

func (t *MCPTool) StreamExecute(ctx context.Context, req *ExecutionRequest) (<-chan any, error)

StreamExecute executes the tool in streaming mode.

Summary: Executes the tool in streaming mode.

Parameters:

  • ctx: context.Context. The context for the request.
  • req: *ExecutionRequest. The request object containing parameters.

Returns:

  • <-chan any: A channel that emits streaming results.
  • error: An error if the operation fails or streaming is not supported.

func (*MCPTool) Tool 

func (t *MCPTool) Tool() *v1.Tool

Tool returns the protobuf definition of the MCP tool.

Returns:

  • *v1.Tool: The underlying protobuf definition.

Summary: Executes Tool operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

type Manager 

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

Manager is the central component for managing tools in MCP Any.

Summary: Central manager for tool lifecycle and execution.

It handles tool registration, retrieval, execution, and profile-based filtering. It is thread-safe and supports efficient lookups via caching and indexing.

func NewManager 

func NewManager(bus *bus.Provider) *Manager

NewManager creates and initializes a new Tool Manager.

Summary: Creates a new Manager.

Parameters:

  • bus (*bus.Provider): The event bus provider for publishing tool execution events.

Returns:

  • *Manager: A pointer to the newly created Manager.

Side Effects:

  • Allocates memory for internal maps and indices.

func (*Manager) AddMiddleware 

func (tm *Manager) AddMiddleware(middleware ExecutionMiddleware)

AddMiddleware adds a middleware to the tool manager.

Summary: Adds execution middleware.

The middleware will be executed as part of the tool execution chain.

Parameters:

  • middleware (ExecutionMiddleware): The middleware instance to add.

Side Effects:

  • Appends middleware to the internal list.

func (*Manager) AddServiceInfo 

func (tm *Manager) AddServiceInfo(serviceID string, info *ServiceInfo)

AddServiceInfo registers metadata about a service.

Summary: Registers service metadata.

It processes the service configuration to set up hooks and call policies.

Parameters:

  • serviceID (string): The unique identifier for the service.
  • info (*ServiceInfo): The ServiceInfo struct containing the service's metadata and configuration.

Side Effects:

  • Stores service info in the internal map.

func (*Manager) AddTool 

func (tm *Manager) AddTool(tool Tool) error

AddTool registers a new tool with the manager.

Summary: Registers a tool.

It performs validation, sanitization, and integrity checks. If an MCP server is configured, it also registers the tool with the server.

Parameters:

  • tool (Tool): The tool instance to be added.

Returns:

  • error: An error if validation fails or the tool cannot be added.

Errors:

  • Returns error if integrity check fails.
  • Returns error if sanitization fails.
  • Returns error if tool registration with MCP server fails.

Side Effects:

  • Stores the tool in internal maps and indices.
  • Registers tool handler with MCP server.

func (*Manager) ClearToolsForService 

func (tm *Manager) ClearToolsForService(serviceID string)

ClearToolsForService removes all tools associated with a given service ID.

Summary: Removes tools for a service.

It efficiently cleans up internal indices and caches.

Parameters:

  • serviceID (string): The unique identifier for the service.

Side Effects:

  • Removes entries from the tools map and secondary indices.
  • Invalidates internal caches.

func (*Manager) ExecuteTool 

func (tm *Manager) ExecuteTool(ctx context.Context, req *ExecutionRequest) (any, error)

ExecuteTool finds a tool by its name and executes it.

Summary: Executes a tool.

It handles the entire lifecycle of a tool call, including: 1. Resolving the tool. 2. Checking service health. 3. Running pre-execution hooks and policies. 4. Executing the tool logic. 5. Running post-execution hooks. 6. Running middlewares.

Parameters:

  • ctx (context.Context): The context for the tool execution.
  • req (*ExecutionRequest): The request containing the tool name and input arguments.

Returns:

  • any: The result of the execution (type varies by tool).
  • error: An error if the tool is not found, execution is denied, or the tool fails.

Errors:

  • ErrToolNotFound: If the tool cannot be found (includes fuzzy matching suggestions).
  • Returns error if service is unhealthy or hooks fail.

Side Effects:

  • Executes the tool logic (which may have side effects).
  • Runs pre/post-execution hooks.
  • Logs execution details.

func (*Manager) GetAllowedServiceIDs 

func (tm *Manager) GetAllowedServiceIDs(profileID string) (map[string]bool, bool)

GetAllowedServiceIDs returns a map of allowed service IDs for a given profile.

Summary: Retrieves allowed service IDs for a profile.

The returned map uses the service ID as the key and a boolean true as the value.

Parameters:

  • profileID (string): The identifier of the profile.

Returns:

  • map[string]bool: A map of allowed service IDs.
  • bool: True if the profile exists and has cached allowed services.

func (*Manager) GetServiceInfo 

func (tm *Manager) GetServiceInfo(serviceID string) (*ServiceInfo, bool)

GetServiceInfo retrieves the metadata for a registered service.

Summary: Retrieves service metadata.

It returns a copy of the service info with secrets stripped from the configuration for security.

Parameters:

  • serviceID (string): The unique identifier for the service.

Returns:

  • *ServiceInfo: The service information.
  • bool: True if the service was found, false otherwise.

func (*Manager) GetTool 

func (tm *Manager) GetTool(toolName string) (Tool, bool)

GetTool retrieves a tool from the manager by its fully qualified name.

Summary: Retrieves a tool by name.

It first attempts to look up the tool by its exact ID (useful if the client sends the ID). If that fails, it looks up the tool by its client-facing name (using the name map).

Parameters:

  • toolName (string): The name or ID of the tool to retrieve.

Returns:

  • Tool: The tool instance.
  • bool: True if the tool was found, false otherwise.

func (*Manager) GetToolCountForService 

func (tm *Manager) GetToolCountForService(serviceID string) int

GetToolCountForService returns the number of tools registered for a given service.

Summary: Counts tools for a service.

It first checks if the service is healthy; if not, it returns 0.

Parameters:

  • serviceID (string): The unique identifier of the service.

Returns:

  • int: The number of active tools for the service.

func (*Manager) IsServiceAllowed 

func (tm *Manager) IsServiceAllowed(serviceID, profileID string) bool

IsServiceAllowed checks if a service is allowed for a given profile.

Summary: Checks if a service is allowed for a profile.

Parameters:

  • serviceID (string): The unique identifier of the service.
  • profileID (string): The identifier of the profile to check.

Returns:

  • bool: True if the service is allowed, false otherwise.

func (*Manager) ListMCPTools 

func (tm *Manager) ListMCPTools() []*mcp.Tool

ListMCPTools returns a slice containing all the tools currently registered with the manager in MCP format.

Summary: Lists all tools in MCP format.

It maintains a cache of the MCP tool definitions to minimize overhead.

Returns:

  • []*mcp.Tool: A slice of MCP tool definitions.

Side Effects:

  • Updates internal caches if they are invalid.

func (*Manager) ListServices 

func (tm *Manager) ListServices() []*ServiceInfo

ListServices returns a list of all currently registered services.

Summary: Lists all services.

It strips secrets from the service configurations before returning them.

Returns:

  • []*ServiceInfo: A slice of ServiceInfo structs.

func (*Manager) ListTools 

func (tm *Manager) ListTools() []Tool

ListTools returns a list of all tools currently registered with the manager.

Summary: Lists all tools.

It uses a read-through cache to avoid rebuilding the list on every call.

Returns:

  • []Tool: A slice of Tool instances.

func (*Manager) SetMCPServer 

func (tm *Manager) SetMCPServer(mcpServer MCPServerProvider)

SetMCPServer provides the Manager with a reference to the MCP server.

Summary: Sets the MCP server.

This allows the manager to register tool handlers directly with the server.

Parameters:

  • mcpServer (MCPServerProvider): The MCP server provider interface.

Side Effects:

  • Updates the internal mcpServer reference.

func (*Manager) SetProfiles 

func (tm *Manager) SetProfiles(enabled []string, defs []*configv1.ProfileDefinition)

SetProfiles sets the enabled profiles and their definitions for filtering.

Summary: Configures profiles for filtering.

This method updates the internal state used for profile-based access control. It pre-computes allowed services for each profile to optimize lookup performance.

Parameters:

  • enabled ([]string): A list of names of the currently active profiles.
  • defs ([]*configv1.ProfileDefinition): The definitions of all available profiles.

Side Effects:

  • Updates internal profile definitions and caches.

func (*Manager) ToolMatchesProfile 

func (tm *Manager) ToolMatchesProfile(tool Tool, profileID string) bool

ToolMatchesProfile checks if a tool matches a given profile.

Summary: Checks if a tool matches a profile.

It delegates to the internal toolMatchesProfile method.

Parameters:

  • tool (Tool): The tool definition.
  • profileID (string): The identifier of the profile.

Returns:

  • bool: True if the tool matches the profile, false otherwise.

type ManagerInterface 

type ManagerInterface interface {
	// AddTool registers a new tool with the manager.
	//
	// Summary: Registers a tool.
	//
	// Parameters:
	//   - tool (Tool): The tool definition to register.
	//
	// Returns:
	//   - error: An error if the tool cannot be registered (e.g., duplicate name).
	AddTool(tool Tool) error

	// GetTool retrieves a tool by its unique name or ID.
	//
	// Summary: Retrieves a tool.
	//
	// Parameters:
	//   - toolName (string): The name or ID of the tool to retrieve.
	//
	// Returns:
	//   - Tool: The tool instance if found.
	//   - bool: True if the tool was found, false otherwise.
	GetTool(toolName string) (Tool, bool)

	// ListTools returns a list of all currently registered tools.
	//
	// Summary: Lists all tools.
	//
	// Returns:
	//   - []Tool: A slice of registered tools.
	ListTools() []Tool

	// ListMCPTools returns a list of all registered tools formatted for the MCP protocol.
	//
	// Summary: Lists all tools in MCP format.
	//
	// This method is optimized for the MCP `tools/list` request.
	//
	// Returns:
	//   - []*mcp.Tool: A slice of MCP tool definitions.
	ListMCPTools() []*mcp.Tool

	// ClearToolsForService removes all tools associated with a specific service ID.
	//
	// Summary: Removes tools for a service.
	//
	// This is typically used when a service is reloaded or removed.
	//
	// Parameters:
	//   - serviceID (string): The unique identifier of the service.
	ClearToolsForService(serviceID string)

	// ExecuteTool executes a specific tool with the provided request parameters.
	//
	// Summary: Executes a tool.
	//
	// Parameters:
	//   - ctx (context.Context): The context for the execution.
	//   - req (*ExecutionRequest): The request containing the tool name and arguments.
	//
	// Returns:
	//   - any: The result of the tool execution.
	//   - error: An error if execution fails.
	ExecuteTool(ctx context.Context, req *ExecutionRequest) (any, error)

	// SetMCPServer sets the MCP server provider for the manager.
	//
	// Summary: Sets the MCP server provider.
	//
	// This allows the manager to register tool handlers with the underlying MCP server.
	//
	// Parameters:
	//   - mcpServer (MCPServerProvider): The provider interface.
	SetMCPServer(mcpServer MCPServerProvider)

	// AddMiddleware adds a middleware to the tool execution chain.
	//
	// Summary: Adds execution middleware.
	//
	// Parameters:
	//   - middleware (ExecutionMiddleware): The middleware to add.
	AddMiddleware(middleware ExecutionMiddleware)

	// AddServiceInfo adds metadata for a registered service.
	//
	// Summary: Adds service metadata.
	//
	// Parameters:
	//   - serviceID (string): The unique identifier of the service.
	//   - info (*ServiceInfo): The metadata associated with the service.
	AddServiceInfo(serviceID string, info *ServiceInfo)

	// GetServiceInfo retrieves metadata for a service by its ID.
	//
	// Summary: Retrieves service metadata.
	//
	// Parameters:
	//   - serviceID (string): The unique identifier of the service.
	//
	// Returns:
	//   - *ServiceInfo: The service metadata if found.
	//   - bool: True if the service info was found, false otherwise.
	GetServiceInfo(serviceID string) (*ServiceInfo, bool)

	// ListServices returns a list of all services known to the manager.
	//
	// Summary: Lists all services.
	//
	// Returns:
	//   - []*ServiceInfo: A slice of service metadata.
	ListServices() []*ServiceInfo

	// SetProfiles configures the active profiles and their definitions.
	//
	// Summary: Configures active profiles.
	//
	// This is used for filtering tools based on user profiles and permissions.
	//
	// Parameters:
	//   - enabled ([]string): A list of enabled profile names.
	//   - defs ([]*configv1.ProfileDefinition): The detailed definitions of the profiles.
	SetProfiles(enabled []string, defs []*configv1.ProfileDefinition)

	// IsServiceAllowed checks if a specific service is accessible under a given profile.
	//
	// Summary: Checks if a service is allowed.
	//
	// Parameters:
	//   - serviceID (string): The unique identifier of the service.
	//   - profileID (string): The identifier of the profile to check against.
	//
	// Returns:
	//   - bool: True if the service is allowed, false otherwise.
	IsServiceAllowed(serviceID, profileID string) bool

	// ToolMatchesProfile checks if a specific tool is accessible under a given profile.
	//
	// Summary: Checks if a tool matches a profile.
	//
	// Parameters:
	//   - tool (Tool): The tool to check.
	//   - profileID (string): The identifier of the profile to check against.
	//
	// Returns:
	//   - bool: True if the tool matches the profile's criteria, false otherwise.
	ToolMatchesProfile(tool Tool, profileID string) bool

	// GetAllowedServiceIDs returns a set of allowed service IDs for a given profile.
	//
	// Summary: Retrieves allowed service IDs for a profile.
	//
	// This is optimized for quick lookups during filtering.
	//
	// Parameters:
	//   - profileID (string): The identifier of the profile.
	//
	// Returns:
	//   - map[string]bool: A map where keys are allowed service IDs.
	//   - bool: True if the profile exists.
	GetAllowedServiceIDs(profileID string) (map[string]bool, bool)

	// GetToolCountForService returns the number of tools registered for a given service.
	//
	// Summary: Counts tools for a service.
	//
	// Parameters:
	//   - serviceID (string): The unique identifier of the service.
	//
	// Returns:
	//   - int: The count of registered tools.
	GetToolCountForService(serviceID string) int
}

ManagerInterface defines the contract for a tool manager.

Summary: Interface for tool management operations.

It outlines the methods required for managing the lifecycle, registration, discovery, and execution of tools within the MCP Any server.

type MockManagerInterface 

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

MockManagerInterface is a mock of ManagerInterface interface.

Summary: Mock tool manager for testing.

func NewMockManagerInterface 

func NewMockManagerInterface(ctrl *gomock.Controller) *MockManagerInterface

NewMockManagerInterface creates a new mock instance.

Summary: Initializes a new mock tool manager.

Parameters:

  • ctrl: *gomock.Controller. The mock controller.

Returns:

  • *MockManagerInterface: A new mock instance.

func (*MockManagerInterface) AddMiddleware 

func (m *MockManagerInterface) AddMiddleware(middleware ExecutionMiddleware)

AddMiddleware mocks base method.

Summary: Mock implementation of AddMiddleware.

Parameters:

  • middleware: ExecutionMiddleware. The middleware to add.

func (*MockManagerInterface) AddServiceInfo 

func (m *MockManagerInterface) AddServiceInfo(serviceID string, info *ServiceInfo)

AddServiceInfo mocks base method.

Summary: Mock implementation of AddServiceInfo.

Parameters:

  • serviceID: string. The service ID.
  • info: *ServiceInfo. The service info.

func (*MockManagerInterface) AddTool 

func (m *MockManagerInterface) AddTool(tool Tool) error

AddTool mocks base method.

Summary: Mock implementation of AddTool.

Parameters:

  • tool: Tool. The tool to add.

Returns:

  • error: An error if the operation fails.

func (*MockManagerInterface) ClearToolsForService 

func (m *MockManagerInterface) ClearToolsForService(serviceID string)

ClearToolsForService mocks base method.

Summary: Mock implementation of ClearToolsForService.

Parameters:

  • serviceID: string. The service ID.

func (*MockManagerInterface) EXPECT 

func (m *MockManagerInterface) EXPECT() *MockManagerInterfaceMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

Summary: Returns the recorder for expectations.

Returns:

  • *MockManagerInterfaceMockRecorder: The recorder.

func (*MockManagerInterface) ExecuteTool 

func (m *MockManagerInterface) ExecuteTool(ctx context.Context, req *ExecutionRequest) (any, error)

ExecuteTool mocks base method.

Summary: Mock implementation of ExecuteTool.

Parameters:

  • ctx: context.Context. The request context.
  • req: *ExecutionRequest. The request object.

Returns:

  • any: The result.
  • error: An error if the operation fails.

func (*MockManagerInterface) GetAllowedServiceIDs 

func (m *MockManagerInterface) GetAllowedServiceIDs(profileID string) (map[string]bool, bool)

GetAllowedServiceIDs mocks base method.

Summary: Mock implementation of GetAllowedServiceIDs.

Parameters:

  • profileID: string. The profile ID.

Returns:

  • map[string]bool: The map of allowed service IDs.
  • bool: True if successful.

func (*MockManagerInterface) GetServiceInfo 

func (m *MockManagerInterface) GetServiceInfo(serviceID string) (*ServiceInfo, bool)

GetServiceInfo mocks base method.

Summary: Mock implementation of GetServiceInfo.

Parameters:

  • serviceID: string. The service ID.

Returns:

  • *ServiceInfo: The service info.
  • bool: True if found.

func (*MockManagerInterface) GetTool 

func (m *MockManagerInterface) GetTool(toolName string) (Tool, bool)

GetTool mocks base method.

Summary: Mock implementation of GetTool.

Parameters:

  • toolName: string. The tool name.

Returns:

  • Tool: The tool.
  • bool: True if found.

func (*MockManagerInterface) GetToolCountForService 

func (m *MockManagerInterface) GetToolCountForService(serviceID string) int

GetToolCountForService mocks base method.

Summary: Mock implementation of GetToolCountForService.

Parameters:

  • serviceID: string. The service ID.

Returns:

  • int: The tool count.

func (*MockManagerInterface) IsServiceAllowed 

func (m *MockManagerInterface) IsServiceAllowed(serviceID, profileID string) bool

IsServiceAllowed mocks base method.

Summary: Mock implementation of IsServiceAllowed.

Parameters:

  • serviceID: string. The service ID.
  • profileID: string. The profile ID.

Returns:

  • bool: True if allowed.

func (*MockManagerInterface) ListMCPTools 

func (m *MockManagerInterface) ListMCPTools() []*mcp.Tool

ListMCPTools mocks base method.

Summary: Mock implementation of ListMCPTools.

Returns:

  • []*mcp.Tool: The list of MCP tools.

func (*MockManagerInterface) ListServices 

func (m *MockManagerInterface) ListServices() []*ServiceInfo

ListServices mocks base method.

Summary: Mock implementation of ListServices.

Returns:

  • []*ServiceInfo: The list of services.

func (*MockManagerInterface) ListTools 

func (m *MockManagerInterface) ListTools() []Tool

ListTools mocks base method.

Summary: Mock implementation of ListTools.

Returns:

  • []Tool: The list of tools.

func (*MockManagerInterface) SetMCPServer 

func (m *MockManagerInterface) SetMCPServer(mcpServer MCPServerProvider)

SetMCPServer mocks base method.

Summary: Mock implementation of SetMCPServer.

Parameters:

  • mcpServer: MCPServerProvider. The MCP server provider.

func (*MockManagerInterface) SetProfiles 

func (m *MockManagerInterface) SetProfiles(enabled []string, defs []*v1.ProfileDefinition)

SetProfiles mocks base method.

Summary: Mock implementation of SetProfiles.

Parameters:

  • enabled: []string. Enabled profiles.
  • defs: []*v1.ProfileDefinition. Profile definitions.

func (*MockManagerInterface) ToolMatchesProfile 

func (m *MockManagerInterface) ToolMatchesProfile(tool Tool, profileID string) bool

ToolMatchesProfile mocks base method.

Summary: Mock implementation of ToolMatchesProfile.

Parameters:

  • tool: Tool. The tool.
  • profileID: string. The profile ID.

Returns:

  • bool: True if the tool matches the profile.

type MockManagerInterfaceMockRecorder 

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

MockManagerInterfaceMockRecorder is the mock recorder for MockManagerInterface.

Summary: Recorder for MockManagerInterface expectations.

func (*MockManagerInterfaceMockRecorder) AddMiddleware 

func (mr *MockManagerInterfaceMockRecorder) AddMiddleware(middleware any) *gomock.Call

AddMiddleware indicates an expected call of AddMiddleware.

Summary: Expectation for AddMiddleware.

Parameters:

  • middleware: any. The expected middleware.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) AddServiceInfo 

func (mr *MockManagerInterfaceMockRecorder) AddServiceInfo(serviceID, info any) *gomock.Call

AddServiceInfo indicates an expected call of AddServiceInfo.

Summary: Expectation for AddServiceInfo.

Parameters:

  • serviceID: any. The expected service ID.
  • info: any. The expected service info.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) AddTool 

func (mr *MockManagerInterfaceMockRecorder) AddTool(tool any) *gomock.Call

AddTool indicates an expected call of AddTool.

Summary: Expectation for AddTool.

Parameters:

  • tool: any. The expected tool.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) ClearToolsForService 

func (mr *MockManagerInterfaceMockRecorder) ClearToolsForService(serviceID any) *gomock.Call

ClearToolsForService indicates an expected call of ClearToolsForService.

Summary: Expectation for ClearToolsForService.

Parameters:

  • serviceID: any. The expected service ID.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) ExecuteTool 

func (mr *MockManagerInterfaceMockRecorder) ExecuteTool(ctx, req any) *gomock.Call

ExecuteTool indicates an expected call of ExecuteTool.

Summary: Expectation for ExecuteTool.

Parameters:

  • ctx: any. The expected context.
  • req: any. The expected request.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) GetAllowedServiceIDs 

func (mr *MockManagerInterfaceMockRecorder) GetAllowedServiceIDs(profileID any) *gomock.Call

GetAllowedServiceIDs indicates an expected call of GetAllowedServiceIDs.

Summary: Expectation for GetAllowedServiceIDs.

Parameters:

  • profileID: any. The expected profile ID.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) GetServiceInfo 

func (mr *MockManagerInterfaceMockRecorder) GetServiceInfo(serviceID any) *gomock.Call

GetServiceInfo indicates an expected call of GetServiceInfo.

Summary: Expectation for GetServiceInfo.

Parameters:

  • serviceID: any. The expected service ID.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) GetTool 

func (mr *MockManagerInterfaceMockRecorder) GetTool(toolName any) *gomock.Call

GetTool indicates an expected call of GetTool.

Summary: Expectation for GetTool.

Parameters:

  • toolName: any. The expected tool name.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) GetToolCountForService 

func (mr *MockManagerInterfaceMockRecorder) GetToolCountForService(serviceID any) *gomock.Call

GetToolCountForService indicates an expected call of GetToolCountForService.

Summary: Expectation for GetToolCountForService.

Parameters:

  • serviceID: any. The expected service ID.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) IsServiceAllowed 

func (mr *MockManagerInterfaceMockRecorder) IsServiceAllowed(serviceID, profileID any) *gomock.Call

IsServiceAllowed indicates an expected call of IsServiceAllowed.

Summary: Expectation for IsServiceAllowed.

Parameters:

  • serviceID: any. The expected service ID.
  • profileID: any. The expected profile ID.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) ListMCPTools 

func (mr *MockManagerInterfaceMockRecorder) ListMCPTools() *gomock.Call

ListMCPTools indicates an expected call of ListMCPTools.

Summary: Expectation for ListMCPTools.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) ListServices 

func (mr *MockManagerInterfaceMockRecorder) ListServices() *gomock.Call

ListServices indicates an expected call of ListServices.

Summary: Expectation for ListServices.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) ListTools 

func (mr *MockManagerInterfaceMockRecorder) ListTools() *gomock.Call

ListTools indicates an expected call of ListTools.

Summary: Expectation for ListTools.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) SetMCPServer 

func (mr *MockManagerInterfaceMockRecorder) SetMCPServer(mcpServer any) *gomock.Call

SetMCPServer indicates an expected call of SetMCPServer.

Summary: Expectation for SetMCPServer.

Parameters:

  • mcpServer: any. The expected MCP server provider.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) SetProfiles 

func (mr *MockManagerInterfaceMockRecorder) SetProfiles(enabled, defs any) *gomock.Call

SetProfiles indicates an expected call of SetProfiles.

Summary: Expectation for SetProfiles.

Parameters:

  • enabled: any. The expected enabled profiles.
  • defs: any. The expected profile definitions.

Returns:

  • *gomock.Call: The mock call.

func (*MockManagerInterfaceMockRecorder) ToolMatchesProfile 

func (mr *MockManagerInterfaceMockRecorder) ToolMatchesProfile(tool, profileID any) *gomock.Call

ToolMatchesProfile indicates an expected call of ToolMatchesProfile.

Summary: Expectation for ToolMatchesProfile.

Parameters:

  • tool: any. The expected tool.
  • profileID: any. The expected profile ID.

Returns:

  • *gomock.Call: The mock call.

type MockTool 

type MockTool struct {
	ToolFunc           func() *v1.Tool
	MCPToolFunc        func() *mcp.Tool
	ExecuteFunc        func(ctx context.Context, req *ExecutionRequest) (any, error)
	GetCacheConfigFunc func() *configv1.CacheConfig
}

MockTool is a mock implementation of the Tool interface for testing purposes.

Summary: Mock tool for testing.

func (*MockTool) Execute 

func (m *MockTool) Execute(ctx context.Context, req *ExecutionRequest) (any, error)

Execute calls the mock ExecuteFunc if set, otherwise returns nil.

Summary: Executes the mock tool.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

Errors:

  • Returns the error returned by the underlying mock ExecuteFunc.

Side Effects:

  • Calls the underlying mock ExecuteFunc.

func (*MockTool) GetCacheConfig 

func (m *MockTool) GetCacheConfig() *configv1.CacheConfig

GetCacheConfig calls the mock GetCacheConfigFunc if set, otherwise returns nil.

Summary: Retrieves the cache configuration.

Returns:

  • *configv1.CacheConfig: The cache configuration.

func (*MockTool) IsStreaming 

func (m *MockTool) IsStreaming() bool

IsStreaming returns whether the mock tool supports streaming.

Summary: Checks if the mock tool supports streaming.

Parameters:

  • None.

Returns:

  • bool: Always returns false.

Errors:

  • None.

Side Effects:

  • None.

func (*MockTool) MCPTool 

func (m *MockTool) MCPTool() *mcp.Tool

MCPTool returns the MCP tool definition.

Summary: Retrieves the MCP tool definition.

Returns:

  • *mcp.Tool: The MCP tool definition.

func (*MockTool) StreamExecute 

func (m *MockTool) StreamExecute(ctx context.Context, req *ExecutionRequest) (<-chan any, error)

StreamExecute executes the mock tool in streaming mode.

Summary: Executes the mock tool in streaming mode.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • <-chan any: A channel that emits the result or error.
  • error: Always nil for the mock tool.

Errors:

  • None.

Side Effects:

  • Executes the mock tool logic asynchronously.

func (*MockTool) Tool 

func (m *MockTool) Tool() *v1.Tool

Tool returns the protobuf definition of the mock tool.

Summary: Retrieves the mock tool definition.

Returns:

  • *v1.Tool: The tool definition.

type OpenAPITool 

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

OpenAPITool implements the Tool interface for a tool defined in an OpenAPI specification.

Summary: Tool implementation for OpenAPI services.

It constructs and sends an HTTP request based on the OpenAPI operation definition.

func NewOpenAPITool 

func NewOpenAPITool(tool *v1.Tool, client client.HTTPClient, parameterDefs map[string]string, method, url string, authenticator auth.UpstreamAuthenticator, callDefinition *configv1.OpenAPICallDefinition) *OpenAPITool

NewOpenAPITool creates a new OpenAPITool instance.

Summary: Initializes a new OpenAPITool.

Parameters:

  • tool: *v1.Tool. The protobuf definition of the tool.
  • client: client.HTTPClient. The HTTP client for requests.
  • parameterDefs: map[string]string. Mapping of parameter names to their locations.
  • method: string. The HTTP method.
  • url: string. The URL template.
  • authenticator: auth.UpstreamAuthenticator. The authenticator for upstream requests.
  • callDefinition: *configv1.OpenAPICallDefinition. The configuration for the OpenAPI call.

Returns:

  • *OpenAPITool: The initialized OpenAPITool.

func (*OpenAPITool) Execute 

func (t *OpenAPITool) Execute(ctx context.Context, req *ExecutionRequest) (any, error)

Execute handles the execution of the OpenAPI tool.

Summary: Executes the OpenAPI tool call.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

Errors:

  • Returns an error if initialization failed.
  • Returns an error if unmarshalling tool inputs fails.
  • Returns an error if URL validation fails.
  • Returns an error if HTTP request creation or execution fails.
  • Returns an error if the upstream HTTP response status is >= 400.
  • Returns an error if reading the response body fails.
  • Returns an error if output parsing or transformation fails.

Side Effects:

  • Makes an HTTP request to the upstream service.

func (*OpenAPITool) GetCacheConfig 

func (t *OpenAPITool) GetCacheConfig() *configv1.CacheConfig

GetCacheConfig returns the cache configuration for the OpenAPI tool.

Returns:

  • *configv1.CacheConfig: The cache configuration, if any.

Summary: Retrieves GetCacheConfig operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func (*OpenAPITool) IsStreaming 

func (t *OpenAPITool) IsStreaming() bool

Execute handles the execution of the OpenAPI tool.

Summary: Executes the OpenAPI tool call.

It constructs an HTTP request based on the operation's method, URL, and parameter definitions, sends the request, and processes the response, applying transformations as needed.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

Side Effects:

  • Makes an HTTP request to the upstream service.
  • Logs execution details.

IsStreaming returns true if the tool supports streaming.

Summary: Checks if the tool supports streaming execution.

Returns:

  • bool: True if streaming is supported.

func (*OpenAPITool) MCPTool 

func (t *OpenAPITool) MCPTool() *mcp.Tool

MCPTool returns the MCP-compliant tool definition.

It lazily converts the internal protobuf definition to the MCP format on first access.

Returns:

  • *mcp.Tool: The MCP tool definition.

Summary: Executes MCPTool operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

func (*OpenAPITool) StreamExecute 

func (t *OpenAPITool) StreamExecute(ctx context.Context, req *ExecutionRequest) (<-chan any, error)

StreamExecute executes the tool in streaming mode.

Summary: Executes the tool in streaming mode.

Parameters:

  • ctx: context.Context. The context for the request.
  • req: *ExecutionRequest. The request object containing parameters.

Returns:

  • <-chan any: A channel that emits streaming results.
  • error: An error if the operation fails or streaming is not supported.

func (*OpenAPITool) Tool 

func (t *OpenAPITool) Tool() *v1.Tool

Tool returns the protobuf definition of the OpenAPI tool.

Returns:

  • *v1.Tool: The underlying protobuf definition.

Summary: Executes Tool operation.

Parameters:

  • TODO: Document parameters.

Returns:

  • TODO: Document returns.

Errors:

  • TODO: Document errors.

Side Effects:

  • None.

type PolicyHook 

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

PolicyHook implements PreCallHook using CallPolicy.

Summary: Pre-call hook that enforces call policies defined in configuration.

func NewPolicyHook 

func NewPolicyHook(policy *configv1.CallPolicy) *PolicyHook

NewPolicyHook creates a new PolicyHook with the given call policy.

Summary: Initializes a new PolicyHook.

Parameters:

  • policy: *configv1.CallPolicy. The policy configuration to enforce.

Returns:

  • *PolicyHook: The initialized hook.

Side Effects:

  • Compiles regex patterns from the policy rules.
  • Logs errors for invalid regexes.

func (*PolicyHook) ExecutePre 

func (h *PolicyHook) ExecutePre(
	_ context.Context,
	req *ExecutionRequest,
) (Action, *ExecutionRequest, error)

ExecutePre executes the policy check before a tool is called.

Summary: Evaluates the tool request against the compiled policy rules.

Parameters:

  • _: context.Context. Unused.
  • req: *ExecutionRequest. The tool execution request.

Returns:

  • Action: The action to take (Allow, Deny, etc.).
  • *ExecutionRequest: The modified request (nil if no modification).
  • error: An error if the policy denies execution.

Errors:

  • Returns error if an explicit DENY rule is matched.
  • Returns error if the default policy is DENY and no ALLOW rule matches.

type PostCallHook 

type PostCallHook interface {
	// ExecutePost runs the hook. It returns the potentially modified result
	// (or original if unchanged) and an error.
	ExecutePost(ctx context.Context, req *ExecutionRequest, result any) (any, error)
}

PostCallHook defines the interface for hooks executed after a tool call.

Summary: Interface for post-execution hooks.

type PreCallHook 

type PreCallHook interface {
	// ExecutePre runs the hook. It returns an action (Allow/Deny),
	// a potentially modified request (or nil if unchanged), and an error.
	ExecutePre(ctx context.Context, req *ExecutionRequest) (Action, *ExecutionRequest, error)
}

PreCallHook defines the interface for hooks executed before a tool call.

Summary: Interface for pre-execution hooks.

type Sampler 

type Sampler = Session

Sampler is an alias for Session for backward compatibility.

Summary: Represents a Sampler.

func GetSampler deprecated 

func GetSampler(ctx context.Context) (Sampler, bool)

GetSampler retrieves the Sampler from the context.

Summary: Retrieves Sampler from context.

Deprecated: Use GetSession instead.

Parameters:

  • ctx: context.Context. The context.

Returns:

  • Sampler: The sampler if found.
  • bool: True if the sampler exists.

type ServiceInfo 

type ServiceInfo struct {
	// Name is the unique name of the service.
	Name string
	// Config is the configuration of the upstream service.
	Config *configv1.UpstreamServiceConfig
	// Fds is the FileDescriptorSet associated with the service (for gRPC/protobuf).
	Fds *descriptorpb.FileDescriptorSet

	// PreHooks are the cached pre-call hooks for the service.
	PreHooks []PreCallHook
	// PostHooks are the cached post-call hooks for the service.
	PostHooks []PostCallHook

	// CompiledPolicies are the pre-compiled call policies for the service.
	CompiledPolicies []*CompiledCallPolicy

	// HealthStatus indicates the health of the service ("healthy", "unhealthy", "unknown").
	HealthStatus string
}

Summary: Encapsulates runtime and configuration metadata for an upstream service, bridging the gap between its static protobuf definitions and its active health state. Parameters: None Returns: None Errors: None Side Effects: None

type ServiceRegistry 

type ServiceRegistry interface {
	// GetTool retrieves a tool by name.
	//
	// Parameters:
	//   - toolName: The name of the tool to retrieve.
	//
	// Returns:
	//   - Tool: The tool instance if found.
	//   - bool: True if the tool exists, false otherwise.
	GetTool(toolName string) (Tool, bool)

	// GetServiceInfo retrieves metadata for a service.
	//
	// Parameters:
	//   - serviceID: The unique identifier of the service.
	//
	// Returns:
	//   - *ServiceInfo: The service metadata info if found.
	//   - bool: True if the service exists, false otherwise.
	GetServiceInfo(serviceID string) (*ServiceInfo, bool)
}

Summary: Provides a read-only registry interface enabling dynamic lookup of available tools and their corresponding upstream service configurations without tight coupling to the active manager. Parameters: None Returns: None Errors: None Side Effects: None

type Session 

type Session interface {
	// CreateMessage requests a message creation (sampling) from the client.
	//
	// Summary: Requests message creation.
	//
	// Parameters:
	//   - ctx: context.Context. The context for the request.
	//   - params: *mcp.CreateMessageParams. The parameters for message creation.
	//
	// Returns:
	//   - *mcp.CreateMessageResult: The result of the message creation.
	//   - error: An error if the operation fails.
	CreateMessage(ctx context.Context, params *mcp.CreateMessageParams) (*mcp.CreateMessageResult, error)

	// ListRoots requests the list of roots from the client.
	//
	// Summary: Requests roots list.
	//
	// Parameters:
	//   - ctx: context.Context. The context for the request.
	//
	// Returns:
	//   - *mcp.ListRootsResult: The list of roots.
	//   - error: An error if the operation fails.
	ListRoots(ctx context.Context) (*mcp.ListRootsResult, error)
}

Session defines the interface for tools to interact with the client session. It includes capabilities like Sampling (CreateMessage) and Roots inspection.

Summary: Represents a Session.

func GetSession 

func GetSession(ctx context.Context) (Session, bool)

GetSession retrieves the Session from the context.

Summary: Retrieves Session from context.

Parameters:

  • ctx: context.Context. The context.

Returns:

  • Session: The session if found.
  • bool: True if the session exists.

type SigningRoundTripper 

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

SigningRoundTripper signs the request using the webhook signer.

Summary: HTTP Transport that adds HMAC signatures to outgoing requests.

func (*SigningRoundTripper) RoundTrip 

func (s *SigningRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip executes the HTTP request with a signature.

Summary: Intercepts the request to add Webhook-Id, Webhook-Timestamp, and Webhook-Signature headers.

Parameters:

  • req: *http.Request. The outgoing request.

Returns:

  • *http.Response: The received response.
  • error: An error if signing or transport fails.

Side Effects:

  • Reads and buffers the request body for signing.
  • Modifies request headers.

type StreamingCallable 

type StreamingCallable interface {
	Callable

	// StreamCall executes the callable with the given request, emitting updates to the channel.
	//
	// Parameters:
	//   - ctx: context.Context. The context for the request.
	//   - req: *ExecutionRequest. The execution request details.
	//
	// Returns:
	//   - <-chan any: A channel that emits streaming results.
	//   - error: An error if the initial operation fails.
	StreamCall(ctx context.Context, req *ExecutionRequest) (<-chan any, error)
}

Summary: Extends the base Callable contract to support asynchronous, continuous data streams for large or long-running computations. Parameters: None Returns: None Errors: None Side Effects: None

type Tool 

type Tool interface {
	// Tool returns the protobuf definition of the tool.
	//
	// Returns:
	//   - *v1.Tool: The protobuf tool definition.
	Tool() *v1.Tool

	// MCPTool returns the MCP tool definition.
	//
	// Returns:
	//   - *mcp.Tool: The MCP tool definition.
	MCPTool() *mcp.Tool

	// Execute runs the tool with the provided context and request, returning
	// the result or an error.
	//
	// Summary: Executes the tool.
	//
	// Parameters:
	//   - ctx: context.Context. The execution context.
	//   - req: *ExecutionRequest. The request payload.
	//
	// Returns:
	//   - any: The execution result.
	//   - error: An error if execution fails.
	//
	// Side Effects:
	//   - Executes the underlying service logic (network calls, command execution, etc.).
	Execute(ctx context.Context, req *ExecutionRequest) (any, error)

	// IsStreaming returns true if the tool supports streaming execution.
	//
	// Summary: Checks if the tool supports streaming execution.
	//
	// Returns:
	//   - bool: True if streaming is supported.
	IsStreaming() bool

	// StreamExecute runs the tool in streaming mode, returning a channel of results.
	//
	// Summary: Executes the tool in streaming mode.
	//
	// Parameters:
	//   - ctx: context.Context. The execution context.
	//   - req: *ExecutionRequest. The request payload.
	//
	// Returns:
	//   - <-chan any: A channel that emits streaming results.
	//   - error: An error if the operation fails or streaming is not supported.
	//
	// Side Effects:
	//   - Executes the underlying service logic in a streaming manner.
	StreamExecute(ctx context.Context, req *ExecutionRequest) (<-chan any, error)

	// GetCacheConfig returns the cache configuration for the tool.
	//
	// Summary: Retrieves cache configuration.
	//
	// Returns:
	//   - *configv1.CacheConfig: The cache configuration, or nil if none.
	GetCacheConfig() *configv1.CacheConfig
}

Tool is the fundamental interface for any executable tool in the system.

Summary: Interface for defining and executing tools.

Each implementation represents a different type of underlying service (e.g., gRPC, HTTP, command-line).

func GetFromContext 

func GetFromContext(ctx context.Context) (Tool, bool)

Summary: Extracts a previously injected Tool instance from the provided context, facilitating decoupled access to tool metadata within isolated execution boundaries.

Parameters:

  • ctx: context.Context. The context to search.

Returns:

  • Tool: The tool instance from the context.
  • bool: True if a tool was found, false otherwise.

func NewCommandTool 

func NewCommandTool(
	tool *v1.Tool,
	service *configv1.CommandLineUpstreamService,
	callDefinition *configv1.CommandLineCallDefinition,
	policies []*configv1.CallPolicy,
	callID string,
) Tool

NewCommandTool creates a new CommandTool instance.

Summary: Initializes a new CommandTool.

Parameters:

  • tool: *v1.Tool. The protobuf definition of the tool.
  • service: *configv1.CommandLineUpstreamService. The service configuration.
  • callDefinition: *configv1.CommandLineCallDefinition. The call configuration.
  • policies: []*configv1.CallPolicy. The security policies.
  • callID: string. The unique identifier for the call.

Returns:

  • Tool: The created CommandTool.

func NewLocalCommandTool 

func NewLocalCommandTool(
	tool *v1.Tool,
	service *configv1.CommandLineUpstreamService,
	callDefinition *configv1.CommandLineCallDefinition,
	policies []*configv1.CallPolicy,
	callID string,
) Tool

NewLocalCommandTool creates a new LocalCommandTool instance.

Summary: Initializes a new LocalCommandTool.

Parameters:

  • tool: *v1.Tool. The protobuf definition of the tool.
  • service: *configv1.CommandLineUpstreamService. The service configuration.
  • callDefinition: *configv1.CommandLineCallDefinition. The call configuration.
  • policies: []*configv1.CallPolicy. The security policies.
  • callID: string. The unique identifier for the call.

Returns:

  • Tool: The created LocalCommandTool.

type WebhookClient 

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

WebhookClient handles the communication with an external webhook.

Summary: Client for sending CloudEvents to external webhooks.

func NewWebhookClient 

func NewWebhookClient(config *configv1.WebhookConfig) *WebhookClient

NewWebhookClient creates a new WebhookClient.

Summary: Initializes a new WebhookClient.

Parameters:

  • config: *configv1.WebhookConfig. The webhook configuration.

Returns:

  • *WebhookClient: The initialized client.

Side Effects:

  • Initializes HTTP client and optional signer.

func (*WebhookClient) Call 

func (c *WebhookClient) Call(ctx context.Context, eventType string, data any) (*cloudevents.Event, error)

Call sends a cloud event to the webhook and returns the response event.

Summary: Sends a synchronous CloudEvent to the webhook URL.

Parameters:

  • ctx: context.Context. The request context.
  • eventType: string. The CloudEvent type.
  • data: any. The event payload.

Returns:

  • *cloudevents.Event: The response CloudEvent.
  • error: An error if the request fails or response is missing.

Errors:

  • Returns error if event creation or serialization fails.
  • Returns error if the HTTP request fails or is undelivered.
  • Returns error if no response event is received.

Side Effects:

  • Makes an external HTTP POST request.

type WebhookHook 

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

WebhookHook supports modification of requests and responses via external webhook using CloudEvents.

Summary: Hook implementation that delegates logic to an external webhook.

func NewWebhookHook 

func NewWebhookHook(config *configv1.WebhookConfig) *WebhookHook

NewWebhookHook creates a new WebhookHook.

Summary: Initializes a new WebhookHook.

Parameters:

  • config: *configv1.WebhookConfig. The webhook configuration.

Returns:

  • *WebhookHook: The initialized hook.

func (*WebhookHook) ExecutePost 

func (h *WebhookHook) ExecutePost(
	ctx context.Context,
	req *ExecutionRequest,
	result any,
) (any, error)

ExecutePost executes the webhook notification after a tool is called.

Summary: Sends a post-call event to the webhook and potentially modifies the result.

Parameters:

  • ctx: context.Context. The request context.
  • req: *ExecutionRequest. The original request.
  • result: any. The result of the tool execution.

Returns:

  • any: The (potentially modified) result.
  • error: An error if the webhook call fails.

Errors:

  • Returns error if webhook call or response processing fails.

Side Effects:

  • Invokes external webhook.

func (*WebhookHook) ExecutePre 

func (h *WebhookHook) ExecutePre(
	ctx context.Context,
	req *ExecutionRequest,
) (Action, *ExecutionRequest, error)

ExecutePre executes the webhook notification before a tool is called.

Summary: Sends a pre-call event to the webhook and handles the response.

Parameters:

  • ctx: context.Context. The request context.
  • req: *ExecutionRequest. The execution request.

Returns:

  • Action: Allow or Deny based on webhook response.
  • *ExecutionRequest: Modified request if webhook returned replacements.
  • error: An error if webhook denies or fails.

Errors:

  • Returns error if input marshaling fails.
  • Returns error if webhook call fails.
  • Returns error if webhook response parsing fails.
  • Returns "denied by webhook" if explicitly denied.

Side Effects:

  • Invokes external webhook.

type WebhookStatus 

type WebhookStatus struct {
	// Code is the status code returned by the webhook.
	Code int `json:"code"`
	// Message is a descriptive message returned by the webhook.
	Message string `json:"message"`
}

WebhookStatus represents the status returned by the webhook.

Summary: Status information included in the webhook response.

type WebrtcTool 

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

WebrtcTool implements the Tool interface for a tool that is exposed via a WebRTC data channel.

Summary: WebRTC Tool implementation.

It handles the signaling and establishment of a peer connection to communicate with the remote service. This is useful for scenarios requiring low-latency, peer-to-peer communication directly from the server.

func NewWebrtcTool 

func NewWebrtcTool(
	tool *v1.Tool,
	poolManager *pool.Manager,
	serviceID string,
	authenticator auth.UpstreamAuthenticator,
	callDefinition *configv1.WebrtcCallDefinition,
) (*WebrtcTool, error)

NewWebrtcTool creates a new WebrtcTool.

Summary: Initializes a new WebrtcTool.

Parameters:

  • tool (*v1.Tool): The protobuf definition of the tool.
  • poolManager (*pool.Manager): Used to get a client from the connection pool.
  • serviceID (string): Identifies the specific service connection pool.
  • authenticator (auth.UpstreamAuthenticator): Handles adding authentication credentials to the signaling request.
  • callDefinition (*configv1.WebrtcCallDefinition): Contains the configuration for the WebRTC call.

Returns:

  • (*WebrtcTool): The initialized WebrtcTool.
  • (error): An error if initialization fails.

func (*WebrtcTool) Close 

func (t *WebrtcTool) Close() error

Close is a placeholder for any cleanup logic.

Summary: Cleans up the WebrtcTool.

Currently, it is a no-op as the peer connection is created and closed within the Execute method, unless a pool is used.

Returns:

  • error: Always nil.

func (*WebrtcTool) Execute 

func (t *WebrtcTool) Execute(ctx context.Context, req *ExecutionRequest) (any, error)

Execute executes the WebRTC tool.

Summary: Executes the WebRTC request and waits for the response.

Parameters:

  • ctx (context.Context): The context for execution.
  • req (*ExecutionRequest): The request parameters.

Returns:

  • any: The response from the WebRTC endpoint.
  • error: An error if the WebRTC communication fails.

Errors:

  • Returns an error if policy evaluation blocks the execution.
  • Returns an error if marshalling the inputs fails.
  • Returns an error if the WebRTC request fails.

Side Effects:

  • Makes a WebRTC network call.

func (*WebrtcTool) GetCacheConfig 

func (t *WebrtcTool) GetCacheConfig() *configv1.CacheConfig

GetCacheConfig returns the cache configuration for the WebRTC tool.

Summary: Returns the cache configuration.

Returns:

  • *configv1.CacheConfig: The cache configuration.

func (*WebrtcTool) IsStreaming 

func (t *WebrtcTool) IsStreaming() bool

Execute handles the execution of the WebRTC tool.

Summary: Executes the WebRTC tool.

It establishes a new peer connection (or reuses one), negotiates the session via an HTTP signaling server, sends the tool inputs over the data channel, and waits for a response.

Parameters:

  • ctx (context.Context): The execution context.
  • req (*ExecutionRequest): The execution request.

Returns:

  • any: The result of the execution.
  • error: An error if execution fails.

IsStreaming returns true if the tool supports streaming.

Summary: Checks if the tool supports streaming execution.

Returns:

  • bool: True if streaming is supported.

func (*WebrtcTool) MCPTool 

func (t *WebrtcTool) MCPTool() *mcp.Tool

MCPTool returns the MCP tool definition.

Summary: Returns the MCP tool definition.

Returns:

  • *mcp.Tool: The MCP tool definition.

func (*WebrtcTool) StreamExecute 

func (t *WebrtcTool) StreamExecute(ctx context.Context, req *ExecutionRequest) (<-chan any, error)

StreamExecute executes the tool in streaming mode.

Summary: Executes the tool in streaming mode.

Parameters:

  • ctx: context.Context. The context for the request.
  • req: *ExecutionRequest. The request object containing parameters.

Returns:

  • <-chan any: A channel that emits streaming results.
  • error: An error if the operation fails or streaming is not supported.

func (*WebrtcTool) Tool 

func (t *WebrtcTool) Tool() *v1.Tool

Tool returns the protobuf definition of the WebRTC tool.

Summary: Returns the protobuf tool definition.

Returns:

  • *v1.Tool: The tool definition.

type WebsocketTool 

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

WebsocketTool implements the Tool interface for a tool exposed via a WebSocket connection. It handles sending and receiving messages over a persistent WebSocket connection managed by a connection pool.

Summary: A tool implementation for WebSocket services.

func NewWebsocketTool 

func NewWebsocketTool(
	tool *v1.Tool,
	poolManager *pool.Manager,
	serviceID string,
	authenticator auth.UpstreamAuthenticator,
	callDefinition *configv1.WebsocketCallDefinition,
) *WebsocketTool

NewWebsocketTool creates a new WebsocketTool.

Summary: Initializes a new WebsocketTool.

Parameters:

  • tool: *v1.Tool. The protobuf definition of the tool.
  • poolManager: *pool.Manager. The manager for WebSocket connections.
  • serviceID: string. The ID of the WebSocket service.
  • authenticator: auth.UpstreamAuthenticator. The authenticator for the connection.
  • callDefinition: *configv1.WebsocketCallDefinition. Configuration for the WebSocket call.

Returns:

  • *WebsocketTool: A new instance of WebsocketTool.

func (*WebsocketTool) Execute 

func (t *WebsocketTool) Execute(ctx context.Context, req *ExecutionRequest) (any, error)

Execute executes the WebSocket tool.

Summary: Executes the WebSocket request and waits for a response.

Parameters:

  • ctx (context.Context): The context for execution.
  • req (*ExecutionRequest): The request parameters.

Returns:

  • any: The response from the WebSocket.
  • error: An error if the WebSocket communication fails.

Errors:

  • Returns an error if the websocket pool is not found.
  • Returns an error if getting a connection from the pool fails.
  • Returns an error if marshalling the inputs fails.
  • Returns an error if secret resolution fails.
  • Returns an error if input transformation fails.
  • Returns an error if sending or reading a message fails.

Side Effects:

  • Makes a WebSocket network call.

func (*WebsocketTool) GetCacheConfig 

func (t *WebsocketTool) GetCacheConfig() *configv1.CacheConfig

GetCacheConfig returns the cache configuration for the WebSocket tool.

Summary: Retrieves the cache configuration.

Returns:

  • *configv1.CacheConfig: The cache configuration.

func (*WebsocketTool) IsStreaming 

func (t *WebsocketTool) IsStreaming() bool

Execute handles the execution of the WebSocket tool.

Summary: Executes the tool over WebSocket.

It retrieves a connection from the pool, sends the tool inputs as a message, and waits for a single response message, which it then processes and returns.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *ExecutionRequest. The request containing input arguments.

Returns:

  • any: The execution result.
  • error: An error if execution fails.

IsStreaming returns true if the tool supports streaming.

Summary: Checks if the tool supports streaming execution.

Returns:

  • bool: True if streaming is supported.

func (*WebsocketTool) MCPTool 

func (t *WebsocketTool) MCPTool() *mcp.Tool

MCPTool returns the MCP tool definition.

Summary: Retrieves the MCP-compatible tool definition.

Returns:

  • *mcp.Tool: The MCP tool definition.

func (*WebsocketTool) StreamExecute 

func (t *WebsocketTool) StreamExecute(ctx context.Context, req *ExecutionRequest) (<-chan any, error)

StreamExecute executes the tool in streaming mode.

Summary: Executes the tool in streaming mode.

Parameters:

  • ctx: context.Context. The context for the request.
  • req: *ExecutionRequest. The request object containing parameters.

Returns:

  • <-chan any: A channel that emits streaming results.
  • error: An error if the operation fails or streaming is not supported.

func (*WebsocketTool) Tool 

func (t *WebsocketTool) Tool() *v1.Tool

Tool returns the protobuf definition of the WebSocket tool.

Summary: Retrieves the underlying tool definition.

Returns:

  • *v1.Tool: The tool definition.

Source Files

View all Source files

Directories

Path Synopsis
Package browser provides a browser automation tool.
 Package browser provides a browser automation tool.

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.