NAME

mcp-ask-user - ask the human questions through MCP

SYNOPSIS

mcp-ask-user --stdio
mcp-ask-user --name questions --print-url

DESCRIPTION

mcp-ask-user lets an assistant ask you a question when it needs clarification or a choice before continuing. ask-user asks one question; ask-form accepts a generic MCP form schema. By default, a local helper displays the form using YAD or a terminal and returns your answer to the caller. --ask mcp uses your MCP client's form interface instead.

Each ask-user call asks one question, with up to three suggested answers and a free-text answer field. You can also decline or cancel the question; these are returned as distinct results.

Run it as an MCP server connected to your client, or include it among the servers configured in mcp-multibroker. A spawned instance delegates presentation to that broker unless you explicitly give it --ask. The broker's ask mode then selects local prompting or upstream elicitation. See AnyEvent::MCP::Intro for configuring server connections.

FIRST USE

Configure your MCP client to launch mcp-ask-user --stdio. Then ask the assistant to call ask-user with these arguments:

{
  "question": "Which part of the project should we inspect first?",
  "options": [
    {"label": "Tests"},
    {"label": "Documentation"}
  ]
}

The helper displays a question and returns the chosen or typed answer. By default its dialog appears on the server machine, not necessarily where you are using the MCP client. It needs YAD or a usable /dev/tty. For a remote or headless server, --ask mcp works only if the MCP client supports form elicitation; otherwise configure a local helper.

With a multibroker prefix questions, call questions.ask-user. A spawned child normally delegates presentation to the broker, whose --ask mode selects local or client-side forms. Independently run servers use their own mode. Decline and cancel are distinct results, not permission grants, and do not cause a fallback prompt.

ASK-USER TOOL

In mcp mode, the connected client must support the modern input-challenge protocol and advertise form elicitation. Local prompting also works for legacy callers and clients without form support.

question => $text

Required nonempty question, up to 4096 characters.

id => $id

Question identifier, defaulting to question. Starts with an ASCII letter or underscore, followed by letters, digits, underscores or hyphens, with a total length of at most 64 characters.

header => $text

Optional form heading, up to 64 characters.

options => [{ label => $label, description => $description }...]

Up to three suggested answers. Labels must be nonempty, distinct and no longer than 100 characters. Descriptions are optional, up to 512 characters. Free text remains available whether or not options are supplied.

An accepted response returns { id, status, answer, source }, with status equal to answered and source equal to choice or free_text. Nonblank free text takes precedence over a selected option; it is limited to 4096 characters. Decline and cancel return { id, status } with status equal to declined or cancelled, without an answer. An accepted form containing neither an answer nor a selected option is a tool error.

Input continuations expire after 30 minutes, are bound to the original call and are consumed once. These results use structuredContent and matching JSON text; see "result" in AnyEvent::MCP::Server::Request.

ASK-FORM TOOL

ask-form exposes the form interface directly when you need several fields or types other than a single text answer. For example:

{
   "message": "Choose the download settings.",
   "requestedSchema": {
      "type": "object",
      "required": ["directory", "overwrite"],
      "properties": {
         "directory": {"type": "string", "title": "Destination directory"},
         "overwrite": {"type": "boolean", "title": "Overwrite existing files"}
      }
   }
}

message => $text

Required text explaining what the form asks and why.

requestedSchema => { type => "object", properties => { ... }, ... }

Required MCP form schema. Field names identify the returned values. The tool forwards the schema unchanged, with mode set to form. The selected renderer determines supported schema features and validates the entered values. The default local helper supports its documented flat form subset; unsupported features fail explicitly. Native mode forwards the schema to the MCP client without imposing the local helper's limits.

The result is the ordinary elicitation response, in structuredContent and matching JSON text:

{"action":"accept","content":{"directory":"/tmp/maps","overwrite":false}}
{"action":"decline"}
{"action":"cancel"}

The tool checks the response action and requires object content on acceptance; it does not interpret field names or revalidate content against the schema. Boolean and numeric values retain their JSON types. Decline and cancel carry no content and never trigger a fallback prompt. Native continuations have the same 30-minute lifetime and one-use, original-call binding as ask-user.

OPTIONS

--ask helper runs anyevent-mcp-form-elicitation, or the executable named by PERL_ANYEVENT_MCP_ELICITATION_HELPER. --ask mcp delegates to the client. --ask auto uses native forms when advertised and the helper otherwise. --ask tty and --ask yad force the built-in form renderer's terminal or YAD interface, ignoring the custom helper variable. They never fall back to another interface. A decline never causes another prompt through a different interface. Clients that advertise forms but silently decline them require explicit helper mode.

An explicit --ask wins. Otherwise spawned multibroker instances delegate to the broker; standalone instances use PERL_ANYEVENT_MCP_PERMISSION_ASK or default to helper. The helper receives standard elicitation parameters and returns a standard response; see anyevent-mcp-form-elicitation.

--name, --bind, --token, --stdio, --connect, --print-url and other common server options are described in "mcp_getoptions" in AnyEvent::MCP::Server::Simple. HTTP is the default; --print-url prints the authenticated URL without starting a listener.