mcptools

package
v0.49.2 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: MIT Imports: 22 Imported by: 0

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

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

View Source
var (
	// ErrInvalidConfig marks an mcp.json file or server entry Peen refuses.
	ErrInvalidConfig = errors.New("invalid MCP configuration")
	// ErrServerUnavailable marks a server that could not be started.
	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 New

func New(options Options) *Manager

New returns a Manager for options. It starts nothing.

func (*Manager) Close

func (m *Manager) Close() error

Close stops every server. It is safe to call more than once.

func (*Manager) Configured

func (m *Manager) Configured() bool

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

func (m *Manager) Refresh(ctx context.Context)

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

func (m *Manager) Start(ctx context.Context)

Start connects every server, once. Later calls wait for the first to finish. ctx bounds the starts, not the connections, which live until Close.

func (*Manager) Status

func (m *Manager) Status(ctx context.Context) []Status

Status starts the servers once and reports every configured server and every refused entry.

func (*Manager) Tools

func (m *Manager) Tools() []elelem.Tool

Tools returns the tools of every server still connected, in configuration order. It waits for a Start in progress. Before any Start it returns none.

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 Source

type Source = string

Source is the layer an MCP server was configured in.

const (
	SourceConfig    Source = "config"
	SourceWorkspace Source = "workspace"
)

type State

type State = string

State is what happened when Peen started a server.

const (
	StateReady  State = "ready"
	StateFailed State = "failed"
)

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.

type Transport

type Transport = string

Transport is how Peen reaches an MCP server.

const (
	TransportStdio Transport = "stdio"
	TransportHTTP  Transport = "http"
)

Jump to

Keyboard shortcuts

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