mcp

type CallResult ¶

type CallResult struct {
	// Server is the configured name of the server the call was routed to.
	Server string
	// Tool is the remote tool name the call was made against (the server-side
	// name, NOT the mcp__<server>__<tool> namespaced name the model sees).
	Tool string
	// Content is the per-block content (text/blob + MIME + URI), extracted from
	// the remote CallToolResult.Content. The model-facing flattened string half
	// is NOT here — CallMcpWithQuery builds its own (filtered) string, or the
	// caller renders the blocks itself.
	Content []ResourceContents
	// StructuredContent is the remote result's structuredContent, marshaled to
	// json.RawMessage. nil when the remote result carried none. CallMcpWithQuery
	// prefers StructuredContent (it is the typed, schema-validated view) and
	// falls back to a JSON-parsing Text block otherwise.
	StructuredContent json.RawMessage
	// IsError reports whether the remote tool reported an error (the MCP
	// IsError flag). A remote error is still a successful CallTool at the
	// transport level — the caller decides how to surface it.
	IsError bool
}

CallResult is the adapter value-object view of a remote MCP tool call's raw result, BEFORE any model-facing truncation. CallMcpWithQuery filters it through jq. It carries NO mcpsdk types (so internal/app can consume it without the SDK dependency): the per-block content is the existing ResourceContents adapter VO, and StructuredContent is a json.RawMessage.

It is deliberately separate from remoteTool.Execute's session.ToolResult: Execute truncates and fail-closes on over-cap structured output (a truncated JSON blob is unparseable, so the model gets an actionable error pointing at CallMcpWithQuery instead). CallTool returns the UNTRUNCATED raw result so the jq filter in CallMcpWithQuery can narrow it BEFORE it enters model context.

type Manager ¶

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

Manager holds a set of connected MCP servers and presents their tools as a single aggregate. It is the convenient entry point when wiring several servers at once.

func NewManager(ctx context.Context, configs []ServerConfig, onError func(cfg ServerConfig, err error), diag port.Diagnostics) (*Manager, error)

func (m *Manager) CallTool(ctx context.Context, server, toolName string, args json.RawMessage) (CallResult, error)

func (m *Manager) Close() error

func (m *Manager) GetPrompt(ctx context.Context, server, name string, args map[string]string) (PromptResult, error)

func (m *Manager) ListPrompts(_ context.Context, server string) ([]Prompt, error)

func (m *Manager) ListResources(_ context.Context, server string) ([]Resource, error)

func (m *Manager) ReadResource(ctx context.Context, server, uri string) (ResourceContents, error)

func (m *Manager) Servers() []*Server

func (m *Manager) Tools() []tool.Tool

type OAuthClientConfig ¶

type OAuthClientConfig struct {
	Preregistered               *oauthex.ClientCredentials
	ClientIDMetadataDocumentURL string
}

OAuthClientConfig selects one durable client-registration profile.

type OAuthController ¶

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

OAuthController owns one official SDK authorization handler and the durable credential state for one MCP resource.

func NewOAuthController(ctx context.Context, resource string, opts OAuthOptions) (*OAuthController, error)

func (c *OAuthController) Authorize(ctx context.Context, req *http.Request, resp *http.Response) error

func (c *OAuthController) Close() error

func (c *OAuthController) ResetCredential(ctx context.Context) error

func (c *OAuthController) TokenSource(ctx context.Context) (oauth2.TokenSource, error)

type OAuthError ¶

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

OAuthError exposes only a stable safe category and never retains its cause.

func (e *OAuthError) Error() string

func (e *OAuthError) Is(target error) bool

type OAuthNetworkPolicy ¶

type OAuthNetworkPolicy struct {
	AdditionalOrigins []string
	PrivateOrigins    []string
	MaxRedirects      int
}

OAuthNetworkPolicy declares endpoint origins. DNS and transport enforcement is added by the controller's hardened HTTP client; persistence uses the origins to reject records for endpoints outside the configured identity.

type OAuthOptions ¶

type OAuthOptions struct {
	Subject     OAuthSubject
	Issuer      string
	Client      OAuthClientConfig
	RedirectURL string
	Presenter   OAuthPresenter
	// CredentialStore enables mutable restore, authorization, refresh rotation, and reset.
	// It is mutually exclusive with CredentialReader so reads and writes cannot cross CAS domains.
	CredentialStore credentialstore.Store
	// CredentialReader restores an existing opaque credential without mutation.
	// It is mutually exclusive with CredentialStore.
	CredentialReader credentialstore.Reader
	// AllowInMemoryRefresh permits a refreshed token from a read-only source to be
	// used only for this controller lifetime. It does not provide restart durability.
	AllowInMemoryRefresh bool
	Network              OAuthNetworkPolicy
	RequestRefreshToken  bool
	AllowedScopes        []string
	Timeout              time.Duration
	// contains filtered or unexported fields
}

OAuthOptions configures the persistence-capable SDK handler core.

type OAuthPresenter ¶

type OAuthPresenter interface {
	PresentAuthorization(context.Context, string) (*auth.AuthorizationResult, error)
}

OAuthPresenter hands an authorization URL to a host-owned interactive flow.

func OAuthLoginPresenter(present func(context.Context, string) (oauthlogin.Result, error)) OAuthPresenter

type OAuthPresenterFunc ¶

type OAuthPresenterFunc func(context.Context, string) (*auth.AuthorizationResult, error)

OAuthPresenterFunc adapts a function into an OAuthPresenter.

func (f OAuthPresenterFunc) PresentAuthorization(ctx context.Context, authorizationURL string) (*auth.AuthorizationResult, error)

type OAuthSubject ¶

type OAuthSubject struct {
	Profile   string
	Principal string
}

OAuthSubject identifies the host profile and principal that own a credential.

type Prompt ¶

type Prompt struct {
	Server      string
	Name        string
	Title       string
	Description string
	Arguments   []PromptArgument
}

Prompt is the adapter's value-object view of a prompt template advertised by a remote MCP server. Like Resource it carries no SDK types so non-adapter layers (and a later gRPC stage) can consume it freely. Server records the owning connected server.

type PromptArgument ¶

type PromptArgument struct {
	Name        string
	Title       string
	Description string
	Required    bool
}

PromptArgument describes a single templating argument a prompt accepts.

type PromptExpander ¶

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

PromptExpander implements prompt.CommandExpander by recognizing an input of the form

/mcp__<server>__<prompt> [key=value ...]

expanding it via Provider.GetPrompt, and returning the flattened, role-tagged expansion. The "mcp__<server>__<prompt>" shape mirrors the namespacing of proxied remote tools, so a model that knows the tool namespace can address a prompt the same way. It carries no SDK types and only depends on the domain CommandExpander interface plus this package's Provider.

ARGUMENT SYNTAX: arguments are whitespace-separated "key=value" pairs (the value may not contain spaces in v1; this is a deliberately simple, documented grammar consistent with the positional feel of DirCommandExpander). A token without an "=" is ignored. The MCP prompt's declared arguments determine what the server actually uses.

PRECEDENCE: this expander only matches the "/mcp__..." shape. Any other input — including a "/name"-style slash command handled by DirCommandExpander — returns ("", false, nil) so the next expander in a prompt.MultiExpander runs. Composed AFTER DirCommandExpander, a file-backed command named "mcp__x__y" would shadow this; in practice command files are not named with the mcp__ prefix, so the two do not overlap.

func NewPromptExpander(p Provider) *PromptExpander

func (e *PromptExpander) Expand(ctx context.Context, _ tool.Workspace, input string) (string, bool, error)

type PromptMessage ¶

type PromptMessage struct {
	Role string
	Text string
}

PromptMessage is one role-tagged message of an expanded prompt. Role is the MCP role string ("user"/"assistant"); Text is the flattened textual content.

type PromptResult ¶

type PromptResult struct {
	Description string
	Messages    []PromptMessage
}

PromptResult is the adapter's view of an expanded prompt: its optional description plus the rendered messages.

type Provider ¶

type Provider interface {
	// ListResources returns the resource snapshots. As of ADR 0057 these are
	// lazily refreshed on a notifications/resources/list_changed (the first call
	// after a notification pays a bounded synchronous re-list). server==""
	// returns the union across all servers; a specific name returns just that
	// server's (or an error if the name is unknown).
	ListResources(ctx context.Context, server string) ([]Resource, error)
	// ReadResource reads a single resource by URI from the named server.
	ReadResource(ctx context.Context, server, uri string) (ResourceContents, error)
	// ListPrompts returns the prompt snapshots. As of ADR 0057 these are lazily
	// refreshed on a notifications/prompts/list_changed. server=="" returns the
	// union across all servers.
	ListPrompts(ctx context.Context, server string) ([]Prompt, error)
	// GetPrompt expands a named prompt with args on the named server.
	GetPrompt(ctx context.Context, server, name string, args map[string]string) (PromptResult, error)
	// CallTool invokes a remote tool by name and returns the raw typed result
	// (content blocks + structured content), BEFORE any model-facing truncation.
	// Used by CallMcpWithQuery to filter the full result through jq before it
	// enters model context (remoteTool.Execute truncates/fail-closes, so it
	// cannot serve that path). Returns ErrUnknownServer (wrapped) for an
	// unknown server name; transport faults surface verbatim. args (a
	// json.RawMessage of the remote tool's input) are passed verbatim to the
	// remote tool.
	CallTool(ctx context.Context, server, toolName string, args json.RawMessage) (CallResult, error)
}

Provider is the read-side seam over the connected MCP servers' resources and prompts. It is what the resource/prompt meta-tools and the prompt expander are built against, and is the surface a later (gRPC) stage consumes to expose resources/prompts to clients. *Manager is the production implementation; routing is by server name, with the empty server name meaning "all servers".

LAYERING: this seam lives in the adapter package (not the domain) for the same reason as skills.Source — resources/prompts are packaged at composition time; no domain port consumes them. ReadResource/GetPrompt return Go errors only for genuine faults (unknown server, transport failure); the tools/expander built over a Provider translate those into model-facing tool errors, never aborting a turn.

type Resource ¶

type Resource struct {
	Server      string
	URI         string
	Name        string
	Title       string
	Description string
	MIMEType    string
	Size        int64
	ReadOnly    bool
}

Resource is the adapter's value-object view of a single resource advertised by a remote MCP server. It is deliberately a plain struct (no SDK types) so the rest of the harness — and a later gRPC stage — can consume it without taking a dependency on the MCP SDK. Server records which connected server owns it.

ReadOnly is always true: a resource is a read; exposing one never mutates the server. The field exists so the resource-reading tool can advertise ReadOnly() uniformly and so callers do not special-case the concept.

type ResourceContents ¶

type ResourceContents struct {
	URI      string
	MIMEType string
	Text     string
	Blob     []byte
}

ResourceContents is the adapter's view of one chunk of a read resource's body. Text holds UTF-8 textual content; Blob holds raw binary bytes. Exactly one is normally populated per chunk by a well-behaved server. The harness never base64-dumps Blob into the model context — readResource summarizes binary chunks instead (see flattenResourceContents).

type Server ¶

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

Server is a live connection to one remote MCP server. It owns the SDK client session and the tool.Tool wrappers derived from the server's tool list, plus the snapshots of the server's resources and prompts captured at connect.

As of ADR 0057 the adapter holds the standalone SSE GET stream open per connected server and subscribes to server-initiated notifications/{tools,prompts,resources}/list_changed: a notification sets the matching *Dirty flag, and the next read of Tools()/Resources()/Prompts() lazily re-lists under a bounded context.Background() and swaps in the fresh snapshot. The dirty flag is cleared BEFORE the fetch (not after) so a notification arriving during the re-list re-arms it — the safe direction (at worst one redundant refresh, never a lost update).

Catalog mutation (live tool.Catalog refresh) is deliberately Phase 2 — it gets its own ADR. In Phase 1, Tools() DOES re-list on dirty (so a per-session catalog assembly that calls mgr.Tools() after a list_changed picks up the fresh set), but the already-registered remoteTool specs in an existing session are NOT updated — a tool the server dropped surfaces a tool-call error on use. This means two sessions created around the same notification may see different tool surfaces (a timing-dependent split); this is the accepted Phase 1 trade-off, documented in ADR 0057.

A dropped session (the SDK's ErrConnectionClosed / errSessionMissing, surfacing as "session not found" / "connection closed") is re-established transparently by withSession: a single bounded reconnect attempt per call, serialized under mu so N concurrent failing calls produce ONE dial. See reconnect.go and ADR 0056.

func Connect(ctx context.Context, cfg ServerConfig, diag port.Diagnostics) (*Server, error)

func (s *Server) Close() error

func (s *Server) HasOAuthCredential() bool

func (s *Server) Name() string

func (s *Server) Prompts() []Prompt

func (s *Server) Resources() []Resource

func (s *Server) Tools() []tool.Tool

type ServerConfig ¶

type ServerConfig struct {
	// Name is a short, stable identifier for the server. It becomes the
	// <server> segment of every wrapped tool's namespaced name, so it should be
	// unique across the configured servers and contain no "__" sequence.
	Name string
	// URL is the server's Streamable HTTP endpoint (e.g. https://host/mcp).
	URL string
	// Headers are extra HTTP headers sent on every request to the server, such
	// as "Authorization: Bearer ...". Optional.
	Headers map[string]string
	// OAuth enables the adapter-local authorization-code controller. It is
	// mutually exclusive with a static Authorization header.
	OAuth *OAuthOptions
	// Timeout bounds the connect handshake and tool listing. If zero,
	// defaultConnectTimeout is used. It does not bound later tool calls, which
	// are governed by the per-call context.
	Timeout time.Duration
}

ServerConfig describes a single remote MCP server to connect to over the Streamable HTTP transport.