mcp

package
v1.16.69 Latest Latest
Warning

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

Go to latest
Published: Feb 10, 2026 License: GPL-3.0 Imports: 10 Imported by: 0

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

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

type Client struct {
	ServerURL  string
	AuthToken  string
	HTTPClient *http.Client
}

Client represents an MCP (Model Context Protocol) client

func NewClient

func NewClient(serverURL, authToken string) *Client

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

func (c *Client) CreateTool(name, description, mcpToolName string, inputSchema any) (*Tool, error)

CreateTool creates a new MCP tool with schema generation from a Go struct

func (*Client) ListTools

func (c *Client) ListTools(ctx context.Context) ([]map[string]any, error)

ListTools lists available tools from the MCP server

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) error

Ping sends a ping request to the MCP server to check connectivity

func (*Client) SetTimeout

func (c *Client) SetTimeout(timeout time.Duration)

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

func NewManager(client MCPClient) *Manager

NewManager creates a new tool manager with the given MCP client

func (*Manager) AddTool

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

AddTool adds a tool to the managed collection

func (*Manager) AddToolFromSchema

func (m *Manager) AddToolFromSchema(name, description, mcpToolName string, inputSchema any) error

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) Clear

func (m *Manager) Clear()

Clear removes all tools from the manager

func (*Manager) Count

func (m *Manager) Count() int

Count returns the number of tools managed

func (*Manager) GetAllTools

func (m *Manager) GetAllTools() []*Tool

GetAllTools returns all managed tools

func (*Manager) GetTool

func (m *Manager) GetTool(name string) (*Tool, bool)

GetTool retrieves a tool by name

func (*Manager) GetToolNames

func (m *Manager) GetToolNames() []string

GetToolNames returns a slice of all tool names

func (*Manager) HasTool

func (m *Manager) HasTool(name string) bool

HasTool checks if a tool with the given name exists

func (*Manager) RemoveTool

func (m *Manager) RemoveTool(name string) error

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL