Help us shape the future of Go! Take the 2026 Go Developer Survey

mcpclient

package
v0.252.0 Latest Latest
Warning

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

Go to latest
Published: Oct 7, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package mcpclient is the Model Context Protocol client umbra's mcp dialect speaks: one declared upstream server, a session over it, and the three calls the dialect needs (tools/list, tools/call, resources/read).

It lives in pkg/ rather than a guarded surface because it expresses no permission. Policy is the guardfile's, enforced above this by http/mcpverb. See docs/mcpverb.md.

Index

Constants

View Source
const DefaultTimeout = 60 * time.Second

DefaultTimeout bounds a single session's whole lifetime when the caller supplies no deadline, so a silent stdio server cannot hang the CLI.

Variables

This section is empty.

Functions

This section is empty.

Types

type Call

type Call struct {
	Name          string
	Arguments     map[string]any
	ProgressToken any
}

Call is one tools/call. ProgressToken, when non-nil, rides as `_meta.progressToken` so the upstream's progress notifications correlate.

type HTTPEndpoint

type HTTPEndpoint struct {
	URL     string
	Headers map[string]string
	Client  *http.Client
}

HTTPEndpoint is the Streamable HTTP transport.

type Options

type Options struct {
	// OnProgress receives the upstream's progress for a call that carried a
	// token. nil drops them, since a one-shot leaf has nowhere to show them.
	OnProgress func(Progress)
}

Options tune one session beyond its declaration. The zero value is what Connect uses, and is what a CLI leaf wants.

type Progress

type Progress struct {
	Token    any
	Progress float64
	Total    float64
	Message  string
}

Progress is one upstream notifications/progress, correlated by the token the call carried. Total is zero when the upstream does not know it.

type Resource

type Resource struct {
	URI         string `json:"uri"`
	Name        string `json:"name,omitempty"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	MIMEType    string `json:"mimeType,omitempty"`
}

Resource is one upstream resource as umbra records it, the fields a listing shows. It is umbra's own type so the SDK's shape does not reach consumers.

type Result

type Result struct {
	Decoded any
	Raw     []byte
	IsError bool
}

Result is one tools/call outcome for the guard floor above: Decoded feeds a fail-when postcondition, Raw the renderer, IsError a tool-reported failure.

type Server

type Server struct {
	// Name is the guardfile's name for this upstream, used only in errors.
	Name string

	Stdio *Stdio
	HTTP  *HTTPEndpoint
}

Server is one fully declared upstream. Exactly one transport is set, which Validate enforces: an under-declared server is a policy hole, not a default.

func (Server) Validate

func (s Server) Validate() error

Validate refuses a server that is under- or over-declared, and puts a stdio command and argv through pkg/policy: a spawn gets no weaker gate here.

type Session

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

Session is a live client session over one upstream. Close it.

func Connect

func Connect(ctx context.Context, s Server) (*Session, error)

Connect validates the declaration, starts or dials the transport, and completes the initialize handshake.

func ConnectWith

func ConnectWith(ctx context.Context, s Server, opts Options) (*Session, error)

ConnectWith is Connect with session options, which a long-lived consumer such as an MCP Apps host needs and a one-shot call does not.

func (*Session) Call

func (s *Session) Call(ctx context.Context, c Call) (Result, error)

Call fires one tool, carrying a progress token when the caller has one.

func (*Session) CallTool

func (s *Session) CallTool(ctx context.Context, name string, args map[string]any) (Result, error)

CallTool fires one tool with already-bound arguments and no progress token.

func (*Session) Close

func (s *Session) Close() error

Close ends the session, terminating a stdio child.

func (*Session) ListResources

func (s *Session) ListResources(ctx context.Context) ([]Resource, error)

ListResources walks every page and returns the full listing sorted by URI, because resources/list order is unspecified.

func (*Session) ListTools

func (s *Session) ListTools(ctx context.Context) ([]Tool, error)

ListTools walks every page and returns the full surface sorted by name, because tools/list order is unspecified and this result reaches a lock.

func (*Session) ReadResource

func (s *Session) ReadResource(ctx context.Context, uri string) (*mcp.ReadResourceResult, error)

ReadResource reads one resource URI. This serves a `ui://` MCP Apps resource, which is an ordinary resources/read against the same session.

type Stdio

type Stdio struct {
	Command string
	Argv    []string
	// Env are `NAME=VALUE` overrides the caller already resolved. A secret reaches
	// the child here rather than through argv, which any local process can read.
	Env []string
}

Stdio is the subprocess transport: a command umbra starts and speaks newline-delimited JSON to over its stdin and stdout.

type Tool

type Tool struct {
	Name         string         `json:"name"`
	Title        string         `json:"title,omitempty"`
	Description  string         `json:"description,omitempty"`
	InputSchema  map[string]any `json:"inputSchema,omitempty"`
	OutputSchema map[string]any `json:"outputSchema,omitempty"`
	Annotations  map[string]any `json:"annotations,omitempty"`
	Meta         map[string]any `json:"_meta,omitempty"`
}

Tool is one upstream tool as umbra records it. It is umbra's own type rather than the SDK's so the lock format does not move when the SDK does.

Jump to

Keyboard shortcuts

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