mcpcatalog

package
v1.74.0 Latest Latest
Warning

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

 Go to latest Published: Jun 9, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package mcpcatalog exposes the Docker MCP Catalog's remote streamable-http servers as a single agent-side toolset that supports on-demand activation.

The toolset surfaces up to five meta-tools to the model:

  • search_remote_mcp_servers — case-insensitive fuzzy search over the curated catalog (id / title / description / category / tags).
  • list_remote_mcp_servers — show currently enabled servers.
  • enable_remote_mcp_server — instantiate an *mcp.Toolset for a server and synchronously drive its connect (including any required OAuth handshake) so the model gets a deterministic success / declined / transport-error result in the same turn.
  • disable_remote_mcp_server — stop the toolset and remove its tools. Only exposed once at least one server is enabled.
  • reset_remote_mcp_server_auth — drop persisted OAuth credentials so the next enable triggers a fresh authorization flow. Only exposed once at least one server is enabled.

Activated servers' tools are merged into Tools(); tool list changes are reported via a tools.ChangeNotifier handler so the runtime refreshes the LLM's tool catalogue as soon as a server is enabled or disabled.

Known limitation: the runtime's MCP-prompt discovery looks for `*mcp.Toolset` directly via tools.As, so prompts exposed by servers activated through this catalog are not surfaced via /prompts. Tools (the primary interface) work fine; the prompt feature would need a separate plumb-through interface to walk into container toolsets.

On-demand semantics: DNS, TCP, MCP handshake and any OAuth flow happen synchronously inside enable_remote_mcp_server's handler. Tool calls run with an interactive context, so OAuth elicitation surfaces a dialog and blocks until the user responds; the handshake runs through the same lifecycle.Supervisor the YAML-declared `mcp.remote` toolset uses, so elicitation and tool-list-change notifications behave identically. The handler returns a deterministic success / declined / auth-required / transport-error result so the model can continue with the user's original request in the *same* turn (success) or recover appropriately (failure) — no second user message required. Tools() additionally retries any toolset left in the "deferred — auth required" state, which keeps the startup non-interactive probe (mcp.WithoutInteractivePrompts) from hanging while still surfacing OAuth dialogs on the first interactive turn.

Index

Constants

View Source 
const (
	ToolNameSearch    = "search_remote_mcp_servers"
	ToolNameEnable    = "enable_remote_mcp_server"
	ToolNameDisable   = "disable_remote_mcp_server"
	ToolNameList      = "list_remote_mcp_servers"
	ToolNameResetAuth = "reset_remote_mcp_server_auth"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Auth 

type Auth struct {
	Type      string          `json:"type"`
	Providers []OAuthProvider `json:"providers,omitempty"`
}

Auth describes how to authenticate against a remote MCP server.

Type is one of:

  • "none" — no credentials required
  • "oauth" — OAuth flow handled by the underlying mcp.Toolset

type Catalog 

type Catalog struct {
	Source        string   `json:"source"`
	SourceURL     string   `json:"source_url"`
	SchemaVersion int      `json:"schema_version"`
	Filter        string   `json:"filter"`
	Count         int      `json:"count"`
	Servers       []Server `json:"servers"`
}

Catalog mirrors the on-disk JSON file. It exposes the curated subset of the Docker MCP Catalog that consists exclusively of remote servers reachable over the streamable-http transport — the format docker-agent can talk to directly without a local subprocess or the MCP gateway.

func Load 

func Load() (*Catalog, error)

Load returns the embedded catalog. The first call decodes the JSON; subsequent calls return a shallow copy so callers can append synthetic servers (notably in tests) without affecting later callers.

func MustLoad 

func MustLoad() *Catalog

MustLoad is like Load but panics on error. Intended for package init.

type DisableArgs 

type DisableArgs struct {
	ID string `json:"id" jsonschema:"Catalog id of the server to disable."`
}

DisableArgs is the input schema for disable_remote_mcp_server.

type EnableArgs 

type EnableArgs struct {
	ID string `json:"id" jsonschema:"Catalog id of the server to enable (use search_remote_mcp_servers to find it)."`
}

EnableArgs is the input schema for enable_remote_mcp_server.

type EnabledServer 

type EnabledServer struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	URL     string `json:"url"`
	Auth    string `json:"auth"`
	Started bool   `json:"started"`
}

EnabledServer reports the runtime state of a single enabled MCP server.

type ListArgs 

type ListArgs struct{}

ListArgs is the input schema for list_remote_mcp_servers (no params).

type OAuthProvider 

type OAuthProvider struct {
	Provider string `json:"provider"`
	Env      string `json:"env"`
	Secret   string `json:"secret"`
}

type Option added in v1.70.0 

type Option func(*options)

Option customizes a Toolset at construction time.

func WithAllowedServers added in v1.70.0 

func WithAllowedServers(ids []string) Option

WithAllowedServers restricts the offered catalog to the given server ids. When the list is non-empty, only these servers are searchable and enableable; every other entry is hidden. An empty or nil list leaves the full catalog in place.

func WithBlockedServers added in v1.70.0 

func WithBlockedServers(ids []string) Option

WithBlockedServers removes the given server ids from the offered catalog. Block takes precedence over allow: a server present in both lists is blocked.

type ResetAuthArgs 

type ResetAuthArgs struct {
	ID string `json:"id" jsonschema:"Catalog id of the server whose persisted credentials should be cleared."`
}

ResetAuthArgs is the input schema for reset_remote_mcp_server_auth.

type SearchArgs 

type SearchArgs struct {
	// Query is the keyword to look for. Empty matches everything.
	Query string `` /* 153-byte string literal not displayed */
}

SearchArgs is the input schema for the search meta-tool.

type SearchResult 

type SearchResult struct {
	ID          string   `json:"id"`
	Title       string   `json:"title"`
	Description string   `json:"description"`
	Category    string   `json:"category,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	Auth        string   `json:"auth"`
	URL         string   `json:"url"`
	Enabled     bool     `json:"enabled"`
}

SearchResult is one row in the search response.

type Server 

type Server struct {
	ID          string   `json:"id"`
	Title       string   `json:"title"`
	Description string   `json:"description"`
	URL         string   `json:"url"`
	Transport   string   `json:"transport"`
	Category    string   `json:"category,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	Icon        string   `json:"icon,omitempty"`
	Readme      string   `json:"readme,omitempty"`
	Auth        Auth     `json:"auth"`
}

Server is a curated, on-demand-activatable remote MCP server description.

The catalog only carries servers reachable over streamable-http with an auth model docker-agent can drive itself: either no credentials at all ("none") or an OAuth flow ("oauth") handled by the underlying mcp.Toolset.

type Toolset 

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

Toolset implements on-demand activation of remote (streamable-http) MCP servers from the Docker MCP Catalog.

func New 

func New(opts ...Option) *Toolset

New returns a Toolset backed by the embedded catalog. Every catalog server is reachable over streamable-http and authenticates with either no credentials ("none") or an OAuth flow ("oauth") driven by the underlying mcp.Toolset.

Optional WithAllowedServers / WithBlockedServers options narrow the set of servers the toolset offers by default.

func (*Toolset) Describe 

func (t *Toolset) Describe() string

Describe returns a short, user-visible label for the /tools dialog.

func (*Toolset) Instructions 

func (t *Toolset) Instructions() string

Instructions tell the model how to discover and activate servers.

func (*Toolset) SetElicitationHandler 

func (t *Toolset) SetElicitationHandler(handler tools.ElicitationHandler)

SetElicitationHandler is captured here and re-attached to every freshly activated MCP toolset so OAuth flows can prompt the user.

func (*Toolset) SetManagedOAuth 

func (t *Toolset) SetManagedOAuth(managed bool)

SetManagedOAuth forwards the managed-OAuth flag to every enabled toolset; new toolsets pick it up at enable time.

func (*Toolset) SetOAuthSuccessHandler 

func (t *Toolset) SetOAuthSuccessHandler(handler func())

SetOAuthSuccessHandler is captured here and re-attached to every freshly activated MCP toolset so the runtime refreshes its tool list once OAuth completes.

func (*Toolset) SetToolsChangedHandler 

func (t *Toolset) SetToolsChangedHandler(handler func())

SetToolsChangedHandler is invoked by the runtime to be notified when the set of available tools changes. We forward to the activated MCP toolsets *and* call it ourselves on every Enable / Disable so the runtime sees the meta-tool surface change too.

func (*Toolset) SetUnmanagedOAuthRedirectURI added in v1.69.0 

func (t *Toolset) SetUnmanagedOAuthRedirectURI(uri string)

SetUnmanagedOAuthRedirectURI forwards the unmanaged-OAuth redirect URI to every enabled toolset; new toolsets pick it up at enable time.

func (*Toolset) Start 

func (t *Toolset) Start(context.Context) error

Start is a no-op: the catalog is embedded and no servers are auto-enabled. Lifecycle for individual MCP toolsets is managed when Enable / Disable are invoked, with first-use lazy start happening inside Tools().

func (*Toolset) Stop 

func (t *Toolset) Stop(ctx context.Context) error

Stop tears down every enabled MCP toolset. Errors are logged but do not abort the loop so a misbehaving server can't block agent shutdown.

func (*Toolset) Tools 

func (t *Toolset) Tools(ctx context.Context) ([]tools.Tool, error)

Tools returns the meta-tools plus every tool exposed by an activated remote MCP server. Tools from unactivated servers are intentionally hidden so they don't bloat the prompt.

First-call lazy start: each enabled server is Start()'d on its first enumeration. On startup the runtime probes tools with a non-interactive context (mcp.WithoutInteractivePrompts), so OAuth-pending servers fail fast with mcp.IsAuthorizationRequired and are silently deferred. On interactive turns, Start() blocks on OAuth elicitation as the user expects, and the resulting tools join the result set on the next enumeration.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.