Documentation
¶
Overview ¶
Package elicitation provides a Client for requesting structured user input via the MCP elicitation protocol.
The Client is a value type — its zero value is safe to use and acts as a no-op when the connected MCP client does not support elicitation. This mirrors the pattern used by progress.Tracker.
Validation and Safety ¶
SECURITY: All responses are validated against the expected JSON Schema. User input is never trusted and must be sanitized by the caller before use in API calls.
Package elicitation: flow.go implements the multi round-trip request (MRTR, SEP-2322) elicitation flow required by MCP protocol version 2026-07-28, where server-initiated elicitation/create requests are forbidden while serving a tool call. A Flow transparently selects the right mechanism per session:
- Sessions negotiated at protocol >= 2026-07-28 receive an InputRequests map in the tool result and retry the call with InputResponses populated (handled automatically by SDK client middleware). Answers gathered in earlier rounds are carried in the opaque RequestState so multi-step flows survive handler re-invocation.
- Older sessions fall back to the synchronous Client path, which issues elicitation/create requests directly.
Package elicitation: schemas.go holds the JSON Schema builders and response-content parsers shared by the synchronous Client path and the multi round-trip Flow path, so both mechanisms request and validate identical shapes.
Index ¶
- Constants
- Variables
- func CancelledResult(message string) *mcp.CallToolResult
- func ConfirmAction(ctx context.Context, req *mcp.CallToolRequest, message string) *mcp.CallToolResult
- func ConfirmFailedResult(err error) *mcp.CallToolResult
- type Client
- func (c Client) Confirm(ctx context.Context, message string) (bool, error)
- func (c Client) ElicitURL(ctx context.Context, gitlabBaseURL, targetURL, message string) error
- func (c Client) GatherData(ctx context.Context, message string, schema map[string]any) (map[string]any, error)
- func (c Client) IsSupported() bool
- func (c Client) IsURLSupported() bool
- func (c Client) PromptNumber(ctx context.Context, message, fieldName string, minVal, maxVal float64) (float64, error)
- func (c Client) PromptText(ctx context.Context, message, fieldName string) (string, error)
- func (c Client) SelectMulti(ctx context.Context, message string, options []string, minItems, maxItems int) ([]string, error)
- func (c Client) SelectOne(ctx context.Context, message string, options []string) (string, error)
- func (c Client) SelectOneInt(ctx context.Context, message string, options []int) (int, error)
- type Flow
- func (f *Flow) Confirm(ctx context.Context, id, message string) (bool, error)
- func (f *Flow) ElicitURL(ctx context.Context, id, gitlabBaseURL, targetURL, message string) error
- func (f *Flow) GatherData(ctx context.Context, id, message string, schema map[string]any) (map[string]any, error)
- func (f *Flow) InputRequiredResult() *mcp.CallToolResult
- func (f *Flow) IsSupported() bool
- func (f *Flow) PendingError() error
- func (f *Flow) PromptNumber(ctx context.Context, id, message, fieldName string, minVal, maxVal float64) (float64, error)
- func (f *Flow) PromptText(ctx context.Context, id, message, fieldName string) (string, error)
- func (f *Flow) SelectMulti(ctx context.Context, id, message string, options []string, ...) ([]string, error)
- func (f *Flow) SelectOne(ctx context.Context, id, message string, options []string) (string, error)
- func (f *Flow) SelectOneInt(ctx context.Context, id, message string, options []int) (int, error)
- func (f *Flow) UsesMultiRoundTrip() bool
- type InputRequiredError
Constants ¶
const ConfirmExchangeID = "confirm"
ConfirmExchangeID is the stable input-request id used by single-round confirmation guards on the multi round-trip elicitation path.
Variables ¶
var ErrCancelled = errors.New("elicitation: user canceled")
ErrCancelled is returned when the user dismisses an elicitation without making an explicit choice.
var ErrDeclined = errors.New("elicitation: user declined")
ErrDeclined is returned when the user explicitly declines an elicitation.
var ErrElicitationNotSupported = errors.New("elicitation: client does not support elicitation capability")
ErrElicitationNotSupported is returned when the MCP client does not advertise the elicitation capability.
var ErrInputPending = errors.New("elicitation: input request pending client response")
ErrInputPending is returned by Flow prompt methods when the answer is not yet available and an input request has been queued for the client. Handlers must stop and surface Flow.InputRequiredResult (or Flow.PendingError for handlers that return errors) so the client can fulfill the request and retry the call.
var ErrURLElicitationNotSupported = errors.New("elicitation: client does not support URL elicitation")
ErrURLElicitationNotSupported is returned when the MCP client supports form elicitation but not URL mode elicitation.
Functions ¶
func CancelledResult ¶
func CancelledResult(message string) *mcp.CallToolResult
CancelledResult returns a non-error tool result indicating the user canceled.
func ConfirmAction ¶
func ConfirmAction(ctx context.Context, req *mcp.CallToolRequest, message string) *mcp.CallToolResult
ConfirmAction asks the user to confirm an action via elicitation. Returns nil if confirmed or elicitation is not supported (backward compatible). Returns a non-nil *mcp.CallToolResult if the user declined or canceled, or an input-required result when the session uses multi round-trip requests and the client has not answered yet. Any other confirmation failure fails closed with an error result: a destructive action must never proceed on a malformed or failed confirmation exchange.
func ConfirmFailedResult ¶ added in v2.5.3
func ConfirmFailedResult(err error) *mcp.CallToolResult
ConfirmFailedResult returns the fail-closed error result used when a destructive-action confirmation exchange fails for a reason other than an explicit user decision (for example a malformed answer or a transport failure). It instructs the caller to re-send with explicit approval.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client sends elicitation requests to the MCP client for user input. Its zero value is an inactive client where IsSupported returns false.
func FromRequest ¶
func FromRequest(req *mcp.CallToolRequest) Client
FromRequest extracts the server session from a CallToolRequest and returns a Client. If the connected MCP client does not support elicitation, the returned Client is inactive (IsSupported returns false).
func (Client) Confirm ¶
Confirm asks the user a yes/no question and returns true if the user accepted with confirmed=true, false otherwise. Returns ErrDeclined or ErrCancelled if the user did not accept.
func (Client) ElicitURL ¶
ElicitURL sends a URL-mode elicitation request, directing the user to a GitLab page. The URL must belong to the configured GitLab instance (SSRF prevention). Per the MCP 2025-11-25 spec, URL mode requests MUST include a unique elicitationId; one is generated automatically. Returns nil on accept, ErrDeclined, ErrCancelled, or another error.
func (Client) GatherData ¶
func (c Client) GatherData(ctx context.Context, message string, schema map[string]any) (map[string]any, error)
GatherData sends an arbitrary JSON Schema to the client and returns the user's response as a map. This is the low-level method underlying the convenience methods.
SECURITY: The caller is responsible for validating and sanitizing the returned data before using it in API calls.
func (Client) IsSupported ¶
IsSupported returns true if the MCP client supports elicitation.
func (Client) IsURLSupported ¶
IsURLSupported returns true if the MCP client supports URL mode elicitation.
func (Client) PromptNumber ¶
func (c Client) PromptNumber(ctx context.Context, message, fieldName string, minVal, maxVal float64) (float64, error)
PromptNumber asks the user for a numeric input within a range. minVal and maxVal define inclusive bounds; use math.Inf(-1) and math.Inf(1) for no bounds.
func (Client) PromptText ¶
PromptText asks the user for free-form text input and returns the value.
func (Client) SelectMulti ¶
func (c Client) SelectMulti(ctx context.Context, message string, options []string, minItems, maxItems int) ([]string, error)
SelectMulti asks the user to pick one or more options from a list. minItems and maxItems constrain the number of selections (0 means no limit).
type Flow ¶ added in v2.5.3
type Flow struct {
// contains filtered or unexported fields
}
Flow performs elicitation exchanges for a single tool call, selecting the synchronous path for legacy sessions and the multi round-trip path for protocol >= 2026-07-28 sessions. Prompt methods take a stable id that identifies the exchange across handler re-invocations; ids must be unique within one tool call.
func FlowFromRequest ¶ added in v2.5.3
func FlowFromRequest(req *mcp.CallToolRequest) (*Flow, error)
FlowFromRequest builds a Flow for the current tool call. For multi round-trip sessions it decodes the client-echoed RequestState and merges the InputResponses from the retried call. It returns an error when the echoed state is malformed.
func (*Flow) Confirm ¶ added in v2.5.3
Confirm asks the user a yes/no question. See Client.Confirm.
func (*Flow) ElicitURL ¶ added in v2.5.3
ElicitURL sends a URL-mode elicitation request, directing the user to a GitLab page. See Client.ElicitURL.
func (*Flow) GatherData ¶ added in v2.5.3
func (f *Flow) GatherData(ctx context.Context, id, message string, schema map[string]any) (map[string]any, error)
GatherData sends an arbitrary JSON Schema to the client and returns the user's response as a map. See Client.GatherData.
func (*Flow) InputRequiredResult ¶ added in v2.5.3
func (f *Flow) InputRequiredResult() *mcp.CallToolResult
InputRequiredResult builds the tool result carrying the queued input requests plus the accumulated answers encoded as opaque RequestState. The result must be returned as-is, with no content added: the protocol forbids mixing content and inputRequests in one result.
func (*Flow) IsSupported ¶ added in v2.5.3
IsSupported reports whether the MCP client supports elicitation.
func (*Flow) PendingError ¶ added in v2.5.3
PendingError wraps Flow.InputRequiredResult in an InputRequiredError for handlers that report outcomes through an error return.
func (*Flow) PromptNumber ¶ added in v2.5.3
func (f *Flow) PromptNumber(ctx context.Context, id, message, fieldName string, minVal, maxVal float64) (float64, error)
PromptNumber asks the user for a numeric input within a range. See Client.PromptNumber.
func (*Flow) PromptText ¶ added in v2.5.3
PromptText asks the user for free-form text input. See Client.PromptText.
func (*Flow) SelectMulti ¶ added in v2.5.3
func (f *Flow) SelectMulti(ctx context.Context, id, message string, options []string, minItems, maxItems int) ([]string, error)
SelectMulti asks the user to pick one or more options from a list. See Client.SelectMulti.
func (*Flow) SelectOne ¶ added in v2.5.3
SelectOne asks the user to pick one option from a list. See Client.SelectOne.
func (*Flow) SelectOneInt ¶ added in v2.5.3
SelectOneInt asks the user to pick one integer from a list of allowed values. See Client.SelectOneInt.
func (*Flow) UsesMultiRoundTrip ¶ added in v2.5.3
UsesMultiRoundTrip reports whether this flow uses the multi round-trip request mechanism (protocol >= 2026-07-28) instead of synchronous server-initiated elicitation.
type InputRequiredError ¶ added in v2.5.3
type InputRequiredError struct {
// contains filtered or unexported fields
}
InputRequiredError carries an input-required tool result out of handlers that report failures through an error return. Surface wrappers unwrap it with errors.AsType and return the embedded result instead of an error.
func (*InputRequiredError) Error ¶ added in v2.5.3
func (e *InputRequiredError) Error() string
Error implements the error interface.
func (*InputRequiredError) Result ¶ added in v2.5.3
func (e *InputRequiredError) Result() *mcp.CallToolResult
Result returns the input-required tool result to send to the client.
Source Files