Documentation
¶
Overview ¶
Package mux is the core of mcpmux: it connects to a set of backend MCP servers, aggregates their tools under namespaced names, and exposes them through a single proxy MCP server (over stdio or streamable HTTP).
Index ¶
- func PartitionBackends(backends []config.Backend) (noninteractive, interactive []config.Backend)
- func SetVersion(v string)
- type ConnectOptions
- type Mux
- func (m *Mux) Catalog() []ToolInfo
- func (m *Mux) Close()
- func (m *Mux) Connect(ctx context.Context, backends []config.Backend, opts ConnectOptions) int
- func (m *Mux) ConnectInBackground(ctx context.Context, backends []config.Backend, opts ConnectOptions)
- func (m *Mux) RetryPendingNow() int
- func (m *Mux) ServeHTTP(ctx context.Context, addr, path string) error
- func (m *Mux) ServeHTTPListener(ctx context.Context, ln net.Listener, path string) error
- func (m *Mux) ServeStdio(ctx context.Context) error
- type RetryPolicy
- type ToolInfo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PartitionBackends ¶ added in v0.4.0
PartitionBackends splits backends into those that connect without human interaction and those that may prompt for an interactive OAuth consent, preserving config order within each group. A daemon connects the non-interactive group synchronously (so its tools and systemd readiness are immediate) and the interactive group in the background.
Types ¶
type ConnectOptions ¶ added in v0.8.0
type ConnectOptions struct {
// Eager drives an interactive OAuth backend through its browser consent
// during connect rather than lazily on its first tool call.
Eager bool
// Retry, when non-nil, keeps a backend that fails its initial connect and
// retries it in the background instead of skipping it for the process's
// lifetime. Only non-interactive backends are retried; see connectOne.
// A one-shot caller (the list command) leaves this nil.
Retry *RetryPolicy
}
ConnectOptions tunes how Connect brings backends up.
type Mux ¶
type Mux struct {
// contains filtered or unexported fields
}
Mux aggregates several backend MCP servers behind a single proxy server.
func New ¶
New connects to every configured backend synchronously, aggregates their tools and returns a ready Mux. It is used by callers that want the full catalog before proceeding (e.g. the `list` command); it blocks on any interactive OAuth consent. On zero connected backends it returns an error. The caller owns Close.
func NewServer ¶ added in v0.4.0
NewServer builds an unconnected Mux: the proxy server and its middleware, with no backends attached. Callers bring backends up with Connect / ConnectInBackground. This lets a daemon start serving (and signal systemd readiness) before interactive OAuth backends have finished authorizing.
func (*Mux) Catalog ¶
Catalog returns the aggregated tools across all backends, captured when each backend was registered (no additional backend round-trips).
func (*Mux) Close ¶
func (m *Mux) Close()
Close shuts down every backend session. It first marks the Mux as closing (so supervisors treat the impending session closures as intentional and do not reconnect), cancels the per-backend goroutines directly — otherwise one sleeping out a retry backoff would stall shutdown for as long as its current delay — and waits for any in-flight background Connect to return (the caller is expected to have cancelled the context, which aborts an in-progress connect/consent) so closing sessions cannot race the goroutine that registers them. Closing each session unblocks its supervisor's Wait; once all sessions are closed it waits for the supervisors to exit.
func (*Mux) Connect ¶ added in v0.4.0
Connect dials the given backends sequentially, registering each one's tools as it succeeds (one bad backend must not take down the proxy). Sequential iteration keeps interactive OAuth consents to one browser window at a time. A backend that fails is either kept for background retry or skipped, per opts.Retry. It returns the number of backends connected. Safe to call after the server has started serving: tool registration notifies connected clients via tools/list_changed.
func (*Mux) ConnectInBackground ¶ added in v0.4.0
func (m *Mux) ConnectInBackground(ctx context.Context, backends []config.Backend, opts ConnectOptions)
ConnectInBackground connects the given backends in a goroutine so their interactive OAuth consents happen after the proxy is already serving, instead of blocking startup. Close waits for the goroutine to finish. A nil/empty slice is a no-op.
func (*Mux) RetryPendingNow ¶ added in v0.8.0
RetryPendingNow asks every backend still waiting on its first successful connect to attempt again immediately instead of waiting out its backoff, and returns how many were kicked. It is the daemon's recovery hook (see the SIGUSR1 handler): after refreshing whatever credential the backends need, one signal brings them up without the restart that would re-trigger every interactive OAuth consent. Sends are non-blocking, so a kick that arrives mid-attempt is coalesced into the next iteration.
func (*Mux) ServeHTTP ¶
ServeHTTP binds addr and serves the proxy over streamable HTTP. It returns when ctx is cancelled or on a fatal error.
func (*Mux) ServeHTTPListener ¶
ServeHTTPListener serves the proxy over streamable HTTP on an existing listener, mounting the single MCP endpoint at path. This is the entry point for systemd socket activation, where the listening socket is supplied by the service manager. It returns when ctx is cancelled or on a fatal error.
type RetryPolicy ¶ added in v0.8.0
RetryPolicy bounds the loop that brings up a backend which failed its initial connect: MaxDelay caps the exponential backoff between attempts and AttemptTimeout bounds each individual attempt.
Source Files