Content
# 🎯 MCP Feedback Collector
[](https://www.npmjs.com/package/mcp-feedback-collector)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
A modern MCP (Model Context Protocol) feedback collector based on Node.js, supporting AI work reports and user feedback collection.
## ✨ Features
- 🚀 **One-click Start**: Run directly with `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
- 🌐 **Cross-platform**: Supports Windows, macOS, and Linux
- ⚡ **High Performance**: Addresses stability issues found in the Python version
## 🚀 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="300" # Feedback collection timeout (seconds), range: 10-3600
# Feature switches
MCP_ENABLE_CHAT="true"
```
## 🔧 Usage
### Command Line Options
```bash
# Start the server (default)
mcp-feedback-collector
# Specify port
mcp-feedback-collector --port 8080
# Web mode only
mcp-feedback-collector --web
# Test collect_feedback functionality
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
In Claude Desktop, add the MCP configuration in the 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": "5000",
"MCP_DIALOG_TIMEOUT": "300"
}
}
}
}
```
## You can configure it in cursor rules 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 OpenAI official API: `https://api.openai.com/v1`
- Or other API services compatible with OpenAI format
## 🛠️ MCP Utility Functions
### collect_feedback
Collect user feedback on AI work:
```typescript
// Basic call (using default timeout)
collect_feedback("I have completed the code refactoring work, mainly improving performance and readability.")
// Custom timeout (seconds)
collect_feedback("I have completed the code refactoring work, mainly improving performance and readability.", 600)
```
**Parameter Description**:
- `work_summary` (required): AI work report content
- `timeout_seconds` (optional): Feedback collection timeout, defaults to the value of the environment variable `MCP_DIALOG_TIMEOUT`
**Functionality**:
- Launch the 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 seconds countdown)
## 🎨 Interface Features
- **Dual Tab Design**: Work report + AI conversation
- **VS Code Theme**: Dark theme, professional and aesthetic
- **Responsive Layout**: Supports desktop and mobile devices
- **Real-time Communication**: WebSocket connection status indication
- **Multimodal Support**: Text + image combined input
- **Smart Close**: Automatically closes the tab after 3 seconds countdown post feedback submission
## 📋 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 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
npm run dev
# Build
npm run build
# Test
npm test
```
### 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
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.0.3
- **Maintenance Status**: Actively maintained
- **Test Coverage**: 85%+
- **Supported Platforms**: Windows, macOS, Linux
## Thank You for Your Support
The API proxy at https://api.ssopen.top/ supports 290+ AI large models, with official costs at one-seventh, supporting high concurrency!
