elicit

package
v0.107.36 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

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

View Source
const (
	Accept  = "accept"
	Decline = "decline"
	Cancel  = "cancel"
)

Actions an elicitation ends with, as the MCP server receives them.

View Source
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.

View Source
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.

View Source
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.

View Source
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

View Source
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

func Redact(fields []ai.ElicitField, content map[string]any) (map[string]any, []string)

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.

func With

func With(ctx context.Context, fn Func) context.Context

With returns ctx carrying fn as the front end for elicitations made during tool calls under ctx.

Types

type Errors

type Errors map[string]string

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

func Validate(fields []ai.ElicitField, content map[string]any) (map[string]any, Errors)

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.

func (Errors) Error

func (e Errors) Error() string

type Func

type Func func(context.Context, Request) Response

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.

func Handler

func Handler(ctx context.Context) Func

Handler returns the front end for ctx: the one With set, else Default, else nil.

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.

Jump to

Keyboard shortcuts

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