MCP AI Supervisor

AI 智能监工系统 —— 让 AI 不再半途而废

MCP AI Supervisor 是一个基于 MCP（Model Context Protocol） 的 AI 任务监督工具。它通过 interactive_feedback MCP 工具在 AI 和用户之间建立持续的反馈循环，确保 AI 完整地完成任务。

工作原理

AI 执行任务 → 调用 interactive_feedback → 监工系统处理 → 返回反馈 → AI 继续工作
   ↑                                                                |
   └────────────────────── 循环直到任务完成 ──────────────────────────┘

核心特性

• 三种运行模式 — semi（半自动，默认）/ auto（全自动）/ manual（手动）
• Tauri 桌面弹窗 — 原生弹窗提醒（macOS / Linux / Windows），比浏览器更醒目
• Workbench 控制台 — React + WebSocket 实时多项目管理面板（V4.0）
• 监工 Agent — 可选的 AI 监工（qodercli），自动评估主 AI 的产出质量
• Timeout 自动重试 — 超时不中断，自动提醒 AI 继续等待（可配置最大重试次数和退避策略）
• 消息队列 — AI 忙碌时消息自动排队，空闲时优先投递，支持置顶/编辑/重试
• 多 IDE 支持 — Cursor、Qoder、Claude Code
• 多语言界面 — 简体中文 / 繁体中文 / English

快速安装

方式一：PyPI 安装（推荐）

pip install mcp-ai-supervisor

安装后在 ~/.cursor/mcp.json 中配置：

{
  "mcpServers": {
    "mcp-ai-supervisor": {
      "command": "uvx",
      "args": ["mcp-ai-supervisor"],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "true",
        "MCP_DELEGATE_MODE": "semi",
        "MCP_LANGUAGE": "zh-CN"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}

也可以直接使用 uvx，无需预先安装：

{
  "mcpServers": {
    "mcp-ai-supervisor": {
      "command": "uvx",
      "args": ["mcp-ai-supervisor"],
      "timeout": 600
    }
  }
}

方式二：脚本安装

# 一键远程安装
curl -fsSL https://gitlab.alibaba-inc.com/AIPlayer_TaoJp/mcp-ai-supervisor/raw/main/scripts/install.sh | bash

# 或本地安装
git clone https://gitlab.alibaba-inc.com/AIPlayer_TaoJp/mcp-ai-supervisor.git
cd mcp-ai-supervisor && ./scripts/install.sh

方式三：手动配置

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "mcp-ai-supervisor": {
      "command": "/path/to/mcp-ai-supervisor/.venv/bin/python",
      "args": ["-m", "mcp_ai_supervisor"],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "true",
        "MCP_DELEGATE_MODE": "semi",
        "MCP_LANGUAGE": "zh-CN"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}

关键说明：

• command 必须指向项目 .venv/bin/python（项目虚拟环境中的 Python）
• args 使用 -m mcp_ai_supervisor 启动 MCP Server
• 安装后运行 bash scripts/verify.sh 验证配置是否正确
• 完整环境变量参考见 配置与部署文档

三种模式对比

模式	用户介入	Agent 评估	适用场景
semi（默认）	弹窗倒计时，可随时介入	倒计时到期后自动触发	日常开发
auto	无 UI 弹窗	每轮必须评估	批量任务、夜间跑批
manual	每次等待用户输入	用户可选触发	精细控制场景

---

系统架构

系统分为 MCP Server、Workbench 后端、Workbench 前端、桌面弹窗 四大部分：

┌──────────────────────────────────────────────────────────┐
│                   Cursor / IDE 中的 AI                     │
│         调用 interactive_feedback MCP 工具                  │
└───────────────────────┬──────────────────────────────────┘
                        │ MCP Protocol (stdio)
┌───────────────────────▼──────────────────────────────────┐
│         MCP Server (packages/mcp-server)                   │
│   • interactive_feedback / get_system_info                 │
│   • DelegateManager 核心编排                                │
│   • WorkbenchClient → 上报消息到 Workbench                  │
└───────────────────────┬──────────────────────────────────┘
                        │ HTTP API
┌───────────────────────▼──────────────────────────────────┐
│      Workbench Server (packages/workbench-server)          │
│   ┌─────────────┬──────────────┬──────────────────────┐   │
│   │ AgentRegistry│ ProjectQueue │ ConversationStore    │   │
│   │ UnreadTracker│ WSManager    │ LogWriter/Parser     │   │
│   └─────────────┴──────────────┴──────────────────────┘   │
│   REST API: /api/projects, /api/messages, /api/queue ...   │
│   WebSocket: /ws (init_snapshot, new_message, ...)         │
└───────────────────────┬──────────────────────────────────┘
                        │ HTTP + WebSocket
┌───────────────────────▼──────────────────────────────────┐
│       Workbench UI (packages/workbench-ui)                 │
│   React 19 + TypeScript + Vite                              │
│   状态管理: useReducer + Context                             │
│   实时通信: WebSocket (自动重连/心跳)                          │
│   组件: ProjectList / MessageList / QueuePanel / LogViewer  │
└──────────────────────────────────────────────────────────┘

项目结构

mcp-ai-supervisor/                     # Monorepo (uv workspace)
├── packages/                          # 5 个子包
│   ├── core/                          # mcp-supervisor-core：基础设施（日志/路径/i18n/错误处理）
│   ├── mcp-server/                    # mcp-ai-supervisor：MCP Server 核心（交互反馈/Web UI）
│   ├── workbench-server/              # mcp-supervisor-workbench：Workbench 后端（多项目控制台）
│   ├── workbench-ui/                  # Workbench 前端（React 19 + TypeScript + Vite）
│   └── desktop/                       # Tauri 桌面应用（Rust + PyO3）
├── artifacts/desktop/                  # 预编译桌面应用二进制（构建产物）
├── tests/                             # 后端测试（pytest，1020+ 用例，~11s 并行）
├── scripts/                           # 安装/部署/工具脚本
│   ├── dev/                           # 开发工具（代码分析/对话提取/迁移）
│   └── test/                          # 测试工具（E2E 轮询/消息投递验证）
├── docs/                              # 项目文档
│   ├── 项目介绍/                     # 模块技术文档（渐进式阅读指南）
│   ├── 工程重构/                     # Monorepo 重构方案与进度
│   ├── 控制台方案/                   # Workbench V4.0 设计
│   ├── AI监工方案/                   # AI 监工功能设计
│   ├── 配置模板/                     # Cursor/Qoder Rule 和 Command 模板
│   ├── 相关资料/                     # 外部参考文档
│   └── temp/                         # 临时方案文档（实施完成后归档或删除）
└── .cursor/rules/                     # Cursor AI 规则配置

各子包的详细设计见：

• packages/core/README.md — 基础设施包
• packages/mcp-server/README.md — MCP Server
• packages/workbench-server/README.md — Workbench 后端
• packages/workbench-ui/README.md — Workbench 前端
• packages/desktop/README.md — 桌面应用

Workbench 控制台（V4.0）

Workbench 是一个实时多项目管理面板，核心能力：

功能	说明
项目列表	实时显示在线/离线项目，WS 广播状态变化
对话消息	AI/用户消息实时展示，支持历史翻页
消息队列	Agent 忙碌时消息排队，空闲时自动投递，支持置顶
未读角标	按项目追踪未读数，切换自动标记已读
日志查看	多日志源、级别过滤、关键词搜索、日期切换
会话浏览	历史对话按日期/项目浏览，可打开本地文件夹
主题切换	dark / light / system 三种主题
WebSocket	init_snapshot、5 种上行、心跳保活、自动重连

详细架构文档见 11-Workbench 控制台。

启动 Workbench

# 1. 启动后端服务（端口 9765）
.venv/bin/python3 -m mcp_supervisor_workbench --port 9765

# 2. 启动前端开发服务器（端口 9766）
cd packages/workbench-ui && npm run dev

前端通过 Vite proxy 将 /api/* 和 /ws 请求转发到后端。详见 packages/workbench-ui/README.md。

Workbench 设计文档

文档	内容
总体设计	架构总览与数据流
后端架构	6 大核心模块设计
前端架构	状态管理/组件/Hooks/WebSocket
API 设计	8 组 API（A1-A8）规范
日志系统	LogWriter/Parser/Tailer/API
落地实施顺序	5 阶段实施路线图
系统集成分析	端到端集成状态

测试

# 后端测试（pytest，1020+ 用例，~11s 并行执行）
cd /path/to/mcp-ai-supervisor
.venv/bin/python3 -m pytest          # 默认并行（-n auto）
.venv/bin/python3 -m pytest -n 0     # 串行执行
.venv/bin/python3 -m pytest -m unit  # 仅 unit 测试（876 个）

# 前端测试（vitest，210+ 用例）
cd packages/workbench-ui && npm test

# 测试优化详情见 docs/工程重构/09-后端测试优化方案.md

对话历史工具

scripts/dev/conversation_extract.py 用于提取、统计、搜索和管理对话历史，零外部依赖。

查看项目列表

python scripts/dev/conversation_extract.py list

提取对话内容

以 AI 问 + 用户答的成对方式清晰展示完整对话：

# 今天的对话（默认 pair 模式，AI/用户成对展示）
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --today

# 最近 3 天
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --days 3

# 只看用户回复
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --today --mode user

# 只看 AI 回复
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --today --mode ai

# 看原始任务列表
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --today --mode task

# 按日期范围
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --from 07-10 --to 07-15

# 输出到文件（支持 text / json / markdown / csv）
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --days 7 --format json -o output.json
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --days 7 --format markdown -o report.md

# 项目支持模糊匹配：名称、hash、序号均可
python scripts/dev/conversation_extract.py extract 1 --today          # 用序号
python scripts/dev/conversation_extract.py extract tao --days 3       # 模糊匹配

查看统计

# 项目统计（按天汇总会话数/轮次/来源分布/高频修改文件）
python scripts/dev/conversation_extract.py stats mcp-ai-supervisor --days 7

# 全局统计（所有项目活跃度排名 + 柱状图）
python scripts/dev/conversation_extract.py stats --days 7

搜索对话

# 全局搜索
python scripts/dev/conversation_extract.py search "心跳"

# 限定项目搜索
python scripts/dev/conversation_extract.py search "心跳" mcp-ai-supervisor --today

# 正则搜索
python scripts/dev/conversation_extract.py search "bug|fix" --regex

删除对话数据

# 删除整个项目数据（交互确认）
python scripts/dev/conversation_extract.py delete dir

# 删除指定日期范围
python scripts/dev/conversation_extract.py delete dir --days 30       # 删除最近 30 天
python scripts/dev/conversation_extract.py delete dir --from 07-01 --to 07-10

# 跳过确认
python scripts/dev/conversation_extract.py delete dir --days 30 -y

其他辅助工具

命令	说明
bash scripts/verify.sh	验证安装完整性
bash scripts/view_logs.sh	查看日志指引
bash scripts/uninstall.sh	完全卸载

深入了解

项目按模块组织了详细的技术文档，建议按以下顺序渐进式阅读：

顺序	文档	内容	建议阅读时机
0	项目概述	架构总览、模块关系图	初次了解项目
1	MCP 服务层	server.py、工具定义、编码初始化	理解入口和 MCP 协议
2	核心编排引擎	DelegateManager、TaskState、模式分发	理解核心逻辑
3	监工 Agent 系统	AgentBridge、AutoResponder、评估流程	理解 Agent 评估机制
4	Web 通信层	FastAPI、WebSocket、REST API	理解前后端通信
5	前端 UI	JS 模块架构、模板系统	需要修改弹窗 UI 时
6	桌面应用	Tauri、Rust-Python 桥接	需要修改桌面弹窗时
7	基础设施	资源管理、内存监控、日志、错误处理、i18n	需要了解底层机制时
8	配置与部署	环境变量、MCP 配置、安装脚本	部署或自定义配置时
11	Workbench 控制台	Workbench 后端/前端架构、消息队列、WebSocket	需要了解 Workbench 时

Cursor MCP 进程机制

Cursor 在启动时会为配置了 MCP 的项目创建 MCP 进程（通过 stdio 协议）。以下是关键机制：

• 进程共享：同一个 Cursor 窗口中的多个 Agent 对话 共享同一个 MCP 进程。不同项目如果在同一个 Cursor 窗口中打开，也共享同一个 MCP 进程
• Web Server 端口：MCP 进程启动时会绑定一个动态端口（port=0 由 OS 分配），用于接收 Workbench 投递的用户消息。所有项目共用同一个 web_url
• 进程重启：部署脚本 (deploy.sh) 通过修改 ~/.cursor/mcp.json 中的 MCP_RELOAD_TS 环境变量触发 Cursor 重启 MCP 进程。旧进程会短暂残留，新进程逐步替代
• Agent 注册：每个项目在调用 interactive_feedback 时自动向 Workbench 注册 Agent，上报 project_directory、agent_id、web_url 等信息，Workbench 通过 project_directory 区分不同项目
• 心跳：MCP 进程内的 WorkbenchClient 每 30 秒发送心跳；Workbench 的 AgentRegistry 在 90 秒无心跳后标记 Agent 为 offline

项目规则

1. 所有文档统一存放在 docs/ 目录下，按主题组织子目录
2. 文档采用渐进式写法：主文档写概要并链接子文档，子文档详细展开
3. 文件名使用中文，便于快速识别内容
4. 代码注释使用中文，核心方法需要有注释，类文件头部要有注释

技术栈

• 后端: Python 3.11+, FastMCP, FastAPI, WebSocket, aiohttp
• Workbench 前端: React 19, TypeScript, Vite 8, CSS Modules
• 原版弹窗前端: HTML/CSS/JS（模块化 IIFE）
• 桌面: Tauri (Rust), 预编译二进制
• 测试: pytest (后端 1020+), vitest + @testing-library/react (前端 210+)
• 协议: MCP (Model Context Protocol)

许可证

MIT License