metatools

package
v0.7.7 Latest Latest
Warning

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

 Go to latest Published: Jun 18, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package metatools provides server-side meta-tool handlers for the MCP aggregator.

This package implements the meta-tools that enable AI assistants to discover and interact with tools, resources, and prompts available through the muster aggregator. Meta-tools provide an indirection layer that allows AI assistants to dynamically discover and call tools without hard-coding specific tool names.

Architecture

The metatools package follows the API Service Locator Pattern established in the muster architecture. It retrieves the aggregator handler through api.GetAggregator() and does not directly depend on other packages.

Key components:

  • Provider: Main entry point that registers meta-tools with the aggregator
  • Handlers: Implementation of individual meta-tool operations
  • Formatters: Response formatting utilities for JSON output
  • Adapter: API layer integration following the service locator pattern

Available Meta-Tools

Discovery tools:

  • list_tools: List all available tools from connected MCP servers
  • describe_tool: Get detailed information about a specific tool
  • list_core_tools: List core muster tools (built-in functionality)
  • filter_tools: Filter tools based on name patterns or descriptions

Execution tools:

  • call_tool: Execute any tool by name with arguments

Resource tools:

  • list_resources: List all available resources
  • describe_resource: Get detailed information about a specific resource
  • get_resource: Retrieve resource contents

Prompt tools:

  • list_prompts: List all available prompts
  • describe_prompt: Get detailed information about a specific prompt
  • get_prompt: Execute a prompt with arguments

Session Awareness

Meta-tools are session-aware and use the context session ID for tool visibility. This ensures that tools requiring authentication are only visible to authenticated sessions.

Response Format

The call_tool meta-tool preserves the full CallToolResult structure (IsError, Content types) as structured JSON, rather than flattening to text. This maintains BDD test validation fidelity and enables proper response unwrapping by clients.

Usage

The metatools package is initialized and registered during application startup via the API adapter: 

// In app initialization
adapter := metatools.NewAdapter()
adapter.Register()

Once registered, meta-tools are available through the aggregator's tool interface and can be called like any other tool.

Index

Constants

View Source 
const (
	// ToolListTools lists all available tools for the session.
	ToolListTools = "list_tools"

	// ToolDescribeTool gets detailed schema for a specific tool.
	ToolDescribeTool = "describe_tool"

	// ToolFilterTools searches/filters tools by pattern.
	ToolFilterTools = "filter_tools"

	// ToolListCoreTools lists only Muster core tools.
	ToolListCoreTools = "list_core_tools"

	// ToolCallTool executes any tool by name.
	ToolCallTool = "call_tool"

	// ToolListResources lists available MCP resources.
	ToolListResources = "list_resources"

	// ToolDescribeResource gets resource metadata.
	ToolDescribeResource = "describe_resource"

	// ToolGetResource reads resource contents.
	ToolGetResource = "get_resource"

	// ToolListPrompts lists available prompts.
	ToolListPrompts = "list_prompts"

	// ToolDescribePrompt gets prompt details.
	ToolDescribePrompt = "describe_prompt"

	// ToolGetPrompt executes a prompt.
	ToolGetPrompt = "get_prompt"
)

Meta-tool name constants. These are the meta-tools exposed by the aggregator that wrap actual tool access.

Variables

This section is empty.

Functions

func SerializeContent 

func SerializeContent(content []mcp.Content) []interface{}

SerializeContent serializes MCP content items to a format suitable for JSON. This preserves the full structure of content items for proper response unwrapping.

Args:

  • content: Slice of MCP content interfaces

Returns:

  • Slice of serializable content representations

Types

type Adapter 

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

Adapter connects the metatools package to the central API layer. It implements the api.MetaToolsHandler interface by delegating to an underlying data provider (typically the aggregator).

The Adapter follows the API service locator pattern, allowing the metatools package to be registered during application initialization and accessed by handlers through the api.GetMetaTools() function.

func NewAdapter 

func NewAdapter() *Adapter

NewAdapter creates a new metatools adapter instance. The adapter manages the metatools provider and handles registration with the API layer.

Returns:

  • *Adapter: A new adapter instance ready for registration

func (*Adapter) CallTool 

func (a *Adapter) CallTool(ctx context.Context, name string, args map[string]interface{}) (*mcp.CallToolResult, error)

CallTool executes a tool by name with the provided arguments. This delegates to the data provider (aggregator) for tool execution.

func (*Adapter) ExecuteTool 

func (a *Adapter) ExecuteTool(ctx context.Context, toolName string, args map[string]interface{}) (*api.CallToolResult, error)

ExecuteTool executes a specific meta-tool by name with the provided arguments. This implements the api.ToolProvider interface for tool execution.

Args:

  • ctx: Context for the operation
  • toolName: The name of the meta-tool to execute
  • args: Arguments for the tool execution

Returns:

  • *api.CallToolResult: The result of the tool execution
  • error: Error if the tool doesn't exist or execution fails

func (*Adapter) GetPrompt 

func (a *Adapter) GetPrompt(ctx context.Context, name string, args map[string]string) (*mcp.GetPromptResult, error)

GetPrompt executes a prompt with the provided arguments. This delegates to the data provider (aggregator) for prompt execution.

func (*Adapter) GetProvider 

func (a *Adapter) GetProvider() *Provider

GetProvider returns the underlying metatools provider. This allows access to provider functionality for direct use.

Returns:

  • *Provider: The metatools provider instance

func (*Adapter) GetResource 

func (a *Adapter) GetResource(ctx context.Context, uri string) (*mcp.ReadResourceResult, error)

GetResource retrieves the contents of a resource by URI. This delegates to the data provider (aggregator) for resource access.

func (*Adapter) GetTools 

func (a *Adapter) GetTools() []api.ToolMetadata

GetTools returns metadata for all meta-tools this package offers. This implements the api.ToolProvider interface for tool discovery.

Returns:

  • []api.ToolMetadata: List of all meta-tools provided

func (*Adapter) ListPrompts 

func (a *Adapter) ListPrompts(ctx context.Context) ([]mcp.Prompt, error)

ListPrompts returns all available prompts for the current session. This delegates to the data provider (aggregator) which handles session-scoped prompt visibility for OAuth-protected servers.

func (*Adapter) ListResources 

func (a *Adapter) ListResources(ctx context.Context) ([]mcp.Resource, error)

ListResources returns all available resources for the current session. This delegates to the data provider (aggregator) which handles session-scoped resource visibility for OAuth-protected servers.

func (*Adapter) ListServersRequiringAuth 

func (a *Adapter) ListServersRequiringAuth(ctx context.Context) []api.ServerAuthInfo

ListServersRequiringAuth returns a list of servers that require authentication for the current session. This is used by the list_tools handler to inform users about available servers that need authentication.

func (*Adapter) ListTools 

func (a *Adapter) ListTools(ctx context.Context) ([]mcp.Tool, error)

ListTools returns all available tools for the current session. This delegates to the data provider (aggregator) which handles session-scoped tool visibility for OAuth-protected servers.

func (*Adapter) Register 

func (a *Adapter) Register()

Register registers the adapter with the API layer. This makes the metatools functionality available through api.GetMetaTools().

This method should be called during application initialization after the aggregator has been set up.

type DescribeToolResponse 

type DescribeToolResponse struct {
	Name        string      `json:"name"`
	Description string      `json:"description"`
	InputSchema interface{} `json:"inputSchema,omitempty"`
}

DescribeToolResponse is the response structure from the describe_tool meta-tool.

type FilterCriteria 

type FilterCriteria struct {
	Pattern           string `json:"pattern,omitempty"`
	DescriptionFilter string `json:"description_filter,omitempty"`
	CaseSensitive     bool   `json:"case_sensitive"`
	IncludeSchema     bool   `json:"include_schema"`
}

FilterCriteria describes the filter parameters applied.

type FilterToolsResponse 

type FilterToolsResponse struct {
	Filters       FilterCriteria `json:"filters"`
	TotalTools    int            `json:"total_tools"`
	FilteredCount int            `json:"filtered_count"`
	Tools         []ToolInfo     `json:"tools"`
}

FilterToolsResponse is the response structure from the filter_tools meta-tool.

type Formatters 

type Formatters struct{}

Formatters provides utilities for formatting MCP data consistently. It supports structured JSON responses for tools, resources, and prompts. The formatters ensure consistent presentation across different output modes.

Key features:

  • JSON formatting for structured data consumption
  • Search and lookup utilities for cached data
  • Consistent error handling and fallback formatting

func NewFormatters 

func NewFormatters() *Formatters

NewFormatters creates a new formatters instance. The formatters instance is stateless and can be safely used concurrently.

func (*Formatters) FindPrompt 

func (f *Formatters) FindPrompt(prompts []mcp.Prompt, name string) *mcp.Prompt

FindPrompt searches for a prompt by name in the provided prompt list. This is a utility method for command implementations and internal lookups.

Args:

  • prompts: Slice of prompts to search in
  • name: Exact name of the prompt to find

Returns:

  • Pointer to the found prompt, or nil if not found

The search is case-sensitive and requires exact name matching.

func (*Formatters) FindResource 

func (f *Formatters) FindResource(resources []mcp.Resource, uri string) *mcp.Resource

FindResource searches for a resource by URI in the provided resource list. This is a utility method for command implementations and internal lookups.

Args:

  • resources: Slice of resources to search in
  • uri: Exact URI of the resource to find

Returns:

  • Pointer to the found resource, or nil if not found

The search is case-sensitive and requires exact URI matching.

func (*Formatters) FindTool 

func (f *Formatters) FindTool(tools []mcp.Tool, name string) *mcp.Tool

FindTool searches for a tool by name in the provided tool list. This is a utility method for command implementations and internal lookups.

Args:

  • tools: Slice of tools to search in
  • name: Exact name of the tool to find

Returns:

  • Pointer to the found tool, or nil if not found

The search is case-sensitive and requires exact name matching.

func (*Formatters) FormatPromptDetailJSON 

func (f *Formatters) FormatPromptDetailJSON(prompt mcp.Prompt) (string, error)

FormatPromptDetailJSON formats detailed prompt information as structured JSON. This format includes argument specifications and is used for programmatic consumption and prompt introspection.

Args:

  • prompt: The prompt to format detailed information for

Returns:

  • JSON string containing complete prompt information including arguments
  • error: JSON marshaling errors (should be rare)

func (*Formatters) FormatPromptsListJSON 

func (f *Formatters) FormatPromptsListJSON(prompts []mcp.Prompt) (string, error)

FormatPromptsListJSON formats a list of prompts as structured JSON. This format is used for programmatic consumption, MCP server responses, and integration with external tools that expect structured data.

Args:

  • prompts: Slice of prompts to format

Returns:

  • JSON string containing array of prompt objects with name and description
  • error: JSON marshaling errors (should be rare)

If no prompts are available, returns a simple message string.

func (*Formatters) FormatResourceDetailJSON 

func (f *Formatters) FormatResourceDetailJSON(resource mcp.Resource) (string, error)

FormatResourceDetailJSON formats detailed resource information as structured JSON. This format includes all available resource metadata and is used for programmatic consumption and resource introspection.

Args:

  • resource: The resource to format detailed information for

Returns:

  • JSON string containing complete resource information
  • error: JSON marshaling errors (should be rare)

func (*Formatters) FormatResourcesListJSON 

func (f *Formatters) FormatResourcesListJSON(resources []mcp.Resource) (string, error)

FormatResourcesListJSON formats a list of resources as structured JSON. This format is used for programmatic consumption, MCP server responses, and integration with external tools that expect structured data.

Args:

  • resources: Slice of resources to format

Returns:

  • JSON string containing array of resource objects with URI, name, description, and MIME type
  • error: JSON marshaling errors (should be rare)

If no resources are available, returns a simple message string.

func (*Formatters) FormatToolDetailJSON 

func (f *Formatters) FormatToolDetailJSON(tool mcp.Tool) (string, error)

FormatToolDetailJSON formats detailed tool information as structured JSON. This format includes the complete tool schema and is used for programmatic consumption and tool introspection.

Args:

  • tool: The tool to format detailed information for

Returns:

  • JSON string containing complete tool information including schema
  • error: JSON marshaling errors (should be rare)

Output format: 

{
  api.FieldName: "tool_name",
  api.SchemaKeyDescription: "Tool description",
  api.FieldInputSchema: { ... }
}

func (*Formatters) FormatToolsListJSON 

func (f *Formatters) FormatToolsListJSON(tools []mcp.Tool) (string, error)

FormatToolsListJSON formats a list of tools as structured JSON. This format is used for programmatic consumption, MCP server responses, and integration with external tools that expect structured data.

Args:

  • tools: Slice of tools to format

Returns:

  • JSON string containing array of tool objects with name and description
  • error: JSON marshaling errors (should be rare)

Output format: 

[
  {
    api.FieldName: "tool_name",
    api.SchemaKeyDescription: "Tool description"
  }
]

If no tools are available, returns a simple message string.

func (*Formatters) FormatToolsListWithAuthJSON 

func (f *Formatters) FormatToolsListWithAuthJSON(tools []mcp.Tool, serversRequiringAuth []api.ServerAuthInfo) (string, error)

FormatToolsListWithAuthJSON formats a list of tools along with information about servers requiring authentication as structured JSON.

This format is used by the list_tools meta-tool to provide users with:

  • Available tools from connected/authenticated servers
  • Information about servers that require authentication

Args:

  • tools: Slice of available tools to format
  • serversRequiringAuth: Slice of servers that need authentication

Returns:

  • JSON string containing tools and auth-required servers
  • error: JSON marshaling errors (should be rare)

Output format: 

{
  api.FieldTools: [...],
  "servers_requiring_auth": [
    {
      api.FieldName: "server-name",
      api.FieldStatus: "auth_required",
      "auth_tool": "core_auth_login"
    }
  ]
}

type ItemKind added in v0.1.162 

type ItemKind string

ItemKind identifies the kind of MCP capability an aggregator entry represents. 

const (
	ItemKindTool     ItemKind = "tool"
	ItemKindResource ItemKind = "resource"
	ItemKindPrompt   ItemKind = "prompt"
)

func (ItemKind) String added in v0.1.162 

func (k ItemKind) String() string

String returns the canonical lowercase token for the item kind.

type ListToolsResponse 

type ListToolsResponse struct {
	Tools                []ToolInfo            `json:"tools"`
	ServersRequiringAuth []ServerRequiringAuth `json:"servers_requiring_auth,omitempty"`
}

ListToolsResponse is the response structure from the list_tools meta-tool.

type Provider 

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

Provider implements the api.ToolProvider interface for meta-tools. It provides the discovery and execution tools that AI assistants use to interact with the muster aggregator's tool ecosystem.

The Provider is session-aware and uses the context session ID for tool visibility when appropriate. It retrieves tools, resources, and prompts through the API layer's service locator pattern.

func NewProvider 

func NewProvider() *Provider

NewProvider creates a new meta-tools provider instance. The provider is stateless except for the formatters and can be safely used concurrently across multiple requests.

Returns:

  • *Provider: A new provider instance ready to handle meta-tool requests

func (*Provider) ExecuteTool 

func (p *Provider) ExecuteTool(ctx context.Context, toolName string, args map[string]interface{}) (*api.CallToolResult, error)

ExecuteTool executes a specific meta-tool by name with the provided arguments. This implements the api.ToolProvider interface for tool execution.

Args:

  • ctx: Context for the operation, including session ID for visibility
  • toolName: The name of the meta-tool to execute
  • args: Arguments for the tool execution

Returns:

  • *api.CallToolResult: The result of the tool execution
  • error: Error if the tool doesn't exist or execution fails

func (*Provider) GetFormatters 

func (p *Provider) GetFormatters() *Formatters

GetFormatters returns the formatters instance used by this provider. This allows handlers to access formatting utilities without creating new instances.

Returns:

  • *Formatters: The formatters instance

func (*Provider) GetTools 

func (p *Provider) GetTools() []api.ToolMetadata

GetTools returns metadata for all meta-tools this provider offers. This implements the api.ToolProvider interface for tool discovery.

The meta-tools provide AI assistants with the ability to:

  • Discover available tools, resources, and prompts
  • Get detailed information about specific primitives
  • Execute tools and retrieve resources/prompts
  • Filter and search the tool catalog

Returns:

  • []api.ToolMetadata: List of all meta-tools provided

type ServerRequiringAuth 

type ServerRequiringAuth struct {
	Name     string `json:"name"`
	Status   string `json:"status"`
	AuthTool string `json:"auth_tool"`
}

ServerRequiringAuth describes an MCP server that requires authentication.

type ToolInfo 

type ToolInfo struct {
	Name        string      `json:"name"`
	Description string      `json:"description"`
	InputSchema interface{} `json:"inputSchema,omitempty"`
}

ToolInfo represents basic tool information returned by list_tools and filter_tools.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.