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 ¶
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 ¶
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 ¶
IsToolName reports whether name is an MCP tool name.
func ToolName ¶
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.