Metadata-Version: 2.4
Name: mcp-keep-feedback
Version: 0.2.1
Summary: Enhanced MCP server for interactive user feedback and command execution in AI-assisted development, featuring Web UI with intelligent environment detection and cross-platform compatibility.
Author-email: ffpy <q1411603774@163.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,cross-platform,development,feedback,interactive,mcp,web-ui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: MacOS X
Classifier: Environment :: Web Environment
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: mcp>=1.9.3
Requires-Dist: psutil>=7.0.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: websockets>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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/独立命令行触发设计方案.md)
- **自动执行命令**：新建会话和提交后可自动执行预设命令
- **OpenAI 兼容 API 代理**：提供标准 OpenAI API 端点，允许外部工具通过 OpenAI SDK 调用 Cursor，详见 [OpenAI 代理设计文档](docs/openai-proxy-design.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_OPENAI_ENABLED` | 启用 OpenAI 代理 | `true`/`false` | `false` |
| `MCP_OPENAI_MODEL_NAME` | OpenAI 模型名称 | 字符串 | `cursor` |
| `MCP_OPENAI_TIMEOUT` | OpenAI 请求超时（秒） | 整数 | `300` |
| `MCP_OPENAI_API_KEY` | OpenAI API Key（可选） | 字符串 | 空（无需验证） |

- **`MCP_WEB_HOST`**：`127.0.0.1` 仅本机；`0.0.0.0` 允许远程（如 SSH 开发）。
- **`MCP_LANGUAGE`**：强制界面语言，覆盖系统检测。
- **`MCP_OPENAI_ENABLED`**：启用后，可通过标准 OpenAI API 调用 Cursor（见下方说明）。
- **`MCP_OPENAI_API_KEY`**：设置后，请求需携带 `Authorization: Bearer <key>` 验证。

### 测试命令

```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
```

---

## OpenAI 兼容 API 代理

启用 OpenAI 代理后，外部工具可通过标准 OpenAI API 调用 Cursor：

### 配置

在 MCP 配置中添加环境变量：

```json
{
  "env": {
    "MCP_OPENAI_ENABLED": "true",
    "MCP_OPENAI_MODEL_NAME": "cursor",
    "MCP_OPENAI_TIMEOUT": "300",
    "MCP_OPENAI_API_KEY": "your-api-key"  // 可选
  }
}
```

### 使用示例

使用 OpenAI SDK 调用：

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8765/v1",
    api_key="your-api-key"  # 如果设置了 MCP_OPENAI_API_KEY
)

response = client.chat.completions.create(
    model="cursor",
    messages=[
        {"role": "user", "content": "用 Python 实现二分查找"}
    ]
)

print(response.choices[0].message.content)
```

使用 curl 调用：

```bash
curl http://localhost:8765/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "cursor",
    "messages": [{"role": "user", "content": "解释快速排序"}]
  }'
```

### 端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/chat/completions` | POST | 聊天补全（OpenAI 兼容） |
| `/v1/models` | GET | 获取可用模型列表 |

### 工作原理

1. 外部工具通过 OpenAI API 发送请求到 `mcp-keep-feedback`
2. 请求被入队并等待 Cursor 通过 MCP 工具消费
3. Cursor 处理请求并通过 `interactive_feedback` 返回结果
4. 结果被格式化为 OpenAI 兼容响应返回给调用方

> ⚠️ **注意**：OpenAI 代理模式仍遵守原有的 MCP 反馈闭环协议。Cursor 需要持续调用 `interactive_feedback` 工具来完成请求处理。详见 [OpenAI 代理设计文档](docs/openai-proxy-design.md)。

---

### 开发者安装

```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
```

### 本地开发配置

在 Cursor 的 MCP 配置中使用本地开发路径：

```json
{
  "mcpServers": {
    "mcp-keep-feedback": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-keep-feedback",
        "run",
        "python",
        "-m",
        "mcp_keep_feedback"
      ],
      "timeout": 604800,
      "env": {
        "MCP_DEBUG": "true",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_LANGUAGE": "zh-CN",
        "MCP_OPENAI_ENABLED": "true"
      },
      "autoApprove": [
        "interactive_feedback"
      ]
    }
  }
}
```

**配置说明**：
- `--directory`：指定项目根目录路径（Windows 路径如 `D:\\project\\mcp-keep-feedback`，Linux/macOS 如 `/home/user/mcp-keep-feedback`）
- `MCP_DEBUG`：开发时建议设为 `true` 以查看详细日志
- 其他环境变量按需配置

## 常见问题

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

