mcpclient

type ApprovalPolicy ¶

type ApprovalPolicy int

ApprovalPolicy decides whether tools discovered from a server are gated behind the orchestrator's approval prompt.

const (
	// ApprovalAlways gates every tool from the server. It is the zero value, so
	// a caller that forgets to think about approval fails closed.
	//
	// Why this is the default: MCP gives a client no way to tell a read from a
	// write. A name and a description are all a tool ships, both written by the
	// third party that also implements the tool. Later protocol revisions add
	// annotations.readOnlyHint, but that is the server's self-declaration about
	// its own safety — precisely the claim an attacker would forge — so this
	// package does not use it to lower a gate. The party who can classify the
	// risk is the operator who chose to configure the server URL, and this
	// policy is where they record that judgement.
	ApprovalAlways ApprovalPolicy = iota

	// ApprovalNever ungates the server's tools. Set it only for a server the
	// operator has vetted — typically their own business-data endpoint, whose
	// tools exist to be called autonomously by an unattended chatbot pane.
	ApprovalNever
)

type CallToolResult ¶

type CallToolResult struct {
	Content []contentBlock `json:"content"`
	IsError bool           `json:"isError,omitempty"`
}

CallToolResult is the server's reply to "tools/call". IsError distinguishes "the tool ran and reported a failure" (recoverable by the model) from a transport or protocol failure (returned as a Go error).

type Client ¶

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

Client is a protocol-level MCP client over a single Streamable-HTTP connection. It performs the handshake, lists tools, and calls them. It is safe for concurrent use.

func Connect(ctx context.Context, cfg Config) (*Client, []sharedtools.ToolExecutor, error)

func New(cfg Config) (*Client, error)

func (c *Client) CallTool(ctx context.Context, name string, args json.RawMessage) (*CallToolResult, error)

func (c *Client) Close() error

func (c *Client) DroppedTools() int

func (c *Client) Executors(list []Tool) []sharedtools.ToolExecutor

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

func (c *Client) ListTools(ctx context.Context) ([]Tool, error)

func (c *Client) ServerInfo() (name, version string)

type Config ¶

type Config struct {
	// Name is a short alias for the server. It prefixes every discovered tool
	// name so two servers exposing "search" do not collide in one registry, and
	// it identifies the server in errors.
	Name string

	// URL is the Streamable-HTTP MCP endpoint (typically ".../mcp").
	URL string

	// Headers are sent on every request — this is where an Authorization
	// header for the customer's server goes.
	Headers map[string]string

	// Guard authorizes the endpoint. Required; see URLGuard.
	Guard URLGuard

	// Timeout bounds one round trip. Zero uses DefaultTimeout.
	Timeout time.Duration

	// MaxResponseBytes caps one response body. Zero uses
	// DefaultMaxResponseBytes; a body over the cap is an error, never a
	// truncated parse.
	MaxResponseBytes int64

	// MaxTools bounds adopted tools. Zero uses DefaultMaxTools.
	MaxTools int

	// Approval selects the approval policy. The zero value is ApprovalAlways.
	Approval ApprovalPolicy

	// HTTPClient overrides the transport client. When nil a client is built
	// with the guard installed as its redirect checker. A supplied client has
	// its CheckRedirect replaced for the same reason.
	HTTPClient *http.Client
}

Config describes one MCP server connection.

type Tool ¶

type Tool struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	InputSchema json.RawMessage `json:"inputSchema"`
}

Tool is a tool advertised by an MCP server. InputSchema stays raw JSON so it can be handed to tools.ToolSpec.Parameters (also a JSON Schema) without a lossy round-trip through a typed struct.

type URLGuard ¶

type URLGuard func(ctx context.Context, u *url.URL) error

URLGuard authorizes one outbound request target. It is applied to the configured endpoint before every request and again to every redirect hop.

--------------------------------------------------------------------------- Which layer owns SSRF protection: the caller, not this package. ---------------------------------------------------------------------------

This package owns *transport* hardening — timeout, response-size cap, tool count, redirect bound. It deliberately does not own *network-position* policy (http(s)-only is checked here as basic input validation, but "is this host publicly routable" is not), for one reason: rysh-server already has that policy, implemented and tested, in internal/agentic/chatbot_ssrf_guard.go, and its own header says a second copy is "a future vulnerability, not a convenience". Duplicating it in rysh-shared would create exactly the drift it warns about — and rysh-shared has no visibility into a deployment's egress rules anyway.

So the policy is injected, and Guard is REQUIRED: New refuses a nil Guard rather than defaulting to allow-all. That refusal is the whole point. The custom HTTP tool shipped with a `strings.HasPrefix(url, "http")` check and nothing else (design 016 gap 3), which let an owner aim a tool at the cloud metadata endpoint. A library default of "no guard means no guarding" is how that happens again; a compile-time-visible required field is how it does not.

Wave 2 (wiring MCP into chatbot_configs) must pass rysh-server's strictURLGuard here. Tests against a loopback httptest server pass AllowAnyURL.

func AllowAnyURL() URLGuard