Content
# 🎯 MCP Feedback Collector
[](https://www.npmjs.com/package/mcp-feedback-collector)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
A modern MCP feedback collector based on Node.js, supporting AI work reports and user feedback collection.
## ✨ Features
- 🚀 **One-click Start**: Run directly using `npx mcp-feedback-collector`
- 🎨 **Modern Interface**: Web interface styled in VS Code dark theme
- 🔧 **MCP Integration**: Fully supports Model Context Protocol
- 💬 **AI Conversation Feature**: Integrated AI assistant, supporting text and image conversations
- 🖼️ **Image Support**: Complete functionality for image upload, processing, and display
- 📄 **Image to Text**: AI intelligent image description to enhance client compatibility
- 🌐 **Cross-Platform**: Supports Windows, macOS, and Linux
- ⚡ **High Performance**: Addresses stability issues present in the Python version
## Development Process Video Tutorials
### 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" # Proxy, can also use OpenAI official 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 switches
MCP_ENABLE_CHAT="true"
MCP_ENABLE_IMAGE_TO_TEXT="true" # Enable image to text feature
# URL and port optimization configuration (added in v2.0.7)
MCP_USE_FIXED_URL="true" # Use fixed URL without session parameters (default: true)
MCP_FORCE_PORT="false" # Force use of specified port (default: false)
MCP_KILL_PORT_PROCESS="false" # Automatically terminate occupying processes (default: false)
MCP_CLEANUP_PORT_ON_START="true" # Clean up port on startup (default: true)
```
## 🔧 Usage
### Command Line Options
```bash
# Start server (default)
mcp-feedback-collector
# Specify port
mcp-feedback-collector --port 8080
# Web mode only
mcp-feedback-collector --web
# Test collect_feedback function
mcp-feedback-collector test-feedback
# Custom test content
mcp-feedback-collector test-feedback -m "My work report" -t 120
# Health check
mcp-feedback-collector health
# Show configuration
mcp-feedback-collector config
```
### Claude Desktop Integration
#### Method 1: Run via NPM Package (Recommended)
In Claude Desktop, add the MCP configuration for 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 (Local Development)
If you 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
- Ensure you have run `npm run build` to build the project
- Use absolute paths, e.g., `d:/zhuomian/nodejsweb/dist/cli.js`
#### Method 3: Directly Run TypeScript Source (Development Mode)
If you want to run TypeScript source 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 source directly
**Disadvantages**: Slightly slower startup, requires tsx dependency
#### 🚀 Quick Configuration Example
Assuming your project is located at `d:\zhuomian\nodejsweb`, recommended configuration:
```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. Ensure 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 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 clean JSON output
- For debugging, use separately in the command line: `npx mcp-feedback-collector --debug`
💡 **Recommended API Services**:
- The default configuration uses the proxy at `https://api.ssopen.top`, supporting various 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 Logging Feature
- **Complete Log Support**: Implements logging functionality according to MCP protocol standards, fully compliant with MCP specifications
- **Multi-level Logging**: Supports eight standard levels: debug, info, notice, warning, error, critical, alert, emergency
- **Client Control**: Allows MCP clients to dynamically set log levels via `logging/setLevel` requests
- **Real-time Notifications**: All logs are automatically sent to MCP clients via `notifications/message`
- **Professional Output**: Removes emojis, providing clean and professional log output suitable for production environments
- **Asynchronous Processing**: Optimizes asynchronous handling of log notifications to avoid unhandled Promise rejection errors
- **Intelligent Filtering**: Smartly filters output content based on the set log level
### 🔧 Major Improvement: Intelligent Port Conflict Resolution
- **Smart Port Management**: Automatically detects and resolves port conflicts without manual intervention
- **Progressive Process Termination**: Graceful termination → Force termination → Various fallback options
- **Self-process Identification**: Accurately identifies and cleans up its own zombie processes
- **Cross-platform Compatibility**: Unified handling mechanism for Windows/macOS/Linux
- **Intelligent Downgrade**: Automatically seeks alternative ports when cleanup fails
### 🛡️ Graceful Exit Handling
- **Complete Signal Handling**: Supports SIGINT, SIGTERM, SIGBREAK (Windows)
- **Intelligent Exception Handling**: Optimizes handling of uncaught exceptions and Promise rejections
- **Prevent Duplicate Closure**: Adds a closure status flag to avoid executing the closure process multiple times
- **Client Notifications**: Notifies all connected clients before closing
- **Resource Cleanup**: Ensures all resources are correctly released to avoid zombie processes
### 🚀 User Experience Enhancements
- **Detailed Logs**: Clear logs for process termination and port release, supporting MCP standard log output
- **Automatic Handling**: Most port conflicts are automatically resolved with intelligent downgrade strategies
- **Smart 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 support for MCP protocol, facilitating integration and debugging
### 📄 Image to Text Feature (v2.1.1)
- **Intelligent Image Description**: AI automatically converts images into detailed text descriptions
- **Compatibility Improvement**: Resolves issues where some MCP clients cannot display images
- **User Control**: Users can actively convert images by clicking the "Image to Text" button
- **Editable Descriptions**: Users can modify AI-generated image descriptions
- **Batch Processing**: Supports converting multiple images simultaneously
### 🎨 UI Simplification and Optimization (v2.1.1)
- **Plain Text Status Display**: Removes spinning animations for a clean and intuitive interface
- **Intelligent Auto-refresh**: Enabled by default, no user selection required
- **Minimalist Design**: Aligns with modern UI design trends
### 🔄 Session Management Optimization (v2.1.1)
- **Intelligent Page Refresh**: Automatically refreshes the page when new content is detected
- **Session Auto-reset**: Resolves "conversation expired" issues
- **Seamless Experience**: 3-second countdown prompt
### 🔗 Fixed URL Mode (v2.0.7)
- Uses a fixed root path: `http://localhost:5000`
- Supports multiple concurrent sessions
- Facilitates remote server forwarding
## 🛠️ MCP Utility Functions
### collect_feedback
Collect user feedback on AI work:
```typescript
// Basic call (timeout read from environment variables)
collect_feedback("I have completed the code refactoring work, mainly improving performance and readability.")
```
### 📋 MCP Logging Functionality
This project fully supports the logging functionality according to MCP protocol standards, providing professional-level log management:
**Server Capability Declaration**:
- Automatically declares `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 functionality
**Supported Log Levels** (sorted by priority):
- `emergency` - Emergency situation, system unavailable
- `alert` - Alert information, requires immediate attention
- `critical` - Critical error, serious issue
- `error` - Error information, functional anomaly
- `warning` - Warning information, potential issue
- `notice` - Notification information, important event
- `info` - General information, routine operations
- `debug` - Debug information, detailed tracing
**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": "Server started successfully",
"port": 5000,
"url": "http://localhost:5000"
}
}
}
```
**Technical Features**:
- **Asynchronous Processing**: Optimized asynchronous log handling to avoid blocking the main thread
- **Error Recovery**: Comprehensive error handling mechanism to prevent the logging system from affecting main functionality
- **Intelligent Filtering**: Automatically filters log output based on the set level
- **Structured Data**: Supports logging of complex objects for easier debugging and analysis
This allows MCP clients like Claude Desktop and Cursor to receive and process server log information, greatly enhancing the development and debugging experience.
**Parameter Description**:
- `work_summary` (required): AI work report content
**Timeout Configuration**:
- Timeout is uniformly configured via the environment variable `MCP_DIALOG_TIMEOUT`
- Default value is 60000 seconds (approximately 16.7 hours)
- Valid range: 10-60000 seconds
**Functionality**:
- Launch web interface to display work reports
- Collect user text and image feedback
- Return structured feedback data
- Automatically manage server lifecycle
- Automatically close the tab after submitting feedback (3-second countdown)
## 🎨 Interface Features
- **Dual Tab Design**: Work report + AI conversation
- **VS Code Theme**: Dark theme, professional and aesthetically pleasing
- **Responsive Layout**: Supports both desktop and mobile devices
- **Real-time Communication**: WebSocket connection status indication
- **Multi-modal Support**: Text + image combined input
- **Intelligent Submission Confirmation**: Users can choose whether to close the page after submission
- **Flexible Operations**: Supports canceling submissions and various interaction methods
## 📋 System Requirements
- **Node.js**: Version 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 test page
http://localhost:5000/test.html
# Check browser console for error messages
```
2. **Port 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 records
## 📝 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 TypeScript compilation)
npm run dev
# Build the project (generate dist directory)
npm run build
# Start the built project
npm start
# Testing
npm test
# Health check
npm start health
# Show configuration
npm start config
```
#### MCP Configuration Testing
After building, you can use the following configuration to test in Cursor:
```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
## 🤝 Contribution
Contributions are welcome! Please 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 Link](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 feature
- **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 guidelines
- **[Technical Documentation](TECHNICAL.md)** - System architecture and technical details
- **[Change Log](CHANGELOG.md)** - Version change history
- **[Release Notes](RELEASE_NOTES.md)** - Detailed release information
## Thank You for Your Support
https://api.ssopen.top/ API proxy, 290+ AI large models, official cost one-seventh, supports high concurrency!
