ai-intervention-agent 1.6.2

AI Intervention Agent: MCP server enabling real-time user intervention in AI-assisted development workflows.

AI Intervention Agent

Real-time user intervention for MCP agents.

English | 简体中文

When using AI CLIs/IDEs, agents can drift from your intent. This project gives you a simple way to intervene at key moments, review context in a Web UI, and send your latest instructions via interactive_feedback so the agent can continue on track.

Works with Cursor, VS Code, Claude Code, Augment, Windsurf, Trae, and more.

Quick start

Quickest: ask your AI to install it for you

If your IDE/CLI has an AI agent (Cursor, Claude Code, VS Code, Windsurf, Trae, Augment, ...), paste the prompt below in chat and let it write the config for you.

Click to copy the install prompt

Please configure my IDE / AI tool to use the `ai-intervention-agent` MCP server:

1. Locate the correct MCP config file for my current IDE
   (e.g. `.cursor/mcp.json` or `~/.cursor/mcp.json` for Cursor,
    `~/.claude.json` for Claude Code,
    `.vscode/mcp.json` for VS Code).
2. Add this entry under `mcpServers`:
   - command: `uvx`
   - args: `["ai-intervention-agent"]`
   - timeout: 600
   - autoApprove: `["interactive_feedback"]`
3. Append the project's recommended prompt rules
   (the "Prompt snippet (copy/paste)" block in this README)
   to my agent rules / system prompt, so the agent always asks me
   through `interactive_feedback` instead of ending tasks silently.
4. Verify by listing MCP servers and confirming `ai-intervention-agent` is loaded.

Option 1: Using uvx (Recommended)

Configure your AI tool to launch the MCP server directly via uvx (this automatically installs and runs the latest version):

{
  "mcpServers": {
    "ai-intervention-agent": {
      "command": "uvx",
      "args": ["ai-intervention-agent"],
      "timeout": 600,
      "autoApprove": ["interactive_feedback"]
    }
  }
}

Option 2: Using pip

1. First, install the package manually (please remember to manually pip install --upgrade ai-intervention-agent periodically to get updates):

pip install ai-intervention-agent

2. Configure your AI tool to launch the installed MCP server:

{
  "mcpServers": {
    "ai-intervention-agent": {
      "command": "ai-intervention-agent",
      "args": [],
      "timeout": 600,
      "autoApprove": ["interactive_feedback"]
    }
  }
}

[!NOTE] interactive_feedback is a long-running tool. Some clients have a hard request timeout, so the Web UI provides a countdown + auto re-submit option to keep sessions alive.

• Default: feedback.frontend_countdown=240 seconds
• Range: 0 (disabled) or [10, 3600] seconds. The default 240 stays under the common 300s session hard timeout; raise it intentionally when your client allows longer turns.

3. (Optional) Customize your config:

• On first run, config.toml will be created under your OS user config directory (see docs/configuration.md).
• Example:

[web_ui]
port = 8080

[feedback]
frontend_countdown = 240
backend_max_wait = 600

Prompt snippet (copy/paste)

- Only ask me through the MCP `ai-intervention-agent` tool; do not ask directly in chat or ask for end-of-task confirmation in chat.
- If a tool call fails, keep asking again through `ai-intervention-agent` instead of making assumptions, until the tool call succeeds.

ai-intervention-agent usage details:

- If requirements are unclear, use `ai-intervention-agent` to ask for clarification with predefined options.
- If there are multiple approaches, use `ai-intervention-agent` to ask instead of deciding unilaterally.
- If a plan/strategy needs to change, use `ai-intervention-agent` to ask instead of deciding unilaterally.
- Before finishing a request, always ask for feedback via `ai-intervention-agent`.
- Do not end the conversation/request unless the user explicitly allows it via `ai-intervention-agent`.

Screenshots

_{Feedback page · auto switches between dark/light · multi-task tabs with independent countdowns}

More screenshots (empty state + settings)

_{Empty state · waiting for the next interactive request}

_{Settings · notifications · Bark · sound · feedback countdown · auto switches between dark/light}

Key features

• Real-time intervention: the agent pauses and waits for your input via interactive_feedback
• Web UI: Markdown, code highlighting, and math rendering
• Multi-task: tab switching with independent countdown timers
• Auto re-submit: keep sessions alive by auto-submitting at timeout
• Notifications: web / sound / system / Bark (loopback URLs auto-suppressed; LAN-IP suggestion surfaced in settings)
• SSH / LAN friendly: works behind port forwarding; mDNS publishes a <host>.local URL when the local network supports it
• Server self-info resource (aiia://server/info): live runtime / fastmcp version / middleware chain / task-queue snapshot for cross-tool diagnostics
• MCP-spec compliant (2025-11-25 protocol): tool annotations, server identity, and self-contained icons let ChatGPT Desktop / Claude Desktop / Cursor render the server natively without nagging "destructive operation" confirmations
• Production-grade middleware: ErrorHandling + RateLimiting (10 req/s, burst 20) + Timing + Logging chain, with structured task.created / task.completed events forwarded to the MCP client via ctx.info

How it works

1. Your AI client calls the MCP tool interactive_feedback.
2. The MCP server ensures the Web UI process is running, then creates a task via HTTP (POST /api/tasks).
3. The browser (or VS Code Webview) renders the task using a dual-channel transport: SSE (GET /api/events, with Last-Event-ID resume) for real-time updates, and HTTP polling as a safety net when SSE drops.
4. When you submit feedback, the Web UI completes the task in the task queue.
5. The MCP server waits via SSE + a low-frequency HTTP poll (GET /api/tasks/{task_id}), then returns your feedback (text + images) back to the AI client.
6. Optionally, the MCP server triggers notifications (Bark / system / sound / web hints) based on your config. Bark URLs that resolve to loopback addresses are automatically suppressed and the Web UI surfaces a LAN-IP suggestion in the settings panel.

VS Code extension (optional)

Item	Value
Purpose	Embed the interaction panel into VS Code’s sidebar to avoid switching to a browser.
Install (Open VSX)	Open VSX
Download VSIX (GitHub Release)	GitHub Releases
Setting	ai-intervention-agent.serverUrl (should match your Web UI URL, e.g. http://localhost:8080; you can change web_ui.port in config.toml.default)
Other settings	ai-intervention-agent.logLevel (Output → AI Intervention Agent). macOS native notifications are enabled by default and can be toggled in the sidebar's Notification Settings panel. See packages/vscode/README.md for the full settings list and the AppleScript executor security model.

Configuration

Item	Value
Docs (English)	docs/configuration.md
Docs (简体中文)	docs/configuration.zh-CN.md
Default template	config.toml.default (on first run it will be copied to config.toml)

OS	User config directory
Linux	~/.config/ai-intervention-agent/
macOS	~/Library/Application Support/ai-intervention-agent/
Windows	%APPDATA%/ai-intervention-agent/

Architecture

flowchart TD
  subgraph CLIENTS["AI clients"]
    AI_CLIENT["AI CLI / IDE<br/>(Cursor, VS Code, Claude Code, ...)"]
  end

  subgraph MCP_PROC["MCP server process (Python)"]
    MCP_SRV["ai-intervention-agent<br/>(server.py / FastMCP)"]
    MCP_TOOL["MCP tool<br/>interactive_feedback"]
    SVC_MGR["Service manager<br/>(ServiceManager)"]
    CFG_MGR_MCP["Config manager<br/>(config_manager.py)"]
    NOTIF_MGR["Notification manager<br/>(notification_manager.py)"]
    NOTIF_PROVIDERS["Providers<br/>(notification_providers.py)"]
    MCP_SRV --> MCP_TOOL
    MCP_SRV --> CFG_MGR_MCP
    MCP_SRV --> NOTIF_MGR
    NOTIF_MGR --> NOTIF_PROVIDERS
  end

  subgraph WEB_PROC["Web UI process (Python / Flask)"]
    WEB_SRV["Web UI service<br/>(web_ui.py / Flask)"]
    WEB_CFG_MGR["Config manager<br/>(config_manager.py)"]
    HTTP_API["HTTP API<br/>(/api/*)"]
    TASK_Q["Task queue<br/>(task_queue.py)"]
    WEB_FRONTEND["Browser frontend<br/>(static/js/app.js + multi_task.js)"]
    WEB_SRV --> HTTP_API
    WEB_SRV --> TASK_Q
    WEB_SRV --> WEB_CFG_MGR
    WEB_FRONTEND <-->|"SSE /api/events + poll /api/tasks"| HTTP_API
    WEB_FRONTEND -->|submit feedback| HTTP_API
  end

  subgraph VSCODE_PROC["VS Code extension (Node)"]
    VSCODE_EXT["Extension host<br/>(packages/vscode/extension.ts)"]
    VSCODE_WEBVIEW["Webview frontend<br/>(webview.ts + webview-ui.js<br/>+ webview-notify-core.js + webview-settings-ui.js<br/>+ tri-state-panel.js)"]
    VSCODE_EXT --> VSCODE_WEBVIEW
    VSCODE_WEBVIEW <-->|"SSE /api/events + poll /api/tasks"| HTTP_API
    VSCODE_WEBVIEW -->|submit feedback| HTTP_API
  end

  subgraph USER_UI["User interfaces"]
    BROWSER["Browser<br/>(desktop/mobile)"]
    VSCODE["VS Code<br/>(sidebar panel)"]
    USER["User"]
  end

  CFG_FILE["config.toml<br/>(user config directory)"]

  AI_CLIENT -->|MCP call| MCP_TOOL
  MCP_TOOL -->|start/check Web UI| SVC_MGR
  SVC_MGR -->|spawn/monitor| WEB_SRV

  USER -->|input / click| WEB_FRONTEND
  USER -->|input / click| VSCODE_WEBVIEW
  BROWSER -->|load UI| WEB_FRONTEND
  VSCODE -->|render UI| VSCODE_WEBVIEW

  MCP_TOOL -->|"HTTP POST /api/tasks"| HTTP_API
  MCP_TOOL -->|"HTTP GET /api/tasks/{task_id}"| HTTP_API

  WEB_CFG_MGR <-->|read/write + watcher| CFG_FILE
  CFG_MGR_MCP <-->|read/write + watcher| CFG_FILE

  MCP_TOOL -->|trigger notifications| NOTIF_MGR
  NOTIF_PROVIDERS -->|system / sound / Bark / web hints| USER

The diagram intentionally shows top-level processes and the most visible modules. Internal helpers — e.g. state_machine.py (per-task lifecycle), web_ui_mdns.py (LAN service discovery via mDNS), web_ui_security.py (CSRF / origin / token gates), task_queue_singleton.py (single-process queue access), server_feedback.py (the interactive_feedback MCP tool body), enhanced_logging.py, protocol.py, etc. — live in the same two processes and are documented per-module under docs/api/ (English) and docs/api.zh-CN/ (中文).

Documentation

• Docs index (by audience): docs/README.md · docs/README.zh-CN.md
• Scripts index (CI gates / generators / QA): scripts/README.md
• Release notes: CHANGELOG.md · VS Code marketplace listing: packages/vscode/CHANGELOG.md
• Contributing: CONTRIBUTING.md · CODE_OF_CONDUCT.md
• API docs index: docs/api/index.md
• API docs (简体中文): docs/api.zh-CN/index.md
• MCP tool reference: docs/mcp_tools.md
• MCP 工具说明: docs/mcp_tools.zh-CN.md
• Troubleshooting / FAQ: docs/troubleshooting.md · docs/troubleshooting.zh-CN.md
• i18n contributor guide: docs/i18n.md
• DeepWiki: deepwiki.com/xiadengma/ai-intervention-agent

Related projects

• interactive-feedback-mcp
• mcp-feedback-enhanced
• cunzhi
• other interactive-feedback-mcp

Acknowledgements

This project's heritage traces back to Fábio Ferreira (2024) and Pau Oliva (2025), whose original noopstudios/interactive-feedback-mcp and poliva/interactive-feedback-mcp seeded the MCP interactive_feedback tool surface. Their copyright notices are preserved in LICENSE per the MIT license terms. The v1.5.x line is a substantial rewrite — Web UI, VS Code extension, i18n, notification stack, CI/CD pipeline — owned and maintained by @xiadengma (PyPI / Open VSX / VS Code Marketplace publisher).

License

MIT License