Metadata-Version: 2.4
Name: cloneloop
Version: 0.1.4
Summary: CloneLoop - Clone your work patterns from conversations, let AI execute by your standards continuously.
Author: 淘日本技术团队
Keywords: ai,cloneloop,development,interactive,mcp,skill,supervisor
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: mcp-supervisor-core>=0.1.0
Requires-Dist: mcp-supervisor-workbench>=0.1.3
Requires-Dist: mcp>=1.9.3
Requires-Dist: psutil>=7.0.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: websockets>=13.0.0
Description-Content-Type: text/markdown

# mcp-ai-supervisor (MCP Server)

MCP AI Supervisor 的核心 MCP 服务器。实现 [Model Context Protocol](https://modelcontextprotocol.io/) 协议，为 AI 编程助手提供交互式反馈和任务监督能力。

## 包信息

- **包名**: `mcp-ai-supervisor`
- **模块名**: `mcp_ai_supervisor`
- **版本**: 0.1.0
- **依赖**: `mcp-supervisor-core`, `mcp-supervisor-workbench`, `fastmcp`, `fastapi`, `uvicorn`, `psutil`, `jinja2`, `websockets`, `mcp`

## 启动方式

```bash
# 通过 python -m 启动（Cursor MCP 使用此方式）
python -m mcp_ai_supervisor

# 通过入口点启动
mcp-ai-supervisor
```

Cursor MCP 配置（`~/.cursor/mcp.json`）：
```json
{
  "mcpServers": {
    "mcp-ai-supervisor": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "mcp_ai_supervisor"]
    }
  }
}
```

## 架构概览

```
MCP Server (本包)
├── MCP 协议层          server.py — FastMCP 工具注册
├── Web UI 层           web/ — 弹窗 UI + WebSocket 通信
├── Workbench 连接层    workbench/ — 代理模块，转发到 workbench-server
├── 桌面应用层          desktop_app/ — Tauri 桌面应用集成
└── 基础设施层          log_writer.py, utils/ — 代理模块，转发到 core
```

## 模块结构

### 顶层模块

| 模块 | 说明 |
|------|------|
| `server.py` | **MCP 入口** — 注册 `interactive_feedback` 和 `get_system_info` 工具 |
| `__main__.py` | CLI 入口，解析参数，启动 MCP 服务器和 Workbench |
| `i18n.py` | 代理模块 → `mcp_supervisor_core.i18n` |
| `log_writer.py` | 代理模块 → `mcp_supervisor_core.log_writer` |
| `debug.py` | 代理模块 → `mcp_supervisor_core.debug` |

### `web/` — Web UI 交互层

弹窗式反馈收集 UI 的后端实现。

| 目录/模块 | 说明 |
|-----------|------|
| `web/main.py` | `WebUIManager` — Web UI 生命周期管理 |
| `web/core/` | 核心业务逻辑 |
| `web/managers/` | 子系统管理器 |
| `web/models/` | 数据模型和会话状态 |
| `web/routes/` | FastAPI 路由 |
| `web/templates/` | Jinja2 HTML 模板 |
| `web/static/` | 前端静态资源（JS/CSS） |
| `web/utils/` | 工具函数 |
| `web/constants/` | 常量定义 |
| `web/locales/` | 多语言翻译文件 |

#### `web/core/` 核心模块

| 模块 | 核心类 | 说明 |
|------|--------|------|
| `feedback_mediator.py` | `FeedbackMediator` | 反馈收集中介 — 协调 Web UI、Workbench、自动回复三个反馈来源 |
| `message_channel.py` | `MessageChannel` | 消息聚合通道 — 合并多条消息后统一投递 |
| `delegate_manager.py` | `DelegateManager` | 委托管理 — 处理 Workbench → MCP Agent 的反馈投递 |
| `auto_responder.py` | `AutoResponder` | 自动回复 — semi 模式下的倒计时自动回复 |
| `response_builder.py` | `ResponseBuilder` | 响应构建 — 构造 MCP 工具返回值 |
| `agent_bridge.py` | `AgentBridge` | Agent 桥接 — Workbench Agent 注册/心跳 |
| `scene_detector.py` | `SceneDetector` | 场景检测 — 判断当前运行环境 |
| `task_state.py` | `TaskState` | 任务状态 — 追踪 AI 声称完成的次数和状态 |
| `conversation_recorder.py` | `ConversationRecorder` | 对话记录 — 保存每轮交互历史 |
| `context_collector.py` | `ContextCollector` | 上下文收集 — 收集项目/环境信息 |

#### `web/managers/` 子系统管理器

| 模块 | 核心类 | 说明 |
|------|--------|------|
| `session_manager.py` | `SessionManager` | 会话管理 — 创建/获取/清理反馈会话 |
| `server_manager.py` | `ServerManager` | 服务器管理 — 启动/停止 Uvicorn HTTP 服务 |
| `desktop_manager.py` | `DesktopManager` | 桌面管理 — 启动/管理 Tauri 桌面窗口 |
| `workbench_connector.py` | `WorkbenchConnector` | Workbench 连接器 — 启动/连接 Workbench 后端服务 |

#### `web/models/` 数据模型

| 模块 | 核心类 | 说明 |
|------|--------|------|
| `feedback_session.py` | `WebFeedbackSession` | 反馈会话 — 包含完整的用户-AI 交互生命周期 |
| `feedback_result.py` | `FeedbackResult` | 反馈结果 — 封装用户反馈数据 |
| `session_cleaner.py` | `SessionCleaner` | 会话清理 — 自动清理过期会话 |
| `session_commands.py` | `SessionCommands` | 会话命令 — 处理用户输入的命令 |
| `session_resolver.py` | `SessionResolver` | 会话解析 — 匹配请求到正确的会话 |
| `session_timer.py` | `SessionTimer` | 会话计时 — 超时管理 |

### `workbench/` — Workbench 代理模块

代理模块，将 `from mcp_ai_supervisor.workbench.xxx` 的导入透明转发到 `mcp_supervisor_workbench` 包。确保 MCP Server 内部使用 `mcp_ai_supervisor.workbench.*` 的代码无需修改。

### `helpers/` — 辅助函数

| 模块 | 说明 |
|------|------|
| `feedback_helpers.py` | 反馈文本构建（从 `server.py` 提取，解决循环依赖） |
| `image_helpers.py` | 图片处理（Base64 编解码、文件保存） |

## MCP 工具

本服务器注册了 2 个 MCP 工具：

### `interactive_feedback`

核心工具 — AI 完成工作后调用，等待用户反馈。

参数：
- `summary` (必填): 本轮工作摘要
- `intention` (必填): 下一步计划
- `project_directory` (可选): 项目目录
- `original_task` (可选): 原始任务描述
- `task_complete` (可选): 是否声明完成
- `changed_files` (可选): 修改的文件列表
- `timeout` (可选): 等待超时秒数

### `get_system_info`

获取系统信息（MCP 版本、运行环境等）。

## 工作流程

```
1. Cursor 启动 MCP Server (python -m mcp_ai_supervisor)
2. AI 完成工作后调用 interactive_feedback
3. server.py 创建 WebFeedbackSession
4. FeedbackMediator 同时等待 Web UI / Workbench / 自动回复
5. 用户通过弹窗或 Workbench 提交反馈
6. 反馈结果返回给 AI，循环继续
```

## 安装

```bash
# 在 monorepo 根目录
uv sync
```
