ai-intervention-agent 1.6.0

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

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)}

More screenshots (empty state + settings)

_{Empty state (auto switches between dark/light)}

_{Settings (dark)}

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