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
- func Ago(now, t time.Time) string
- func DecodeTool(raw json.RawMessage) (mcp.Tool, error)
- func DefaultEditor() func(string) error
- func EditServer(ctx context.Context, opts EditOptions) error
- func EndpointPath(server string) string
- func EntryURL(port int, server string) string
- func LoadClaudeServers(path string, exclude []string) (map[string]ServerConfig, error)
- func LoadServerFile(path string) (map[string]ServerConfig, []string, error)
- func LoadServers(path string) (map[string]ServerConfig, error)
- func MergeServers(saved, fromClaude map[string]ServerConfig, keep ...string) map[string]ServerConfig
- func NewServers(cat *Catalog, pool *Pool) map[string]*server.MCPServer
- func ProbeServerDirect(ctx context.Context, cfg ServerConfig, timeout time.Duration, ...) ([]json.RawMessage, error)
- func ReadPlistEnv(path string) (env map[string]string, found bool, err error)
- func RefreshCatalog(ctx context.Context, cat *Catalog, start Starter, servers []string) map[string]error
- func SaveServerFile(path string, servers map[string]ServerConfig, resolved []string) error
- func SaveServers(path string, servers map[string]ServerConfig) error
- func Serve(ctx context.Context, ln net.Listener, servers map[string]*server.MCPServer, ...) error
- func SkippedTools(cat *Catalog) []string
- func ToolsFingerprint(tools []json.RawMessage) string
- type Agent
- type Backend
- type Catalog
- type CatalogEntry
- type CatalogUpdater
- type DaemonOptions
- type EditOptions
- type FailureReason
- type InstallPlan
- type InstallState
- type Installer
- func (i Installer) DryRun(skip []string) (InstallPlan, error)
- func (i Installer) Install(skip []string) (err error)
- func (i Installer) InstallStatus() (InstallState, error)
- func (i Installer) Plan(skip []string) (InstallPlan, error)
- func (i Installer) PrintInstallStatus(st InstallState)
- func (i Installer) PrintPlan(p InstallPlan)
- func (i Installer) Restart() (StatusReport, error)
- func (i Installer) Uninstall() error
- func (i Installer) UpgradeText(daemon string) string
- type LiveStarter
- type Manifest
- type Monitor
- type MovedEntry
- type Pool
- func (p *Pool) Call(ctx context.Context, server, session string, req mcp.CallToolRequest) *mcp.CallToolResult
- func (p *Pool) Close()
- func (p *Pool) CloseServer(server string)
- func (p *Pool) CloseSession(session string)
- func (p *Pool) Lease(ctx context.Context, server string) (Backend, error)
- func (p *Pool) Reap(idle time.Duration) int
- func (p *Pool) RetireServer(server string) (closeRetired func())
- func (p *Pool) SessionBusy(session string) bool
- func (p *Pool) Status(servers []string) []ServerStatus
- type PoolOptions
- type ReloadOptions
- type ReloadResult
- type RequestError
- type ServerConfig
- type ServerReport
- type ServerSet
- type ServerState
- type ServerStatus
- type Starter
- type StatusReport
Constants ¶
const ( InstallNotInstalled = "not_installed" InstallInPlace = "installed" InstallDrifted = "drifted" )
Install states reported by InstallStatus.
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.
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.
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 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 ¶
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 ¶
EndpointPath is where the daemon serves the named server.
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 ¶
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 ¶
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 ¶
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 ¶
Install writes the plist atomically (0644), bootouts (ignoring "not loaded"), then bootstraps
func (Agent) Kickstart ¶
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) Plist ¶
Plist generates the launchd plist XML with RunAtLoad, KeepAlive, stdout/stderr paths, and ProgramArguments
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 ¶
LoadCatalog reads a catalog file. A missing file is an empty catalog.
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 ¶
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 ¶
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 ¶
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 ¶
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.
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 ¶
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 ¶
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) CloseServer ¶
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 (*Pool) Lease ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.