Documentation
¶
Overview ¶
Package mcpkit is the product-neutral half of a product's MCP server: the server and its stdio transport, the profile a call is for, progress notifications while the human decides, the untrusted-data framing of results, the "no console" answer naming the start command, refusals as structured tool errors and exact large integers. A product declares its own tools with the SDK (mcp.AddTool) and keeps their names, descriptions and texts; mcpkit holds no secret and no connection.
SDK: github.com/modelcontextprotocol/go-sdk/mcp v1.8.0.
Index ¶
- Constants
- func Exact(v any) any
- func ExactRows(rows [][]any) [][]any
- func New(p kit.Product, version, instructions string) *mcp.Server
- func NoConsole(p kit.Product, profile string, err error) (start, hint string, ok bool)
- func NoConsoleLine(profile, hint string) string
- func NonNil[T any](s []T) []T
- func PendingText(lock, ticket string) string
- func Progress(ctx context.Context, req *mcp.CallToolRequest, every time.Duration, ...) (stop func())
- func ProgressInterval(d time.Duration) time.Duration
- func ProtocolVersions() []string
- func Refused(err error) (res *mcp.CallToolResult, info *refusal.Info, ok bool)
- func RequesterFromEnv() ipc.Requester
- func Serve(ctx context.Context, s *mcp.Server, r io.Reader, w io.Writer) error
- func Text(s string) *mcp.CallToolResult
- func Untrusted(what, source string) string
- func WaitingMessage(p kit.Product) func(time.Duration) string
- type PendingResult
- type Profiles
- type ToolError
Constants ¶
const ( EnvAgent = "LEA_AGENT" EnvAgentToken = "LEA_AGENT_TOKEN" )
Environment variables lea sets in every agent it starts.
const DefaultProgressEvery = 5 * time.Second
DefaultProgressEvery is how often Progress reports while the human decides. It stays well under the 10 s that clients tolerate.
const StatusPending = "pending"
StatusPending is the status of a request waiting for the human on the approval hub.
Variables ¶
This section is empty.
Functions ¶
func Exact ¶
Exact returns v, or, for an integer outside ±2^53, its decimal string. It handles json.Number, int, int64, uint and uint64 (the narrower integer types cannot leave that range). The SDK decodes structured output into float64 values when it validates it, which would silently change such ids; the text rendering keeps them as they are.
func New ¶
New returns p's MCP server, reported to the client as p.Name and version ("dev" when empty), with the server instructions shown to the model. It accepts the ProtocolVersions only.
func NoConsole ¶
NoConsole tells, for an error of a dial to profile's console, whether no console runs; then start is the command that starts it (`lox run`) and hint what the agent must ask of the user (client.StartHint).
func NoConsoleLine ¶
NoConsoleLine is the line a status text gives for a profile without a console.
func NonNil ¶
func NonNil[T any](s []T) []T
NonNil returns s, or an empty slice for nil, so that structured output holds [] and not null.
func PendingText ¶ added in v0.3.0
PendingText is the fixed text of a pending answer.
func Progress ¶
func Progress(ctx context.Context, req *mcp.CallToolRequest, every time.Duration, message func(waited time.Duration) string) (stop func())
Progress sends a progress notification at once and then every ProgressInterval(every) until the returned stop is called, when the request carries a progress token. message gets the time waited so far. It keeps clients from timing out while the human decides.
func ProgressInterval ¶
ProgressInterval is d when it lies in (0, 10s), else DefaultProgressEvery.
func ProtocolVersions ¶ added in v0.17.0
func ProtocolVersions() []string
ProtocolVersions returns the MCP revisions the servers of New accept, newest first.
func Refused ¶
Refused returns the error result of a refusal (a *ToolError with a Refusal) with its structured form, or ok false for any other error. A tool returns the result with its output, not the error, so the model gets both the text and the structured refusal.
func RequesterFromEnv ¶ added in v0.3.0
RequesterFromEnv is the requester the MCP server reports in its plan and run requests: the agent's name from lea's environment and the hash of its token (plans.HashToken), empty outside lea. The raw token never leaves the agent's process: the console only compares tokens, and a hash compares the same (it is just as replayable; the binding is no security boundary).
func Serve ¶
Serve runs s on r and w (the agent's stdin and stdout: w carries only the protocol) until the client disconnects or ctx ends; both are a clean end (nil). Neither r nor w is closed.
Serve adds the outermost receiving middleware of s (add a product's own before): it gives every tools/call result the resultType that a client at revision 2026-07-28 or later requires, also when a product's middleware replaced the SDK's result with its own.
Types ¶
type PendingResult ¶ added in v0.3.0
type PendingResult struct {
Status string `json:"status"` // StatusPending
Ticket string `json:"ticket"`
Lock string `json:"lock"`
// Instance is the lock instance the ticket is on (the console's
// --instance), set in hub mode.
Instance string `json:"instance,omitempty"`
}
PendingResult is the structured content of a pending answer, shared by every lock: a hook of the agent's harness reads status, ticket and lock to suspend the agent until the ticket is decided. A tool with a typed output embeds it (its fields at the top level of the output).
func Pending ¶ added in v0.3.0
func Pending(lock, ticket string) (*mcp.CallToolResult, PendingResult)
Pending is the answer of a run that waits for the human on the hub: not an error, the fixed text, and the structured PendingResult (also returned, for a tool with a typed output, whose output the SDK puts in the structured content).
func PendingOn ¶ added in v0.3.0
func PendingOn(lock, instance, ticket string) (*mcp.CallToolResult, PendingResult)
PendingOn is Pending for a ticket on lock instance instance ("" none: the answer of Pending).
type Profiles ¶
type Profiles struct {
Product kit.Product
// Pinned pins the server to one profile (`<name> mcp --profile P`).
// Empty lets the tool argument choose among the configured profiles.
Pinned string
// List returns the configured profile names. It is called on every
// call, so profiles added to the config are seen. Nil means only an
// explicit or pinned profile is accepted, unchecked.
List func() ([]string, error)
}
Profiles resolves the profile of a tool call.
Source Files