Documentation
¶
Overview ¶
Package optimizer provides the Optimizer interface for intelligent tool discovery and invocation in the Virtual MCP Server.
When the optimizer is enabled, vMCP exposes only two tools to clients:
- find_tool: Semantic search over available tools
- call_tool: Dynamic invocation of any backend tool
This reduces token usage by avoiding the need to send all tool definitions to the LLM, instead allowing it to discover relevant tools on demand.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CallToolInput ¶
type CallToolInput struct {
// ToolName is the name of the tool to invoke.
ToolName string `json:"tool_name" description:"Name of the tool to call"`
// Parameters are the arguments to pass to the tool.
Parameters map[string]any `json:"parameters" description:"Parameters to pass to the tool"`
}
CallToolInput contains the parameters for calling a tool.
type DummyOptimizer ¶
type DummyOptimizer struct {
// contains filtered or unexported fields
}
DummyOptimizer implements the Optimizer interface using exact string matching.
This implementation is intended for testing and development. It performs case-insensitive substring matching on tool names and descriptions.
For production use, see the EmbeddingOptimizer which uses semantic similarity.
func (DummyOptimizer) CallTool ¶
func (d DummyOptimizer) CallTool(ctx context.Context, input CallToolInput) (*mcp.CallToolResult, error)
CallTool invokes a tool by name using its registered handler.
The tool is looked up by exact name match. If found, the handler is invoked directly with the given parameters.
func (DummyOptimizer) FindTool ¶
func (d DummyOptimizer) FindTool(_ context.Context, input FindToolInput) (*FindToolOutput, error)
FindTool searches for tools using exact substring matching.
The search is case-insensitive and matches against:
- Tool name (substring match)
- Tool description (substring match)
Returns all matching tools with a score of 1.0 (exact match semantics). TokenMetrics are returned as zero values (not implemented in dummy).
type FindToolInput ¶
type FindToolInput struct {
// ToolDescription is a natural language description of the tool to find.
ToolDescription string `json:"tool_description" description:"Natural language description of the tool to find"`
// ToolKeywords is an optional list of keywords to narrow the search.
ToolKeywords []string `json:"tool_keywords,omitempty" description:"Optional keywords to narrow search"`
}
FindToolInput contains the parameters for finding tools.
type FindToolOutput ¶
type FindToolOutput struct {
// Tools contains the matching tools, ranked by relevance.
Tools []ToolMatch `json:"tools"`
// TokenMetrics provides information about token savings from using the optimizer.
TokenMetrics TokenMetrics `json:"token_metrics"`
}
FindToolOutput contains the results of a tool search.
type Optimizer ¶
type Optimizer interface {
// FindTool searches for tools matching the given description and keywords.
// Returns matching tools ranked by relevance score.
FindTool(ctx context.Context, input FindToolInput) (*FindToolOutput, error)
// CallTool invokes a tool by name with the given parameters.
// Returns the tool's result or an error if the tool is not found or execution fails.
// Returns the MCP CallToolResult directly from the underlying tool handler.
CallTool(ctx context.Context, input CallToolInput) (*mcp.CallToolResult, error)
}
Optimizer defines the interface for intelligent tool discovery and invocation.
Implementations may use various strategies for tool matching:
- DummyOptimizer: Exact string matching (for testing)
- EmbeddingOptimizer: Semantic similarity via embeddings (production)
func NewDummyOptimizer ¶
func NewDummyOptimizer(tools []server.ServerTool) Optimizer
NewDummyOptimizer creates a new DummyOptimizer with the given tools.
The tools slice should contain all backend tools (as ServerTool with handlers).
type TokenMetrics ¶
type TokenMetrics struct {
// BaselineTokens is the estimated tokens if all tools were sent.
BaselineTokens int `json:"baseline_tokens"`
// ReturnedTokens is the actual tokens for the returned tools.
ReturnedTokens int `json:"returned_tokens"`
// SavingsPercent is the percentage of tokens saved.
SavingsPercent float64 `json:"savings_percent"`
}
TokenMetrics provides information about token usage optimization.
type ToolMatch ¶
type ToolMatch struct {
// Name is the unique identifier of the tool.
Name string `json:"name"`
// Description is the human-readable description of the tool.
Description string `json:"description"`
// InputSchema is the JSON schema for the tool's input parameters.
// Uses json.RawMessage to preserve the original schema format.
InputSchema json.RawMessage `json:"input_schema"`
// Score indicates how well this tool matches the search criteria (0.0-1.0).
Score float64 `json:"score"`
}
ToolMatch represents a tool that matched the search criteria.
Source Files