# MCP Keep Feedback（交互反馈 MCP）

> **📋 项目来源：** 本项目基于 [Minidoracat/mcp-feedback-enhanced](https://github.com/Minidoracat/mcp-feedback-enhanced) 改造而来，特此致谢！

## 针对 Cursor：变相提高使用额度

本项目**主要面向 [Cursor](https://www.cursor.com)** 用户，用于**变相提高可用额度**：

- 在 Cursor 中，**每发起一次提问**或**每次使用子代理**都会消耗一次额度。
- 使用本工具后，AI 通过 **MCP 工具** 把多步结果汇总成一次汇报，在 **Web 界面** 上与你确认；你只需在浏览器里点选/输入并提交，AI 再根据反馈继续，**无需在对话里多次发问**。
- 这样可以把「多次对话轮次」收敛为「一次提问 + 多次 MCP 反馈」，从而**减少提问次数、节省额度**，同时保持「先确认再执行」的节奏，减少误操作。
- **节约效果**：在需要多轮确认的场景下，至少可节约 **3～4 倍** 额度（例如从 500 次等效扩容到约 2000 次）。

下面用流程图对比「不用本工具」与「使用本工具」时额度的消耗方式：

```mermaid
flowchart TB
  subgraph 不用本工具["不用本工具：每轮确认都算一次提问"]
    direction TB
    A1["用户提问 ①"] -->|消耗 1 次| B1[AI 执行]
    B1 --> A2["用户再提问 ②"]
    A2 -->|消耗 1 次| B2[AI 继续]
    B2 --> A3["用户再提问 ③"]
    A3 -->|消耗 1 次| B3[AI 继续]
    B3 --> A4["用户再提问 ④"]
    A4 -->|消耗 1 次| B4[完成]
    style A1 fill:#f96,color:#000
    style A2 fill:#f96,color:#000
    style A3 fill:#f96,color:#000
    style A4 fill:#f96,color:#000
  end

  subgraph 用本工具["使用本工具：一次提问后循环确认，永不结束"]
    direction TB
    U1["用户提问 ①"] -->|消耗 1 次| V1[AI 执行多步]
    V1 --> W1[MCP 汇报]
    W1 --> X1[用户在 Web 点选/确认]
    X1 -->|不消耗额度| V1
    style U1 fill:#9f9,color:#000
  end
```

- **左图**：用户只在对话里发 1 次提问，后续确认在 Web 里循环进行，不产生新对话消息、不额外消耗额度；理论上可**永不结束**，直到你或 Cursor 端停止。
- **右图**：每轮「用户发一条消息」都计为一次额度，4 轮确认 ≈ 消耗 4 次。

因此同样完成多轮确认，使用本工具可把额度消耗降到约 1/4，**相当于 500 次额度当 2000 次用**。

**使用限制**：有时会遇到 Cursor 页面卡住、网络波动断连或 “Take too long” 等提示。此时需要**手动停止当前会话**，并重新在对话里发送 `call feedback`（或让 AI 再次调用本工具）以重新拉起反馈流程。这是目前的主要限制；否则理论上一次请求可以持续多轮确认而不额外消耗额度。

**支持平台：** [Cursor](https://www.cursor.com)（推荐） | [Cline](https://cline.bot) | [Windsurf](https://windsurf.com) | [Augment](https://www.augmentcode.com) | [Trae](https://www.trae.ai)

**模型建议**：为获得更稳定的反馈与额度节约效果，建议在 Cursor 中使用 **Claude Opus** 或 **Claude Sonnet** 模型。

---

## 核心概念

这是一个 [MCP 服务器](https://modelcontextprotocol.io/)，建立**反馈导向的开发工作流程**，提供 **Web UI**，适配本地、**SSH 远程**与 **WSL**。通过引导 AI 先与用户确认再继续，可将多轮工具调用合并为「单次汇报 → 用户反馈 → AI 继续」的循环，节省平台成本并提升可控性。

### 工作流程

1. **AI 调用** → `mcp-keep-feedback` 工具（传入汇报内容）
2. **界面启动** → 自动打开浏览器 Web UI
3. **智能交互** → 提示词选择、文字输入、图片上传、自动提交
4. **即时反馈** → WebSocket 将你的反馈即时传回 AI
5. **会话追踪** → 自动记录会话历史与统计
6. **流程继续** → AI 根据反馈调整行为或结束任务

## 主要功能

- **Web UI**：轻量级浏览器界面，无需本地 GUI，适合远程和 WSL；环境自动检测（SSH Remote、WSL 等）
- **提示词管理**：常用提示词的 CRUD、使用统计、智能排序
- **永不超时**：会话支持无限期等待用户反馈后再提交
- **独立命令行触发**：可脱离 MCP，在终端直接交互，详见 [独立命令行触发方案](docs/zh-CN/独立命令行触发设计方案.md)
- **自动执行命令**：新建会话和提交后可自动执行预设命令

---

## 独立模式（Standalone Mode）

即使不接 MCP，也可在终端使用：

1. **触发反馈**（自动管理后台服务）：
   ```bash
   echo "任务汇报内容" | uv run python -m mcp_keep_feedback feedback
   ```
2. **手动管理服务**（可选）：
   - 启动：`uv run python -m mcp_keep_feedback web`
   - 停止：`uv run python -m mcp_keep_feedback stop`

AI 会在终端阻塞等待你的反馈。

---

## 快速开始

### Web UI 示意

<div align="center">
  <img src="docs/images/web1.png" width="400" alt="Web UI 主界面 - 提示词管理与自动提交" />
</div>

<details>
<summary>📱 点击查看完整界面截图</summary>

<div align="center">
  <img src="docs/images/web2.jpeg" width="800" alt="Web UI 完整界面 - 会话管理与设置" />
</div>

</details>

### 1. 安装与测试

```bash
# 安装 uv（如果尚未安装）
pip install uv
```

### 2. 配置 MCP（Cursor）

在 Cursor 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "mcp-keep-feedback": {
      "command": "uvx",
      "args": [
        "mcp-keep-feedback"
      ],
      "timeout": 604800,
      "env": {
        "MCP_DEBUG": "false",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_DESKTOP_MODE": "false",
        "MCP_LANGUAGE": "zh-CN"
      },
      "autoApprove": [
        "interactive_feedback"
      ]
    }
  }
}
```

### 3. 提示工程

为获得最佳效果，建议在 Cursor Settings 的 Rules 中配置提示工程规则，详见 [提示工程设置指南](docs/prompt-engineering.md)。

---

## 高级设置

### 环境变量

| 变量 | 用途 | 值 | 默认 |
|------|------|-----|------|
| `MCP_DEBUG` | 调试模式 | `true`/`false` | `false` |
| `MCP_WEB_HOST` | Web UI 绑定地址 | IP 或主机名 | `127.0.0.1` |
| `MCP_WEB_PORT` | Web UI 端口 | 1024–65535 | `8765` |
| `MCP_LANGUAGE` | 界面语言 | `zh-TW`/`zh-CN`/`en` | 自动检测 |
| `MCP_AUTO_REPLY_TIMEOUT` | 自动回复超时（分钟） | 整数 | `0`（禁用） |

- **`MCP_WEB_HOST`**：`127.0.0.1` 仅本机；`0.0.0.0` 允许远程（如 SSH 开发）。
- **`MCP_LANGUAGE`**：强制界面语言，覆盖系统检测。

### 测试命令

```bash
uvx mcp-keep-feedback@latest version
uvx mcp-keep-feedback@latest test --web
MCP_LANGUAGE=zh-CN uvx mcp-keep-feedback@latest test --web
```

### 开发者安装

```bash
git clone https://github.com/Minidoracat/mcp-keep-feedback.git
cd mcp-keep-feedback
uv sync
```

```bash
make test-func
make test
make check
```

## 常见问题

### SSH Remote / 远程

**Q: 浏览器打不开或无法访问 Web UI**  
A: 在 MCP 配置中设置 `"MCP_WEB_HOST": "0.0.0.0"`，然后在本地浏览器访问 `http://[远程主机IP]:8765`。或使用 SSH 端口转发 8765，访问 `http://localhost:8765`。详见 [SSH Remote 使用指南](docs/zh-CN/ssh-remote/browser-launch-issues.md)。

**Q: 收不到新反馈**  
A: 多为 WebSocket 问题，刷新浏览器页面即可。

**Q: MCP 没被调用**  
A: 确认 MCP 工具为绿灯，可反复开关 MCP 等待重连。

### 一般

**Q: "Unexpected token 'D'"**  
A: 调试输出干扰，设置 `MCP_DEBUG=false` 或移除该变量。

**Q: 客户端（如 Cursor）自己超时**  
A: 本工具无超时，但客户端常有 5–10 分钟限制，可缩短单次反馈时间或调整客户端设置。

**Q: UV Cache 占用大**  
A: 使用 `uv cache clean` 或项目内 `python scripts/cleanup_cache.py`，详见 [Cache 管理](docs/zh-CN/cache-management.md)。

## 授权

MIT - 详见 [LICENSE](LICENSE)

