Documentation
¶
Overview ¶
Package mcphost provides MCP registration and lifecycle without application roles or workflow policy. Handlers and their collaborators belong to callers.
Index ¶
- Constants
- Variables
- func AddDone(r *Registry, opts DoneOptions, roles ...string)
- func AddDoneTool[In any](r *Registry, opts DoneOptions, decode func(In, work.Ref) agent.Outcome, ...)
- func AddTool[In, Out any](r *Registry, tool *mcp.Tool, handler mcp.ToolHandlerFor[In, Out], ...)
- func BearerTransport(token string, base http.RoundTripper) http.RoundTripper
- func Connect(ctx context.Context, server *mcp.Server, client mcp.Implementation) (*mcp.ClientSession, *mcp.ServerSession, error)
- func HTTPHandler(srv *mcp.Server, token string) http.Handler
- func IsCleanShutdown(err error) bool
- func Run(ctx context.Context, srv *mcp.Server, transport mcp.Transport) error
- func SchemaFor[In any](enums map[string][]string) *jsonschema.Schema
- func ServeHTTP(ctx context.Context, srv *mcp.Server, ln net.Listener, token string) error
- func Start(ctx context.Context, srv *mcp.Server) (Endpoint, Lease, error)
- func StartMemory(ctx context.Context, srv *mcp.Server) (Endpoint, Lease, error)
- func StartOn(ctx context.Context, srv *mcp.Server, addr string) (Endpoint, Lease, error)
- func Tools(ctx context.Context, server *mcp.Server, client mcp.Implementation) ([]*mcp.Tool, error)
- type DoneInput
- type DoneOptions
- type Endpoint
- type Lease
- type Registry
- type RolePolicy
- type StartFunc
Constants ¶
const EndpointPath = "/mcp"
EndpointPath is the URL path Start serves on. The handler answers on any path; the endpoint names this one.
Variables ¶
var ErrLeaseClosed = errors.New("mcphost: lease closed")
ErrLeaseClosed is returned by Lease.Connect once the lease is closed.
Functions ¶
func AddDone ¶
func AddDone(r *Registry, opts DoneOptions, roles ...string)
AddDone registers done using the standard input shape and default work.
func AddDoneTool ¶
func AddDoneTool[In any](r *Registry, opts DoneOptions, decode func(In, work.Ref) agent.Outcome, roles ...string)
AddDoneTool registers done with a caller-defined input shape containing a status property. Decode maps that shape onto a generic outcome. Each request receives its own copy of the default work tags, including under concurrency.
func AddTool ¶
func AddTool[In, Out any](r *Registry, tool *mcp.Tool, handler mcp.ToolHandlerFor[In, Out], roles ...string)
AddTool registers a typed handler. No roles means every known role. Duplicate names (even across disjoint roles), unknown scopes and invalid metadata panic, like the SDK's typed registration. Metadata is copied; caller edits cannot alter a registration. An unregistered or hidden tool gets the SDK's unknown tool error and never reaches a handler.
func BearerTransport ¶
func BearerTransport(token string, base http.RoundTripper) http.RoundTripper
BearerTransport returns an http.RoundTripper that presents token as the bearer credential on every request through base (http.DefaultTransport when nil): the client side of an Endpoint.
func Connect ¶
func Connect(ctx context.Context, server *mcp.Server, client mcp.Implementation) (*mcp.ClientSession, *mcp.ServerSession, error)
Connect returns a client session connected to server over an in-memory transport. Callers close the client session and wait for the server one. Client metadata is supplied by the caller.
func HTTPHandler ¶
HTTPHandler serves srv over streamable HTTP to a client presenting token as its bearer credential, and answers 401 to any other request. The SDK's own guard, which refuses a request to a loopback listener whose Host header is not a loopback name, is switched off: it protects a local server from a browser tricked into reaching it (DNS rebinding), which the token does here, and the container reaches the loopback listener through the host's alias, which is exactly such a Host header.
func IsCleanShutdown ¶
IsCleanShutdown reports whether an error from mcp.Server.Run is an ordinary end of session rather than a failure. A client closes the server's stdin when it is done with it and kills the process on shutdown; neither is worth a nonzero exit status, which the client would record as the server having crashed.
func Run ¶
Run serves any SDK transport, including StdioTransport, until closure or cancellation. Normal client closure is successful shutdown.
func SchemaFor ¶
func SchemaFor[In any](enums map[string][]string) *jsonschema.Schema
SchemaFor infers a typed input schema and constrains named properties. Empty value lists leave properties unconstrained. Invalid types/properties panic.
func ServeHTTP ¶
ServeHTTP serves an already-bound listener until cancellation or failure. It owns and closes the listener. An empty token is refused.
func Start ¶
Start serves srv to one turn over streamable HTTP on a fresh loopback port with a fresh bearer token, until the lease is closed or ctx ends. Each call has its own listener and token, so one turn cannot reach another's server. A host turn reaches the loopback; so does a container under Docker Desktop through Endpoint.Via. On Linux a container reaches the host only on the bridge gateway: use StartOn with that address.
func StartMemory ¶
StartMemory is Start without a listener, for tests: the endpoint's URL is a memory:// name nothing outside this process can open, and Lease.Connect reaches the server over an in-memory transport, with no token. Closing the lease, or the end of ctx, closes every session it connected and refuses further ones.
Types ¶
type DoneInput ¶
type DoneInput struct {
Status string `json:"status" jsonschema:"the outcome to report"`
Note string `json:"note,omitempty" jsonschema:"one short line describing the outcome"`
}
DoneInput is the tracker-independent wire format. Callers with an existing wire contract can use their own input type with AddDoneTool.
type DoneOptions ¶
type DoneOptions struct {
Title string
Description string
Statuses []string
Work work.Ref
Report func(context.Context, agent.Outcome) (agent.Outcome, error)
}
DoneOptions supplies workflow policy and default work context. Report must validate the outcome and persist/report it; its returned status is acknowledged to the client. Statuses constrain the schema (empty means unconstrained). Description is the caller's prose; the host appends the valid status list.
type Endpoint ¶
type Endpoint struct {
// URL is the endpoint as the host reaches it.
URL string
// Host and Port are the address the listener is bound to.
Host, Port string
Token string
}
Endpoint is where one turn reaches its server: what an agent's MCP configuration points at. Token is the bearer credential the endpoint requires; hand it to the turn in an environment variable, not an argument.
type Lease ¶
type Lease interface {
Connect(ctx context.Context, client mcp.Implementation) (*mcp.ClientSession, error)
Close() error
}
Lease is one turn's hold on a started server. Close stops the server, frees its endpoint and returns the error serving ended with, if any; it is safe to call more than once. Connect returns a client session of the endpoint for callers that talk to it themselves; over HTTP it presents the endpoint's token.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds typed registrations. Servers are independent snapshots; later registrations do not change existing servers. Handlers must synchronize their own collaborators, but request decoding is private to each call.
func NewRegistry ¶
func NewRegistry(roles []string, empty, unknown RolePolicy) *Registry
NewRegistry takes the complete role set and explicit fallback policies. Invalid policies and empty or duplicate role names are programming errors.
type RolePolicy ¶
type RolePolicy int
RolePolicy determines what an empty or unknown role may see.
const ( RejectRole RolePolicy = iota AllTools NoTools )
Source Files