Documentation
¶
Index ¶
- Constants
- Variables
- func ContainerOwnedByAny(serverNames []string, containerName, ownerLabel, instanceLabel string) bool
- func GetInstanceID() string
- func IsNetworkError(err error) bool
- func IsOAuthPending(err error) bool
- func IsSpeculativeOAuthPending(err error) bool
- func IsUnresolvedSecretError(err error) bool
- func RunDispatchRecheck(ctx context.Context) error
- func SetBrowserStartForTest(fn func(*exec.Cmd) error) (restore func())
- func SetDockerBinaryResolverForTest(fn func(*zap.Logger) (string, error)) (restore func())
- func SetInstanceDataDir(dir string)
- func SetLaunchObserverForTest(fn func(server, kind string)) (restore func())
- func SetStdioLaunchHookForTest(fn func()) (restore func())
- func WithConnectionGeneration(ctx context.Context, epoch int64) context.Context
- func WithDispatchRecheck(ctx context.Context, check func() error) context.Context
- func WithSessionGeneration(ctx context.Context, gen uint64) context.Context
- type Client
- func (c *Client) AuthStrategy() string
- func (c *Client) CallTool(ctx context.Context, toolName string, args map[string]interface{}) (*mcp.CallToolResult, error)
- func (c *Client) CheckConnectionHealth(ctx context.Context) error
- func (c *Client) CheckManualLoginAllowed() error
- func (c *Client) ClearOAuthState()
- func (c *Client) ClearRetryAfter()
- func (c *Client) Connect(ctx context.Context) error
- func (c *Client) CredentialBinding() commitview.CredentialBinding
- func (c *Client) Disconnect() error
- func (c *Client) DisconnectWithContext(_ context.Context) error
- func (c *Client) ForceOAuthFlow(ctx context.Context) error
- func (c *Client) ForceOAuthFlowWithResult(ctx context.Context) (*OAuthStartResult, error)
- func (c *Client) ForceRemoveTrackedContainerIfOwned(ctx context.Context, containerID string) (owner string, owned bool, err error)
- func (c *Client) Gate() *dialgate.Gate
- func (c *Client) GetConfig() *config.ServerConfig
- func (c *Client) GetConnectionDiagnostics() map[string]interface{}
- func (c *Client) GetConnectionInfo() types.ConnectionInfo
- func (c *Client) GetContainerID() string
- func (c *Client) GetEnvManager() interface{}
- func (c *Client) GetOAuthHandler() *transport.OAuthHandler
- func (c *Client) GetPrompt(ctx context.Context, name string, args map[string]string) (*mcp.GetPromptResult, error)
- func (c *Client) GetServerInfo() *mcp.InitializeResult
- func (c *Client) GetSkill(ctx context.Context, uri string) (skills.Entry, error)
- func (c *Client) GetStderr() io.Reader
- func (c *Client) GetTransportType() string
- func (c *Client) IsConnected() bool
- func (c *Client) ListPrompts(ctx context.Context) ([]mcp.Prompt, error)
- func (c *Client) ListSkills(ctx context.Context) (entries []skills.Entry, entryErrs []skills.EntryError, err error)
- func (c *Client) ListTools(ctx context.Context) ([]*config.ToolMetadata, error)
- func (c *Client) Ping(ctx context.Context) error
- func (c *Client) ReadSkillFile(ctx context.Context, ref skills.FileRef) (content []byte, isText bool, mimeType string, err error)
- func (c *Client) RecentStderrSnapshot() []string
- func (c *Client) RefreshOAuthTokenDirect(ctx context.Context) error
- func (c *Client) ReinitializeSession(ctx context.Context) error
- func (c *Client) Retire()
- func (c *Client) Retired() bool
- func (c *Client) RetryAfterDeadline() time.Time
- func (c *Client) SessionGeneration() uint64
- func (c *Client) SessionSnapshot() (id string, modern bool)
- func (c *Client) SetCredentialBinding(b commitview.CredentialBinding)
- func (c *Client) SetExposePrompts(exposePrompts *bool)
- func (c *Client) SetExposeSkills(expose *bool)
- func (c *Client) SetForwardPolicyProvider(p func() headerfwd.Policy)
- func (c *Client) SetGate(g *dialgate.Gate)
- func (c *Client) SetOnPromptsChangedCallback(callback func(serverName string))
- func (c *Client) SetOnToolsChangedCallback(callback func(serverName string))
- func (c *Client) StartOAuthFlowQuick(ctx context.Context) (*OAuthStartResult, error)
- func (c *Client) StartProcessMonitoring()
- func (c *Client) StartStderrMonitoring()
- func (c *Client) StopProcessMonitoring()
- func (c *Client) StopStderrMonitoring()
- func (c *Client) SupportsSkills() bool
- func (c *Client) UnresolvedSecrets() error
- type ContainerLock
- type ContainerMutation
- type ContainerMutator
- type ContainerRow
- type DockerCommand
- type ErrOAuthPending
- type IsolationManager
- func (im *IsolationManager) BuildDockerArgs(serverConfig *config.ServerConfig, runtimeType string) ([]string, error)
- func (im *IsolationManager) DetectRuntimeType(command string) string
- func (im *IsolationManager) GetDockerImage(serverConfig *config.ServerConfig, runtimeType string) (string, error)
- func (im *IsolationManager) GetDockerIsolationWarning(serverConfig *config.ServerConfig) string
- func (im *IsolationManager) HasLocalFilePath(serverConfig *config.ServerConfig) bool
- func (im *IsolationManager) ResolveDefaults(serverConfig *config.ServerConfig) *ResolvedIsolationDefaults
- func (im *IsolationManager) ResolveIsolation(serverConfig *config.ServerConfig) ResolvedIsolation
- func (im *IsolationManager) ResolveMode(serverConfig *config.ServerConfig) config.IsolationMode
- func (im *IsolationManager) ResolveScannerMode(serverConfig *config.ServerConfig) (config.IsolationMode, string)
- func (im *IsolationManager) SetLogger(logger *zap.Logger)
- func (im *IsolationManager) ShouldIsolate(serverConfig *config.ServerConfig) bool
- func (im *IsolationManager) TransformCommandForContainer(command string, args []string, runtimeType string) (containerCommand string, containerArgs []string)
- type MutationResult
- type OAuthParameterError
- type OAuthStartResult
- type ProcessGroup
- type ResolvedIsolation
- type ResolvedIsolationDefaults
- type UnresolvedSecretError
- type UnresolvedSecretRef
Constants ¶
const AuthStrategyOAuth = "OAuth"
AuthStrategyOAuth is the name of the OAuth auth strategy as recorded by AuthStrategy. The other strategies ("headers", "no-auth") are internal; only OAuth is something a consumer needs to recognise, because it is the one strategy whose credential lives in the oauth_tokens bucket (GH #1172).
Variables ¶
var ErrDispatchRecheckRefused = errors.New("dispatch refused by the pre-transport re-check")
ErrDispatchRecheckRefused marks a call that a WithDispatchRecheck check refused immediately before the transport. Nothing was sent upstream. The check's own error is wrapped alongside it, so callers can errors.Is on either. managed.ErrDispatchRecheckRefused is this same value.
var ErrSessionChanged = errors.New("upstream session was re-initialized before the request was sent")
ErrSessionChanged is returned, with nothing sent, by a request whose context was pinned to a session generation (WithSessionGeneration) when a session re-initialize ran after the pin was taken. The caller re-validates what it checked against the old session and sends again.
Functions ¶
func ContainerOwnedByAny ¶ added in v0.68.0
func ContainerOwnedByAny(serverNames []string, containerName, ownerLabel, instanceLabel string) bool
ContainerOwnedByAny is the whole-manager predicate: a container (its name, its com.mcpproxy.server label and its com.mcpproxy.instance label as Docker reported them) is canonically owned by one of serverNames — the configured servers, on THIS mcpproxy instance — under the same label-AND-name-AND-instance rule ownsContainer applies per server. The manager's shutdown and emergency sweeps select containers by the shared com.mcpproxy.managed / com.mcpproxy.instance labels, which any foreign container can copy; only the rows this admits may be stopped, removed or named (codex round 3). Requiring the instance label here too (not just in the sweep's own Docker filter) closes the gap where a sweep that filtered broadly, or a caller re-verifying a single tracked id with no filter at all, would otherwise admit another live mcpproxy instance's container for a same-named server.
func GetInstanceID ¶
func GetInstanceID() string
GetInstanceID returns the unique identifier for this mcpproxy instance (exported for use by manager)
func IsNetworkError ¶ added in v0.71.0
IsNetworkError reports whether err is (or wraps) a transport-level failure that says nothing about authentication: a DNS lookup, dial, reset or timeout.
GH #1537: the auth ladder and the managed client classify failures by substring, and both match a bare "401"/"403". Go's net errors quote addresses and ephemeral ports ("read udp 192.168.1.20:54012->…:53: i/o timeout", "dial tcp 127.0.0.1:14010"), so a DNS failure during a network outage could read as an OAuth challenge and push a no-auth server into the OAuth strategy — where an empty token store parks it in Pending Auth for good. A typed check runs first so the address text is never consulted.
A *url.Error in the chain means http.Client.Do failed before any response arrived (TLS verification, a connection closed with EOF, an HTTP/2 GOAWAY): whatever it is, no server asked for credentials, and the URL it quotes is exactly the text the substring classifiers must not see.
A typed HTTP 401 from mcp-go always wins: it is a real challenge, even when it arrives wrapped together with other error text.
func IsOAuthPending ¶
IsOAuthPending checks if an error is (or wraps) an ErrOAuthPending.
It MUST unwrap: the pending error is raised inside an auth strategy and then wrapped twice on its way out — connectHTTP/connectSSE add "all authentication strategies failed, last error: %w" and Connect adds "failed to connect: %w". With a bare type assertion the check therefore never fired in production, and every login-blocked server fell through to the generic error path and was re-dialed instead of parked (#1013).
func IsSpeculativeOAuthPending ¶ added in v0.71.0
IsSpeculativeOAuthPending reports whether err wraps an ErrOAuthPending whose requirement was never confirmed by the upstream (ErrOAuthPending.Probe).
func IsUnresolvedSecretError ¶ added in v0.74.0
IsUnresolvedSecretError reports whether err carries an UnresolvedSecretError.
func RunDispatchRecheck ¶ added in v0.71.0
RunDispatchRecheck runs ctx's attached checks; nil when there are none or all pass.
func SetBrowserStartForTest ¶ added in v0.71.0
SetBrowserStartForTest makes the OAuth browser launch call fn instead of starting a browser, and returns a restore func. Test-only.
func SetDockerBinaryResolverForTest ¶ added in v0.71.0
SetDockerBinaryResolverForTest points the docker spawn at fn's binary (a mock docker in the Spec 116 PR4 launch-admission tests) and returns a restore func. Test-only.
func SetInstanceDataDir ¶ added in v0.68.0
func SetInstanceDataDir(dir string)
SetInstanceDataDir records the data directory this process's instance ID should be persisted under (normally cfg.DataDir). Call it once at startup, before the first GetInstanceID() call — e.g. from upstream.NewManager, which every entry point constructs early with the loaded config.
Concurrent mcpproxy processes on the same host must already use distinct data directories (BBolt takes an exclusive lock on config.db), so keying the instance ID off the data dir rather than a single shared file under os.TempDir() gives each process a genuinely distinct ID. A call after the ID has already been resolved, or no call at all, has no effect beyond that first read: GetInstanceID() then falls back to a fresh id for the process's lifetime instead of reusing a host-wide file.
func SetLaunchObserverForTest ¶ added in v0.71.0
func SetLaunchObserverForTest(fn func(server, kind string)) (restore func())
SetLaunchObserverForTest installs the launch observer and returns a restore func. Test-only.
func SetStdioLaunchHookForTest ¶ added in v0.71.0
func SetStdioLaunchHookForTest(fn func()) (restore func())
SetStdioLaunchHookForTest installs the stdio launch-section test seam (T4.11) and returns a restore func. Test-only.
func WithConnectionGeneration ¶ added in v0.71.0
WithConnectionGeneration records the managed client's connection epoch on ctx so core can attach it to structured tool-call timeout/cancel logs.
func WithDispatchRecheck ¶ added in v0.71.0
WithDispatchRecheck attaches check to ctx. The attached checks run at every point a call may have waited after its gate read a policy verdict — the managed layer's admission-control queue, and Client.CallTool once it holds the SSE request lock, immediately before the request is handed to the transport — so a verdict such as Spec 117 FR-018's review-dirty mark is re-read for a call that was parked while it changed. A non-nil error refuses the call with ErrDispatchRecheckRefused and zero transport calls. Checks attached by nested contexts all run, innermost first.
func WithSessionGeneration ¶ added in v0.71.0
WithSessionGeneration pins the requests made with ctx to session generation gen (from SessionGeneration): such a request is refused with ErrSessionChanged, before anything is sent, if a session re-initialize has run since. The managed layer pins tools/call this way so a call checked against one session's toolset is never sent on a session whose toolset has not been verified yet.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client implements basic MCP client functionality without state management
func NewClient ¶
func NewClient(id string, serverConfig *config.ServerConfig, logger *zap.Logger, logConfig *config.LogConfig, globalConfig *config.Config, storage *storage.BoltDB, secretResolver *secret.Resolver) (*Client, error)
NewClient creates a new core MCP client
func NewClientWithOptions ¶
func NewClientWithOptions(id string, serverConfig *config.ServerConfig, logger *zap.Logger, logConfig *config.LogConfig, globalConfig *config.Config, storage *storage.BoltDB, cliDebugMode bool, secretResolver *secret.Resolver) (*Client, error)
NewClientWithOptions creates a new core MCP client with additional options
func (*Client) AuthStrategy ¶ added in v0.66.0
AuthStrategy reports the name of the auth strategy the CURRENT connection was established with ("headers", "no-auth" or AuthStrategyOAuth), or "" when the client is not connected over HTTP/SSE. It is a fact about the live connection, not the config: a server with a stored OAuth token that connected through its static headers did not use that token.
func (*Client) CallTool ¶
func (c *Client) CallTool(ctx context.Context, toolName string, args map[string]interface{}) (*mcp.CallToolResult, error)
CallTool executes a tool on the upstream server
Spec 112: this is the ONLY place that derives the per-server outbound set of forwarded client headers (from the edge snapshot in ctx, key A) and puts it on the context handed to mcp-go (key B). Every other request (initialize, list, reconnect) never sets key B and so cannot forward.
func (*Client) CheckConnectionHealth ¶
CheckConnectionHealth performs a health check on the connection
func (*Client) CheckManualLoginAllowed ¶ added in v0.74.0
CheckManualLoginAllowed runs the manual-login guard for callers that start the login asynchronously (upstream.Manager.StartManualOAuth): it returns the coded MCPX_OAUTH_TOKEN_UNDECRYPTABLE error while the stored OAuth row cannot be decrypted, before any goroutine, discovery or callback server exists.
func (*Client) ClearOAuthState ¶
func (c *Client) ClearOAuthState()
ClearOAuthState clears OAuth state (public API for manual OAuth flows)
func (*Client) ClearRetryAfter ¶ added in v0.61.0
func (c *Client) ClearRetryAfter()
ClearRetryAfter drops any recorded rate-limit hint. Called once a connection succeeds so a hint observed by an auth strategy that was superseded by a working one cannot hold back a later, unrelated reconnect.
func (*Client) CredentialBinding ¶ added in v0.71.0
func (c *Client) CredentialBinding() commitview.CredentialBinding
CredentialBinding returns the instance's credential binding (zero: unbound, the CLI and hand-built test clients).
func (*Client) DisconnectWithContext ¶
DisconnectWithContext closes the connection with context timeout
func (*Client) ForceOAuthFlow ¶
ForceOAuthFlow forces an OAuth authentication flow, bypassing rate limiting (for manual auth)
func (*Client) ForceOAuthFlowWithResult ¶
func (c *Client) ForceOAuthFlowWithResult(ctx context.Context) (*OAuthStartResult, error)
ForceOAuthFlowWithResult forces an OAuth authentication flow and returns the auth URL and browser status. This is used by Phase 3 (Spec 020) to provide the auth URL to clients even when browser opens successfully.
func (*Client) ForceRemoveTrackedContainerIfOwned ¶ added in v0.68.0
func (c *Client) ForceRemoveTrackedContainerIfOwned(ctx context.Context, containerID string) (owner string, owned bool, err error)
ForceRemoveTrackedContainerIfOwned is the manager's emergency path for a client whose Disconnect hung: `docker rm -f` the container tracked as containerID, but only after re-establishing canonical ownership NOW — the same ContainerMutator every mutation goes through — so a container renamed, relabelled or reused under that id since it was tracked is left alone (codex round 3). owned reports whether the predicate admitted the container (removal was attempted) and owner is then the com.mcpproxy.server label read back at that moment — the evidence the caller's own records must carry when they name the container (D8, codex round 5); err is the docker error when removal ran and failed, or the lookup error. Records carry container_owner from the label read back; an unowned container is never named in the per-server log.
func (*Client) GetConfig ¶ added in v0.17.3
func (c *Client) GetConfig() *config.ServerConfig
GetConfig returns the server configuration
func (*Client) GetConnectionDiagnostics ¶
GetConnectionDiagnostics returns detailed diagnostic information about the connection
func (*Client) GetConnectionInfo ¶
func (c *Client) GetConnectionInfo() types.ConnectionInfo
GetConnectionInfo returns basic connection information
func (*Client) GetContainerID ¶
GetContainerID returns the Docker container ID if this is a Docker-based server
func (*Client) GetEnvManager ¶
func (c *Client) GetEnvManager() interface{}
GetEnvManager returns the environment manager for testing purposes
func (*Client) GetOAuthHandler ¶ added in v0.17.3
func (c *Client) GetOAuthHandler() *transport.OAuthHandler
GetOAuthHandler returns the OAuth handler if the transport supports OAuth. Returns nil if no OAuth handler is configured or transport doesn't support OAuth.
func (*Client) GetPrompt ¶ added in v0.59.0
func (c *Client) GetPrompt(ctx context.Context, name string, args map[string]string) (*mcp.GetPromptResult, error)
GetPrompt resolves a single prompt by its unqualified name on the upstream server.
func (*Client) GetServerInfo ¶
func (c *Client) GetServerInfo() *mcp.InitializeResult
GetServerInfo returns server information from initialization
func (*Client) GetTransportType ¶
GetTransportType returns the transport type being used
func (*Client) IsConnected ¶
IsConnected returns whether the client is currently connected
func (*Client) ListPrompts ¶ added in v0.59.0
ListPrompts returns the prompts advertised by the upstream server. It returns (nil, nil) — not an error — when the server doesn't advertise Capabilities.Prompts, or when this server's config has explicitly opted out via ExposePrompts: false.
func (*Client) ListSkills ¶ added in v0.74.0
func (c *Client) ListSkills(ctx context.Context) (entries []skills.Entry, entryErrs []skills.EntryError, err error)
ListSkills pages skills/list. It returns nothing, and sends nothing, when the server does not announce skills or expose_skills is false. A bound that cuts the listing short comes back as a *skills.TruncatedError next to the partial entries; it is never swallowed.
func (*Client) Ping ¶ added in v0.38.0
Ping issues the MCP-standard lightweight liveness check (`ping`) to the upstream server. It is used by the managed client's health loop as a cheap replacement for re-listing every tool just to confirm the connection is alive (spec 074, FR-001). Returns an error if the client is not connected or the request fails so the caller can classify and drive reconnection.
func (*Client) ReadSkillFile ¶ added in v0.74.0
func (c *Client) ReadSkillFile(ctx context.Context, ref skills.FileRef) (content []byte, isText bool, mimeType string, err error)
ReadSkillFile reads one listed file with resources/read. The caller verifies the digest (skills.VerifyFile); the length is checked here, before any hashing, so a response that disagrees with its listing is refused cheaply.
func (*Client) RecentStderrSnapshot ¶ added in v0.24.8
RecentStderrSnapshot returns a copy of the recent stderr lines captured from the child process. Returns nil if nothing has been captured yet.
func (*Client) RefreshOAuthTokenDirect ¶ added in v0.17.3
RefreshOAuthTokenDirect forces an OAuth token refresh without reconnecting. This is used by the RefreshManager for proactive token refresh. Unlike ForceReconnect (which returns early when already connected), this refreshes even a still-valid token.
Spec 113 FR-001: the refresh runs as a flight of the process-wide oauth.RefreshCoordinator, shared with the reactive path of the token store handed to mcp-go, so one expiry causes at most one token request. The flight uses the same refresh function as the reactive path (oauthRefreshFunc): mcp-go's handler.RefreshToken when the live handler has a client id, else the stored DCR credentials.
func (*Client) ReinitializeSession ¶ added in v0.71.0
ReinitializeSession performs a fresh initialize + notifications/initialized handshake on the existing mcp-go client and transport, so the upstream issues a new session id. It does not Close/Start the transport and does not change the connection generation. The legacy-era pin (Spec 058 FR-027) applies exactly as on the first handshake.
func (*Client) Retire ¶ added in v0.71.0
func (c *Client) Retire()
Retire closes the instance's gate (FR-022): from its return, the client launches nothing, dials nothing and writes nothing. The upstream manager calls it, through the managed client, when it unregisters the instance. Teardown (Disconnect: the MCP close, the process-group kill, `docker stop`) is not gated and still runs afterwards.
func (*Client) RetryAfterDeadline ¶ added in v0.61.0
RetryAfterDeadline reports the instant before which this upstream asked us not to come back (from a `Retry-After` on a 429/503), or the zero time when it gave no such hint. The managed client stamps it onto the state machine so both reconnect gates honour it (#1040).
func (*Client) SessionGeneration ¶ added in v0.71.0
SessionGeneration counts the session re-initializes run on this client. It changes while ReinitializeSession holds the session gate exclusively, so a request admitted to the gate sees a stable value for its whole send.
func (*Client) SessionSnapshot ¶ added in v0.71.0
SessionSnapshot reports the Streamable HTTP transport's current session id (empty when the transport has none, e.g. mcp-go cleared it after a 404, or when the transport is stdio/SSE) and whether the negotiated protocol is the stateless 2026-07-28 era, where sessions do not exist and no re-init applies.
func (*Client) SetCredentialBinding ¶ added in v0.71.0
func (c *Client) SetCredentialBinding(b commitview.CredentialBinding)
SetCredentialBinding binds the instance's OAuth state to b, the committed credential binding of the view it was built for (Spec 116 PR2b, #1607). The upstream manager sets it before the instance becomes reachable, and on the transient clients of a manual OAuth flow (the registered instance's binding), so every token, client registration and completion record the instance writes, reads or clears is bound to it. Call it before the client is used.
func (*Client) SetExposePrompts ¶ added in v0.59.0
SetExposePrompts updates the ExposePrompts override without requiring a reconnect (PR #973 review, P2). Call this whenever the owning managed.Client's config is refreshed so a hot-reloaded expose_prompts value takes effect immediately instead of only after the connection is torn down and recreated.
func (*Client) SetExposeSkills ¶ added in v0.74.0
SetExposeSkills pushes the per-server expose_skills value to a running connection, like SetExposePrompts. nil means "not set" (exposed).
func (*Client) SetForwardPolicyProvider ¶ added in v0.70.0
SetForwardPolicyProvider installs the live forwarding policy provider (Spec 112). It is read on every CallTool, so it takes effect immediately and never forces a reconnect. Passing nil removes forwarding.
func (*Client) SetGate ¶ added in v0.71.0
SetGate makes this client share g. The upstream manager uses it for the transient clients of a manual OAuth flow, so retiring the registered instance also stops the login it started (FR-024). Call it before the client is used.
func (*Client) SetOnPromptsChangedCallback ¶ added in v0.59.0
SetOnPromptsChangedCallback sets the callback invoked when a notifications/prompts/list_changed notification is received from the upstream MCP server (F13). Enables reactive re-aggregation of upstream prompts.
func (*Client) SetOnToolsChangedCallback ¶
SetOnToolsChangedCallback sets the callback invoked when a notifications/tools/list_changed notification is received from the upstream MCP server. This enables reactive tool re-indexing.
func (*Client) StartOAuthFlowQuick ¶
func (c *Client) StartOAuthFlowQuick(ctx context.Context) (*OAuthStartResult, error)
StartOAuthFlowQuick starts the OAuth flow and returns browser status immediately. Unlike ForceOAuthFlowWithResult which blocks until OAuth completes, this function: 1. Gets authorization URL synchronously (quick operation) 2. Checks HEADLESS environment variable 3. Attempts browser open and captures result 4. Returns OAuthStartResult immediately 5. Continues OAuth callback handling in a goroutine
This is used by the login API endpoint to return accurate browser_opened status without blocking the HTTP response for the full OAuth flow.
func (*Client) StartProcessMonitoring ¶
func (c *Client) StartProcessMonitoring()
StartProcessMonitoring starts monitoring the underlying process
func (*Client) StartStderrMonitoring ¶
func (c *Client) StartStderrMonitoring()
StartStderrMonitoring starts monitoring stderr output and logging it
func (*Client) StopProcessMonitoring ¶
func (c *Client) StopProcessMonitoring()
StopProcessMonitoring stops process monitoring
func (*Client) StopStderrMonitoring ¶
func (c *Client) StopStderrMonitoring()
StopStderrMonitoring stops stderr monitoring
func (*Client) SupportsSkills ¶ added in v0.74.0
SupportsSkills reports whether the upstream announced the skills extension. The extension requires the resources capability too, so one without the other is not enough.
func (*Client) UnresolvedSecrets ¶ added in v0.74.0
UnresolvedSecrets returns the refusal for unresolved secret references in the fields sent to the upstream, or nil.
type ContainerLock ¶
type ContainerLock struct {
// contains filtered or unexported fields
}
ContainerLock provides per-server locking for container creation This prevents race conditions where multiple goroutines try to create containers for the same server simultaneously (e.g., during ForceReconnectAll)
type ContainerMutation ¶ added in v0.68.0
type ContainerMutation string
ContainerMutation is one of the docker commands that change a container's state.
const ( ContainerStop ContainerMutation = "stop" ContainerKill ContainerMutation = "kill" ContainerRemove ContainerMutation = "rm" // run as `docker rm -f` )
type ContainerMutator ¶ added in v0.68.0
type ContainerMutator struct {
Docker DockerCommand
Owns func(containerName, ownerLabel, instanceLabel string) bool
}
ContainerMutator is the one verify-then-mutate implementation every Docker mutation goes through — the core client's cleanup paths and the manager's sweeps alike (Spec 105 FR-007 / D9, codex round 6). Docker runs the CLI; Owns is the ownership predicate over the name and label read back (ownsContainer for one server, ContainerOwnedByAny for the manager).
func (ContainerMutator) Mutate ¶ added in v0.68.0
func (cm ContainerMutator) Mutate(ctx context.Context, id string, op ContainerMutation, intent func(ContainerRow)) MutationResult
Mutate re-reads container id immediately before running op on it and runs it only if the row read back has exactly that full id and satisfies Owns. intent, when set, is called with that row right before the command so the caller can record what is about to happen with mutation-time evidence.
func (ContainerMutator) Verify ¶ added in v0.68.0
func (cm ContainerMutator) Verify(ctx context.Context, id string) (ContainerRow, bool, error)
Verify re-reads container id and reports whether it still satisfies Owns right now — the same read+predicate Mutate applies before running a command, exposed for a caller that only needs to confirm ownership without mutating anything (e.g. a health check re-establishing ownership before trusting `docker inspect`, codex round 8). ok is true only when the read succeeded and the row's label and name pass Owns; row is the meaningful evidence — id, name and owner label as Docker reported them — only when ok is true.
type ContainerRow ¶ added in v0.68.0
ContainerRow is a container's identity AND running state as Docker reported them in one read: full id, name, com.mcpproxy.server label value and `docker ps`'s own human status text (e.g. "Up 5 minutes", "Exited (0) 2 minutes ago", "Up 5 minutes (Paused)"). Status, not just identity, comes from this same read (codex round 16 finding 1): a caller that re-read state with a SEPARATE `docker inspect <id>` after Verify trusted whatever container held that id at the LATER moment, which another Docker client can have relabelled or renamed in between.
func (ContainerRow) Running ¶ added in v0.68.0
func (r ContainerRow) Running() bool
Running reports whether the container was up — running or paused, exactly `docker inspect`'s State.Running — at the read that produced this row. `docker ps --format` has no `.Running` boolean field (verified against a live daemon: only `.State`, the short State.Status word, and `.Status`, the human text `docker ps` prints in its STATUS column); `.State` is State.Status, not State.Running, so a paused container (State.Status "paused", State.Running true) would misreport as not running through it. Docker's own convention for that STATUS text prefixes "Up" precisely when State.Running is true — including while paused ("Up 5 minutes (Paused)") — so Status carries the same information State.Running would, without a second command.
type DockerCommand ¶ added in v0.68.0
DockerCommand builds one docker invocation: the core client resolves the binary through newDockerCmd, the manager execs the bare name.
type ErrOAuthPending ¶
type ErrOAuthPending struct {
ServerName string
ServerURL string
Message string
// Probe marks a speculative park (GH #1537): no oauth block, no stored
// token, and the anonymous attempt never received an HTTP 401. The
// managed client records it so the reconnect loop re-tries the server
// periodically rather than waiting forever for a sign-in it may not need.
Probe bool
}
ErrOAuthPending represents a deferred OAuth authentication requirement. This error indicates that OAuth is required but has been intentionally deferred (e.g., for user action via tray UI or CLI) rather than being a connection failure.
func (*ErrOAuthPending) Code ¶ added in v0.39.0
func (e *ErrOAuthPending) Code() diagnostics.Code
Code attributes a stable diagnostic code so diagnostics.Classify's typed fast-path resolves this to an actionable OAuth user-state instead of MCPX_UNKNOWN_UNCLASSIFIED. A first-time sign-in maps to OAuthLoginRequired; the "stored token broke" variant (connection_oauth.go server-5xx path) maps to OAuthReauthRequired. The distinction is carried in the message text so the stringified error classifies the same way downstream (e.g. health). MCP-1820.
func (*ErrOAuthPending) Error ¶
func (e *ErrOAuthPending) Error() string
type IsolationManager ¶
type IsolationManager struct {
// contains filtered or unexported fields
}
IsolationManager handles Docker isolation logic for MCP servers
func NewIsolationManager ¶
func NewIsolationManager(globalConfig *config.DockerIsolationConfig) *IsolationManager
NewIsolationManager creates a new isolation manager.
func NewIsolationManagerWithLogger ¶ added in v0.24.7
func NewIsolationManagerWithLogger(globalConfig *config.DockerIsolationConfig, logger *zap.Logger) *IsolationManager
NewIsolationManagerWithLogger creates a new isolation manager with a structured logger. The logger is optional — when nil, warnings about ignored per-server isolation opt-ins are silently dropped (callers that care about those warnings should pass a logger).
func (*IsolationManager) BuildDockerArgs ¶
func (im *IsolationManager) BuildDockerArgs(serverConfig *config.ServerConfig, runtimeType string) ([]string, error)
BuildDockerArgs constructs Docker run arguments for isolation
func (*IsolationManager) DetectRuntimeType ¶
func (im *IsolationManager) DetectRuntimeType(command string) string
DetectRuntimeType detects the runtime type based on the command
func (*IsolationManager) GetDockerImage ¶
func (im *IsolationManager) GetDockerImage(serverConfig *config.ServerConfig, runtimeType string) (string, error)
GetDockerImage returns the appropriate Docker image for a server.
Resolution order:
- the per-server `isolation.image` override — an explicit user choice always wins;
- the git-capable image, when the server is a Python package runner installing from a git URL AND nothing in `default_images` has been retargeted at the operator's own registry (#1143 — see resolveDefaultImage, which explains why a mirrored install keeps its own image instead);
- the runtime type's entry in `default_images`;
- alpine, for unknown runtime types.
func (*IsolationManager) GetDockerIsolationWarning ¶
func (im *IsolationManager) GetDockerIsolationWarning(serverConfig *config.ServerConfig) string
GetDockerIsolationWarning returns a warning message if Docker isolation is enabled with local files
func (*IsolationManager) HasLocalFilePath ¶
func (im *IsolationManager) HasLocalFilePath(serverConfig *config.ServerConfig) bool
HasLocalFilePath checks if server arguments contain local file paths
func (*IsolationManager) ResolveDefaults ¶ added in v0.26.0
func (im *IsolationManager) ResolveDefaults(serverConfig *config.ServerConfig) *ResolvedIsolationDefaults
ResolveDefaults returns the resolved default isolation values for the given server, computed from the detected runtime type and global DockerIsolationConfig — without applying any per-server overrides.
This intentionally does NOT short-circuit when isolation is disabled for the server: the result describes what would be used if isolation were active, which is what UI placeholders need to surface.
Returns nil if the global config is missing (degenerate state).
func (*IsolationManager) ResolveIsolation ¶ added in v0.64.0
func (im *IsolationManager) ResolveIsolation(serverConfig *config.ServerConfig) ResolvedIsolation
ResolveIsolation resolves the effective isolation state for a server — the single source of truth for "is this server isolated" (GH #1142). The algorithm lives in config.ResolveIsolation so every reporting surface runs the same code; this wrapper adds the deduplicated warning for a per-server opt-in that the global setting is ignoring.
func (*IsolationManager) ResolveMode ¶ added in v0.46.0
func (im *IsolationManager) ResolveMode(serverConfig *config.ServerConfig) config.IsolationMode
ResolveMode resolves the effective isolation mode for a server (MCP-34.2) — the mode-only view of ResolveIsolation. See config.ResolveIsolation for the precedence rules and the structural gates.
func (*IsolationManager) ResolveScannerMode ¶ added in v0.68.0
func (im *IsolationManager) ResolveScannerMode(serverConfig *config.ServerConfig) (config.IsolationMode, string)
ResolveScannerMode resolves the isolation mode governing whether DOCKER-BASED security scanner plugins may run against this server, and why (GH #1303).
It is NOT the process-isolation mode: ResolveMode/ShouldIsolate remain the only answer to "how is this server's child process launched". Scanner plugins run in their own short-lived containers over tool definitions already captured over MCP, so the process-spawn structural gates (no local command to wrap; the command already invokes docker) do not apply — see config.ResolveScannerIsolationMode.
Unlike ResolveIsolation this emits no ignored-opt-in warning: that warning is about the spawn decision and is deduped per server name, so firing it here would suppress the one the spawn path owes the operator.
func (*IsolationManager) SetLogger ¶ added in v0.24.7
func (im *IsolationManager) SetLogger(logger *zap.Logger)
SetLogger sets the logger on an existing IsolationManager. Intended for call sites that build the manager before a logger is available (e.g. in config-time code) but want per-server warnings at runtime.
func (*IsolationManager) ShouldIsolate ¶
func (im *IsolationManager) ShouldIsolate(serverConfig *config.ServerConfig) bool
ShouldIsolate determines if a server should be isolated via Docker, based on global and server config. It is the legacy boolean view of ResolveMode and stays in lockstep with it: it returns true iff the resolved mode is "docker". Callers that need to distinguish sandbox/none should call ResolveMode.
func (*IsolationManager) TransformCommandForContainer ¶
func (im *IsolationManager) TransformCommandForContainer(command string, args []string, runtimeType string) (containerCommand string, containerArgs []string)
TransformCommandForContainer transforms the original command to run inside the container
type MutationResult ¶ added in v0.68.0
type MutationResult struct {
Container ContainerRow
Verified bool
Err error
}
MutationResult is what ContainerMutator.Mutate reports. Verified is true when ownership held at the re-read and the command ran, in which case Container is the row read then and Err the docker error if the command failed. Verified false with a nil Err means the container no longer satisfies the predicate (or is gone); with a non-nil Err the re-read itself failed. Nothing was run in either case.
type OAuthParameterError ¶
type OAuthParameterError struct {
Parameter string
Location string // "authorization_url" or "token_request"
Message string
OriginalErr error
}
OAuthParameterError represents a missing or invalid OAuth parameter
func (*OAuthParameterError) Error ¶
func (e *OAuthParameterError) Error() string
func (*OAuthParameterError) Unwrap ¶
func (e *OAuthParameterError) Unwrap() error
type OAuthStartResult ¶
type OAuthStartResult struct {
AuthURL string // The authorization URL for manual use
BrowserOpened bool // Whether the browser was successfully opened
BrowserError string // Error message if browser opening failed
CorrelationID string // Unique ID for tracking this OAuth flow
}
OAuthStartResult contains the result of initiating an OAuth flow. Used by Phase 3 (Spec 020) to return auth URL and browser status synchronously.
type ProcessGroup ¶
type ProcessGroup struct {
PGID int
}
ProcessGroup represents a Unix process group for proper child process management
type ResolvedIsolation ¶ added in v0.64.0
type ResolvedIsolation = config.ResolvedIsolation
ResolvedIsolation is re-exported from the config package so callers in this package can keep referring to it without importing config explicitly.
type ResolvedIsolationDefaults ¶ added in v0.26.0
type ResolvedIsolationDefaults struct {
// RuntimeType is the runtime detected from the server command (e.g.
// "uvx", "npx", "python"). Useful for diagnostic display.
RuntimeType string
// Image is the fully-qualified Docker image that would be used,
// already including registry prefixes via buildFullImageName.
Image string
// NetworkMode is the network mode that would be used (typically
// inherited from the global DockerIsolationConfig).
NetworkMode string
// ExtraArgs is the global extra args list that the server would
// inherit. Per-server extra_args are appended on top, so this
// communicates the baseline.
ExtraArgs []string
// ContainerWorkingDir is the working directory that would be used
// inside the container. Empty when the global config does not
// specify one (Docker default applies).
ContainerWorkingDir string
}
ResolvedIsolationDefaults captures the per-runtime default values that would be used for a server when no per-server overrides are set. It is used by the REST API to expose contextual placeholders to UI clients (notably the macOS tray) so users can see exactly what an "empty" override field will resolve to before deciding whether to override it.
type UnresolvedSecretError ¶ added in v0.74.0
type UnresolvedSecretError struct {
Server string
Refs []UnresolvedSecretRef
}
UnresolvedSecretError reports secret references in the fields an HTTP upstream receives (URL, headers, OAuth settings) that could not be resolved when the client was built. Release QA F9: such a reference used to be sent to the upstream verbatim (`Authorization: Bearer ${keyring:name}`) while health stayed green. The client now refuses to connect, sign in or refresh a token, so nothing reaches the upstream, and the error says which reference is missing, where, and how to add it.
The error names references (`${keyring:name}`) and field paths only, never a field's value: a value may hold literal text or other resolved secrets.
func (*UnresolvedSecretError) Error ¶ added in v0.74.0
func (e *UnresolvedSecretError) Error() string
func (*UnresolvedSecretError) Unwrap ¶ added in v0.74.0
func (e *UnresolvedSecretError) Unwrap() error
Unwrap lets diagnostics classify the failure as MCPX_CONFIG_MISSING_SECRET.
type UnresolvedSecretRef ¶ added in v0.74.0
type UnresolvedSecretRef struct {
Field string // e.g. "Headers[Authorization]", "OAuth.ClientSecret"
Reference string // e.g. "${keyring:github-token}"
Type string // e.g. "keyring"
Name string // e.g. "github-token"
}
UnresolvedSecretRef is one reference that could not be resolved.
Source Files
¶
- auth_evidence.go
- client.go
- connection.go
- connection_browser.go
- connection_docker.go
- connection_http.go
- connection_launcher.go
- connection_lifecycle.go
- connection_oauth.go
- connection_stdio.go
- constants.go
- container_lock.go
- dispatch_recheck.go
- docker.go
- docker_ownership.go
- gate.go
- instance.go
- isolation.go
- list_changed_stream.go
- monitoring.go
- oauth_refresh.go
- oauth_refresh_replay.go
- oauth_stale_dcr_client.go
- output_schema.go
- process_unix.go
- prompts.go
- sandbox.go
- sandbox_rlimits_linux.go
- session_reinit.go
- skills.go
- unresolved_secrets.go