mcp

package
v1.3.11 Latest Latest
Warning

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

 Go to latest Published: Jan 19, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// Health check configuration
	DefaultHealthCheckInterval = 10 * time.Second // Interval between health checks
	DefaultHealthCheckTimeout  = 5 * time.Second  // Timeout for each health check
	MaxConsecutiveFailures     = 5                // Number of failures before marking as unhealthy
)
View Source 
const (
	// MCP defaults and identifiers
	BifrostMCPVersion                   = "1.0.0"           // Version identifier for Bifrost
	BifrostMCPClientName                = "BifrostClient"   // Name for internal Bifrost MCP client
	BifrostMCPClientKey                 = "bifrostInternal" // Key for internal Bifrost client in clientMap
	MCPLogPrefix                        = "[Bifrost MCP]"   // Consistent logging prefix
	MCPClientConnectionEstablishTimeout = 30 * time.Second  // Timeout for MCP client connection establishment

	// Context keys for client filtering in requests
	// NOTE: []string is used for both keys, and by default all clients/tools are included (when nil).
	// If "*" is present, all clients/tools are included, and [] means no clients/tools are included.
	// Request context filtering takes priority over client config - context can override client exclusions.
	MCPContextKeyIncludeClients schemas.BifrostContextKey = "mcp-include-clients" // Context key for whitelist client filtering
	MCPContextKeyIncludeTools   schemas.BifrostContextKey = "mcp-include-tools"   // Context key for whitelist tool filtering (Note: toolName should be in "clientName/toolName" format)
)
View Source 
const (
	ToolTypeListToolFiles   string = "listToolFiles"
	ToolTypeReadToolFile    string = "readToolFile"
	ToolTypeExecuteToolCode string = "executeToolCode"
)
View Source 
const (
	CodeModeLogPrefix = "[CODE MODE]"
)

Variables

This section is empty.

Functions

func ExecuteAgentForChatRequest 

func ExecuteAgentForChatRequest(
	ctx *schemas.BifrostContext,
	maxAgentDepth int,
	originalReq *schemas.BifrostChatRequest,
	initialResponse *schemas.BifrostChatResponse,
	makeReq func(ctx *schemas.BifrostContext, req *schemas.BifrostChatRequest) (*schemas.BifrostChatResponse, *schemas.BifrostError),
	fetchNewRequestIDFunc func(ctx *schemas.BifrostContext) string,
	executeToolFunc func(ctx *schemas.BifrostContext, toolCall schemas.ChatAssistantMessageToolCall) (*schemas.ChatMessage, error),
	clientManager ClientManager,
) (*schemas.BifrostChatResponse, *schemas.BifrostError)

ExecuteAgentForChatRequest handles the agent mode execution loop for Chat API. It orchestrates iterative tool execution up to the maximum depth, handling auto-executable and non-auto-executable tools appropriately.

Parameters:

  • ctx: Context for agent execution
  • maxAgentDepth: Maximum number of agent iterations allowed
  • originalReq: The original chat request
  • initialResponse: The initial chat response containing tool calls
  • makeReq: Function to make subsequent chat requests during agent execution
  • fetchNewRequestIDFunc: Optional function to generate unique request IDs for each iteration
  • executeToolFunc: Function to execute individual tool calls
  • clientManager: Client manager for accessing MCP clients and tools

Returns:

  • *schemas.BifrostChatResponse: The final response after agent execution
  • *schemas.BifrostError: Any error that occurred during agent execution

func ExecuteAgentForResponsesRequest 

func ExecuteAgentForResponsesRequest(
	ctx *schemas.BifrostContext,
	maxAgentDepth int,
	originalReq *schemas.BifrostResponsesRequest,
	initialResponse *schemas.BifrostResponsesResponse,
	makeReq func(ctx *schemas.BifrostContext, req *schemas.BifrostResponsesRequest) (*schemas.BifrostResponsesResponse, *schemas.BifrostError),
	fetchNewRequestIDFunc func(ctx *schemas.BifrostContext) string,
	executeToolFunc func(ctx *schemas.BifrostContext, toolCall schemas.ChatAssistantMessageToolCall) (*schemas.ChatMessage, error),
	clientManager ClientManager,
) (*schemas.BifrostResponsesResponse, *schemas.BifrostError)

ExecuteAgentForResponsesRequest handles the agent mode execution loop for Responses API. It orchestrates iterative tool execution up to the maximum depth, handling auto-executable and non-auto-executable tools appropriately.

Parameters:

  • ctx: Context for agent execution
  • maxAgentDepth: Maximum number of agent iterations allowed
  • originalReq: The original responses request
  • initialResponse: The initial responses response containing tool calls
  • makeReq: Function to make subsequent responses requests during agent execution
  • fetchNewRequestIDFunc: Optional function to generate unique request IDs for each iteration
  • executeToolFunc: Function to execute individual tool calls
  • clientManager: Client manager for accessing MCP clients and tools

Returns:

  • *schemas.BifrostResponsesResponse: The final response after agent execution
  • *schemas.BifrostError: Any error that occurred during agent execution

func SetLogger 

func SetLogger(l schemas.Logger)

Types

type ClientHealthMonitor 

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

ClientHealthMonitor tracks the health status of an MCP client

func NewClientHealthMonitor 

func NewClientHealthMonitor(
	manager *MCPManager,
	clientID string,
	interval time.Duration,
) *ClientHealthMonitor

NewClientHealthMonitor creates a new health monitor for an MCP client

func (*ClientHealthMonitor) Start 

func (chm *ClientHealthMonitor) Start()

Start begins monitoring the client's health in a background goroutine

func (*ClientHealthMonitor) Stop 

func (chm *ClientHealthMonitor) Stop()

Stop stops monitoring the client's health

type ClientManager 

type ClientManager interface {
	GetClientByName(clientName string) *schemas.MCPClientState
	GetClientForTool(toolName string) *schemas.MCPClientState
	GetToolPerClient(ctx context.Context) map[string][]schemas.ChatTool
}

type ExecutionEnvironment 

type ExecutionEnvironment struct {
	ServerKeys      []string `json:"serverKeys"`
	ImportsStripped bool     `json:"importsStripped"`
	StrippedLines   []int    `json:"strippedLines"`
	TypeScriptUsed  bool     `json:"typescriptUsed"`
}

ExecutionEnvironment contains information about the execution environment

type ExecutionError 

type ExecutionError struct {
	Kind    ExecutionErrorType `json:"kind"` // "compile", "typescript", or "runtime"
	Message string             `json:"message"`
	Hints   []string           `json:"hints"`
}

ExecutionError represents an error during code execution

type ExecutionErrorType 

type ExecutionErrorType string
const (
	ExecutionErrorTypeCompile    ExecutionErrorType = "compile"
	ExecutionErrorTypeTypescript ExecutionErrorType = "typescript"
	ExecutionErrorTypeRuntime    ExecutionErrorType = "runtime"
)

type ExecutionResult 

type ExecutionResult struct {
	Result      interface{}          `json:"result"`
	Logs        []string             `json:"logs"`
	Errors      *ExecutionError      `json:"errors,omitempty"`
	Environment ExecutionEnvironment `json:"environment"`
}

ExecutionResult represents the result of code execution

type HealthMonitorManager 

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

HealthMonitorManager manages all client health monitors

func NewHealthMonitorManager 

func NewHealthMonitorManager() *HealthMonitorManager

NewHealthMonitorManager creates a new health monitor manager

func (*HealthMonitorManager) StartMonitoring 

func (hmm *HealthMonitorManager) StartMonitoring(monitor *ClientHealthMonitor)

StartMonitoring starts monitoring a specific client

func (*HealthMonitorManager) StopAll 

func (hmm *HealthMonitorManager) StopAll()

StopAll stops all monitoring

func (*HealthMonitorManager) StopMonitoring 

func (hmm *HealthMonitorManager) StopMonitoring(clientID string)

StopMonitoring stops monitoring a specific client

type MCPManager 

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

MCPManager manages MCP integration for Bifrost core. It provides a bridge between Bifrost and various MCP servers, supporting both local tool hosting and external MCP server connections.

func NewMCPManager 

func NewMCPManager(ctx context.Context, config schemas.MCPConfig, logger schemas.Logger) *MCPManager

NewMCPManager creates and initializes a new MCP manager instance.

Parameters:

  • config: MCP configuration including server port and client configs
  • logger: Logger instance for structured logging (uses default if nil)

Returns:

  • *MCPManager: Initialized manager instance
  • error: Any initialization error

func (*MCPManager) AddClient 

func (m *MCPManager) AddClient(config schemas.MCPClientConfig) error

AddClient adds a new MCP client to the manager. It validates the client configuration and establishes a connection. If connection fails, the client entry is automatically cleaned up.

Parameters:

  • config: MCP client configuration

Returns:

  • error: Any error that occurred during client addition or connection

func (*MCPManager) AddToolsToRequest 

func (m *MCPManager) AddToolsToRequest(ctx context.Context, req *schemas.BifrostRequest) *schemas.BifrostRequest

AddToolsToRequest parses available MCP tools from the context and adds them to the request. It respects context-based filtering for clients and tools, and returns the modified request with tools attached.

Parameters:

  • ctx: Context containing optional client/tool filtering keys
  • req: The Bifrost request to add tools to

Returns:

  • *schemas.BifrostRequest: The request with tools added

func (*MCPManager) CheckAndExecuteAgentForChatRequest 

func (m *MCPManager) CheckAndExecuteAgentForChatRequest(
	ctx *schemas.BifrostContext,
	req *schemas.BifrostChatRequest,
	response *schemas.BifrostChatResponse,
	makeReq func(ctx *schemas.BifrostContext, req *schemas.BifrostChatRequest) (*schemas.BifrostChatResponse, *schemas.BifrostError),
) (*schemas.BifrostChatResponse, *schemas.BifrostError)

CheckAndExecuteAgentForChatRequest checks if the chat response contains tool calls, and if so, executes agent mode to handle the tool calls iteratively. If no tool calls are present, it returns the original response unchanged.

Agent mode enables autonomous tool execution where:

  1. Tool calls are automatically executed
  2. Results are fed back to the LLM
  3. The loop continues until no more tool calls are made or max depth is reached
  4. Non-auto-executable tools are returned to the caller

This method is available for both Chat Completions and Responses APIs. For Responses API, use CheckAndExecuteAgentForResponsesRequest().

Parameters:

  • ctx: Context for the agent execution
  • req: The original chat request
  • response: The initial chat response that may contain tool calls
  • makeReq: Function to make subsequent chat requests during agent execution

Returns:

  • *schemas.BifrostChatResponse: The final response after agent execution (or original if no tool calls)
  • *schemas.BifrostError: Any error that occurred during agent execution

func (*MCPManager) CheckAndExecuteAgentForResponsesRequest 

func (m *MCPManager) CheckAndExecuteAgentForResponsesRequest(
	ctx *schemas.BifrostContext,
	req *schemas.BifrostResponsesRequest,
	response *schemas.BifrostResponsesResponse,
	makeReq func(ctx *schemas.BifrostContext, req *schemas.BifrostResponsesRequest) (*schemas.BifrostResponsesResponse, *schemas.BifrostError),
) (*schemas.BifrostResponsesResponse, *schemas.BifrostError)

CheckAndExecuteAgentForResponsesRequest checks if the responses response contains tool calls, and if so, executes agent mode to handle the tool calls iteratively. If no tool calls are present, it returns the original response unchanged.

Agent mode for Responses API works identically to Chat API:

  1. Detects tool calls in the response (function_call messages)
  2. Automatically executes tools in parallel when possible
  3. Feeds results back to the LLM in Responses API format
  4. Continues the loop until no more tool calls or max depth reached
  5. Returns non-auto-executable tools to the caller

Format Handling: This method automatically handles format conversions:

  • Responses tool calls (ResponsesToolMessage) are converted to Chat format for execution
  • Tool execution results are converted back to Responses format (ResponsesMessage)
  • All conversions use the adapters in agent_adaptors.go and converters in schemas/mux.go

This provides full feature parity between Chat Completions and Responses APIs for tool execution.

Parameters:

  • ctx: Context for the agent execution
  • req: The original responses request
  • response: The initial responses response that may contain tool calls
  • makeReq: Function to make subsequent responses requests during agent execution

Returns:

  • *schemas.BifrostResponsesResponse: The final response after agent execution (or original if no tool calls)
  • *schemas.BifrostError: Any error that occurred during agent execution

func (*MCPManager) Cleanup 

func (m *MCPManager) Cleanup() error

Cleanup performs cleanup of all MCP resources including clients and local server. This function safely disconnects all MCP clients (HTTP, STDIO, and SSE) and cleans up the local MCP server. It handles proper cancellation of SSE contexts and closes all transport connections.

Returns:

  • error: Always returns nil, but maintains error interface for consistency

func (*MCPManager) EditClient 

func (m *MCPManager) EditClient(id string, updatedConfig schemas.MCPClientConfig) error

EditClient updates an existing MCP client's configuration and refreshes its tool list. It updates the client's execution config with new settings and retrieves updated tools from the MCP server if the client is connected. This method does not refresh the client's tool list. To refresh the client's tool list, use the ReconnectClient method.

Parameters:

  • id: ID of the client to edit
  • updatedConfig: Updated client configuration with new settings

Returns:

  • error: Any error that occurred during client update or tool retrieval

func (*MCPManager) ExecuteChatTool 

func (m *MCPManager) ExecuteChatTool(ctx *schemas.BifrostContext, toolCall schemas.ChatAssistantMessageToolCall) (*schemas.ChatMessage, error)

ExecuteChatTool executes a single tool call and returns the result as a chat message. This is the primary tool executor and is used by both Chat Completions and Responses APIs.

The method accepts tool calls in Chat API format (ChatAssistantMessageToolCall) and returns results in Chat API format (ChatMessage). For Responses API users:

  • Convert ResponsesToolMessage to ChatAssistantMessageToolCall using ToChatAssistantMessageToolCall()
  • Execute the tool with this method
  • Convert the result back using ChatMessage.ToResponsesToolMessage()

Alternatively, use ExecuteResponsesTool() in the ToolsManager for a type-safe wrapper that handles format conversions automatically.

Parameters:

  • ctx: Context for the tool execution
  • toolCall: The tool call to execute in Chat API format

Returns:

  • *schemas.ChatMessage: The result message containing tool execution output
  • error: Any error that occurred during tool execution

func (*MCPManager) ExecuteResponsesTool 

func (m *MCPManager) ExecuteResponsesTool(ctx *schemas.BifrostContext, toolCall *schemas.ResponsesToolMessage) (*schemas.ResponsesMessage, error)
  • ctx: Context for the tool execution
  • toolCall: The tool call to execute in Responses API format

Returns:

  • *schemas.ResponsesMessage: The result message containing tool execution output
  • error: Any error that occurred during tool execution

func (*MCPManager) GetAvailableTools 

func (m *MCPManager) GetAvailableTools(ctx context.Context) []schemas.ChatTool

func (*MCPManager) GetClientByName 

func (m *MCPManager) GetClientByName(clientName string) *schemas.MCPClientState

GetClientByName returns a client by name.

Parameters:

  • clientName: Name of the client to get

Returns:

  • *schemas.MCPClientState: Client state if found, nil otherwise

func (*MCPManager) GetClientForTool 

func (m *MCPManager) GetClientForTool(toolName string) *schemas.MCPClientState

GetClientForTool safely finds a client that has the specified tool. Returns a copy of the client state to avoid data races. Callers should be aware that fields like Conn and ToolMap are still shared references and may be modified by other goroutines, but the struct itself is safe from concurrent modification.

func (*MCPManager) GetClients 

func (m *MCPManager) GetClients() []schemas.MCPClientState

GetClients returns all MCP clients managed by the manager.

Returns:

  • []*schemas.MCPClientState: List of all MCP clients

func (*MCPManager) GetToolPerClient 

func (m *MCPManager) GetToolPerClient(ctx context.Context) map[string][]schemas.ChatTool

GetToolPerClient returns all tools from connected MCP clients. Applies client filtering if specified in the context. Returns a map of client name to its available tools. Parameters:

  • ctx: Execution context

Returns:

  • map[string][]schemas.ChatTool: Map of client name to its available tools

func (*MCPManager) ReconnectClient 

func (m *MCPManager) ReconnectClient(id string) error

ReconnectClient attempts to reconnect an MCP client if it is disconnected. It validates that the client exists and then establishes a new connection using the client's existing configuration.

Parameters:

  • id: ID of the client to reconnect

Returns:

  • error: Any error that occurred during reconnection

func (*MCPManager) RegisterTool 

func (m *MCPManager) RegisterTool(name, description string, toolFunction MCPToolFunction[any], toolSchema schemas.ChatTool) error

RegisterTool registers a typed tool handler with the local MCP server. This is a convenience function that handles the conversion between typed Go handlers and the MCP protocol.

Type Parameters:

  • T: The expected argument type for the tool (must be JSON-deserializable)

Parameters:

  • name: Unique tool name
  • description: Human-readable tool description
  • handler: Typed function that handles tool execution
  • toolSchema: Bifrost tool schema for function calling

Returns:

  • error: Any registration error

Example: 

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

err := bifrost.RegisterMCPTool("echo", "Echo a message",
    func(args EchoArgs) (string, error) {
        return args.Message, nil
    }, toolSchema)

func (*MCPManager) RemoveClient 

func (m *MCPManager) RemoveClient(id string) error

RemoveClient removes an MCP client from the manager. It handles cleanup for all transport types (HTTP, STDIO, SSE).

Parameters:

  • id: ID of the client to remove

func (*MCPManager) UpdateToolManagerConfig 

func (m *MCPManager) UpdateToolManagerConfig(config *schemas.MCPToolManagerConfig)

UpdateToolManagerConfig updates the configuration for the tool manager. This allows runtime updates to settings like execution timeout and max agent depth.

Parameters:

  • config: The new tool manager configuration to apply

type MCPToolFunction 

type MCPToolFunction[T any] func(args T) (string, error)

MCPToolFunction is a generic function type for handling tool calls with typed arguments. T represents the expected argument structure for the tool.

type ToolsManager 

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

func NewToolsManager 

func NewToolsManager(config *schemas.MCPToolManagerConfig, clientManager ClientManager, fetchNewRequestIDFunc func(ctx *schemas.BifrostContext) string) *ToolsManager

NewToolsManager creates and initializes a new tools manager instance. It validates the configuration, sets defaults if needed, and initializes atomic values for thread-safe configuration updates.

Parameters:

  • config: Tool manager configuration with execution timeout and max agent depth
  • clientManager: Client manager interface for accessing MCP clients and tools
  • fetchNewRequestIDFunc: Optional function to generate unique request IDs for agent mode

Returns:

  • *ToolsManager: Initialized tools manager instance

func (*ToolsManager) ExecuteAgentForChatRequest 

func (m *ToolsManager) ExecuteAgentForChatRequest(
	ctx *schemas.BifrostContext,
	req *schemas.BifrostChatRequest,
	resp *schemas.BifrostChatResponse,
	makeReq func(ctx *schemas.BifrostContext, req *schemas.BifrostChatRequest) (*schemas.BifrostChatResponse, *schemas.BifrostError),
) (*schemas.BifrostChatResponse, *schemas.BifrostError)

ExecuteAgentForChatRequest executes agent mode for a chat request, handling iterative tool calls up to the configured maximum depth. It delegates to the shared agent execution logic with the manager's configuration and dependencies.

Parameters:

  • ctx: Context for agent execution
  • req: The original chat request
  • resp: The initial chat response containing tool calls
  • makeReq: Function to make subsequent chat requests during agent execution

Returns:

  • *schemas.BifrostChatResponse: The final response after agent execution
  • *schemas.BifrostError: Any error that occurred during agent execution

func (*ToolsManager) ExecuteAgentForResponsesRequest 

func (m *ToolsManager) ExecuteAgentForResponsesRequest(
	ctx *schemas.BifrostContext,
	req *schemas.BifrostResponsesRequest,
	resp *schemas.BifrostResponsesResponse,
	makeReq func(ctx *schemas.BifrostContext, req *schemas.BifrostResponsesRequest) (*schemas.BifrostResponsesResponse, *schemas.BifrostError),
) (*schemas.BifrostResponsesResponse, *schemas.BifrostError)

ExecuteAgentForResponsesRequest executes agent mode for a responses request, handling iterative tool calls up to the configured maximum depth. It delegates to the shared agent execution logic with the manager's configuration and dependencies.

Parameters:

  • ctx: Context for agent execution
  • req: The original responses request
  • resp: The initial responses response containing tool calls
  • makeReq: Function to make subsequent responses requests during agent execution

Returns:

  • *schemas.BifrostResponsesResponse: The final response after agent execution
  • *schemas.BifrostError: Any error that occurred during agent execution

func (*ToolsManager) ExecuteChatTool 

func (m *ToolsManager) ExecuteChatTool(ctx *schemas.BifrostContext, toolCall schemas.ChatAssistantMessageToolCall) (*schemas.ChatMessage, error)

ExecuteChatTool executes a tool call in Chat Completions API format and returns the result as a chat tool message. This is the primary tool executor that works with both Chat Completions and Responses APIs.

For Responses API users, use ExecuteResponsesTool() for a more type-safe interface. However, internally this method is format-agnostic - it executes the tool and returns a ChatMessage which can then be converted to ResponsesMessage via ToResponsesToolMessage().

Parameters:

  • ctx: Execution context
  • toolCall: The tool call to execute (from assistant message)

Returns:

  • *schemas.ChatMessage: Tool message with execution result
  • error: Any execution error

func (*ToolsManager) ExecuteResponsesTool 

func (m *ToolsManager) ExecuteResponsesTool(
	ctx *schemas.BifrostContext,
	toolMessage *schemas.ResponsesToolMessage,
) (*schemas.ResponsesMessage, error)

ExecuteToolForResponses executes a tool call from a Responses API tool message and returns the result in Responses API format. This is a type-safe wrapper around ExecuteTool that handles the conversion between Responses and Chat API formats.

This method: 1. Converts the Responses tool message to Chat API format 2. Executes the tool using the standard tool executor 3. Converts the result back to Responses API format

Parameters:

  • ctx: Execution context
  • toolMessage: The Responses API tool message to execute
  • callID: The original call ID from the Responses API

Returns:

  • *schemas.ResponsesMessage: Tool result message in Responses API format
  • error: Any execution error

Example: 

responsesToolMsg := &schemas.ResponsesToolMessage{
    Name:      Ptr("calculate"),
    Arguments: Ptr("{\"x\": 10, \"y\": 20}"),
}
resultMsg, err := toolsManager.ExecuteResponsesTool(ctx, responsesToolMsg, "call-123")
// resultMsg is a ResponsesMessage with type=function_call_output

func (*ToolsManager) GetAvailableTools 

func (m *ToolsManager) GetAvailableTools(ctx context.Context) []schemas.ChatTool

GetAvailableTools returns the available tools for the given context.

func (*ToolsManager) GetCodeModeBindingLevel 

func (m *ToolsManager) GetCodeModeBindingLevel() schemas.CodeModeBindingLevel

GetCodeModeBindingLevel returns the current code mode binding level. This method is safe to call concurrently from multiple goroutines.

func (*ToolsManager) ParseAndAddToolsToRequest 

func (m *ToolsManager) ParseAndAddToolsToRequest(ctx context.Context, req *schemas.BifrostRequest) *schemas.BifrostRequest

ParseAndAddToolsToRequest parses the available tools per client and adds them to the Bifrost request.

Parameters:

  • ctx: Execution context
  • req: Bifrost request
  • availableToolsPerClient: Map of client name to its available tools

Returns:

  • *schemas.BifrostRequest: Bifrost request with MCP tools added

func (*ToolsManager) UpdateConfig 

func (m *ToolsManager) UpdateConfig(config *schemas.MCPToolManagerConfig)

UpdateConfig updates tool manager configuration atomically. This method is safe to call concurrently from multiple goroutines.

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.