Content
# 🎯 MCP Feedback Collector
[](https://www.npmjs.com/package/mcp-feedback-collector)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
A modern Node.js-based MCP feedback collector that supports AI work reports and user feedback collection.
## ✨ Features
- 🚀 **One-Click Start**: Run directly using `npx mcp-feedback-collector`
- 🎨 **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 conversations
- 🖼️ **Image Support**: Complete image upload, processing, and display functions
- 📄 **Image-to-Text**: AI-powered intelligent image description, improving client compatibility
- 🌐 **Cross-Platform**: Supports Windows, macOS, Linux
- ⚡ **High Performance**: Solves the stability issues of the Python version
## Development Process Video Tutorial
### YouTube: https://youtu.be/Osr1OSMgzlg
### Bilibili: 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" # Relay 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 on startup (default: true)
```
## 🔧 Usage
### Command Line Options
```bash
# Start the server (default)
mcp-feedback-collector
# Specify the port
mcp-feedback-collector --port 8080
# Web-only mode
mcp-feedback-collector --web
# Test the collect_feedback function
mcp-feedback-collector test-feedback
# Custom 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 from 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 the 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 is 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
## In cursor rules, you can configure it like this:
“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**, as 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` relay station, which supports multiple AI models
- You can also use the official OpenAI API: `https://api.openai.com/v1`
- Or other OpenAI-compatible API services
## 🆕 Latest Features (v2.1.3)
### 📋 MCP Standard Logging Function
- **Complete Log Support**: Implements the MCP protocol standard logging 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 the log level through `logging/setLevel` requests
- **Real-Time Notifications**: All logs are automatically sent to the MCP client via `notifications/message`
- **Professional Output**: Removes emoticons, providing clean and professional log output suitable for production environments
- **Asynchronous Processing**: Optimizes asynchronous processing of log notifications to avoid unhandled Promise rejection errors
- **Intelligent Filtering**: Intelligently filters output content based on the set log level
### 🔧 Major Improvement: Intelligent Port Conflict Resolution
- **Intelligent Port Management**: Automatically detects and resolves port conflicts without manual intervention
- **Progressive Process Termination**: Graceful termination → Forced termination → Multiple alternative solutions
- **Self-Process Identification**: Accurately identifies and cleans up its own zombie processes
- **Cross-Platform Compatibility**: Unified processing mechanism for Windows/macOS/Linux
- **Intelligent Degradation**: Automatically finds alternative ports when cleaning is not possible
### 🛡️ Graceful Exit Handling
- **Complete Signal Handling**: Supports SIGINT, SIGTERM, SIGBREAK (Windows)
- **Intelligent Exception Handling**: Optimizes the handling mechanism for uncaught exceptions and Promise rejections
- **Anti-Duplicate Shutdown**: Adds a shutdown status flag to avoid repeated execution of the shutdown process
- **Client Notification**: Notifies all connected clients before closing
- **Resource Cleanup**: Ensures all resources are properly released to avoid zombie processes
### 🚀 User Experience Improvement
- **Detailed Logs**: Clear process termination and port release logs, supporting MCP standard log output
- **Automatic Handling**: Most port conflicts are automatically resolved with intelligent degradation strategies
- **Intelligent Prompts**: Clear status prompts and error messages with professional output format
- **Seamless Experience**: Users do not need to worry about underlying port management and log configuration
- **Developer-Friendly**: Full MCP protocol support for easy integration and debugging
### 📄 Image-to-Text Function (v2.1.1)
- **Intelligent Image Description**: AI automatically converts images into detailed text descriptions
- **Compatibility Improvement**: Solves the problem that some MCP clients cannot display images
- **User Controllable**: Actively convert by clicking the "Image to Text" button
- **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**: Removes rotation animations for simplicity and intuitiveness
- **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 refreshes the page when new content is detected
- **Automatic Session Reset**: Solves the "dialogue expired" issue
- **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 Utility Functions
### collect_feedback
Collect user feedback on AI work:
```typescript
// Basic call (timeout read from environment variables)
collect_feedback("我已经完成了代码重构工作，主要改进了性能和可读性。")
```
### 📋 MCP Logging Function
This project fully supports the MCP protocol standard logging function, providing professional-grade log management:
**Server Capability Declaration**:
- Automatically declares the `logging` capability during MCP initialization
- Fully compliant with MCP protocol specifications, supporting 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, requires immediate attention
- `critical` - Critical error, serious problem
- `error` - Error information, functional abnormality
- `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**: Improved error handling mechanism to prevent the log system from affecting the main functions
- **Intelligent Filtering**: Automatically filters log output based on the set level
- **Structured Data**: Supports logging of complex objects for easy debugging and analysis
This allows 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 indicator
- **Multi-Modal Support**: Text + image combination input
- **Intelligent Submission Confirmation**: Users can choose whether to close the page after submission
- **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 simultaneous connections
## 🐛 Troubleshooting
### Common Issues
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 variable
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](DOCUMENTATION_INDEX.md) to find the information you need:
- **User Guide**: [USER_GUIDE.md](USER_GUIDE.md) - Detailed usage instructions
- **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": ["your_project_path/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
## 🤝 Contributing
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 Documentation](CONFIGURATION.md)** - Environment variables and configuration options
- **[Troubleshooting](TROUBLESHOOTING.md)** - Common issues and solutions
- **[Development Documentation](DEVELOPMENT.md)** - Development environment setup and contribution guide
- **[Technical Documentation](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 relay station, 290+ AI large models, one-seventh of the official cost, supports high concurrency!
