Interactive Feedback (人机协作反馈)
interactive_feedbackAsks the human to provide feedback through a web UI when the AI agent needs a decision, clarification, approval, or design review before continuing.
Instructions
Ask the human user for interactive feedback through the Web UI.
Use this tool whenever you need a human decision, clarification, confirmation, plan approval, design review, or final sign-off before continuing — especially when the next step has multiple valid approaches, irreversible side effects, or significant trade-offs.
Behavior:
Renders the resolved message (Markdown) and an optional list of options in a Web UI; the user submits text + selected options + optional images.
The call blocks until the user submits, the auto-resubmit countdown expires, or the configured backend timeout is reached.
On success, returns a list of MCP content blocks (text + image) that include the user reply, selected options, and an optional prompt suffix.
On parameter validation failure, raises
ToolErrorso the agent can retry with corrected arguments. On service / task failure, returns a configurable resubmit prompt instructing the agent to call this tool again, instead of silently dropping the request.
Cross-tool compatibility:
summary/promptare accepted as aliases formessageso the samemcp.jsonconfig can target other feedback MCP variants without retraining the agent.optionsis an alias forpredefined_options.project_directory,submit_button_text,timeout,timeout_seconds,feedback_type,priority,language,tags,user_id,task_idare accepted but ignored. They prevent the first-call validation failures observed when an agent reuses arguments shaped for a different feedback MCP server.
Note: this function is not the MCP registration site itself; server.py
wraps it with mcp.tool() to expose it to MCP clients.
R25.2: 函数体首行 import httpx 让下面 except httpx.HTTPError 在运行时
解析符号——本工具被 MCP 客户端首次调用时一次性付 ~55 ms 加载费,而 MCP server
cold-start 路径完全不会进入此函数(server.py 顶层 import 时只是定义而已)。
R44 FastMCP 最佳实践:ctx 关键字参数(FastMCP 自动注入)让本函数可以走
await _emit_ctx_info(ctx, ...) 把 task lifecycle 事件回送给 client
(Cursor / Claude Desktop / ChatGPT Desktop)。client 收到后会在 chat
sidebar 渲染一行进度日志,让人类用户能"看到工具确实在工作、正在等真人
回复",而不是猜"agent 是不是 hung 住了"。ctx 永远 keyword-only 且
默认 None,所以本工具被通过别的入口(pytest 直接调)调用时不会因为缺
ctx 而崩;具体安全语义见 _emit_ctx_info 的 docstring。
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Accepted for compatibility; ignored by this server. | |
| prompt | No | Compatibility alias for `message`. Ignored when `message` is provided. | |
| loop_id | No | Loop engineering: optional stable identifier shared by every feedback round that belongs to the same goal / outer loop (agent-chosen, e.g. 'auth-refactor-2026-07'). Rounds that carry the same loop_id are grouped in the UI so the human reviewer can replay 'which rounds did this objective go through, and what was decided each time'. Length: clamped to 64 characters server-side. Omit for standalone one-shot questions (default behavior unchanged). | |
| message | No | Question, summary, or proposal to display to the human user. MUST be a non-empty string. Supports CommonMark / GitHub-Flavored Markdown (headings, lists, tables, fenced code blocks, links, inline code). Recommended length: 1-2000 characters; soft cap 1,000,000 characters (~1 MB UTF-8, R166); inputs longer than the cap are truncated with a trailing ellipsis marker. Best practices: (1) state the question clearly in the first line; (2) include the recommended/default answer when proposing options; (3) escape special characters properly in JSON (use \" for quotes, \n for newlines). If omitted, the server falls back to `summary` or `prompt` for cross-tool compatibility. | |
| options | No | Compatibility alias for `predefined_options`. Ignored when `predefined_options` is provided. | |
| summary | No | Compatibility alias for `message` (used by noopstudios/Minidoracat interactive-feedback-mcp variants). Ignored when `message` is provided. | |
| task_id | No | Accepted for compatibility (some agents pre-generate a trace ID and pass it through); this server always auto-generates an internal task ID and ignores the externally supplied value. Useful when the same `mcp.json` config also points at MCP variants that *do* honour an externally supplied task ID. | |
| timeout | No | Accepted for compatibility; this server uses its own configured backend timeout and auto-resubmit countdown. | |
| user_id | No | Accepted for compatibility; ignored by this server. | |
| language | No | Accepted for compatibility; UI language follows the user's saved settings. | |
| priority | No | Accepted for compatibility; ignored by this server. | |
| loop_phase | No | Loop engineering: optional free-form phase tag for this round, e.g. 'investigate' / 'implement' / 'verify' / 'review'. Helps the reviewer see where in the inner loop the agent currently is. Length: clamped to 32 characters server-side. | |
| header_label | No | Optional short chip / tag rendered above the prompt in the task pane to give a one-word context cue (e.g. 'Auth', 'DB', 'Layout', 'CSS', 'i18n'). Length: clamped to 16 characters server-side; single-word recommendation, no spaces if avoidable. Especially useful in multi-task mode where the user juggles 3+ concurrent feedback requests — the chip lets them visually distinguish task domains at a glance. If omitted or empty, no chip is shown (default existing layout). (mining-cycle-3 §2.1 — borrowed from gemini-cli ``ask_user.header`` schema.) | |
| feedback_type | No | Accepted for compatibility; ignored by this server. | |
| loop_objective | No | Loop engineering: optional one-sentence description of the loop's goal (e.g. 'Migrate auth/session.py to PyJWT 2.x with green integration tests'). Pass it on the first round of a loop_id; later rounds may omit it. Shown to the reviewer as loop context above the prompt. Length: clamped to 500 characters server-side. | |
| iteration_label | No | Loop engineering: optional round label such as 'iter-3' or 'attempt-2'. Shown with the loop context so multiple rounds of the same loop are distinguishable at a glance. Length: clamped to 32 characters server-side. | |
| timeout_seconds | No | Compatibility alias for `timeout` (used by some MCP clients that explicitly suffix the unit). Both fields are accepted for compatibility — this server ignores them and uses its own configured backend timeout / auto-resubmit countdown. When both are provided, this server logs a debug line and discards both, since neither overrides server config. | |
| success_criteria | No | Loop engineering: optional verifiable completion criteria the human should judge the evidence against (e.g. 'pytest all green + no new ruff warnings + docs regenerated'). Rendered alongside the loop context so the verdict is made against an explicit baseline. Length: clamped to 500 characters server-side. | |
| project_directory | No | Accepted for compatibility with other feedback MCP variants; this server ignores it (project context is taken from the running Web UI / config). | |
| predefined_options | No | Optional list of predefined choices the user can pick from (rendered as multi-select checkboxes alongside a free-text reply). Two canonical input shapes (v1.6.0+ — the legacy parallel-array shape `predefined_options_defaults` was removed in R167; use the dict form below to mark recommended options): (a) **RECOMMENDED** list[dict] of shape {"label": str, "default": bool} — mark the recommended option with `default: true` so the UI shows a pre-checked checkbox (field aliases accepted: "label"/"text"/"value", "default"/"selected"/"checked"); (b) list[str] — simple labels, all initially unchecked (use this when no recommendation is needed). Non-string and non-{label,...} items are silently dropped. Each option max length: 10000 characters (longer items truncated). Tips: (1) keep options short, action-oriented and mutually distinguishable; (2) PREFER the dict form for ANY recommended option — `{"label": "Apply", "default": true}`. The UI renders real pre-checked checkboxes, so do NOT use text-prefix hacks (adding marker words to the label) for marking recommendations; (3) the user may also ignore options and reply with free text. If omitted, the server falls back to `options` for cross-tool compatibility. | |
| submit_button_text | No | Accepted for compatibility; this server uses its own UI labels. | |
| feedback_placeholder | No | Optional textarea placeholder hint shown to the user when waiting for free-text feedback. Per-task override of the global ``page.feedbackPlaceholder`` i18n string. Examples: 'Paste the error stack trace', 'Describe the visual glitch', 'Reply 'ok' to approve or 'no' + reason to reject'. Length: clamped to 200 characters server-side (single-line placeholders only; longer text is silently truncated; the response includes ``placeholder_truncated: true`` + ``placeholder_original_length`` + ``placeholder_max_length`` when clamping activates so callers can warn). If omitted or empty, the UI uses its default i18n placeholder. (mining-cycle-3 §2.1 — borrowed from gemini-cli ``ask_user`` schema.) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |