Documentation
¶
Overview ¶
Package mcptools connects a session's worker to the MCP servers the operator configures, through elelem's mcp package.
Servers are read from .agents/mcp.json in PEEN_CONFIG_DIR and, when the operator allows it, in the session workspace. A stdio server runs as a child of the worker, with the agent's access. A Streamable HTTP server is reached from the worker's network. Only tools are supported.
Index ¶
Constants ¶
const ( // FileName is the MCP configuration file inside a layer's .agents // directory. FileName = "mcp.json" // DefaultStartTimeout bounds starting one server and listing its tools. DefaultStartTimeout = 30 * time.Second )
Variables ¶
var ( // ErrInvalidConfig marks an mcp.json file or server entry Peen refuses. ErrInvalidConfig = errors.New("invalid MCP configuration") ErrServerUnavailable = errors.New("MCP server unavailable") )
Functions ¶
func Load ¶
func Load(options LoadOptions) ([]Server, []Status)
Load reads the config directory's mcp.json and, when allowed, the workspace's. A file or entry that fails validation does not stop the others: it comes back as a failed status that names the problem.
Types ¶
type LoadOptions ¶
type LoadOptions struct {
// ConfigDirectory is PEEN_CONFIG_DIR. Its .agents/mcp.json is trusted.
ConfigDirectory string
// Workspace is the session workspace. Its .agents/mcp.json is read only
// when WorkspaceEnabled is set, and a stdio server runs there.
Workspace string
WorkspaceEnabled bool
// SecretEnv lists the variables envFrom and bearerTokenEnv may name.
SecretEnv []string
}
LoadOptions says where to read mcp.json and what it may use.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager owns a worker's MCP server connections. Start connects them, Status starts them if nothing has, and Close stops them.
func (*Manager) Configured ¶
Configured reports whether any server or refused entry exists, so a caller can skip MCP work for a session that configures none.
func (*Manager) Refresh ¶ added in v0.39.0
Refresh brings the servers up to date at the start of a turn, so a turn sees the current configuration and tool lists. It starts the servers if nothing has. When the configuration changed it restarts every server. A server that ran and stopped restarts. A server that never started is tried again only when the configuration changes, so a server that cannot start does not cost every turn its start timeout. Every running server lists its tools again, which picks up a server's own tool changes.
func (*Manager) Start ¶
Start connects every server, once. Later calls wait for the first to finish. ctx bounds the starts, not the connections, which live until Close.
type Options ¶
type Options struct {
Servers []Server
// Failures are the entries Load refused. They are reported in Status.
Failures []Status
// BaseEnvironment is the environment every stdio server starts with,
// before its env and envFrom. It is the agent command environment, so
// it holds no Peen secret.
BaseEnvironment []string
// LookupEnv reads the worker variables envFrom and bearerTokenEnv name.
LookupEnv func(string) (string, bool)
// StartTimeout bounds starting one server and listing its tools.
StartTimeout time.Duration
// HTTPTransport carries Streamable HTTP requests. Nil takes
// http.DefaultTransport.
HTTPTransport http.RoundTripper
// Reload reads the configuration again, for Refresh. Nil keeps the
// configuration the Manager was built with.
Reload func() ([]Server, []Status)
}
Options builds a Manager.
type Server ¶
type Server struct {
Name string
Source Source
Transport Transport
Command string
Args []string
Env map[string]string
// EnvFrom maps a variable the server receives to the worker variable
// that holds its value, so a secret never sits in mcp.json.
EnvFrom map[string]string
// Directory is where a stdio server runs. It is absolute.
Directory string
URL string
Headers map[string]string
// BearerTokenEnv names the worker variable sent as
// "Authorization: Bearer <value>".
BearerTokenEnv string
// Tools limits the server's tools to these names. Empty keeps them all.
Tools []string
}
Server is one validated MCP server entry.
type Status ¶
type Status struct {
// Name is the server name. It is empty when a whole mcp.json file failed.
Name string `json:"name"`
Source Source `json:"source"`
Transport Transport `json:"transport,omitempty"`
State State `json:"state"`
// Tools lists the exposed names of the server's tools.
Tools []string `json:"tools"`
// Error says why the server failed.
Error string `json:"error,omitempty"`
// Warnings lists problems that did not stop the server, such as a tool
// in the allowlist the server does not offer.
Warnings []string `json:"warnings,omitempty"`
}
Status is what a session's worker knows about one configured server.