Supports OpenAI tool invocations, helping to reduce the number of premium requests by providing a human feedback mechanism before making speculative tool calls
Interactive Feedback MCP - Node.js Implementation
Interactive Feedback MCP - Phiên bản Node.js
🌍 Language / Ngôn ngữ
📋 MCP Usage Rulesets / Bộ quy tắc sử dụng MCP
- English Ruleset - Comprehensive usage rules for AI assistants
- Vietnamese Ruleset - Quy tắc sử dụng toàn diện cho AI assistants
English
Overview
Interactive Feedback MCP - Node.js Implementation is a modern Node.js implementation of the Interactive Feedback MCP (Python) developed by Fábio Ferreira. This version replaces the Qt desktop interface with a responsive web-based UI, providing better user experience and cross-platform compatibility.
Developed by Zivhd (@zivhdinfo) as part of the STMMO Project.
Purpose
Create a "human-in-the-loop" workflow for AI development tools like Cursor, Cline, and Windsurf. This server allows you to:
- Run commands and view their output
- Provide textual feedback directly to the AI
- Manage per-project configurations
- Auto-execute commands when needed
Why Use This?
By guiding the assistant to check in with the user instead of branching out into speculative, high-cost tool calls, this module can drastically reduce the number of premium requests (e.g., OpenAI tool invocations) on platforms like Cursor. In some cases, it helps consolidate what would be up to 25 tool calls into a single, feedback-aware request — saving resources and improving performance.
🌟 Features
- ✅ MCP Specification Compliant: 100% compatible with official MCP specification and JSON-RPC 2.0
- 🔄 Proper Handshake: Implements correct initialize/initialized handshake protocol
- 🛠️ Tool Management: Full support for tools/list and tools/call methods
- 🌐 Interactive Web UI: Modern, dark-themed interface with real-time feedback
- 🖥️ Cross-Platform: Works on Windows, macOS, and Linux
- ⚡ Real-Time Communication: WebSocket-based live updates
- 💻 Command Execution: Run and monitor system commands with live output
- 📁 Project Management: Per-project configuration and settings
- 📱 Responsive Design: Works on desktop and mobile devices
- 🚀 Zero Configuration: Works out of the box with sensible defaults
- 🧪 Comprehensive Testing: Includes MCP compliance test suite
- ⌨️ Keyboard Shortcuts: Enter to run, Ctrl+Enter to submit
- 🎛️ Process Management: Start/stop controls with auto-focus
Technologies Used
Core Technologies
- Node.js (v18.0.0+) - Runtime environment
- Express.js (v4.18.2+) - Web framework
- WebSocket (ws v8.14.2+) - Real-time communication
- fs-extra (v11.1.1+) - Enhanced file system operations
Frontend Technologies
- HTML5 - Modern semantic markup
- CSS3 - Dark theme with responsive design
- Vanilla JavaScript - ES6+ features, no frameworks
- WebSocket Client - Real-time UI updates
System Requirements
Minimum Requirements
- Node.js: Version 18.0.0 or higher (LTS recommended)
- npm: Version 8.0.0 or higher
- Browser: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
- RAM: 512MB available memory
- Disk: 100MB free space
- Network: Port access for local server (fixed port 3636)
Supported Operating Systems
- ✅ Windows 10/11
- ✅ macOS 10.15+
- ✅ Linux (Ubuntu 20.04+, CentOS 8+, etc.)
Quick Installation
Prerequisites
Ensure you have Node.js 18.0.0 or newer installed:
Installation Steps
Configuration
For Cursor IDE
Add to Cursor settings.json:
Note: Update the path in args
to match your installation directory.
For Claude Desktop
Add to Claude Desktop config:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Note: Update the path in args
to match your installation directory.
For Cline / Windsurf
Use the same configuration format as above. Configure the server in the respective tool's MCP settings with interactive-feedback-mcp
as the server identifier.
MCP Usage Rules for AI IDEs
📋 Detailed Rulesets Available: For comprehensive usage guidelines, see the English Ruleset document.
When AI Assistants MUST Use Interactive Feedback
🔴 Critical Actions (ALWAYS Required)
- Before making significant code changes - Modifying multiple files or core functionality
- Before running system commands - Commands that affect system, install packages, or modify configurations
- Before build/deploy operations -
npm run build
,docker build
, deployment scripts - Before package management - Installing, updating, or removing dependencies
- Before major refactoring - Large-scale code restructuring or architecture changes
- When encountering errors - Need debugging guidance or error resolution clarification
- Before finalizing responses - To confirm completion and get user approval
🟡 Recommended Actions (Strongly Suggested)
- When requirements are unclear - Need clarification on user intentions
- Before creating new files - Configuration files, documentation, or new modules
- When multiple solution approaches exist - Let user choose preferred approach
- Before making breaking changes - Changes affecting existing functionality
- When working with sensitive data - Database operations, API keys, security-related code
🟢 Optional Actions (Use When Beneficial)
- For progress updates - On long-running tasks to keep user informed
- When seeking optimization feedback - Performance improvements or code quality suggestions
- For educational purposes - Explaining complex concepts or decisions
Usage
Basic Workflow
- AI Assistant calls tool: AI uses
interactive_feedback
tool - Web UI opens: Browser automatically opens with feedback interface
- Review project: View project directory and prompt from AI
- Run commands (optional): Execute commands to test/verify
- Provide feedback: Enter feedback for AI assistant
- Submit: Send feedback and close UI
Available Tool
interactive_feedback
Parameters:
project_directory
(string): Path to the project directorysummary
(string): Summary of the request or context
Returns:
command_logs
(string): Output from executed commandsinteractive_feedback
(string): User feedback for the AI
Example Usage
Testing
Manual Testing
Troubleshooting
Common Issues
- Port conflicts: Server uses fixed port 3636 (ensure it's available)
- Permission errors: Ensure Node.js has proper permissions
- Browser not opening: Check default browser settings
- WebSocket connection failed: Verify firewall settings
Debug Mode
License
MIT License - see LICENSE file for details.
Contributing
Contributions are welcome! Please read the contributing guidelines before submitting PRs.
Support
For issues and questions:
- GitHub Issues: Create an issue
- Email: nguyenhop530@gmail.com
Tiếng Việt
Tổng quan
Interactive Feedback MCP - Phiên bản Node.js là phiên bản Node.js hiện đại của Interactive Feedback MCP (Python) được phát triển bởi Fábio Ferreira. Phiên bản này thay thế giao diện desktop Qt bằng giao diện web responsive, mang lại trải nghiệm người dùng tốt hơn và khả năng tương thích đa nền tảng.
Phát triển bởi Zivhd (@zivhdinfo) như một phần của STMMO Project.
Mục đích
Tạo ra một workflow "human-in-the-loop" cho các công cụ phát triển AI như Cursor, Cline, và Windsurf. Server này cho phép bạn:
- Chạy các lệnh và xem kết quả đầu ra
- Cung cấp phản hồi văn bản trực tiếp cho AI
- Quản lý cấu hình theo từng dự án
- Tự động thực thi lệnh khi cần thiết
Tại sao nên sử dụng?
Bằng cách hướng dẫn trợ lý kiểm tra với người dùng thay vì phân nhánh thành các lệnh gọi công cụ đầy suy đoán và tốn kém, module này có thể giảm đáng kể số lượng yêu cầu premium (ví dụ: lệnh gọi công cụ OpenAI) trên các nền tảng như Cursor. Trong một số trường hợp, nó giúp hợp nhất những gì có thể là tới 25 lệnh gọi công cụ thành một yêu cầu duy nhất có nhận thức phản hồi — tiết kiệm tài nguyên và cải thiện hiệu suất.
🌟 Tính năng
- ✅ Tuân thủ MCP Specification: Tương thích 100% với MCP specification chính thức và JSON-RPC 2.0
- 🔄 Handshake đúng chuẩn: Triển khai giao thức handshake initialize/initialized chính xác
- 🛠️ Quản lý Tool: Hỗ trợ đầy đủ các phương thức tools/list và tools/call
- 🌐 Web UI tương tác: Giao diện hiện đại với theme tối và phản hồi thời gian thực
- 🖥️ Đa nền tảng: Hoạt động trên Windows, macOS, và Linux
- ⚡ Giao tiếp thời gian thực: Cập nhật trực tiếp qua WebSocket
- 💻 Thực thi lệnh: Chạy và giám sát lệnh hệ thống với đầu ra trực tiếp
- 📁 Quản lý dự án: Cấu hình và cài đặt theo từng dự án
- 📱 Thiết kế responsive: Hoạt động trên desktop và mobile
- 🚀 Cấu hình zero: Hoạt động ngay với cài đặt mặc định hợp lý
- 🧪 Kiểm thử toàn diện: Bao gồm bộ test tuân thủ MCP
- ⌨️ Phím tắt: Enter để chạy, Ctrl+Enter để gửi
- 🎛️ Quản lý tiến trình: Điều khiển start/stop với auto-focus
Công nghệ sử dụng
Công nghệ cốt lõi
- Node.js (v18.0.0+) - Môi trường runtime
- Express.js (v4.18.2+) - Web framework
- WebSocket (ws v8.14.2+) - Giao tiếp thời gian thực
- fs-extra (v11.1.1+) - Thao tác file system nâng cao
Công nghệ Frontend
- HTML5 - Markup ngữ nghĩa hiện đại
- CSS3 - Theme tối với thiết kế responsive
- Vanilla JavaScript - Tính năng ES6+, không framework
- WebSocket Client - Cập nhật UI thời gian thực
Yêu cầu hệ thống
Yêu cầu tối thiểu
- Node.js: Phiên bản 18.0.0 trở lên (khuyến nghị LTS)
- npm: Phiên bản 8.0.0 trở lên
- Trình duyệt: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
- RAM: 512MB bộ nhớ khả dụng
- Ổ đĩa: 100MB dung lượng trống
- Mạng: Truy cập port cho local server (port cố định 3636)
Hệ điều hành được hỗ trợ
- ✅ Windows 10/11
- ✅ macOS 10.15+
- ✅ Linux (Ubuntu 20.04+, CentOS 8+, v.v.)
Cài đặt nhanh
Điều kiện tiên quyết
Đảm bảo bạn đã cài đặt Node.js 18.0.0 trở lên:
Các bước cài đặt
Cấu hình
Cho Cursor IDE
Phương pháp 1: Sử dụng settings.json (Khuyến nghị)
- Mở Cursor Settings (Ctrl+,)
- Nhấp "Open Settings (JSON)" ở góc phải trên
- Thêm cấu hình MCP server:
Phương pháp 2: Sử dụng file cấu hình
- Copy nội dung file
cursor-mcp-config.json
được cung cấp - Dán vào file settings.json của Cursor
- Cập nhật đường dẫn
cwd
để khớp với thư mục cài đặt của bạn
Phương pháp 3: Cấu hình trực tiếp qua UI
- Mở Cursor Settings (Ctrl+,)
- Tìm "MCP Servers"
- Nhấp "Add Server" và cấu hình:
- Server Name:
interactive-feedback-mcp
- Command:
node
- Arguments:
server.js
- Working Directory:
C:\\path\\to\\interactive-feedback-mcp-nodejs
- Environment Variables:
NODE_ENV=production
- Server Name:
Xác minh
Sau khi cấu hình, khởi động lại Cursor và xác minh MCP server đã được tải:
- Mở Command Palette (Ctrl+Shift+P)
- Gõ "MCP" để xem các lệnh MCP có sẵn
- Tìm tool "interactive_feedback" trong gợi ý của AI assistant
Cho Claude Desktop
Thêm vào cấu hình Claude Desktop:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Cho Cline / Windsurf
Áp dụng nguyên tắc cài đặt tương tự. Cấu hình lệnh server trong cài đặt MCP của công cụ tương ứng, sử dụng interactive-feedback
làm định danh server.
Quy tắc sử dụng MCP cho AI IDEs
📋 Bộ quy tắc chi tiết có sẵn: Để có hướng dẫn sử dụng toàn diện, xem tài liệu Vietnamese Ruleset.
Khi nào AI Assistants BẮT BUỘC sử dụng Interactive Feedback
🔴 Hành động quan trọng (LUÔN LUÔN bắt buộc)
- Trước khi thực hiện thay đổi code quan trọng - Sửa đổi nhiều file hoặc chức năng cốt lõi
- Trước khi chạy lệnh hệ thống - Lệnh ảnh hưởng đến hệ thống, cài đặt package, hoặc sửa đổi cấu hình
- Trước khi thực hiện build/deploy -
npm run build
,docker build
, script triển khai - Trước khi quản lý package - Cài đặt, cập nhật, hoặc gỡ bỏ dependencies
- Trước khi refactoring lớn - Tái cấu trúc code quy mô lớn hoặc thay đổi kiến trúc
- Khi gặp lỗi - Cần hướng dẫn debug hoặc làm rõ về giải quyết lỗi
- Trước khi hoàn thành phản hồi - Để xác nhận hoàn thành và nhận sự chấp thuận của người dùng
🟡 Hành động được khuyến nghị (Rất nên làm)
- Khi yêu cầu không rõ ràng - Cần làm rõ ý định của người dùng
- Trước khi tạo file mới - File cấu hình, tài liệu, hoặc module mới
- Khi có nhiều cách tiếp cận giải pháp - Để người dùng chọn cách tiếp cận ưa thích
- Trước khi thực hiện thay đổi breaking - Thay đổi có thể ảnh hưởng đến chức năng hiện có
- Khi làm việc với dữ liệu nhạy cảm - Thao tác database, API keys, hoặc code liên quan bảo mật
🟢 Hành động tùy chọn (Sử dụng khi có lợi)
- Để cập nhật tiến độ - Trong các tác vụ chạy lâu để thông báo cho người dùng
- Khi tìm kiếm phản hồi tối ưu hóa - Cải thiện hiệu suất hoặc gợi ý chất lượng code
- Cho mục đích giáo dục - Giải thích các khái niệm hoặc quyết định phức tạp
Sử dụng
Quy trình cơ bản
- AI Assistant gọi tool: AI sử dụng tool
interactive_feedback
- Web UI mở: Trình duyệt tự động mở với giao diện phản hồi
- Xem lại dự án: Xem thư mục dự án và prompt từ AI
- Chạy lệnh (tùy chọn): Thực thi lệnh để kiểm tra/xác minh
- Cung cấp phản hồi: Nhập phản hồi cho AI assistant
- Gửi: Gửi phản hồi và đóng UI
Tool có sẵn
interactive_feedback
Tham số:
project_directory
(string): Đường dẫn đến thư mục dự ánsummary
(string): Tóm tắt yêu cầu hoặc ngữ cảnh
Trả về:
command_logs
(string): Đầu ra từ các lệnh đã thực thiinteractive_feedback
(string): Phản hồi của người dùng cho AI
Ví dụ sử dụng
Kiểm thử
Kiểm thử thủ công
Khắc phục sự cố
Vấn đề thường gặp
- Xung đột port: Server sử dụng port cố định 3636 (đảm bảo port khả dụng)
- Lỗi quyền: Đảm bảo Node.js có quyền phù hợp
- Trình duyệt không mở: Kiểm tra cài đặt trình duyệt mặc định
- Kết nối WebSocket thất bại: Xác minh cài đặt firewall
Chế độ Debug
Giấy phép
Giấy phép MIT - xem file LICENSE để biết chi tiết.
Đóng góp
Chào mừng các đóng góp! Vui lòng đọc hướng dẫn đóng góp trước khi gửi PR.
Hỗ trợ
Đối với các vấn đề và câu hỏi:
- GitHub Issues: Tạo issue
- Email: nguyenhop530@gmail.com
Developed with ❤️ by Zivhd (@zivhdinfo) - STMMO Project
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A Node.js MCP server that enables human-in-the-loop workflow for AI development tools, allowing users to run commands, view output, and provide textual feedback directly to AI assistants.
Related MCP Servers
- AsecurityFlicenseAqualityAn MCP server that supercharges AI assistants with powerful tools for software development, enabling research, planning, code generation, and project scaffolding through natural language interaction.Last updated -1161TypeScript
- AsecurityAlicenseAqualityA MCP server that enables human-in-the-loop workflow in AI-assisted development tools by allowing users to run commands, view their output, and provide textual feedback directly to the AI assistant.Last updated -11,442PythonMIT License
- AsecurityAlicenseAqualityA Node.js/TypeScript MCP server that facilitates interactive communication between LLMs and users, allowing AI assistants to request user input, display notifications, and manage command-line chat sessions.Last updated -5485TypeScriptMIT License
- AsecurityAlicenseAqualityA powerful MCP server that provides interactive user feedback and command execution capabilities for AI-assisted development, featuring a graphical interface with text and image support.Last updated -133PythonMIT License