Documentation
¶
Overview ¶
Package mcp provides a client implementation for the Model Context Protocol (MCP).
MCP is a standardized protocol for AI models to interact with external tools and resources. This package provides a clean, reusable interface for calling MCP tools from any AI model implementation in the Karma framework.
Basic Usage:
// Create a new MCP client
client := mcp.NewClient("http://localhost:3000", "your-auth-token")
// Create a tool manager
manager := mcp.NewManager(client)
// Define a tool schema
type FileReadParams struct {
Path string `json:"path" jsonschema:"required"`
}
// Add a tool
err := manager.AddToolFromSchema(
"read_file",
"Read contents of a file",
"file_read",
FileReadParams{},
)
// Call the tool
result, err := manager.CallTool(context.Background(), "read_file", map[string]any{
"path": "/path/to/file.txt",
})
The package supports:
- Automatic JSON schema generation from Go structs
- Concurrent tool management with proper synchronization
- Context-aware HTTP requests with configurable timeouts
- Comprehensive error handling and response parsing
- Interface-based design for easy testing and mocking
Integration with AI Models:
This package is designed to be used by AI model implementations (Claude, Gemini, etc.) to provide tool calling capabilities. The clean interface allows each model to integrate MCP tools without duplicating the protocol implementation.
Index ¶
- type CallToolParams
- type Client
- func (c *Client) CallTool(ctx context.Context, tool *Tool, arguments map[string]any) (*ToolResult, error)
- func (c *Client) CallToolByName(ctx context.Context, mcpToolName string, arguments map[string]any) (*ToolResult, error)
- func (c *Client) CreateTool(name, description, mcpToolName string, inputSchema any) (*Tool, error)
- func (c *Client) ListTools(ctx context.Context) ([]map[string]any, error)
- func (c *Client) Ping(ctx context.Context) error
- func (c *Client) SetTimeout(timeout time.Duration)
- type Error
- type MCPClient
- type Manager
- func (m *Manager) AddTool(tool *Tool) error
- func (m *Manager) AddToolFromSchema(name, description, mcpToolName string, inputSchema any) error
- func (m *Manager) CallTool(ctx context.Context, name string, arguments map[string]any) (*ToolResult, error)
- func (m *Manager) Clear()
- func (m *Manager) Count() int
- func (m *Manager) GetAllTools() []*Tool
- func (m *Manager) GetTool(name string) (*Tool, bool)
- func (m *Manager) GetToolNames() []string
- func (m *Manager) HasTool(name string) bool
- func (m *Manager) RemoveTool(name string) error
- type MultiManager
- func (mm *MultiManager) AddServer(serverID, serverURL, authToken string)
- func (mm *MultiManager) AddToolToServer(serverID, name, description, mcpToolName string, inputSchema any) error
- func (mm *MultiManager) CallTool(ctx context.Context, toolName string, arguments map[string]any) (*ToolResult, error)
- func (mm *MultiManager) Clear()
- func (mm *MultiManager) Count() int
- func (mm *MultiManager) GetAllTools() []*Tool
- func (mm *MultiManager) GetTool(name string) (*Tool, bool)
- func (mm *MultiManager) HasTool(name string) bool
- func (mm *MultiManager) RemoveServer(serverID string) error
- type Request
- type Response
- type Tool
- type ToolManager
- type ToolResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CallToolParams ¶
type CallToolParams struct {
Name string `json:"name"`
Arguments map[string]any `json:"arguments,omitempty"`
}
CallToolParams represents MCP tool call parameters
type Client ¶
Client represents an MCP (Model Context Protocol) client
func NewClient ¶
NewClient creates a new MCP client with the given server URL and optional auth token
func (*Client) CallTool ¶
func (c *Client) CallTool(ctx context.Context, tool *Tool, arguments map[string]any) (*ToolResult, error)
CallTool calls an MCP tool with the given arguments and returns the result
func (*Client) CallToolByName ¶
func (c *Client) CallToolByName(ctx context.Context, mcpToolName string, arguments map[string]any) (*ToolResult, error)
CallToolByName calls an MCP tool by its MCP tool name directly
func (*Client) CreateTool ¶
CreateTool creates a new MCP tool with schema generation from a Go struct
func (*Client) SetTimeout ¶
SetTimeout sets the HTTP client timeout for MCP requests
type Error ¶
type Error struct {
Code int `json:"code"`
Message string `json:"message"`
Data any `json:"data,omitempty"`
}
Error represents an MCP error
type MCPClient ¶
type MCPClient interface {
// SetTimeout sets the HTTP client timeout for MCP requests
SetTimeout(timeout time.Duration)
// CreateTool creates a new MCP tool with schema generation from a Go struct
CreateTool(name, description, mcpToolName string, inputSchema any) (*Tool, error)
// CallTool calls an MCP tool with the given arguments and returns the result
CallTool(ctx context.Context, tool *Tool, arguments map[string]any) (*ToolResult, error)
// CallToolByName calls an MCP tool by its MCP tool name directly
CallToolByName(ctx context.Context, mcpToolName string, arguments map[string]any) (*ToolResult, error)
// Ping sends a ping request to the MCP server to check connectivity
Ping(ctx context.Context) error
// ListTools lists available tools from the MCP server
ListTools(ctx context.Context) ([]map[string]any, error)
}
MCPClient defines the interface for MCP (Model Context Protocol) clients
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager implements the ToolManager interface for managing MCP tools
func NewManager ¶
NewManager creates a new tool manager with the given MCP client
func (*Manager) AddToolFromSchema ¶
AddToolFromSchema creates and adds a tool from schema parameters
func (*Manager) CallTool ¶
func (m *Manager) CallTool(ctx context.Context, name string, arguments map[string]any) (*ToolResult, error)
CallTool calls a managed tool by name
func (*Manager) GetAllTools ¶
GetAllTools returns all managed tools
func (*Manager) GetToolNames ¶
GetToolNames returns a slice of all tool names
func (*Manager) RemoveTool ¶
RemoveTool removes a tool from the managed collection
type MultiManager ¶ added in v1.15.3
type MultiManager struct {
// contains filtered or unexported fields
}
func NewMultiManager ¶ added in v1.15.3
func NewMultiManager() *MultiManager
func (*MultiManager) AddServer ¶ added in v1.15.3
func (mm *MultiManager) AddServer(serverID, serverURL, authToken string)
func (*MultiManager) AddToolToServer ¶ added in v1.15.3
func (mm *MultiManager) AddToolToServer(serverID, name, description, mcpToolName string, inputSchema any) error
func (*MultiManager) CallTool ¶ added in v1.15.3
func (mm *MultiManager) CallTool(ctx context.Context, toolName string, arguments map[string]any) (*ToolResult, error)
func (*MultiManager) Clear ¶ added in v1.15.3
func (mm *MultiManager) Clear()
func (*MultiManager) Count ¶ added in v1.15.3
func (mm *MultiManager) Count() int
func (*MultiManager) GetAllTools ¶ added in v1.15.3
func (mm *MultiManager) GetAllTools() []*Tool
func (*MultiManager) GetTool ¶ added in v1.15.3
func (mm *MultiManager) GetTool(name string) (*Tool, bool)
func (*MultiManager) HasTool ¶ added in v1.15.3
func (mm *MultiManager) HasTool(name string) bool
func (*MultiManager) RemoveServer ¶ added in v1.15.3
func (mm *MultiManager) RemoveServer(serverID string) error
type Request ¶
type Request struct {
JSONRPC string `json:"jsonrpc"`
ID int `json:"id"`
Method string `json:"method"`
Params any `json:"params,omitempty"`
}
Request represents an MCP JSON-RPC request
type Response ¶
type Response struct {
JSONRPC string `json:"jsonrpc"`
ID int `json:"id"`
Result any `json:"result,omitempty"`
Error *Error `json:"error,omitempty"`
}
Response represents an MCP JSON-RPC response
type Tool ¶
type Tool struct {
Name string `json:"name"`
Description string `json:"description"`
InputSchema map[string]any `json:"inputSchema"`
MCPToolName string `json:"mcpToolName"` // The actual tool name in MCP server
}
Tool represents an MCP tool that can be called
type ToolManager ¶
type ToolManager interface {
// AddTool adds a tool to the managed collection
AddTool(tool *Tool) error
// RemoveTool removes a tool from the managed collection
RemoveTool(name string) error
// GetTool retrieves a tool by name
GetTool(name string) (*Tool, bool)
// GetAllTools returns all managed tools
GetAllTools() []*Tool
// CallTool calls a managed tool by name
CallTool(ctx context.Context, name string, arguments map[string]any) (*ToolResult, error)
}
ToolManager defines the interface for managing MCP tools
type ToolResult ¶
type ToolResult struct {
Content string `json:"content"`
IsError bool `json:"isError"`
ErrorCode int `json:"errorCode,omitempty"`
}
ToolResult represents the result of an MCP tool call