agentmcp

package
v0.6.5 Latest Latest
Warning

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

Go to latest
Published: Oct 5, 2026 License: MIT Imports: 19 Imported by: 0

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

View Source
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.

View Source
const (
	DefaultStopIfIdle    = 30 * time.Minute
	DefaultDestroyIfIdle = 24 * time.Hour
	DefaultMaxCreates    = 5
)

Defaults for sandboxes the MCP server creates (eng review D7).

Variables

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.

View Source
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

func BindFlags(fs *flag.FlagSet) func() (Options, error)

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

func ParseToolsets(s string) []string

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

type OptionError struct {
	Param   string
	Message string
}

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

func ParseQuery(q url.Values) (Options, error)

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.

func (*Options) Validate

func (o *Options) Validate() error

Validate checks the options and normalises them in place.

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.

func (*Server) MCP

func (s *Server) MCP() *mcp.Server

MCP is the underlying server, for transports and tests.

func (*Server) Run

func (s *Server) Run(ctx context.Context, t mcp.Transport) error

Run serves the transport until the client disconnects or ctx ends.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown runs the clean-exit work: with Ephemeral, destroy the pinned sandbox once. Best effort; the idle lifecycle is the real guarantee, because MCP hosts often SIGKILL their servers.

type ServerOption

type ServerOption func(*Server)

ServerOption configures New.

func WithInstrument

func WithInstrument(fn Instrument) ServerOption

WithInstrument sets the per-call instrumentation.

Jump to

Keyboard shortcuts

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