mcp

package
v0.15.1 Latest Latest
Warning

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

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

Documentation

Overview

Package mcp turns the tools of an MCP (Model Context Protocol) server into elelem tools.

Connect starts or reaches one server, over stdio (a command elelem runs as a child process) or Streamable HTTP (a URL), lists its tools, and returns a Connection whose Tools are ready to add to a Request. A tool's text comes back as ToolResult.Content and its images as ToolResult.Images, so the engine shows them to a model that takes images and says so to one that does not.

Only tools are supported. Resources, prompts, sampling, elicitation, and roots are not, and the client advertises none of them. Authentication is a static bearer token or caller-supplied headers. The OAuth flow the MCP specification defines for HTTP servers is not implemented.

A stdio server and every process it starts share a process group, which Close stops. A Connection outlives the context passed to Connect: only Close ends it.

Index

Constants

View Source
const (
	// ToolNamePrefix starts every tool name this package builds. The full
	// name is mcp__<server>__<tool>, the format other agent tools use, so hook
	// and allowlist patterns written for them keep working.
	ToolNamePrefix = "mcp__"

	// MaxToolNameLength is the longest tool name providers accept.
	MaxToolNameLength = 64
	// MaxServerNameLength bounds a server name, so the tool names built from
	// it keep room for the tool.
	MaxServerNameLength = 32

	// DefaultStopTimeout is how long a stdio server gets to exit after its
	// input closes before it is signalled.
	DefaultStopTimeout = 5 * time.Second
)

Variables

View Source
var (
	// ErrInvalidServer marks a Server that cannot be connected as given.
	ErrInvalidServer = errors.New("invalid MCP server")
	// ErrConnectFailed marks a server that could not be started or reached,
	// or whose tools could not be listed.
	ErrConnectFailed = errors.New("MCP server connection failed")
	// ErrServerStopped marks a call to a server whose connection ended.
	ErrServerStopped = errors.New("MCP server stopped")
)

Functions

func IsToolName

func IsToolName(name string) bool

IsToolName reports whether name is an MCP tool name.

func ToolName

func ToolName(server, tool string) string

ToolName is the name the model sees for a server's tool: mcp__<server>__<tool>. A tool name with a character providers refuse, or one that makes the result too long, is cleaned and cut, and gets a short hash of the original so two such names never collide. The result depends only on the two names, so a saved transcript finds the same tool after a restart.

Types

type Connection

type Connection struct {
	// contains filtered or unexported fields
}

Connection is one connected server. Its methods are safe for concurrent use.

func Connect

func Connect(ctx context.Context, server Server) (*Connection, error)

Connect starts or reaches server and lists its tools. ctx bounds only the start: the connection lives until Close, even after ctx ends.

func (*Connection) Close

func (c *Connection) Close() error

Close ends the connection and stops a stdio server and every process it started. It is safe to call more than once.

func (*Connection) Done

func (c *Connection) Done() <-chan struct{}

Done is closed when the connection ends, by Close or because the server went away.

func (*Connection) Err

func (c *Connection) Err() error

Err says why the connection ended. It is nil while the connection is up and after Close.

func (*Connection) RefreshTools added in v0.14.0

func (c *Connection) RefreshTools(ctx context.Context) error

RefreshTools lists the server's tools again, so a server that added, removed, or changed a tool since Connect is seen. Tools returned earlier keep working. On failure the previous list stays.

func (*Connection) Tools

func (c *Connection) Tools() []elelem.Tool

Tools returns the server's tools, ready to add to a Request. A call after the connection ended fails with ErrServerStopped.

func (*Connection) Warnings

func (c *Connection) Warnings() []string

Warnings lists problems that did not stop the connection, such as an allowed tool the server does not offer.

type Server

type Server struct {
	// Name identifies the server in its tool names. It takes letters,
	// digits, and hyphens, at most MaxServerNameLength of them.
	Name string

	// Command and Args start a stdio server. Env is its whole environment
	// as KEY=VALUE entries; nil gives it none. Dir is where it runs.
	Command string
	Args    []string
	Env     []string
	Dir     string
	// StopTimeout is how long the server gets to exit after Close before it
	// is signalled. Zero takes DefaultStopTimeout.
	StopTimeout time.Duration

	// URL reaches a Streamable HTTP server. Headers go on every request.
	// BearerToken, when set, is sent as "Authorization: Bearer <token>".
	URL         string
	Headers     map[string]string
	BearerToken string
	// HTTPTransport carries the requests. Nil takes http.DefaultTransport.
	HTTPTransport http.RoundTripper

	// Tools limits the server's tools to these names. Empty keeps them all.
	// A name the server does not offer is reported by Connection.Warnings.
	Tools []string

	// ClientName is the client name sent to the server. Empty sends
	// "elelem".
	ClientName string
}

Server says how to reach one MCP server. Set Command for a stdio server or URL for a Streamable HTTP server, never both.

Jump to

Keyboard shortcuts

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