Content
# 🎯 MCP Feedback Collector
[](https://www.npmjs.com/package/mcp-feedback-collector)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
Based on Node.js, it is a modern MCP feedback collector that supports AI work reports and user feedback collection.
## ✨ Features
- 🚀 **One-click Start**: Use `npx mcp-feedback-collector` to run directly
- 🎨 **Modern Interface**: VS Code dark theme style Web interface
- 🔧 **MCP Integration**: Full support for Model Context Protocol
- 💬 **AI Dialogue Function**: Integrated AI assistant, supports text and image dialogue
- 🖼️ **Image Support**: Complete image upload, processing, and display functions
- 📄 **Image to Text**: AI intelligent image description to improve client compatibility
- 🌐 **Cross-platform**: Supports Windows, macOS, Linux
- ⚡ **High Performance**: Solved the stability problem of the Python version
## Development Process Video Tutorial
### 油管：https://youtu.be/Osr1OSMgzlg
### B站：https://www.bilibili.com/video/BV1PHTxzSErb/
## 🚀 Quick Start
### Installation and Running
```bash
# Run directly (recommended)
npx mcp-feedback-collector
# Or install globally
npm install -g mcp-feedback-collector
mcp-feedback-collector
```
### Configure Environment Variables
Create a `.env` file:
```bash
# AI API configuration
MCP_API_KEY="your_api_key_here"
MCP_API_BASE_URL="https://api.ssopen.top" # Transit station, you can also use the official OpenAI API
MCP_DEFAULT_MODEL="grok-3"
# Web server configuration
MCP_WEB_PORT="5000"
MCP_DIALOG_TIMEOUT="60000" # Feedback collection timeout (seconds), range: 10-60000
# Feature switch
MCP_ENABLE_CHAT="true"
MCP_ENABLE_IMAGE_TO_TEXT="true" # Enable image-to-text function
# URL and port optimization configuration (new in v2.0.7)
MCP_USE_FIXED_URL="true" # Use a fixed URL without session parameters (default: true)
MCP_FORCE_PORT="false" # Force the use of the specified port (default: false)
MCP_KILL_PORT_PROCESS="false" # Automatically terminate the occupied process (default: false)
MCP_CLEANUP_PORT_ON_START="true" # Clean up the port at startup (default: true)
```
## 🔧 Usage
### Command Line Options
```bash
# Start the server (default)
mcp-feedback-collector
# Specify the port
mcp-feedback-collector --port 8080
# Web mode only
mcp-feedback-collector --web
# Test the collect_feedback function
mcp-feedback-collector test-feedback
# Customize the test content
mcp-feedback-collector test-feedback -m "我的工作汇报" -t 120
# Health check
mcp-feedback-collector health
# Show configuration
mcp-feedback-collector config
```
### Claude Desktop Integration
#### Method 1: Run with NPM Package (Recommended)
In Claude Desktop, add the following to the MCP configuration of cursor:
```json
{
"mcpServers": {
"mcp-feedback-collector": {
"command": "npx",
"args": ["-y", "mcp-feedback-collector@latest"],
"env": {
"MCP_API_KEY": "your_api_key_here",
"MCP_API_BASE_URL": "https://api.ssopen.top",
"MCP_DEFAULT_MODEL": "grok-3",
"MCP_WEB_PORT": "5050",
"MCP_DIALOG_TIMEOUT": "60000",
"MCP_ENABLE_IMAGE_TO_TEXT": "true"
}
}
}
}
```
#### Method 2: Run with Source Code (Local Development)
If you have cloned the source code and want to run it directly, you can use the following configuration:
```json
{
"mcpServers": {
"mcp-feedback-collector": {
"command": "node",
"args": ["path/to/your/project/dist/cli.js"],
"env": {
"MCP_API_KEY": "your_api_key_here",
"MCP_API_BASE_URL": "https://api.ssopen.top",
"MCP_DEFAULT_MODEL": "grok-3",
"MCP_WEB_PORT": "5050",
"MCP_DIALOG_TIMEOUT": "60000"
}
}
}
}
```
**Note**:
- Replace `path/to/your/project` with your actual project path
- Make sure you have run `npm run build` to build the project
- Use absolute paths, for example: `d:/zhuomian/nodejsweb/dist/cli.js`
#### Method 3: Run TypeScript Source Code Directly (Development Mode)
If you want to run TypeScript source code directly without building:
```json
{
"mcpServers": {
"mcp-feedback-collector": {
"command": "npx",
"args": ["tsx", "path/to/your/project/src/cli.ts"],
"env": {
"MCP_API_KEY": "your_api_key_here",
"MCP_API_BASE_URL": "https://api.ssopen.top",
"MCP_DEFAULT_MODEL": "grok-3",
"MCP_WEB_PORT": "5050",
"MCP_DIALOG_TIMEOUT": "60000",
"NODE_ENV": "development"
}
}
}
}
```
**Advantages**: No need to build, run the source code directly
**Disadvantages**: Slower startup, requires tsx dependency
#### 🚀 Quick Configuration Example
Assuming your project is located at `d:\zhuomian\nodejsweb`, the recommended configuration is:
```json
{
"mcpServers": {
"mcp-feedback-collector": {
"command": "node",
"args": ["d:/zhuomian/nodejsweb/dist/cli.js"],
"env": {
"MCP_API_KEY": "your_api_key_here",
"MCP_API_BASE_URL": "https://api.ssopen.top",
"MCP_DEFAULT_MODEL": "grok-3",
"MCP_WEB_PORT": "5050",
"MCP_DIALOG_TIMEOUT": "60000"
}
}
}
}
```
**Configuration Steps**:
1. Make sure the project has been built: `npm run build`
2. Add the above configuration to Cursor's MCP settings
3. Replace `your_api_key_here` with your actual API key
4. Restart Cursor and check that the MCP server status is green
## 在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 ”
⚠️ **Important Reminder**:
- **Do not add the `--debug` parameter in args**, this will cause JSON parsing to fail
- Cursor/Claude Desktop requires extremely pure JSON output
- If you need to debug, please use it separately in the command line: `npx mcp-feedback-collector --debug`
💡 **API Service Recommendation**:
- The default configuration uses the `https://api.ssopen.top` transit station, which supports multiple AI models
- You can also use the official OpenAI API: `https://api.openai.com/v1`
- Or other API services compatible with OpenAI format
## 🆕 Latest Features (v2.1.3)
### 📋 MCP Standard Log Function
- **Complete Log Support**: Implement MCP protocol standard log function, fully compliant with MCP specifications
- **Multi-level Logs**: Supports eight standard levels: debug, info, notice, warning, error, critical, alert, emergency
- **Client Control**: Supports MCP clients to dynamically set log levels through `logging/setLevel` requests
- **Real-time Notification**: All logs are automatically sent to the MCP client through `notifications/message`
- **Professional Output**: Remove emoticons, provide clean and professional log output, suitable for production environments
- **Asynchronous Processing**: Optimize asynchronous processing of log notifications to avoid unhandled Promise rejection errors
- **Intelligent Filtering**: Intelligently filter output content based on the set log level
### 🔧 Major Improvement: Intelligent Port Conflict Resolution
- **Intelligent Port Management**: Automatically detect and resolve port conflicts without manual intervention
- **Progressive Process Termination**: Graceful termination → Forced termination → Multiple alternative solutions
- **Self-Process Identification**: Accurately identify and clean up its own zombie processes
- **Cross-Platform Compatibility**: Unified processing mechanism for Windows/macOS/Linux
- **Intelligent Degradation**: Automatically find alternative ports when cleaning is not possible
### 🛡️ Graceful Exit Handling
- **Complete Signal Handling**: Supports SIGINT, SIGTERM, SIGBREAK (Windows)
- **Intelligent Exception Handling**: Optimize handling mechanisms for uncaught exceptions and Promise rejections
- **Prevent Duplicate Shutdowns**: Add a shutdown status flag to avoid repeated execution of the shutdown process
- **Client Notification**: Notify all connected clients before closing
- **Resource Cleanup**: Ensure all resources are properly released to avoid zombie processes
### 🚀 User Experience Improvement
- **Detailed Logs**: Clear process termination and port release logs, support MCP standard log output
- **Automatic Processing**: Most port conflicts are automatically resolved, with intelligent degradation strategies
- **Intelligent Prompts**: Clear status prompts and error messages, professional output format
- **Seamless Experience**: Users do not need to worry about underlying port management and log configuration
- **Developer Friendly**: Complete MCP protocol support, easy to integrate and debug
### 📄 Image to Text Function (v2.1.1)
- **Intelligent Image Description**: AI automatically converts images into detailed text descriptions
- **Compatibility Improvement**: Solve the problem that some MCP clients cannot display images
- **User Controllable**: Click the "Image to Text" button to actively convert
- **Editable Description**: Users can modify the AI-generated image description
- **Batch Processing**: Supports simultaneous conversion of multiple images
### 🎨 UI Simplification and Optimization (v2.1.1)
- **Pure Text Status Display**: Remove rotation animation, simple and intuitive
- **Intelligent Automatic Refresh**: Enabled by default, no user selection required
- **Minimalist Design**: Conforms to modern UI design trends
### 🔄 Session Management Optimization (v2.1.1)
- **Intelligent Page Refresh**: Automatically refresh the page when new content is detected
- **Automatic Session Reset**: Solve the "dialogue expired" problem
- **Seamless Experience**: 3-second countdown prompt
### 🔗 Fixed URL Mode (v2.0.7)
- Use a fixed root path: `http://localhost:5000`
- Supports multiple concurrent sessions
- Easy for remote server forwarding
## 🛠️ MCP Tool Functions
### collect_feedback
Collect user feedback on AI work:
```typescript
// Basic call (timeout read from environment variables)
collect_feedback("我已经完成了代码重构工作，主要改进了性能和可读性。")
```
### 📋 MCP Log Function
This project fully supports the MCP protocol standard log function, providing professional-grade log management:
**Server Capability Declaration**:
- Automatically declare the `logging` capability during MCP initialization
- Fully compliant with MCP protocol specifications, supports all standard log levels
- Provides dynamic log level control and real-time notification functions
**Supported Log Levels** (sorted by priority):
- `emergency` - Emergency situation, system unavailable
- `alert` - Alert information, needs immediate attention
- `critical` - Critical error, serious problem
- `error` - Error information, function exception
- `warning` - Warning information, potential problem
- `notice` - Notification information, important event
- `info` - General information, routine operation
- `debug` - Debug information, detailed tracking
**Client Control**:
```json
{
"method": "logging/setLevel",
"params": {
"level": "info"
}
}
```
**Log Notification Format**:
```json
{
"method": "notifications/message",
"params": {
"level": "info",
"logger": "mcp-feedback-collector",
"data": {
"message": "服务器启动成功",
"port": 5000,
"url": "http://localhost:5000"
}
}
}
```
**Technical Features**:
- **Asynchronous Processing**: Optimized asynchronous log processing to avoid blocking the main thread
- **Error Recovery**: Complete error handling mechanism to prevent the log system from affecting the main function
- **Intelligent Filtering**: Automatically filter log output based on the set level
- **Structured Data**: Supports logging of complex objects for easy debugging and analysis
This enables MCP clients such as Claude Desktop and Cursor to receive and process server log information, greatly improving the development and debugging experience.
**Parameter Description**:
- `work_summary` (required): AI work report content
**Timeout Configuration**:
- The timeout is configured uniformly through the environment variable `MCP_DIALOG_TIMEOUT`
- The default value is 60000 seconds (approximately 16.7 hours)
- Valid range: 10-60000 seconds
**Function**:
- Start the Web interface to display the work report
- Collect user text and image feedback
- Return structured feedback data
- Automatically manage the server lifecycle
- Automatically close the tab after submitting feedback (3-second countdown)
## 🎨 Interface Features
- **Dual Tab Design**: Work report + AI dialogue
- **VS Code Theme**: Dark theme, professional and beautiful
- **Responsive Layout**: Supports desktop and mobile devices
- **Real-time Communication**: WebSocket connection status indication
- **Multi-modal Support**: Text + image combination input
- **Intelligent Submission Confirmation**: Users can choose whether to close the page after submitting
- **Flexible Operation**: Supports canceling submissions and multiple interaction methods
## 📋 System Requirements
- **Node.js**: 18.0.0 or higher
- **Browser**: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
- **Operating System**: Windows 10+, macOS 10.15+, Ubuntu 18.04+
## 🔒 Security Features
- Input validation and file size limits
- CORS configuration and security headers
- Secure storage of API keys
- Basic detection of malicious content
## 📊 Performance Metrics
- **Startup Time**: < 3 seconds
- **Memory Usage**: < 100MB
- **Response Time**: < 2 seconds
- **Concurrent Connections**: Supports 10 concurrent connections
## 🐛 Troubleshooting
### Common Problems
1. **WebSocket connection failed**
```bash
# Check server status
mcp-feedback-collector health
# Access the test page
http://localhost:5000/test.html
# View error messages in the browser console
```
2. **Port is occupied**
```bash
# Check port usage
netstat -an | grep :5000
# Use another port
mcp-feedback-collector --port 5001
```
3. **API key error**
```bash
# Check configuration
mcp-feedback-collector config
# Set environment variables
export MCP_API_KEY="your_key_here"
```
4. **Permission issues**
```bash
# Use npx to avoid global installation permission issues
npx mcp-feedback-collector
```
For a detailed troubleshooting guide, please refer to: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
## 📚 Complete Documentation
This project provides a complete documentation system, please refer to [📚 文档索引](DOCUMENTATION_INDEX.md) to find the information you need:
- **User Guide**: [USER_GUIDE.md](USER_GUIDE.md) - Detailed instructions for use
- **Configuration Guide**: [CONFIGURATION.md](CONFIGURATION.md) - Environment variable configuration
- **Technical Documentation**: [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture design
- **Troubleshooting**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Problem solutions
- **Release Notes**: [RELEASE_NOTES.md](RELEASE_NOTES.md) - Version update history
## 📝 Development
### Local Development
```bash
# Clone the project
git clone https://github.com/sanshao85/mcp-feedback-collector-web.git
cd mcp-feedback-collector-web
# Install dependencies
npm install
# Development mode (real-time compilation of TypeScript)
npm run dev
# Build the project (generate the dist directory)
npm run build
# Start the built project
npm start
# Test
npm test
# Health check
npm start health
# Show configuration
npm start config
```
#### MCP Configuration Test
After building, you can test in Cursor using the following configuration:
```json
{
"mcpServers": {
"mcp-feedback-collector": {
"command": "node",
"args": ["您的项目路径/dist/cli.js"],
"env": {
"MCP_API_KEY": "your_api_key_here",
"MCP_API_BASE_URL": "https://api.ssopen.top",
"MCP_DEFAULT_MODEL": "grok-3",
"MCP_WEB_PORT": "5050",
"MCP_DIALOG_TIMEOUT": "180"
}
}
}
}
```
### Project Structure
```
src/
├── cli.ts # CLI entry point
├── index.ts # Main entry point
├── config/ # Configuration management
├── server/ # Server implementation
├── utils/ # Utility functions
├── types/ # Type definitions
└── static/ # Static files
```
## 📄 License
MIT License - See [LICENSE](LICENSE) file for details
## 🤝 Contribution
Welcome to submit Issues and Pull Requests!
1. Fork this repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 🔗 Related Links
- **Project Homepage**: [GitHub Repository](https://github.com/sanshao85/mcp-feedback-collector-web)
- **NPM Package**: [mcp-feedback-collector](https://www.npmjs.com/package/mcp-feedback-collector)
- **Model Context Protocol**: [Official Website](https://modelcontextprotocol.io)
- **MCP Specification**: [Technical Specification](https://spec.modelcontextprotocol.io)
- **Claude Desktop**: [Download Address](https://claude.ai/desktop)
## 📊 Project Status
- **Current Version**: v2.1.3
- **Maintenance Status**: Actively maintained
- **Supported Platforms**: Windows, macOS, Linux
- **Latest Feature**: MCP standard logging function
- **Protocol Support**: MCP v2025-03-26, v2024-11-05, v2024-10-07
- **SDK Version**: @modelcontextprotocol/sdk v1.12.1
## 📚 Documentation Navigation
- **[User Guide](USER_GUIDE.md)** - Detailed usage instructions and best practices
- **[Configuration](CONFIGURATION.md)** - Environment variables and configuration options
- **[Troubleshooting](TROUBLESHOOTING.md)** - Common issues and solutions
- **[Development](DEVELOPMENT.md)** - Development environment setup and contribution guide
- **[Technical](TECHNICAL.md)** - System architecture and technical details
- **[Changelog](CHANGELOG.md)** - Version change history
- **[Release Notes](RELEASE_NOTES.md)** - Detailed release information
## Thank you for your support
https://api.ssopen.top/ API transit station, 290+AI large models, one-seventh of the official cost, supports high concurrency!
