Documentation
¶
Index ¶
- func StateChangeNotifier(nm *NotificationManager, serverName string) func(oldState, newState types.ConnectionState, info *types.ConnectionInfo)
- type ClientFactory
- type ClientPool
- type MCPClient
- type Manager
- func (m *Manager) AddNotificationHandler(handler NotificationHandler)
- func (m *Manager) AddServer(id string, serverConfig *config.ServerConfig) error
- func (m *Manager) AddServerConfig(id string, serverConfig *config.ServerConfig) error
- func (m *Manager) CallTool(ctx context.Context, toolName string, args map[string]interface{}) (interface{}, error)
- func (m *Manager) CallToolOnEpoch(ctx context.Context, toolName string, args map[string]interface{}, ...) (interface{}, error)
- func (m *Manager) CaptureReplacementQueued() bool
- func (m *Manager) ClearOAuthToken(serverName string) error
- func (m *Manager) ConcurrencyStats() (global limiter.Stats, servers map[string]limiter.Stats)
- func (m *Manager) ConnectAll(ctx context.Context) error
- func (m *Manager) DisconnectAll() error
- func (m *Manager) DisconnectServer(serverName string) error
- func (m *Manager) DiscoverTools(ctx context.Context) ([]*config.ToolMetadata, error)
- func (m *Manager) DiscoverToolsDue(ctx context.Context) ([]*config.ToolMetadata, error)
- func (m *Manager) DiscoverToolsReport(ctx context.Context, dueOnly bool) ([]*config.ToolMetadata, []string, error)
- func (m *Manager) ForceCleanupAllContainers()
- func (m *Manager) ForceReconnectAll(reason string) *ReconnectResult
- func (m *Manager) GetAllClients() map[string]*managed.Client
- func (m *Manager) GetAllServerNames() []string
- func (m *Manager) GetClient(id string) (*managed.Client, bool)
- func (m *Manager) GetDockerRecoveryStatus() *storage.DockerRecoveryState
- func (m *Manager) GetPrompt(ctx context.Context, name string, args map[string]string) (*mcp.GetPromptResult, error)
- func (m *Manager) GetStats() map[string]interface{}
- func (m *Manager) GetTotalToolCount() int
- func (m *Manager) GlobalConfig() *config.Config
- func (m *Manager) HasDockerContainers() bool
- func (m *Manager) InvalidateAllToolCountCaches()
- func (m *Manager) Limiters() *limiter.Registry
- func (m *Manager) ListPrompts(ctx context.Context) ([]mcp.Prompt, error)
- func (m *Manager) ListServers() map[string]*config.ServerConfig
- func (m *Manager) RefreshOAuthToken(serverName string) error
- func (m *Manager) RemoveServer(id string)
- func (m *Manager) ResolveToolDiscoverySweepTick(globalCfg *config.Config) (time.Duration, bool)
- func (m *Manager) RetryConnection(serverName string) error
- func (m *Manager) SetGlobalConfig(globalConfig *config.Config)
- func (m *Manager) SetLogConfig(logConfig *config.LogConfig)
- func (m *Manager) SetPromptsChangedCallback(callback func(serverName string))
- func (m *Manager) SetRejectionObserver(observe limiter.Observer)
- func (m *Manager) SetToolDiscoveryCallback(callback func(ctx context.Context, serverName string) error)
- func (m *Manager) SetUserLoggedOut(serverName string, loggedOut bool) error
- func (m *Manager) ShutdownAll(ctx context.Context) error
- func (m *Manager) StartManualOAuth(serverName string, force bool) error
- func (m *Manager) StartManualOAuthQuick(serverName string) (*core.OAuthStartResult, error)
- func (m *Manager) StartManualOAuthWithInfo(serverName string, force bool) (*core.OAuthStartResult, error)
- func (m *Manager) UsesDockerIsolation() bool
- func (m *Manager) WithCurrentClientOnEpoch(id string, expected *managed.Client, expectedEpoch int64, fn func() error) (current bool, err error)
- type Notification
- type NotificationHandler
- type NotificationLevel
- type NotificationManager
- func (nm *NotificationManager) AddHandler(handler NotificationHandler)
- func (nm *NotificationManager) NotifyOAuthRequired(serverName string)
- func (nm *NotificationManager) NotifyServerConnected(serverName string)
- func (nm *NotificationManager) NotifyServerConnecting(serverName string)
- func (nm *NotificationManager) NotifyServerDisconnected(serverName string, reason error)
- func (nm *NotificationManager) NotifyServerError(serverName string, err error)
- func (nm *NotificationManager) SendNotification(notification *Notification)
- type ReconnectResult
- type StatefulClient
- type TransportClient
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func StateChangeNotifier ¶
func StateChangeNotifier(nm *NotificationManager, serverName string) func(oldState, newState types.ConnectionState, info *types.ConnectionInfo)
StateChangeNotifier creates state change notifications based on state transitions
Types ¶
type ClientFactory ¶
type ClientFactory interface {
// Create core client for basic operations
CreateCoreClient(id string, config *config.ServerConfig) (MCPClient, error)
// Create managed client with state machine
CreateManagedClient(id string, config *config.ServerConfig) (StatefulClient, error)
// Create CLI client for debugging
CreateCLIClient(id string, config *config.ServerConfig) (MCPClient, error)
}
ClientFactory creates different types of clients
type ClientPool ¶
type ClientPool interface {
// Pool management
AddClient(id string, client StatefulClient) error
RemoveClient(id string)
GetClient(id string) (StatefulClient, bool)
GetAllClients() map[string]StatefulClient
// Bulk operations
ConnectAll(ctx context.Context) error
DisconnectAll() error
// Tool operations across all clients
DiscoverTools(ctx context.Context) ([]*config.ToolMetadata, error)
CallTool(ctx context.Context, toolName string, args map[string]interface{}) (*mcp.CallToolResult, error)
}
ClientPool manages multiple clients
type MCPClient ¶
type MCPClient interface {
// Connection management
Connect(ctx context.Context) error
Disconnect() error
IsConnected() bool
// MCP operations
ListTools(ctx context.Context) ([]*config.ToolMetadata, error)
CallTool(ctx context.Context, toolName string, args map[string]interface{}) (*mcp.CallToolResult, error)
// Status and info
GetConnectionInfo() types.ConnectionInfo
GetServerInfo() *mcp.InitializeResult
}
MCPClient defines the core interface for MCP client operations
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager manages connections to multiple upstream MCP servers
func NewManager ¶
func NewManager(logger *zap.Logger, globalConfig *config.Config, boltStorage *storage.BoltDB, secretResolver *secret.Resolver, storageMgr *storage.Manager) *Manager
NewManager creates a new upstream manager
func (*Manager) AddNotificationHandler ¶
func (m *Manager) AddNotificationHandler(handler NotificationHandler)
AddNotificationHandler adds a notification handler to receive state change notifications
func (*Manager) AddServer ¶
func (m *Manager) AddServer(id string, serverConfig *config.ServerConfig) error
AddServer adds a new upstream server and connects to it (legacy method)
func (*Manager) AddServerConfig ¶
func (m *Manager) AddServerConfig(id string, serverConfig *config.ServerConfig) error
AddServerConfig adds a server configuration without connecting
func (*Manager) CallTool ¶
func (m *Manager) CallTool(ctx context.Context, toolName string, args map[string]interface{}) (interface{}, error)
CallTool calls a tool on the appropriate upstream server
func (*Manager) CallToolOnEpoch ¶ added in v0.67.0
func (m *Manager) CallToolOnEpoch(ctx context.Context, toolName string, args map[string]interface{}, expectedEpoch int64) (interface{}, error)
CallToolOnEpoch is CallTool pinned to the connection generation the caller certified the tool identity against (Spec 105 FR-009 "stale generation"; codex r3 D2): the dispatch reaches the upstream on exactly that generation of the server's live client (managed.Client.CallToolOnEpoch) or is refused with managed.ErrConnectionGenerationChanged and zero upstream calls. The reconnect_on_use branch is deliberately NOT taken for a pinned call — a reconnect is a new generation by construction, whose tool set the caller never certified — so a client found disconnected is refused the same way. The refusal is returned verbatim, never enriched, so errors.Is holds.
func (*Manager) CaptureReplacementQueued ¶ added in v0.70.0
CaptureReplacementQueued reports whether a replacement/removal is waiting behind an active capture persistence section. It is primarily useful for observability and deterministic concurrency tests; it never mutates state.
func (*Manager) ClearOAuthToken ¶
ClearOAuthToken clears the OAuth token for a specific server. This is called by the OAuth logout flow to remove stored credentials. Works for both explicit OAuth config and discovered OAuth (server-announced OAuth).
func (*Manager) ConcurrencyStats ¶ added in v0.54.0
ConcurrencyStats reports the current occupancy of the global aggregate limiter and of every live per-server limiter (FR-013: queue depth).
func (*Manager) ConnectAll ¶
ConnectAll connects to all configured servers that should retry
func (*Manager) DisconnectAll ¶
DisconnectAll disconnects from all servers
func (*Manager) DisconnectServer ¶
DisconnectServer disconnects a specific server without removing its configuration. This is used after OAuth logout to force re-authentication on next connect.
func (*Manager) DiscoverTools ¶
DiscoverTools discovers all tools from all connected upstream servers. Security: Tools from quarantined servers are NOT discovered to prevent Tool Poisoning Attacks (TPA) from exposing potentially malicious tool descriptions.
func (*Manager) DiscoverToolsDue ¶ added in v0.38.0
DiscoverToolsDue is the periodic-sweep variant of DiscoverTools: it lists only servers whose per-server tool_discovery_interval has elapsed and skips those whose resolved interval disables the sweep (<=0). The background indexing loop uses this so a per-server override changes how often that server is re-listed; event-driven callers (connect, reload, manual refresh) use DiscoverTools for a full sweep (spec 074, US3/SC-006/FR-005).
func (*Manager) DiscoverToolsReport ¶ added in v0.67.0
func (m *Manager) DiscoverToolsReport(ctx context.Context, dueOnly bool) ([]*config.ToolMetadata, []string, error)
DiscoverToolsReport is DiscoverTools / DiscoverToolsDue with the names of the servers whose tools/list actually SUCCEEDED in this sweep, so a caller can tell a server that listed zero tools (discovery completed, nothing served) from one the sweep skipped or that failed to list (Spec 105 FR-009: the discovery-completed marker must be stamped for the former and left alone for the latter).
func (*Manager) ForceCleanupAllContainers ¶
func (m *Manager) ForceCleanupAllContainers()
ForceCleanupAllContainers is a public wrapper for emergency container cleanup This is called when graceful shutdown fails and containers must be force-removed Only removes containers owned by THIS instance (matching instance ID) AND canonically owned by a configured server (listOwnedManagedContainers).
func (*Manager) ForceReconnectAll ¶
func (m *Manager) ForceReconnectAll(reason string) *ReconnectResult
ForceReconnectAll triggers reconnection attempts for all managed clients. For Docker-based servers, this includes container health verification to catch frozen containers. Returns detailed results about which servers were reconnected, skipped, or failed.
func (*Manager) GetAllClients ¶
GetAllClients returns all clients
func (*Manager) GetAllServerNames ¶
GetAllServerNames returns a slice of all configured server names
func (*Manager) GetDockerRecoveryStatus ¶
func (m *Manager) GetDockerRecoveryStatus() *storage.DockerRecoveryState
GetDockerRecoveryStatus returns the current Docker recovery status
func (*Manager) GetPrompt ¶ added in v0.59.0
func (m *Manager) GetPrompt(ctx context.Context, name string, args map[string]string) (*mcp.GetPromptResult, error)
GetPrompt resolves a colon-qualified "serverName:promptName" and forwards the call to the owning upstream client.
func (*Manager) GetStats ¶
GetStats returns statistics about upstream connections GetStats returns statistics about all managed clients. Phase 6 Fix: Lock-free implementation to prevent deadlock with async operations.
Issue #1148, round 4: this map is not an internal counter — it is served verbatim as `upstream_stats` on GET /api/v1/status, on the /api/v1/servers response, and on every SSE `status` event, and it is what the tray renders. Its per-server entries therefore sit behind the same trust boundary as the server list on those same payloads, which httpapi.redactServerSecrets and Runtime.redactServerSecrets already mask. Leaving `url` and `last_error` raw here meant one half of a single response was masked and the other half was not. Mask them at the point they are written.
Issue #1167: unconditionally, with no reveal_secret_headers opt-out. This producer takes no ctx and neither does its consumer chain, so there is no caller identity to AND the operator flag with - and the flag alone handed a scoped agent token every server's raw url and last_error on /api/v1/status and on every SSE status event. Same rule, same reason, as the StateView implementation in internal/server.Server.GetUpstreamStats, which is the one that actually runs.
func (*Manager) GetTotalToolCount ¶
GetTotalToolCount returns the total number of tools across all servers. Uses cached counts to avoid excessive network calls (2-minute cache per server). Phase 6 Fix: Lock-free implementation to prevent deadlock.
func (*Manager) GlobalConfig ¶ added in v0.52.0
GlobalConfig returns the proxy-wide config the manager currently uses for newly created clients and Docker-recovery decisions (see SetGlobalConfig). May be nil before the first Store.
func (*Manager) HasDockerContainers ¶
HasDockerContainers reports whether any RUNNING Docker container this instance manages (com.mcpproxy.managed=true, com.mcpproxy.instance=<this instance>) is also canonically owned by a configured server — core.ContainerOwnedByAny over listOwnedManagedContainers, the same selection the shutdown and emergency sweeps apply. The instance/managed labels alone are shared and copyable (Spec 105 D9): a foreign container that copies them, or one whose owning server was since removed from config, must not be reported as still running — that false positive drove the runtime/server shutdown path into its 15-second cleanup-verification wait, a second force-clean, and a false "still running after force cleanup" report for a container mcpproxy neither started nor can act on (codex round 10, docker finding 1). includeStopped is false: an already-stopped row must not read as still running either.
func (*Manager) InvalidateAllToolCountCaches ¶
func (m *Manager) InvalidateAllToolCountCaches()
InvalidateAllToolCountCaches invalidates tool count caches for all clients This should be called when tools are known to have changed (e.g., after indexing)
func (*Manager) Limiters ¶ added in v0.54.0
Limiters exposes the live limiter registry (metrics surface, tests).
func (*Manager) ListPrompts ¶ added in v0.59.0
ListPrompts aggregates prompts from every connected, enabled, non-quarantined upstream client. Each returned prompt's Name is rewritten to "serverName:promptName" so a subsequent GetPrompt call can be routed back to the right server. A per-client failure is logged and that client is skipped; the rest of the aggregation proceeds.
func (*Manager) ListServers ¶
func (m *Manager) ListServers() map[string]*config.ServerConfig
ListServers returns information about all registered servers
func (*Manager) RefreshOAuthToken ¶
RefreshOAuthToken triggers a token refresh for a specific server. This is called by the RefreshManager for proactive token refresh.
OAuth detection checks both: 1. Static config (serverConfig.OAuth) - for servers with pre-configured OAuth 2. Database tokens - for servers using dynamic OAuth discovery (Protected Resource Metadata)
func (*Manager) RemoveServer ¶
RemoveServer removes an upstream server
func (*Manager) ResolveToolDiscoverySweepTick ¶ added in v0.38.0
ResolveToolDiscoverySweepTick computes how long the periodic indexing loop should wait between sweeps: the smallest positive resolved tool-discovery interval across the global default and every managed server. Per-server configs are read through each client's thread-safe GetConfig() snapshot — deliberately NOT by iterating globalCfg.Servers, which would race in-place mutation of the shared (copy-on-write) config snapshot from the background loop (the original cause of the MCP-1189 -race failure). anyEnabled is false when every resolved interval is disabled (<=0), in which case the loop idles.
func (*Manager) RetryConnection ¶
RetryConnection triggers a connection retry for a specific server This is typically called after OAuth completion to immediately use new tokens
func (*Manager) SetGlobalConfig ¶ added in v0.38.0
SetGlobalConfig swaps the proxy-wide config the manager uses for newly created clients and Docker-recovery decisions, and propagates it to every existing managed client so their background health-check loops re-resolve the new global interval on the next cycle (spec 074, FR-012/SC-002). Called from the runtime on a config hot-reload (ApplyConfig). The atomic swap is lock-free; the client fan-out snapshots under mu.RLock to avoid holding the lock while touching each client.
func (*Manager) SetLogConfig ¶
SetLogConfig sets the logging configuration for upstream server loggers
func (*Manager) SetPromptsChangedCallback ¶ added in v0.59.0
SetPromptsChangedCallback sets the callback for triggering aggregated-prompt refresh when an upstream sends notifications/prompts/list_changed (F13). It is passed to all new clients created by the manager.
func (*Manager) SetRejectionObserver ¶ added in v0.54.0
SetRejectionObserver installs the origin-independent shed seam (FR-012): the runtime passes a callback that turns a rejection into a "rejected" activity record and a rejection metric, regardless of which surface originated the call. Existing clients are re-wired immediately.
func (*Manager) SetToolDiscoveryCallback ¶
func (m *Manager) SetToolDiscoveryCallback(callback func(ctx context.Context, serverName string) error)
SetToolDiscoveryCallback sets the callback for triggering tool re-indexing when upstream servers send notifications/tools/list_changed notifications. This callback will be passed to all new clients created by the manager.
func (*Manager) SetUserLoggedOut ¶
SetUserLoggedOut marks a server as explicitly logged out by the user. This prevents automatic reconnection until the user explicitly logs in again.
func (*Manager) ShutdownAll ¶
ShutdownAll disconnects all clients and ensures all Docker containers are stopped This should be called during application shutdown to ensure clean exit
func (*Manager) StartManualOAuth ¶
StartManualOAuth performs an in-process OAuth flow for the given server. This avoids cross-process DB locking by using the daemon's storage directly.
func (*Manager) StartManualOAuthQuick ¶
func (m *Manager) StartManualOAuthQuick(serverName string) (*core.OAuthStartResult, error)
StartManualOAuthQuick starts OAuth and returns browser status immediately. Unlike StartManualOAuth (fully async, no result) or StartManualOAuthWithInfo (fully sync, blocks), this returns browser status quickly but continues the OAuth callback handling in background.
This is the recommended method for API endpoints that need to return browser_opened status.
func (*Manager) StartManualOAuthWithInfo ¶
func (m *Manager) StartManualOAuthWithInfo(serverName string, force bool) (*core.OAuthStartResult, error)
StartManualOAuthWithInfo performs an in-process OAuth flow and returns the auth URL and browser status. This is used by Phase 3 (Spec 020) to return structured information about the OAuth flow start. Unlike StartManualOAuth, this method waits for the auth URL to be obtained before returning.
func (*Manager) UsesDockerIsolation ¶ added in v0.32.0
UsesDockerIsolation reports whether this manager could have launched Docker containers (a global or per-server isolation mode that resolves to docker, or a server whose own command is docker). When false, no container cleanup verification is needed on shutdown — shelling out to `docker ps` would be pure waste (and, in test processes, adds ~17s/Close via the verification loop). Same predicate the Docker recovery monitor uses, so behavior stays consistent.
func (*Manager) WithCurrentClientOnEpoch ¶ added in v0.70.0
func (m *Manager) WithCurrentClientOnEpoch(id string, expected *managed.Client, expectedEpoch int64, fn func() error) (current bool, err error)
WithCurrentClientOnEpoch runs fn only while id still names expected and that exact client remains on expectedEpoch. captureMu makes the pointer check and fn one linearization region with AddServerConfig/RemoveServer (which need its writer lock to replace the entry); the managed-client epoch lock keeps a same-pointer reconnect from changing its connection identity in the middle of fn. fn must be bounded and must not initiate a connection change, because those transitions wait for the locks held here.
type Notification ¶
type Notification struct {
Level NotificationLevel `json:"level"`
Title string `json:"title"`
Message string `json:"message"`
ServerName string `json:"server_name,omitempty"`
Timestamp time.Time `json:"timestamp"`
}
Notification represents a notification to be sent to the UI
type NotificationHandler ¶
type NotificationHandler interface {
SendNotification(notification *Notification)
}
NotificationHandler defines the interface for handling notifications
type NotificationLevel ¶
type NotificationLevel int
NotificationLevel represents the level of a notification
const ( NotificationInfo NotificationLevel = iota NotificationWarning NotificationError )
func (NotificationLevel) String ¶
func (l NotificationLevel) String() string
String returns the string representation of the notification level
type NotificationManager ¶
type NotificationManager struct {
// contains filtered or unexported fields
}
NotificationManager manages notification handlers and provides convenience methods
func NewNotificationManager ¶
func NewNotificationManager() *NotificationManager
NewNotificationManager creates a new notification manager
func (*NotificationManager) AddHandler ¶
func (nm *NotificationManager) AddHandler(handler NotificationHandler)
AddHandler adds a notification handler
func (*NotificationManager) NotifyOAuthRequired ¶
func (nm *NotificationManager) NotifyOAuthRequired(serverName string)
NotifyOAuthRequired sends a notification when OAuth authentication is required
func (*NotificationManager) NotifyServerConnected ¶
func (nm *NotificationManager) NotifyServerConnected(serverName string)
NotifyServerConnected sends a notification when a server connects
func (*NotificationManager) NotifyServerConnecting ¶
func (nm *NotificationManager) NotifyServerConnecting(serverName string)
NotifyServerConnecting sends a notification when a server starts connecting
func (*NotificationManager) NotifyServerDisconnected ¶
func (nm *NotificationManager) NotifyServerDisconnected(serverName string, reason error)
NotifyServerDisconnected sends a notification when a server disconnects
func (*NotificationManager) NotifyServerError ¶
func (nm *NotificationManager) NotifyServerError(serverName string, err error)
NotifyServerError sends a notification when a server encounters an error
func (*NotificationManager) SendNotification ¶
func (nm *NotificationManager) SendNotification(notification *Notification)
SendNotification sends a notification to all registered handlers
type ReconnectResult ¶
type ReconnectResult struct {
TotalServers int
AttemptedServers int
SuccessfulServers []string
FailedServers map[string]error
SkippedServers map[string]string // server name -> skip reason
}
ReconnectResult tracks the results of a ForceReconnectAll operation
type StatefulClient ¶
type StatefulClient interface {
MCPClient
// State management
GetState() types.ConnectionState
IsConnecting() bool
// Advanced connection management
ShouldRetry() bool
SetStateChangeCallback(callback func(oldState, newState types.ConnectionState, info *types.ConnectionInfo))
// Tool count optimization
GetCachedToolCount(ctx context.Context) (int, error)
}
StatefulClient extends MCPClient with state management capabilities
type TransportClient ¶
type TransportClient interface {
// Transport-specific connection
ConnectWithTransport(ctx context.Context, transportType string) error
// Access to underlying transport details
GetTransportType() string
GetStderr() io.Reader // For stdio transport
}
TransportClient defines transport-specific client creation
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package launcher manages locally-spawned upstream processes that expose their MCP endpoint over HTTP / SSE / streamable-HTTP transports.
|
Package launcher manages locally-spawned upstream processes that expose their MCP endpoint over HTTP / SSE / streamable-HTTP transports. |
|
Package limiter implements the bounded-concurrency admission control used by the upstream tool-call choke point (spec 093, GH #955).
|
Package limiter implements the bounded-concurrency admission control used by the upstream tool-call choke point (spec 093, GH #955). |