Documentation
¶
Overview ¶
Package elicit implements the client side of MCP form elicitation: it checks a server's requestedSchema against the restricted subset the specification allows, flattens it into form fields, validates the user's answer against those fields, and carries the hook through which a front end (the TUI, a /v1 client) asks the user.
Index ¶
- Constants
- Variables
- func CheckField(f ai.ElicitField, v any) string
- func Parse(raw json.RawMessage, order []string) ([]ai.ElicitField, error)
- func Redact(fields []ai.ElicitField, content map[string]any) (map[string]any, []string)
- func RedactFor(source string, fields []ai.ElicitField, content map[string]any) (map[string]any, []string)
- func With(ctx context.Context, fn Func) context.Context
- type Errors
- type Func
- type Request
- type Response
Constants ¶
const ( Accept = "accept" Decline = "decline" Cancel = "cancel" )
Actions an elicitation ends with, as the MCP server receives them.
const ( // ReasonUser: the user chose the action. ReasonUser = "user" // ReasonTimeout: nobody answered before the deadline (cancel). ReasonTimeout = "timeout" // ReasonCancelled: the run stopped, or the server withdrew the request // (cancel). ReasonCancelled = "cancelled" // ReasonNoClient: no front end that can show a form is attached // (decline). ReasonNoClient = "no_client" // ReasonUnattended: the run is unattended, so no one can answer // (decline). ReasonUnattended = "unattended" // ReasonLimit: the tool call has already made MaxPerCall elicitations // (decline). ReasonLimit = "limit" )
Reasons say how an action came about. They are K-brain's own: the MCP server sees only the action.
const ( MaxFields = 64 MaxOptions = 100 MaxNameLen = 128 MaxTitleLen = 200 MaxTextLen = 2000 MaxMessageLen = 10000 )
Limits on a requested schema. The specification sets none; they keep a hostile or broken server from sending a form no one can review.
const MaxPerCall = 8
MaxPerCall caps the elicitations one tool call may make; past it the server is declined without asking. It keeps a looping server from holding the user in a stream of forms.
const SourceSSH = "ssh"
SourceSSH marks a request that comes from an SSH server's keyboard-interactive login (SSHManager) rather than an MCP server. Server is then "ssh:<host name>", and RedactFor keeps none of the answers.
Variables ¶
var Formats = []string{"email", "uri", "date", "date-time"}
Formats are the string formats the specification allows.
Functions ¶
func CheckField ¶
func CheckField(f ai.ElicitField, v any) string
CheckField reports what is wrong with v as the value of f ("" when valid). Clients use it to show a message beside a field as the user types.
func Parse ¶
func Parse(raw json.RawMessage, order []string) ([]ai.ElicitField, error)
Parse checks raw, an elicitation's requestedSchema, against the subset MCP allows and returns its properties as fields. order, when it names exactly the schema's properties, is the order the server wrote them in (Go maps lose it); otherwise required properties come first, in required order, then the rest by name. A missing or empty schema is a form with no fields: a plain confirmation.
The subset: a flat object whose properties are each
- string: title, description, minLength, maxLength, pattern, format (email, uri, date, date-time), default;
- string choice: enum (with optional legacy enumNames) or oneOf of {const, title}, default;
- number or integer: title, description, minimum, maximum, default;
- boolean: title, description, default;
- multiple choice: type array, items {type: string, enum} or {anyOf: [{const, title}]}, minItems, maxItems, default;
and required lists property names. Anything else is refused.
func Redact ¶
Redact returns content without the values of sensitive fields, and the names of the fields it left out. The journal and history keep the result; only the MCP server receives the full answer.
func RedactFor ¶ added in v0.107.28
func RedactFor(source string, fields []ai.ElicitField, content map[string]any) (map[string]any, []string)
RedactFor is Redact for a request from source. Answers to an SSH login (SourceSSH) are credentials even when the server echoes them, so none is kept: every answered field is left out.
Types ¶
type Errors ¶
Errors maps a field name to what is wrong with its value. The key "" holds problems that belong to no field, such as an unknown property.
func Validate ¶
Validate checks content, an accepted answer, against fields and returns it in canonical JSON form (string, float64, bool, []any of strings), ready to send to the server. Every key must name a field; required fields must be present and not null; each value must match its field's type and constraints. A null value of an optional field counts as absent.
type Func ¶
Func asks the user. It blocks until the user answers or ctx ends; it must always return one of the three actions.
var Default Func
Default is the front end used when the context carries none. The TUI sets it; nil means no front end.
type Request ¶
type Request struct {
// Source is empty for an MCP server, SourceSSH for an SSH login.
Source string
Server string
Tool string
Message string
Fields []ai.ElicitField
// Schema is the requestedSchema as the server sent it, for clients that
// render JSON Schema themselves.
Schema json.RawMessage
}
Request is an elicitation a front end should show: Server is the configured MCP server name, the identity the user must see.
type Response ¶
type Response struct {
Action string
Content map[string]any
Reason string
// ID is the front end's id for the request (the /v1 elicitation id),
// recorded in history.
ID string
}
Response is how an elicitation ended. Content, for Accept, has been validated against the request's fields by the front end.