Interactive Feedback (人机协作反馈)
interactive_feedbackRequests human feedback through a web interface, blocking AI execution until the user provides input, approval, or clarification.
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. | |
| question_type | No | Optional UI mode hint: when ``'yesno'``, the frontend hides the free-text textarea and renders a single-row Yes/No button pair. User's click submits the literal string 'yes' or 'no' as the feedback result — saves typing + Submit-button click for binary decisions (approve/reject, proceed/abort, etc.). Allowed values: ``'yesno'`` (current) or ``None`` (default: keep textarea + optional ``predefined_options`` checkboxes). Unknown values silently treated as None (forward-compat for future types like ``'choice'`` / ``'rating'`` once the frontend supports them). (mining-cycle-3 §2.1 — borrowed from gemini-cli ``ask_user`` schema.) | |
| 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 |