mcpproxy

package
v0.14.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 35 Imported by: 0

Documentation

Overview

Install (install.go) moves Claude Code's stdio MCP servers behind the proxy and back, one mcpServers entry per server under its own name, so tool names and every permission rule stay as they are.

Install prepares the daemon before it touches Claude's config: it lists the moved servers' tools into the catalog, saves their resolved definitions (and adds them to the servers file's moved list), starts the launchd agent or has a running daemon reload in place, and probes exactly those servers. Only then does one atomic jsonedit edit of mcpServers swap each moved entry for its HTTP entry. The manifest, written once after that edit, records per server the original raw entry and the entry written. If install fails before the edit, the daemon's files are put back as they were (and a running daemon reloads them); nothing in Claude's config changed. Running install again moves only the stdio servers not moved yet. Uninstall puts back, in one edit, each entry that is still what install wrote, keeps and reports any the owner changed, then removes the agent and the manifest.

Index

Constants

View Source
const (
	InstallNotInstalled = "not_installed"
	InstallInPlace      = "installed"
	InstallDrifted      = "drifted"
)

Install states reported by InstallStatus.

View Source
const DefaultCallTimeout = 100_000_000 * time.Millisecond

DefaultCallTimeout is Claude Code's default MCP_TOOL_TIMEOUT (1e8 ms in Claude Code 2.1.319): how long it lets a direct stdio tool call run.

View Source
const DriftFix = "run `aimux mcp proxy uninstall`, then `aimux mcp proxy install`"

DriftFix is the advice for a moved server whose entry is no longer its proxy URL.

View Source
const ProbeHeader = "X-Aimux-Probe"

ProbeHeader must be set (to any value) on POST /status/probe. A web page can submit a form to the proxy without an Origin header, which LocalOnly lets through; a form cannot set this header, and a script that sets it needs a CORS preflight the proxy never allows.

Variables

This section is empty.

Functions

func Ago

func Ago(now, t time.Time) string

Ago is t relative to now: "never", "just now", "30s ago", "5m ago", "3h ago", "2d ago".

func DecodeTool

func DecodeTool(raw json.RawMessage) (mcp.Tool, error)

DecodeTool turns a cached tool into an mcp.Tool whose input and output schemas are the server's original JSON.

func DefaultEditor

func DefaultEditor() func(string) error

DefaultEditor returns a function that opens $EDITOR on the given path, falling back to vi if $EDITOR is not set. $EDITOR may carry arguments (`code --wait`, `vim -n`), split as a shell would (editorCommand).

func EditServer

func EditServer(ctx context.Context, opts EditOptions) error

EditServer opens the server's definition in $EDITOR, validates the changes, probes with the new definition, saves it and the tools it listed, and reloads the daemon. Any failure before the save leaves the old definition unchanged. It holds the install lock, so it never races install or uninstall.

func EndpointPath

func EndpointPath(server string) string

EndpointPath is where the daemon serves the named server.

func EntryURL

func EntryURL(port int, server string) string

EntryURL is the proxy URL of server's endpoint on port.

func LoadClaudeServers

func LoadClaudeServers(path string, exclude []string) (map[string]ServerConfig, error)

LoadClaudeServers returns the stdio MCP servers in a Claude Code config (~/.claude.json), minus excluded names and any entry that runs this proxy. Remote (http, sse) servers are left out: they cost no local processes, so clients keep connecting to them directly.

func LoadServerFile

func LoadServerFile(path string) (map[string]ServerConfig, []string, error)

LoadServerFile reads the definitions and the resolved-by-install set (nil when the file has none, empty when it has an empty one). A missing file is empty.

func LoadServers

func LoadServers(path string) (map[string]ServerConfig, error)

LoadServers reads a file written by SaveServers. A missing file is empty.

func MergeServers

func MergeServers(saved, fromClaude map[string]ServerConfig, keep ...string) map[string]ServerConfig

MergeServers returns saved overlaid with fromClaude: an entry still in the Claude config wins, and one already moved out of it is kept. For the names in keep (resolved by install) the saved definition wins.

func NewServers

func NewServers(cat *Catalog, pool *Pool) map[string]*server.MCPServer

NewServers builds one MCP server per catalog server. Each lists that server's catalog tools under their original names and forwards calls through pool, so a backend starts on its first call. A tool the catalog holds in a form that cannot be decoded is left out.

func ProbeServerDirect

func ProbeServerDirect(ctx context.Context, cfg ServerConfig, timeout time.Duration, base map[string]string) ([]json.RawMessage, error)

ProbeServerDirect starts the server once with cfg and lists its tools, as the daemon would run it: its environment is base (PATH and HOME as the launchd plist sets them) plus cfg.Env, nothing else inherited from this shell. A server that starts and initializes is accepted with no tools when its initialize result has no tools capability or it answers tools/list with "method not found" (-32601): it returns an empty list. Any other listing failure (an auth error, a malformed answer) is an error. It returns the tools it listed.

func ReadPlistEnv

func ReadPlistEnv(path string) (env map[string]string, found bool, err error)

ReadPlistEnv reads the EnvironmentVariables of the launchd plist at path: the environment the agent's daemon runs with. found is false when there is no plist (no error); a plist without the key has an empty map.

func RefreshCatalog

func RefreshCatalog(ctx context.Context, cat *Catalog, start Starter, servers []string) map[string]error

RefreshCatalog starts each named server, records its tools in cat, and stops it again; when ctx ends, every backend it started is closed before it returns. A server that fails keeps its previous entry; the failures are returned by server name.

func SaveServerFile

func SaveServerFile(path string, servers map[string]ServerConfig, resolved []string) error

SaveServerFile writes the definitions and the resolved-by-install set; nil writes no set, an empty slice an empty one.

func SaveServers

func SaveServers(path string, servers map[string]ServerConfig) error

SaveServers writes the backend definitions the proxy runs, so they survive removing the stdio entries from the Claude config, keeping the file's resolved-by-install set. The file is owner-only: env values often hold tokens.

func Serve

func Serve(ctx context.Context, ln net.Listener, servers map[string]*server.MCPServer, pool *Pool, opt DaemonOptions) error

Serve exposes each of servers over Streamable HTTP at EndpointPath(name) on ln, for local clients only, and stops idle backends in pool. With opt.Reload, POST /reload changes the served set in place, never restarting the process. It returns when ctx is cancelled, after closing every backend.

func SkippedTools

func SkippedTools(cat *Catalog) []string

SkippedTools is one message per catalog tool NewServers leaves out, "<server>: <why>", sorted by server. It never holds env values or tool arguments.

func ToolsFingerprint

func ToolsFingerprint(tools []json.RawMessage) string

ToolsFingerprint identifies a backend's tool list as the proxy registers it: the tools in order, each as compact JSON, hashed. The daemon reports it for what it loaded at start; install compares it with the catalog.

Types

type Agent

type Agent struct {
	Label     string                                            // launchd label (e.g., "com.aimux.mcp-proxy")
	PlistPath string                                            // absolute path to plist file
	Binary    string                                            // absolute path to binary
	LogDir    string                                            // directory for stdout/stderr logs
	Args      []string                                          // arguments to binary (e.g., ["mcp","proxy","serve","--port","7381"])
	Run       func(name string, args ...string) ([]byte, error) // launchctl runner (injected)
	// Sleep waits between launchctl checks; default time.Sleep (tests pass a no-op).
	Sleep func(time.Duration)
	UID   int // user ID for gui/<uid>
	// Env is the agent's EnvironmentVariables. The plist is world-readable:
	// only non-secret values such as PATH and HOME belong here.
	Env map[string]string
}

Agent manages a launchd agent for the MCP proxy daemon.

func (Agent) Install

func (a Agent) Install() error

Install writes the plist atomically (0644), bootouts (ignoring "not loaded"), then bootstraps

func (Agent) Kickstart

func (a Agent) Kickstart() error

Kickstart restarts the daemon in place (launchctl kickstart -k): the job stays loaded, so no failed bootstrap can leave it down. An agent that is not loaded is bootstrapped. The plist is not re-read; use Restart for that.

func (Agent) Loaded

func (a Agent) Loaded() (bool, error)

Loaded returns true if the service is currently loaded in launchd

func (Agent) Plist

func (a Agent) Plist() []byte

Plist generates the launchd plist XML with RunAtLoad, KeepAlive, stdout/stderr paths, and ProgramArguments

func (Agent) Restart

func (a Agent) Restart() error

Restart reloads the service from the plist on disk as it is (bootout, ignoring "not loaded", then bootstrap); it does not rewrite the plist.

func (Agent) Uninstall

func (a Agent) Uninstall() error

Uninstall bootouts the service and removes the plist (both idempotent)

type Backend

type Backend interface {
	ListToolsRaw(ctx context.Context) ([]json.RawMessage, error)
	CallTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error)
	Close() error
}

Backend is one running MCP server the proxy forwards calls to.

type Catalog

type Catalog struct {
	Servers map[string]CatalogEntry `json:"servers"`
}

Catalog is the cached tools/list of every backend, so the proxy can list tools without starting the servers that provide them.

func LoadCatalog

func LoadCatalog(path string) (*Catalog, error)

LoadCatalog reads a catalog file. A missing file is an empty catalog.

func (*Catalog) Only

func (c *Catalog) Only(keep func(server string) bool) *Catalog

Only returns a copy holding the servers keep accepts; c is unchanged.

func (*Catalog) Save

func (c *Catalog) Save(path string) error

Save writes the catalog atomically with owner-only permissions.

func (*Catalog) Set

func (c *Catalog) Set(server string, tools []json.RawMessage, fetchedAt time.Time)

Set replaces a backend's tools.

type CatalogEntry

type CatalogEntry struct {
	Tools     []json.RawMessage `json:"tools"`
	FetchedAt time.Time         `json:"fetchedAt"`
}

CatalogEntry holds one backend's tools exactly as the server sent them. Raw JSON is kept because mcp.Tool drops schema keywords it does not model, such as a top-level anyOf.

type CatalogUpdater

type CatalogUpdater struct {

	// Current is a server's definition as a reload would load it now; a
	// refresh from a backend started with another definition is dropped.
	// Nil, or false (unknown), keeps every refresh.
	Current func(server string) (ServerConfig, bool)
	// contains filtered or unexported fields
}

CatalogUpdater keeps a catalog and its file current as backends start, so tools a server added appear the next time the proxy starts.

func NewCatalogUpdater

func NewCatalogUpdater(cat *Catalog, path string) *CatalogUpdater

NewCatalogUpdater keeps a copy of cat current and saves it to path. The copy is its own: callers (the reloader's current set) may go on reading cat while backend starts refresh the updater's catalog.

func (*CatalogUpdater) Changes

func (u *CatalogUpdater) Changes() <-chan struct{}

Changes receives a value after a Refresh saved a server's tools that differ from the ones it had: the daemon reloads, so the endpoint serves them. Changes not yet received collapse into one.

func (*CatalogUpdater) Refresh

func (u *CatalogUpdater) Refresh(ctx context.Context, server string, b Backend) error

Refresh re-lists a started backend's tools and records them. The file is read, changed for this server only and saved, so entries other programs wrote since (install's refresh, edit) survive; the served copy changes for this server only, a reload replaces the rest. A failed listing keeps the previous entry and writes nothing.

func (*CatalogUpdater) Replace

func (u *CatalogUpdater) Replace(cat *Catalog)

Replace swaps in a copy of cat, e.g. after a reload re-read the file.

func (*CatalogUpdater) Snapshot

func (u *CatalogUpdater) Snapshot() *Catalog

Snapshot returns a copy of the current catalog.

func (*CatalogUpdater) ToolCount

func (u *CatalogUpdater) ToolCount(server string) int

ToolCount is how many tools the catalog lists for server.

type DaemonOptions

type DaemonOptions struct {
	// IdleTimeout is how long a backend may sit unused before it is stopped.
	// Default 10 minutes.
	IdleTimeout time.Duration
	// ReapEvery is how often idle backends are checked. Default 1 minute.
	ReapEvery time.Duration
	// Status, when set, adds GET /status and POST /status/probe.
	Status *Monitor
	// Reload, when set, adds POST /reload.
	Reload *ReloadOptions
	// Log receives one line per catalog tool a reload could not serve.
	// nil discards them.
	Log io.Writer
	// contains filtered or unexported fields
}

DaemonOptions configures Serve. Zero values give the defaults.

type EditOptions

type EditOptions struct {
	Server       string            // server name
	ServersPath  string            // ~/.aimux/mcp-servers.json
	ManifestPath string            // ~/.aimux/mcp-proxy-install.json
	CatalogPath  string            // ~/.aimux/mcp-catalog.json
	BaseEnv      map[string]string // the proxy's PATH and HOME (its plist); the command is resolved on that PATH
	Out          io.Writer
	Port         int                     // daemon port
	Editor       func(path string) error // opens $EDITOR on path (injectable for tests)
	Probe        func(ctx context.Context, cfg ServerConfig) ([]json.RawMessage, error)
	Reload       func() (ReloadResult, error) // reloads the daemon (injectable for tests)
	Timeout      time.Duration                // probe timeout
}

EditOptions configures editing a moved server's definition.

type FailureReason

type FailureReason string

FailureReason is how a server last failed, as a fixed category. Unlike LastError it carries no text from the server, so it is safe to show to a model.

const (
	ReasonNone           FailureReason = ""
	ReasonStartFailed    FailureReason = "start_failed"    // the start returned an error
	ReasonTimedOut       FailureReason = "timed_out"       // a start or a call ran past its timeout
	ReasonExited         FailureReason = "exited"          // the process exited on its own
	ReasonTransportError FailureReason = "transport_error" // a call broke the connection
)

type InstallPlan

type InstallPlan struct {
	Move    []string // stdio servers that would move behind the proxy
	Skip    []string // left direct with --skip
	Moved   []string // already behind the proxy (the manifest)
	Remove  []string // moved, but their entry is gone from the Claude config: install takes them off
	Refresh []string // missing from the catalog (after DryRun: the ones it could not list)
	Listed  []string // DryRun started these once to list their tools into a temporary catalog
}

InstallPlan is what install would do, by name only.

type InstallState

type InstallState struct {
	State string   `json:"state"`
	Moved []string `json:"moved,omitempty"`
	// Drifted are moved servers whose entry is no longer their proxy URL.
	Drifted []string `json:"drifted,omitempty"`
	// Removed are moved servers whose entry is gone from the Claude config
	// (the owner removed it); the proxy still serves them, unused.
	Removed []string `json:"removed,omitempty"`
	// NotProxied are stdio servers in mcpServers not behind the proxy.
	NotProxied []string `json:"notProxied,omitempty"`
	// Skipped are stdio servers kept direct with --skip.
	Skipped []string `json:"skipped,omitempty"`
	// UpgradePending: the running daemon's version differs from this aimux.
	UpgradePending bool   `json:"upgradePending,omitempty"`
	DaemonVersion  string `json:"daemonVersion,omitempty"`
}

InstallState is how the install looks now.

type Installer

type Installer struct {
	ClaudeConfig string // ~/.claude.json
	ManifestPath string // ~/.aimux/mcp-proxy-install.json
	BackupDir    string // ~/.aimux/backups
	ServersPath  string // the proxy's saved backend definitions
	CatalogPath  string // the tool catalog
	Settings     string // ~/.claude/settings.json, for the http idle limit; empty leaves it alone
	Port         int    // the daemon's port on 127.0.0.1
	Version      string // this aimux's version, compared with the daemon's
	// Unskip are recorded --skip servers this run moves after all.
	Unskip []string

	Agent    Agent
	Status   func() (StatusReport, error)
	Probe    func(servers []string) (StatusReport, error)                // the daemon's POST /status/probe for these servers
	Reload   func() (ReloadResult, error)                                // the daemon's POST /reload
	Refresh  func(catalogPath string, servers []string) map[string]error // lists tools and saves them in the catalog at catalogPath
	Sessions func() ([]string, error)                                    // ids of open Claude Code sessions; nil skips the note
	Out      io.Writer
	Wait     time.Duration // for the daemon to answer; 0 means 10 s
	Sleep    func(time.Duration)
	Now      func() time.Time // default time.Now; bounds the wait for the daemon
	// contains filtered or unexported fields
}

Installer moves Claude Code's stdio MCP servers behind the proxy and back. Every path, the launchctl runner and the daemon calls are injected.

func (Installer) DryRun

func (i Installer) DryRun(skip []string) (InstallPlan, error)

DryRun is Plan with the tool listing the real install does first: the servers to move that are missing from the catalog are started once each to list their tools into a temporary copy of the catalog. Nothing outside a temporary directory is written; the copy is removed before it returns. Servers that fail to list stay in Refresh.

func (Installer) Install

func (i Installer) Install(skip []string) (err error)

Install moves the stdio servers not moved yet (minus skip) behind the proxy; see the package comment for the order. A run with nothing new to move changes nothing.

func (Installer) InstallStatus

func (i Installer) InstallStatus() (InstallState, error)

InstallStatus reports the moved servers whose entry drifted, the stdio servers not behind the proxy and whether an upgrade restart is pending.

func (Installer) Plan

func (i Installer) Plan(skip []string) (InstallPlan, error)

Plan reports what Install(skip) would change, touching nothing.

func (Installer) PrintInstallStatus

func (i Installer) PrintInstallStatus(st InstallState)

PrintInstallStatus prints st in a few plain lines.

func (Installer) PrintPlan

func (i Installer) PrintPlan(p InstallPlan)

PrintPlan prints p by name only.

func (Installer) Restart

func (i Installer) Restart() (StatusReport, error)

Restart restarts the daemon under launchd (after an upgrade), in place, and waits until a new daemon (another pid) answers, then returns its report. Open sessions reconnect on their next call.

func (Installer) Uninstall

func (i Installer) Uninstall() error

Uninstall puts back, in one edit, every moved entry still as install wrote it, keeps and reports the others, then removes the manifest and the launchd agent. Without a manifest it only removes a leftover agent.

func (Installer) UpgradeText

func (i Installer) UpgradeText(daemon string) string

UpgradeText says the running daemon is another version than this aimux and how to restart it.

type LiveStarter

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

LiveStarter starts stdio servers from definitions a reload can replace.

func NewLiveStarter

func NewLiveStarter(cfgs map[string]ServerConfig, resolved []string) *LiveStarter

NewLiveStarter starts servers from cfgs, as StdioStarter does.

func (*LiveStarter) Set

func (l *LiveStarter) Set(cfgs map[string]ServerConfig, resolved []string)

Set replaces the definitions; starts already under way keep the old ones.

func (*LiveStarter) Start

func (l *LiveStarter) Start(ctx context.Context, server string) (Backend, error)

Start is a Starter using the current definitions.

type Manifest

type Manifest struct {
	Version int                   `json:"version"`
	Port    int                   `json:"port"`
	Servers map[string]MovedEntry `json:"servers"`
	// Skipped are the stdio servers kept direct with --skip; a re-run keeps
	// them direct until --unskip.
	Skipped []string `json:"skipped,omitempty"`
	// IdleTimeout is what install did to Claude Code's http idle limit in
	// settings.json (idleAdded, idleAddedEnv, or empty: nothing).
	IdleTimeout string `json:"idleTimeout,omitempty"`
}

Manifest is what install changed, in ~/.aimux/mcp-proxy-install.json (owner-only: the original entries hold env values).

func LoadManifest

func LoadManifest(path string) (*Manifest, error)

LoadManifest reads the manifest; nil when there is none.

type Monitor

type Monitor struct {
	Pool    *Pool
	Servers []string                // configured servers
	Tools   func(server string) int // tool count from the catalog; nil means 0
	// Registered is each server's ToolsFingerprint as currently served.
	Registered map[string]string
	PID        int
	StartedAt  time.Time
	Port       int
	Version    string // the aimux version this daemon runs
	// contains filtered or unexported fields
}

Monitor reports the proxy's health over HTTP (/status, /status/probe).

func (*Monitor) Probe

func (m *Monitor) Probe(ctx context.Context) StatusReport

Probe starts each configured server once through the pool, lists its tools, and reports. Servers that cannot finish within ctx carry the error in ProbeError.

func (*Monitor) ProbeServers

func (m *Monitor) ProbeServers(ctx context.Context, names []string) StatusReport

ProbeServers is Probe for the named servers only (all configured ones when names is empty). A name the proxy does not serve is reported with a ProbeError, so a caller checking those servers sees it fail.

func (*Monitor) Report

func (m *Monitor) Report() StatusReport

Report is every configured server's current health.

type MovedEntry

type MovedEntry struct {
	Original string `json:"original"`
	Written  string `json:"written"`
}

MovedEntry is one moved server's mcpServers entry: Original is its raw bytes before install (put back verbatim), Written the entry install wrote. They are strings because encoding/json reformats a RawMessage.

type Pool

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

Pool starts backends on first use, shares them, and closes idle ones.

func NewPool

func NewPool(start Starter, opt PoolOptions) *Pool

NewPool returns a Pool that starts backends with start.

func (*Pool) Call

func (p *Pool) Call(ctx context.Context, server, session string, req mcp.CallToolRequest) *mcp.CallToolResult

Call forwards a tool call to the server's backend, starting it if needed. Failures come back as error results naming the server, never as Go errors, so one broken backend cannot break the proxy's other tools.

func (*Pool) Close

func (p *Pool) Close()

Close closes every backend and rejects further calls.

func (*Pool) CloseServer

func (p *Pool) CloseServer(server string)

CloseServer closes every backend of server, shared and per-session. One with a call in flight is retired instead and closed when its last call returns; the next call starts a new backend. A call waiting on a start under way is told to retry.

func (*Pool) CloseSession

func (p *Pool) CloseSession(session string)

func (*Pool) Lease

func (p *Pool) Lease(ctx context.Context, server string) (Backend, error)

Lease starts the server through the pool as a tool call would, sharing a running backend, but counts no call. Closing the lease releases it; a per-session server's backend started for the lease is stopped then.

func (*Pool) Reap

func (p *Pool) Reap(idle time.Duration) int

Reap closes started shared backends with no call in flight that have been idle longer than idle, and returns how many it closed.

func (*Pool) RetireServer

func (p *Pool) RetireServer(server string) (closeRetired func())

RetireServer takes every backend of server out of use at once, so the next call starts a new backend, and returns the function that closes the retired ones (one with a call in flight closes when its last call returns). A call waiting on a start under way is told to retry.

func (*Pool) SessionBusy

func (p *Pool) SessionBusy(session string) bool

CloseSession closes the per-session backends of one client session. A backend with a call still running is closed when that call returns. SessionBusy reports whether a call of session is in flight on any server.

func (*Pool) Status

func (p *Pool) Status(servers []string) []ServerStatus

Status reports every configured server, sorted by name. A server the pool has never seen is not_started.

type PoolOptions

type PoolOptions struct {
	// CallTimeout bounds each tool call. Default DefaultCallTimeout, the
	// limit Claude Code puts on a direct stdio call, so a slow tool that
	// works direct works through the proxy too.
	CallTimeout time.Duration
	// ListTimeout bounds a tools/list on a leased backend (probes, catalog
	// refreshes). Default 2 minutes.
	ListTimeout time.Duration
	// StartTimeout bounds starting and initializing a backend, so a server
	// that never answers cannot hold its callers. Default 2 minutes (npx and
	// uvx may download the server first).
	StartTimeout time.Duration
	// PerSession names servers that get one backend per client session
	// instead of one shared backend (for example browser automation).
	PerSession map[string]bool
	// OnStart runs after a backend starts, e.g. to refresh the catalog.
	OnStart func(server string, b Backend)
	// Now is the clock, for tests.
	Now func() time.Time
}

PoolOptions configures a Pool. Zero values give the defaults.

type ReloadOptions

type ReloadOptions struct {
	// Current is the set the servers given to Serve were built from.
	Current ServerSet
	// Load re-reads the servers file and catalog.
	Load func() (ServerSet, error)
	// Apply, when set, receives the new set before any backend is closed,
	// so the next start uses the new definitions.
	Apply func(ServerSet)
	// Changes, when set, triggers a reload on each value received
	// (CatalogUpdater.Changes): tools a backend start found are published.
	Changes <-chan struct{}
}

ReloadOptions enables POST /reload.

type ReloadResult

type ReloadResult struct {
	Added   []string `json:"added"`
	Removed []string `json:"removed"`
	Changed []string `json:"changed"`
}

ReloadResult is the POST /reload answer: the servers whose endpoint was added or removed, and those whose definition changed.

func ReloadDaemon

func ReloadDaemon(port int) (ReloadResult, error)

ReloadDaemon asks the daemon on 127.0.0.1:port to re-read its servers file and catalog and apply the difference in place.

type RequestError

type RequestError struct {
	Err  error
	Code int // the JSON-RPC error code when the server answered with one; 0 otherwise
}

RequestError is a backend's JSON-RPC error answer to a call (unknown tool, invalid params). The server is healthy, so the pool keeps it.

func (*RequestError) Error

func (e *RequestError) Error() string

func (*RequestError) Unwrap

func (e *RequestError) Unwrap() error

type ServerConfig

type ServerConfig struct {
	Command string            `json:"command"`
	Args    []string          `json:"args"`
	Env     map[string]string `json:"env"`
}

ServerConfig is how to launch one stdio MCP server, as in ~/.claude.json.

type ServerReport

type ServerReport struct {
	ServerStatus
	Tools int `json:"tools"`
	// Registered is the ToolsFingerprint of the tools the daemon registered
	// for this server ("" from a daemon that does not report it).
	Registered string `json:"registered,omitempty"`
	// Endpoint: the daemon serves /mcp/<server> for it (a configured server
	// without a catalog entry has none).
	Endpoint bool `json:"endpoint"`
	// ProbeError is why a probe could not start the server or list its
	// tools; only set in a probe's answer.
	ProbeError string `json:"probeError,omitempty"`
}

ServerReport is one server's health plus its tool count.

type ServerSet

type ServerSet struct {
	Configs  map[string]ServerConfig
	Resolved []string
	Catalog  *Catalog
}

ServerSet is what the daemon serves: each server's launch definition, the ones install already resolved, and the tool catalog. A server gets an endpoint when it has both a definition and a catalog entry.

type ServerState

type ServerState string

ServerState is what a configured MCP server is doing, as the proxy sees it.

const (
	StateNotStarted  ServerState = "not_started"  // never started
	StateStarting    ServerState = "starting"     // a start is in progress
	StateRunning     ServerState = "running"      // started and not reaped
	StateIdleStopped ServerState = "idle_stopped" // stopped (reaped idle or closed) after a good run
	StateFailed      ServerState = "failed"       // last start failed, or it broke, and no start since
)

type ServerStatus

type ServerStatus struct {
	Server    string      `json:"server"`
	State     ServerState `json:"state"`
	Instances int         `json:"instances"`     // >1 for per-session servers
	PID       int         `json:"pid,omitempty"` // 0 unless exactly one instance runs
	StartedAt time.Time   `json:"startedAt,omitzero"`
	LastCall  time.Time   `json:"lastCall,omitzero"`
	// Calls counts every tool call routed to the server. Failures counts
	// the calls that failed because of it (start failed, timed out, broken
	// transport), so Failures <= Calls: N callers waiting on one failed
	// start count N failures. A process that exits between calls marks the
	// server failed without counting a failure.
	Calls       int           `json:"calls"`
	Failures    int           `json:"failures"`
	LastError   string        `json:"lastError,omitempty"` // first line only, secrets scrubbed by the backend
	Reason      FailureReason `json:"reason,omitempty"`    // how LastError happened; set and kept with it
	LastErrorAt time.Time     `json:"lastErrorAt,omitzero"`
	StderrTail  []string      `json:"stderrTail,omitempty"` // last 5 lines of a failed start, scrubbed
}

ServerStatus is one server's health. It never holds env values or tool arguments: only names, counts, times and the server's own error text.

type Starter

type Starter func(ctx context.Context, server string) (Backend, error)

Starter starts the named backend.

func StdioStarter

func StdioStarter(cfgs map[string]ServerConfig, resolved ...string) Starter

StdioStarter returns a Starter that launches servers from cfgs, expanding ${VAR} references as Claude Code does, except for the servers in resolved: install already expanded those, and a value may legitimately contain "${...}".

type StatusReport

type StatusReport struct {
	Running   bool      `json:"running"`
	PID       int       `json:"pid"`
	StartedAt time.Time `json:"startedAt"`
	Port      int       `json:"port"`
	// Version is the aimux version the daemon runs ("" from an older one).
	// Install and status compare it with the binary's: a difference is an
	// upgrade restart pending.
	Version string         `json:"version,omitempty"`
	Servers []ServerReport `json:"servers"`
}

StatusReport is the daemon's GET /status answer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL