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
- type Call
- type HTTPEndpoint
- type Options
- type Progress
- type Resource
- type Result
- type Server
- type Session
- func (s *Session) Call(ctx context.Context, c Call) (Result, error)
- func (s *Session) CallTool(ctx context.Context, name string, args map[string]any) (Result, error)
- func (s *Session) Close() error
- func (s *Session) ListResources(ctx context.Context) ([]Resource, error)
- func (s *Session) ListTools(ctx context.Context) ([]Tool, error)
- func (s *Session) ReadResource(ctx context.Context, uri string) (*mcp.ReadResourceResult, error)
- type Stdio
- type Tool
Constants ¶
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 ¶
Call is one tools/call. ProgressToken, when non-nil, rides as `_meta.progressToken` so the upstream's progress notifications correlate.
type HTTPEndpoint ¶
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 ¶
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 ¶
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.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is a live client session over one upstream. Close it.
func Connect ¶
Connect validates the declaration, starts or dials the transport, and completes the initialize handshake.
func ConnectWith ¶
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) CallTool ¶
CallTool fires one tool with already-bound arguments and no progress token.
func (*Session) ListResources ¶
ListResources walks every page and returns the full listing sorted by URI, because resources/list order is unspecified.
func (*Session) ListTools ¶
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 ¶
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.