README.md•11.4 kB
# 🎯 MCP反馈收集器
一个现代化的 Model Context Protocol (MCP) 服务器，为AI助手提供交互式用户反馈收集功能。
## 在cursor规则中可以下面这样配置
"Whenever you want to ask a question, always call the MCP .
Whenever you're about to complete a user request, call the MCP instead of simply ending the process. Keep calling MCP until the user's feedback is empty, then end the request. mcp-feedback-collector.collect_feedback "
## ✨ 主要特性
- 🎨 **现代化界面** - 美观的700x800像素GUI，支持中文界面
- 📷 **多图片支持** - 同时选择多张图片，支持文件选择和剪贴板粘贴
- 💬 **灵活反馈** - 支持纯文字、纯图片或文字+图片组合反馈
- ⚡ **零配置安装** - 使用uvx一键安装，无需复杂配置
- 🔧 **智能超时** - 可配置的对话框超时时间，避免操作中断
## 🚀 快速开始
### 1. 安装uvx
```bash
pip install uvx
```
### 2. 配置Claude Desktop
在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"mcp-feedback-collector": {
"command": "uvx",
"args": ["mcp-feedback-collector"],
"env": {
"PYTHONIOENCODING": "utf-8",
"MCP_DIALOG_TIMEOUT": "600"
}
}
}
}
```
### 3. 重启Claude Desktop
配置完成后重启Claude Desktop即可使用。
## 🧪 快速验证页面修改效果
修改代码后，可以通过以下三种方式快速验证界面效果：
### 方法1：直接运行服务器（推荐）
```bash
# 安装依赖
pip install fastmcp pillow
# 直接运行主服务器
python -m mcp_feedforward.server
# 或者运行测试脚本
python -c "
from mcp_feedforward.server import collect_feedback
result = collect_feedback('🎨 界面测试', 30)
print(f'测试完成，收集到 {len(result)} 项反馈')
"
```
### 方法2：使用测试工具验证GUI
```bash
# 运行单独的GUI测试
python -c "
import tkinter as tk
from mcp_feedforward.gui import FeedbackDialog
root = tk.Tk()
root.withdraw()
dialog = FeedbackDialog(
work_summary='🎨 GUI界面测试\n\n测试当前的界面效果和功能',
timeout_seconds=60
)
result = dialog.run()
print('测试结果:', result)
"
```
### 方法3：模拟MCP调用环境
```bash
# 模拟完整的MCP环境
python -c "
import sys
import asyncio
from mcp_feedforward.server import app
# 模拟工具调用
async def test_mcp():
tools = app.list_tools()
print('可用工具:', [tool.name for tool in tools])
# 测试collect_feedback工具
result = await app.call_tool('collect_feedback', {
'work_summary': '🧪 MCP环境测试',
'timeout_seconds': 30
})
print('MCP测试结果:', result)
asyncio.run(test_mcp())
"
```
## 🐛 本地MCP调试完整指南
### 步骤1：设置开发环境
```bash
# 克隆项目
git clone https://github.com/your-repo/mcp-feedback-collector.git
cd mcp-feedback-collector
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或者 venv\Scripts\activate # Windows
# 安装开发依赖
pip install -e .
pip install fastmcp pillow
```
### 步骤2：配置本地MCP服务器
创建本地配置文件 `local_claude_config.json`：
```json
{
"mcpServers": {
"mcp-feedback-collector-dev": {
"command": "python",
"args": ["-m", "mcp_feedforward.server"],
"cwd": "/path/to/your/project",
"env": {
"PYTHONPATH": "/path/to/your/project",
"PYTHONIOENCODING": "utf-8",
"MCP_DEBUG": "true",
"MCP_DIALOG_TIMEOUT": "300"
}
}
}
}
```
### 步骤3：启用调试模式
```bash
# 设置调试环境变量
export MCP_DEBUG=true
export PYTHONPATH=$PWD
# 运行调试服务器
python -m mcp_feedforward.server --debug
# 或者使用详细日志
python -m mcp_feedforward.server --log-level DEBUG
```
### 步骤4：使用MCP Inspector调试
```bash
# 安装MCP Inspector
npm install -g @modelcontextprotocol/inspector
# 启动Inspector
mcp-inspector python -m mcp_feedforward.server
# 在浏览器中访问 http://localhost:5173
# 测试所有MCP工具功能
```
### 步骤5：实时代码调试
在VS Code中创建 `.vscode/launch.json`：
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug MCP Server",
"type": "python",
"request": "launch",
"module": "mcp_feedforward.server",
"console": "integratedTerminal",
"env": {
"PYTHONPATH": "${workspaceFolder}",
"MCP_DEBUG": "true"
},
"args": ["--debug"]
}
]
}
```
## 📦 打包发布完整指南
### 阶段1：准备发布环境
```bash
# 更新版本号
# 编辑 pyproject.toml 中的 version
# 清理旧的构建文件
rm -rf dist/ build/ *.egg-info/
# 安装构建工具
pip install build twine
```
### 阶段2：构建发布包
```bash
# 构建源码包和wheel包
python -m build
# 验证构建结果
ls dist/
# 应该看到:
# mcp_feedback_collector-2.0.0-py3-none-any.whl
# mcp_feedback_collector-2.0.0.tar.gz
# 检查包内容
twine check dist/*
```
### 阶段3：测试安装包
```bash
# 在新环境中测试安装
python -m venv test_env
source test_env/bin/activate
# 从本地包安装
pip install dist/mcp_feedback_collector-2.0.0-py3-none-any.whl
# 测试安装结果
python -c "
from mcp_feedforward.server import collect_feedback
print('✅ 安装测试成功')
"
```
### 阶段4：发布到PyPI
```bash
# 发布到测试PyPI（推荐先测试）
twine upload --repository testpypi dist/*
# 从测试PyPI安装验证
pip install -i https://test.pypi.org/simple/ mcp-feedback-collector
# 发布到正式PyPI
twine upload dist/*
# 验证正式发布
pip install mcp-feedback-collector
```
## 🔄 多种安装方式完整指南
### 方式1：uvx安装（推荐，零配置）
```bash
# 安装uvx
pip install uvx
# 一键安装和使用
uvx mcp-feedback-collector
# Claude Desktop配置
{
"mcpServers": {
"mcp-feedback-collector": {
"command": "uvx",
"args": ["mcp-feedback-collector"]
}
}
}
```
### 方式2：pip全局安装
```bash
# 全局安装
pip install mcp-feedback-collector
# Claude Desktop配置
{
"mcpServers": {
"mcp-feedback-collector": {
"command": "python",
"args": ["-m", "mcp_feedforward.server"]
}
}
}
```
### 方式3：pipx隔离安装
```bash
# 安装pipx
pip install pipx
# 使用pipx安装
pipx install mcp-feedback-collector
# Claude Desktop配置
{
"mcpServers": {
"mcp-feedback-collector": {
"command": "pipx",
"args": ["run", "mcp-feedback-collector"]
}
}
}
```
### 方式4：conda环境安装
```bash
# 创建conda环境
conda create -n mcp-feedback python=3.9
conda activate mcp-feedback
# 安装包
pip install mcp-feedback-collector
# Claude Desktop配置（需指定conda路径）
{
"mcpServers": {
"mcp-feedback-collector": {
"command": "/path/to/conda/envs/mcp-feedback/bin/python",
"args": ["-m", "mcp_feedforward.server"]
}
}
}
```
### 方式5：Docker容器安装
```dockerfile
# Dockerfile
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
RUN pip install -e .
EXPOSE 8000
CMD ["python", "-m", "mcp_feedforward.server"]
```
```bash
# 构建和运行
docker build -t mcp-feedback-collector .
docker run -p 8000:8000 mcp-feedback-collector
# Claude Desktop配置（网络模式）
{
"mcpServers": {
"mcp-feedback-collector": {
"command": "curl",
"args": ["-X", "POST", "http://localhost:8000/mcp"]
}
}
}
```
### 方式6：源码开发安装
```bash
# 克隆源码
git clone https://github.com/your-repo/mcp-feedback-collector.git
cd mcp-feedback-collector
# 开发模式安装
pip install -e .
# 或使用poetry
poetry install
poetry shell
# Claude Desktop配置
{
"mcpServers": {
"mcp-feedback-collector": {
"command": "python",
"args": ["-m", "mcp_feedforward.server"],
"cwd": "/path/to/mcp-feedback-collector"
}
}
}
```
## 🛠️ 核心功能
### collect_feedback()
收集用户反馈的主要工具，AI可以汇报工作内容，用户提供文字和图片反馈。
```python
# AI调用示例
result = collect_feedback("我已经完成了代码优化工作...")
```
### pick_image()
快速图片选择工具，用于单张图片选择场景。
### get_image_info()
获取图片文件的详细信息（格式、尺寸、大小等）。
## 🖼️ 界面预览
```
🎯 工作完成汇报与反馈收集
┌─────────────────────────────────────────┐
│ 📋 AI工作完成汇报 │
│ ┌─────────────────────────────────────┐ │
│ │ [AI汇报的工作内容显示在这里] │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘
┌─────────────────────────────────────────┐
│ 💬 您的文字反馈（可选） │
│ ┌─────────────────────────────────────┐ │
│ │ [多行文本输入区域] │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘
┌─────────────────────────────────────────┐
│ 🖼️ 图片反馈（可选，支持多张） │
│ [📁选择文件] [📋粘贴] [❌清除] │
│ [图片缩略图预览区域] │
└─────────────────────────────────────────┘
[✅ 提交反馈] [❌ 取消]
```
## ⚙️ 配置说明
### 超时设置
- `MCP_DIALOG_TIMEOUT`: 对话框等待时间（秒）
- 默认：300秒（5分钟）
- 建议：600秒（10分钟）
- 复杂操作：1200秒（20分钟）
### 支持的图片格式
PNG、JPG、JPEG、GIF、BMP、WebP
## 💡 使用场景
- ✅ AI完成任务后收集用户评价
- ✅ 收集包含截图的详细反馈
- ✅ 获取用户对代码/设计的意见
- ✅ 收集bug报告和改进建议
## 🔧 技术栈
- **MCP框架**: FastMCP
- **GUI**: tkinter + PIL
- **多线程**: threading + queue
- **图片处理**: Pillow
## 📝 更新日志
### v2.0.0 (2025-05-28)
- 🎨 全新现代化UI设计
- 📷 多图片同时提交支持
- 🖼️ 横向滚动图片预览
- 💫 彩色按钮和图标
- 🔧 优化用户体验
## 📄 许可证
MIT License - 详见 [LICENSE](LICENSE) 文件
## 🤝 贡献
欢迎提交Issue和Pull Request！
---
**让AI与用户的交互更高效直观！** 🎯