mcpclient

Documentation

Overview

Package mcpclient implements an MCP client that connects to external MCP servers over stdio. This allows odek to use tools from any MCP server (e.g., Claude Code's MCP servers for web scraping, databases, APIs, etc.) alongside its built-in tools.

Protocol: JSON-RPC 2.0 over stdin/stdout

• initialize — protocol handshake
• tools/list — discover available tools
• tools/call — invoke a tool
• ping — health check

Usage:

client, err := mcpclient.New("some-server", "node", []string{"server.js"})
tools, err := client.Discover(ctx)
result, err := client.CallTool(ctx, "tool_name", `{"arg":"val"}`)
client.Close()

Config in odek.json:

{
  "mcp_servers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server.js"]
    }
  }
}

Index

• Constants
• type Client
  • func New(name string, cfg ServerConfig) (*Client, error)
  • func (c *Client) CallTool(ctx context.Context, name string, argsJSON string) (string, error)
  • func (c *Client) Close() error
  • func (c *Client) Discover(ctx context.Context) ([]ToolDef, error)
  • func (c *Client) Name() string
• type ServerConfig
• type ToolAdapter
  • func (a *ToolAdapter) Call(args string) (string, error)
  • func (a *ToolAdapter) Description() string
  • func (a *ToolAdapter) Name() string
  • func (a *ToolAdapter) Schema() any
• type ToolDef

Constants

const (
	ProtocolVersion = "2025-03-26"
	DefaultTimeout  = 30 * time.Second
)

Types

type Client

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

Client manages a connection to an external MCP server over stdio.

func New

func New(name string, cfg ServerConfig) (*Client, error)

New spawns an MCP server process and returns a client connected to it. The server process is started immediately and cleaned up on Close().

func (*Client) CallTool

func (c *Client) CallTool(ctx context.Context, name string, argsJSON string) (string, error)

CallTool invokes a tool on the MCP server with the given JSON arguments and returns the text content of the result.

func (*Client) Close

func (c *Client) Close() error

Close terminates the MCP server process and cleans up resources. Safe to call multiple times.

func (*Client) Discover

func (c *Client) Discover(ctx context.Context) ([]ToolDef, error)

Discover performs the MCP handshake and returns all available tools.

func (*Client) Name

func (c *Client) Name() string

Name returns the server name for this client.

type ServerConfig

type ServerConfig struct {
	// Command is the executable to run (e.g., "node", "python3", "uvx").
	Command string `json:"command"`
	// Args are the command-line arguments.
	Args []string `json:"args,omitempty"`
	// Env overrides environment variables for the subprocess.
	// Empty strings remove the variable from the environment.
	Env map[string]string `json:"env,omitempty"`
}

ServerConfig defines an external MCP server to connect to. Matches the Claude Code MCP server config format.

type ToolAdapter

type ToolAdapter struct {
	// Client is the MCP client connection.
	Client *Client

	// ToolName is the name of the tool on the MCP server.
	ToolName string

	// Desc is the tool description.
	Desc string

	// ParamSchema is the JSON schema for the tool's parameters.
	ParamSchema any
}

ToolAdapter wraps an MCP client tool as a odek.Tool-compatible value. It implements the Name(), Description(), Schema(), and Call() methods that odek's agent loop expects, forwarding calls to the MCP server.

func (*ToolAdapter) Call

func (a *ToolAdapter) Call(args string) (string, error)

Call invokes the tool on the MCP server with the given JSON arguments.

func (*ToolAdapter) Description

func (a *ToolAdapter) Description() string

Description returns the tool's description.

func (*ToolAdapter) Name

func (a *ToolAdapter) Name() string

Name returns the tool's name, prefixed with the server name to avoid collisions when multiple MCP servers expose tools with the same name.

func (*ToolAdapter) Schema

func (a *ToolAdapter) Schema() any

Schema returns the tool's input JSON schema.

type ToolDef

type ToolDef struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	InputSchema any    `json:"inputSchema"`
}

ToolDef is the definition of a tool from tools/list.