mcp-interactive-feedback-server/README.md

一个简洁高效的MCP服务器，支持AI与用户的实时交互问答

# Interactive Feedback MCP Server

一个简洁高效的MCP（Model Context Protocol）服务器，为AI助手提供与用户实时交互的能力。

## 🚀 功能特性

- **MCP协议支持**: 完整实现MCP协议，提供 `ask_user_question` 工具
- **实时交互**: 基于WebSocket的实时双向通信
- **现代化界面**: 响应式Web界面，支持Markdown渲染和代码高亮
- **历史记录**: 自动保存问答历史，支持恢复未完成的对话
- **自定义端口**: 支持命令行配置端口号
- **文件日志**: 所有日志输出到本地文件，便于调试和监控
- **简洁设计**: 精简代码，专注核心功能，易于维护
- **优雅关闭**: 完善的信号处理和资源清理

## 📦 安装依赖

```bash
npm install
```

## 🎯 使用方法

### 通过 npx 直接运行（推荐）✅

```bash
# 直接运行，使用默认端口 8888
npx mcp-interactive-feedback

# 指定端口号
npx mcp-interactive-feedback 9000

# 查看帮助
npx mcp-interactive-feedback --help
```

### 直接从GitHub运行

```bash
# 方法1：使用npx直接从GitHub运行
npx github:yourusername/interactive-feedback-mcp

# 方法2：克隆并运行
git clone https://github.com/yourusername/interactive-feedback-mcp.git
cd interactive-feedback-mcp
npm install
npm start

# 指定端口
npm start 9000
# 或
node index.js 9000
```

### 本地安装

```bash
# 全局安装
npm install -g mcp-interactive-feedback-server

# 运行
mcp-interactive-feedback
mcp-interactive-feedback 9000
```

### 从源码运行

```bash
# 克隆项目
git clone https://github.com/yourusername/interactive-feedback-mcp.git
cd interactive-feedback-mcp

# 安装依赖
npm install

# 运行
npm start
# 或
node index.js 9000
```

## 🔧 配置选项

| 参数 | 描述 | 默认值 |
|------|------|--------|
| `端口号` | 服务器监听的端口号 | 8888 |
| `--help` 或 `-h` | 显示帮助信息 | - |

## 🖥️ 界面布局

- **左侧面板（70%）**: 当前问答区域
  - 显示AI提出的问题
  - 提供答案输入框
  - 支持Markdown格式显示

- **右侧面板（30%）**: 历史记录区域
  - 显示所有问答历史
  - 支持清理历史记录
  - 实时更新状态

## 🌐 访问界面

启动服务器后，在浏览器中访问：
- 默认地址: http://localhost:8888
- 自定义端口: http://localhost:[您的端口号]

## 📝 日志文件

所有服务器日志都会写入到 `server.log` 文件中，包括：
- 服务器启动/关闭信息
- 客户端连接/断开记录
- 问答交互日志
- 错误信息

```bash
# 查看实时日志
tail -f server.log

# 查看所有日志
cat server.log
```

## 📝 MCP工具

### ask_user_question

向用户提出问题并等待回答。

**参数:**
- `question` (string): 要向用户提出的问题

**返回:**
- 包含用户回答的文本内容

**示例:**
```json
{
  "name": "ask_user_question",
  "arguments": {
    "question": "您希望使用哪种编程语言来实现这个功能？"
  }
}
```

## 🧪 测试

运行手动测试脚本：

```bash
node manual-test.js
```

## 📁 项目结构

```
interactive-mcp/
├── index.js                    # 主服务器文件（简化版）
├── package.json                # 项目配置
├── server.log                  # 服务器日志文件
├── qa_history.json             # 问答历史记录
├── manual-test.js              # 手动测试脚本
├── public/                     # 前端静态文件
│   ├── index.html              # 主界面
│   └── libs/                   # 第三方库
└── temp_images/                # 临时图片目录
```

## 🔒 安全特性

- 自动端口绑定检测
- 优雅关闭处理（SIGINT、SIGTERM）
- 未捕获异常处理
- WebSocket连接状态监控
- 数据持久化保护

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交Issue和Pull Request！