Documentation
¶
Overview ¶
Package agentmcp is the AerolVM MCP tool registry (plans/mcp-server-and- agent-cli.md §5.3). `aerolvm mcp` serves it over stdio, and sandboxd's remote /mcp endpoint serves the same registry over Streamable HTTP, so a tool behaves the same wherever the model reaches it. Every tool runs through internal/agenttools, which the CLI shares.
Index ¶
Constants ¶
const ( ToolsetCore = "core" ToolsetFiles = "files" ToolsetProcess = "process" )
Toolsets. Every extra tool costs the model selection accuracy and context, so only core is on by default.
const ( DefaultStopIfIdle = 30 * time.Minute DefaultDestroyIfIdle = 24 * time.Hour DefaultMaxCreates = 5 )
Defaults for sandboxes the MCP server creates (eng review D7).
Variables ¶
var MCPRuntimes = []string{ models.RuntimeDocker, models.RuntimeGvisor, models.RuntimeFirecracker, models.RuntimeWasm, }
MCPRuntimes is the runtime enum sandbox_create offers. Isolate is left out: it has no shell or filesystem, so none of the other tools would work on it (eng review D11). Kata is reserved and rejected at create.
var RemoteParams = []string{"sandbox", "create_if_missing", "image", "runtime", "toolsets", "read_only"}
RemoteParams are the options the remote endpoint takes as URL query parameters (CEO review CF1). The token stays in the Authorization header; stdio-only options (ephemeral, max_creates, ...) are not accepted there.
Functions ¶
func BindFlags ¶
BindFlags registers the stdio flags on fs (query names with dashes) and returns a parser that validates them. It and ParseQuery are the only two ways to build Options, and both end in Validate.
func ParseToolsets ¶
ParseToolsets splits a comma-separated toolset list ("core,files", "all").
Types ¶
type Instrument ¶
type Instrument func(ctx context.Context, tool string) (context.Context, func(sandboxID string, err error))
Instrument wraps every tool call. It runs before the call with the tool name and returns the context to run the call in and a func called after it with the sandbox the call acted on (if known) and its error. The remote endpoint uses it for metrics, a log line and a span per call; stdio has none.
type Notice ¶
type Notice struct {
SandboxRecreated bool `json:"sandbox_recreated,omitempty"`
SandboxCreated bool `json:"sandbox_created,omitempty"`
Text string `json:"notice,omitempty"`
}
Notice tells the model when the sandbox behind a pinned server is new: recreated after it disappeared (stdio, eng review D6) or created by a remote call (eng re-review RR2). Files from earlier calls are gone.
The text field isn't named Notice: an embedded Notice would shadow it and drop "notice" from the inferred output schema.
type OptionError ¶
OptionError names the option a validation failure is about, so the remote endpoint can answer 400 naming the parameter and the CLI can name the flag.
func (*OptionError) Error ¶
func (e *OptionError) Error() string
func (*OptionError) Flag ¶
func (e *OptionError) Flag() string
Flag is the stdio flag spelling of the parameter.
type Options ¶
type Options struct {
// Sandbox pins the server to one sandbox (name or ID): the sandbox
// argument disappears from every tool and the fleet tools
// (sandbox_create/list/destroy) are not registered.
Sandbox string
// CreateIfMissing creates the pinned sandbox, by name, on the first tool
// call that needs it (never at startup), and recreates it if it later
// disappears.
CreateIfMissing bool
Image string
Runtime string
// Toolsets lists the enabled toolsets; empty means core.
Toolsets []string
// ReadOnly registers only tools that change nothing.
ReadOnly bool
// Ephemeral destroys the pinned sandbox on clean shutdown (stdio only;
// best effort, the lifecycle timers are the guarantee).
Ephemeral bool
// Keep turns off the idle stop/destroy defaults on created sandboxes.
Keep bool
// StopIfIdle and DestroyIfIdle override the defaults. Zero means the
// default; Keep turns both off.
StopIfIdle time.Duration
DestroyIfIdle time.Duration
// MaxCreates caps successful creates per process in unpinned mode (CEO
// review C4). Zero means unlimited; parsers default it to
// DefaultMaxCreates.
MaxCreates int
// MaxOutputBytes bounds exec output per stream; zero means 16 KiB.
MaxOutputBytes int
// Remote marks the sandboxd /mcp endpoint: pinned only, buffered exec,
// and a notice on every lazy create (CEO review CF2, eng re-review RR2).
Remote bool
}
Options configure one MCP server. The stdio flags (`aerolvm mcp --...`) and the remote endpoint's URL query parameters both fill an Options and call Validate, so the two front ends can't drift apart on names or rules (eng re-review, required by CEO review CF1). Option names below are the query-parameter spelling; the flags use dashes for underscores.
func ParseQuery ¶
ParseQuery builds Options for the remote endpoint from URL query parameters, parsed on every request (the endpoint is stateless). An unknown or stdio-only parameter is refused by name, so a typo such as create-if-missing fails loudly instead of being ignored.
type SandboxRow ¶
type SandboxRow struct {
ID string `json:"id"`
Name string `json:"name,omitempty"`
Status string `json:"status"`
Runtime string `json:"runtime,omitempty"`
CreatedAt string `json:"created_at"`
Tags map[string]string `json:"tags,omitempty"`
}
SandboxRow is the compact sandbox view returned to the model (eng review D15): enough to choose a sandbox, nothing that costs context for no use.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is one MCP server over one agenttools.Tools.
func New ¶
func New(tools *agenttools.Tools, opts Options, version string, options ...ServerOption) (*Server, error)
New builds a server with the tools opts enable. It validates opts.
type ServerOption ¶
type ServerOption func(*Server)
ServerOption configures New.
func WithInstrument ¶
func WithInstrument(fn Instrument) ServerOption
WithInstrument sets the per-call instrumentation.