mcpcatalog

package
v1.62.0 Latest Latest
Warning

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

 Go to latest Published: May 21, 2026 License: Apache-2.0 Imports: 14 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 (defers the actual TCP connect / OAuth handshake until Tools() is next enumerated).
  • 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: the expensive parts — DNS, TCP, MCP handshake, OAuth flow — happen the first time Tools() is called for a freshly enabled server. The handshake runs through the same lifecycle.Supervisor the YAML-declared `mcp.remote` toolset uses, so OAuth elicitation and tool-list-change notifications behave identically.

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"`
	Secrets   []SecretSpec    `json:"secrets,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
  • "api_key" — caller-provided secret(s) (env vars listed in Secrets)

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 ResetAuthArgs 

type ResetAuthArgs struct {
	ID string `json:"id" jsonschema:"Catalog id of the server whose persisted OAuth 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 SecretSpec 

type SecretSpec struct {
	Name    string `json:"name"`
	Env     string `json:"env"`
	Example string `json:"example,omitempty"`
}

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"`
	Headers     map[string]string `json:"headers,omitempty"`
	Auth        Auth              `json:"auth"`
}

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

Headers may contain ${ENV_VAR} placeholders that are resolved at request time against the agent's env provider — exactly like a YAML-declared `mcp` toolset with `remote.headers`. This lets API-key servers like Apify pull APIFY_API_KEY from the user's shell at activation time.

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(envProvider environment.Provider) *Toolset

New returns a Toolset backed by the embedded catalog. envProvider is used to resolve ${ENV_VAR} placeholders in catalog headers (e.g. the Apify `Authorization: Bearer ${APIFY_API_KEY}` header) at enable time, mirroring how a YAML-declared `mcp.remote` toolset works.

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) 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.