# Interactive MCP Server
**🌐 Language / 語言切換:** **English** | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
**Original Author:** [Fábio Ferreira](https://x.com/fabiomlferreira) | [Original Project](https://github.com/noopstudios/interactive-feedback-mcp) ⭐
**Enhanced Fork:** [NekoNuo](https://github.com/NekoNuo)
**UI Design Reference:** [sanshao85/mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector)
## 🎯 Core Concept
This is an [MCP server](https://modelcontextprotocol.io/) that establishes **feedback-oriented development workflows**, providing **Web UI and Desktop Application** dual interface options, perfectly adapting to local, **SSH Remote environments**, and **WSL (Windows Subsystem for Linux) environments**. By guiding AI to confirm with users rather than making speculative operations, it can consolidate multiple tool calls into a single feedback-oriented request, dramatically reducing platform costs and improving development efficiency.
**🌐 Dual Interface Architecture Advantages:**
- 🖥️ **Desktop Application**: Native cross-platform desktop experience, supporting Windows, macOS, Linux
- 🌐 **Web UI**: No GUI dependencies required, suitable for remote and WSL environments
- 🔧 **Flexible Deployment**: Choose the most suitable interface mode based on environment requirements
- 📦 **Unified Functionality**: Both interfaces provide exactly the same functional experience
**🖥️ Desktop Application:** v2.5.0 introduces cross-platform desktop application support based on Tauri framework, supporting Windows, macOS, and Linux platforms with native desktop experience.
**Supported Platforms:** [Cursor](https://www.cursor.com) | [Cline](https://cline.bot) | [Windsurf](https://windsurf.com) | [Augment](https://www.augmentcode.com) | [Trae](https://www.trae.ai)
### 🔄 Workflow
1. **AI Call** → `interactive-mcp-server` tool
2. **Interface Launch** → Auto-open desktop application or browser interface (based on configuration)
3. **Smart Interaction** → Prompt selection, text input, image upload, auto-submit
4. **Real-time Feedback** → WebSocket connection delivers information to AI instantly
5. **Session Tracking** → Auto-record session history and statistics
6. **Process Continuation** → AI adjusts behavior or ends task based on feedback
## 🌟 Key Features
### 🖥️ Dual Interface Support
- **Desktop Application**: Cross-platform native application based on Tauri, supporting Windows, macOS, Linux
- **Web UI Interface**: Lightweight browser interface suitable for remote and WSL environments
- **Automatic Environment Detection**: Intelligently recognizes SSH Remote, WSL and other special environments
- **Unified Feature Experience**: Both interfaces provide exactly the same functionality
### 📝 Smart Workflow
- **Prompt Management**: CRUD operations for common prompts, usage statistics, intelligent sorting
- **Auto-Timed Submit**: 1-86400 second flexible timer, supports pause, resume, cancel with new pause/resume button controls
- **Auto Command Execution** (v2.6.0): Automatically execute preset commands after creating new sessions or commits for improved development efficiency
- **Session Management & Tracking**: Local file storage, privacy controls, history export (supports JSON, CSV, Markdown formats), real-time statistics, flexible timeout settings
- **Connection Monitoring**: WebSocket status monitoring, auto-reconnection, quality indicators
- **AI Work Summary Markdown Display**: Support for rich Markdown syntax rendering including headers, bold text, code blocks, lists, links and other formats for enhanced content readability
### 🎨 Modern Experience
- **Responsive Design**: Adapts to different screen sizes, modular JavaScript architecture
- **Audio Notifications**: Built-in multiple sound effects, custom audio upload support, volume control
- **System Notifications** (v2.6.0): System-level real-time alerts for important events (like auto-commit, session timeout)
- **Smart Memory**: Input box height memory, one-click copy, persistent settings
- **Multi-language Support**: Traditional Chinese, English, Simplified Chinese, instant switching
### 🖼️ Images & Media
- **Full Format Support**: PNG, JPG, JPEG, GIF, BMP, WebP
- **Convenient Upload**: Drag & drop files, clipboard paste (Ctrl+V)
- **Unlimited Processing**: Support for any size images, automatic intelligent processing
## 🌐 Interface Preview
### Web UI Interface (v2.5.0 - Desktop Application Support)
<div align="center">
<img src="docs/en/images/web1.png" width="400" alt="Web UI Main Interface - Prompt Management & Auto Submit" />
</div>
<details>
<summary>📱 Click to view complete interface screenshots</summary>
<div align="center">
<img src="docs/en/images/web2.jpeg" width="800" alt="Web UI Complete Interface - Session Management & Settings" />
</div>
</details>
*Web UI Interface - Supports desktop application and Web interface, providing prompt management, auto-submit, session tracking and other smart features*
### Desktop Application Interface (v2.5.0 New Feature)
<div align="center">
<img src="docs/en/images/desktop1.png" width="600" alt="Desktop Application - Native Cross-platform Desktop Experience" />
</div>
*Desktop Application - Native cross-platform desktop application based on Tauri framework, supporting Windows, macOS, Linux with exactly the same functionality as Web UI*
**Shortcut Support**
- `Ctrl+Enter`（Windows/Linux）/ `Cmd+Enter`（macOS）：Submit feedback (both main keyboard and numeric keypad supported)
- `Ctrl+V`（Windows/Linux）/ `Cmd+V`（macOS）：Direct paste clipboard images
- `Ctrl+I`（Windows/Linux）/ `Cmd+I`（macOS）：Quick focus input box (Thanks @penn201500)
## 🚀 Quick Start
### 1. Installation & Testing
```bash
# Install uv (if not already installed)
pip install uv
```
### 2. Configure MCP
**Basic Configuration** (suitable for most users):
```json
{
"mcpServers": {
"interactive-mcp-server": {
"command": "uvx",
"args": ["interactive-mcp-server@latest"],
"timeout": 600,
"autoApprove": ["interactive_feedback"]
}
}
}
```
**Advanced Configuration** (requires custom environment):
```json
{
"mcpServers": {
"interactive-mcp-server": {
"command": "uvx",
"args": ["interactive-mcp-server@latest"],
"timeout": 600,
"env": {
"MCP_DEBUG": "false",
"MCP_WEB_HOST": "127.0.0.1",
"MCP_WEB_PORT": "8765",
"MCP_LANGUAGE": "en"
},
"autoApprove": ["interactive_feedback"]
}
}
}
```
**Desktop Application Configuration** (v2.5.0 new feature - using native desktop application):
```json
{
"mcpServers": {
"interactive-mcp-server": {
"command": "uvx",
"args": ["interactive-mcp-server@latest"],
"timeout": 600,
"env": {
"MCP_DESKTOP_MODE": "true",
"MCP_WEB_HOST": "127.0.0.1",
"MCP_WEB_PORT": "8765",
"MCP_DEBUG": "false"
},
"autoApprove": ["interactive_feedback"]
}
}
}
```
**Configuration File Examples**:
- Desktop Mode: [examples/mcp-config-desktop.json](examples/mcp-config-desktop.json)
- Web Mode: [examples/mcp-config-web.json](examples/mcp-config-web.json)
### 3. Prompt Engineering Setup
For optimal results, add the following rules to your AI assistant:
```
# MCP Interactive Feedback Rules
follow interactive-mcp-server instructions
```
## ⚙️ Advanced Settings
### Environment Variables
| Variable | Purpose | Values | Default |
|----------|---------|--------|---------|
| `MCP_DEBUG` | Debug mode | `true`/`false` | `false` |
| `MCP_WEB_HOST` | Web UI host binding | IP address or hostname | `127.0.0.1` |
| `MCP_WEB_PORT` | Web UI port | `1024-65535` | `8765` |
| `MCP_DESKTOP_MODE` | Desktop application mode | `true`/`false` | `false` |
| `MCP_LANGUAGE` | Force UI language | `zh-TW`/`zh-CN`/`en` | Auto-detect |
**`MCP_WEB_HOST` Explanation**:
- `127.0.0.1` (default): Local access only, higher security
- `0.0.0.0`: Allow remote access, suitable for SSH remote development environments
**`MCP_LANGUAGE` Explanation**:
- Used to force the interface language, overriding automatic system detection
- Supported language codes:
- `zh-TW`: Traditional Chinese
- `zh-CN`: Simplified Chinese
- `en`: English
- Language detection priority:
1. User-saved language settings in the interface (highest priority)
2. `MCP_LANGUAGE` environment variable
3. System environment variables (LANG, LC_ALL, etc.)
4. System default language
5. Fallback to default language (Traditional Chinese)
### Testing Options
```bash
# Version check
uvx interactive-mcp-server@latest version # Check version
# Interface testing
uvx interactive-mcp-server@latest test --web # Test Web UI (auto continuous running)
uvx interactive-mcp-server@latest test --desktop # Test desktop application (v2.5.0 new feature)
# Debug mode
MCP_DEBUG=true uvx interactive-mcp-server@latest test
# Specify language for testing
MCP_LANGUAGE=en uvx interactive-mcp-server@latest test --web # Force English interface
MCP_LANGUAGE=zh-TW uvx interactive-mcp-server@latest test --web # Force Traditional Chinese
MCP_LANGUAGE=zh-CN uvx interactive-mcp-server@latest test --web # Force Simplified Chinese
```
### Developer Installation
```bash
git clone https://github.com/NekoNuo/interactive-mcp-server.git
cd interactive-mcp-server
uv sync
```
**Local Testing Methods**
```bash
# Functional testing
make test-func # Standard functional testing
make test-web # Web UI testing (continuous running)
make test-desktop-func # Desktop application functional testing
# Or use direct commands
uv run python -m interactive_mcp_server test # Standard functional testing
uvx --no-cache --with-editable . interactive-mcp-server test --web # Web UI testing (continuous running)
uvx --no-cache --with-editable . interactive-mcp-server test --desktop # Desktop application testing
# Desktop application build (v2.5.0 new feature)
make build-desktop # Build desktop application (debug mode)
make build-desktop-release # Build desktop application (release mode)
make test-desktop # Test desktop application
make clean-desktop # Clean desktop build artifacts
# Unit testing
make test # Run all unit tests
make test-fast # Fast testing (skip slow tests)
make test-cov # Test and generate coverage report
# Code quality checks
make check # Complete code quality check
make quick-check # Quick check and auto-fix
```
**Testing Descriptions**
- **Functional Testing**: Test complete MCP tool functionality workflow
- **Unit Testing**: Test individual module functionality
- **Coverage Testing**: Generate HTML coverage report to `htmlcov/` directory
- **Quality Checks**: Include linting, formatting, type checking
## 🆕 Version History
📋 **Complete Version History:** [RELEASE_NOTES/CHANGELOG.en.md](RELEASE_NOTES/CHANGELOG.en.md)
### Latest Version Highlights (v2.6.0)
- 🚀 **Auto Command Execution**: Automatically execute preset commands after creating new sessions or commits, improving workflow efficiency
- 📊 **Session Export Feature**: Support exporting session records to multiple formats for easy sharing and archiving
- ⏸️ **Auto-commit Control**: Added pause and resume buttons for better control over auto-commit timing
- 🔔 **System Notifications**: System-level notifications for important events with real-time alerts
- ⏱️ **Session Timeout Optimization**: Redesigned session management with more flexible configuration options
- 🌏 **I18n Enhancement**: Refactored internationalization architecture with full multilingual support for notifications
- 🎨 **UI Simplification**: Significantly simplified user interface for improved user experience
## 🐛 Common Issues
### 🌐 SSH Remote Environment Issues
**Q: Browser cannot launch or access in SSH Remote environment**
A: Two solutions available:
**Solution 1: Environment Variable Setting (v2.5.5 Recommended)**
Set `"MCP_WEB_HOST": "0.0.0.0"` in MCP configuration to allow remote access:
```json
{
"mcpServers": {
"interactive-mcp-server": {
"command": "uvx",
"args": ["interactive-mcp-server@latest"],
"timeout": 600,
"env": {
"MCP_WEB_HOST": "0.0.0.0",
"MCP_WEB_PORT": "8765"
},
"autoApprove": ["interactive_feedback"]
}
}
}
```
Then open in local browser: `http://[remote-host-IP]:8765`
**Solution 2: SSH Port Forwarding (Traditional Method)**
1. Use default configuration (`MCP_WEB_HOST`: `127.0.0.1`)
2. Set up SSH port forwarding:
- **VS Code Remote SSH**: Press `Ctrl+Shift+P` → "Forward a Port" → Enter `8765`
- **Cursor SSH Remote**: Manually add port forwarding rule (port 8765)
3. Open in local browser: `http://localhost:8765`
For detailed solutions, refer to: [SSH Remote Environment Usage Guide](docs/en/ssh-remote/browser-launch-issues.md)
**Q: Why am I not receiving new MCP feedback?**
A: Likely a WebSocket connection issue. **Solution**: Directly refresh the browser page.
**Q: Why isn't MCP being called?**
A: Please confirm MCP tool status shows green light. **Solution**: Repeatedly toggle MCP tool on/off, wait a few seconds for system reconnection.
**Q: Augment cannot start MCP**
A: **Solution**: Completely close and restart VS Code or Cursor, reopen the project.
### 🔧 General Issues
**Q: How to use desktop application?**
A: v2.5.0 introduces cross-platform desktop application support. Set `"MCP_DESKTOP_MODE": "true"` in MCP configuration to enable:
```json
{
"mcpServers": {
"interactive-mcp-server": {
"command": "uvx",
"args": ["interactive-mcp-server@latest"],
"timeout": 600,
"env": {
"MCP_DESKTOP_MODE": "true",
"MCP_WEB_PORT": "8765"
},
"autoApprove": ["interactive_feedback"]
}
}
}
```
**Configuration File Example**: [examples/mcp-config-desktop.json](examples/mcp-config-desktop.json)
**Q: How to use legacy PyQt6 GUI interface?**
A: v2.4.0 completely removed PyQt6 GUI dependencies. To use legacy GUI, specify v2.3.0 or earlier: `uvx interactive-mcp-server@2.3.0`
**Note**: Legacy versions don't include new features (prompt management, auto-submit, session management, desktop application, etc.).
**Q: "Unexpected token 'D'" error appears**
A: Debug output interference. Set `MCP_DEBUG=false` or remove the environment variable.
**Q: Chinese character garbled text**
A: Fixed in v2.0.3. Update to latest version: `uvx interactive-mcp-server@latest`
**Q: Window disappears or positioning errors in multi-screen environment**
A: Fixed in v2.1.1. Go to "⚙️ Settings" tab, check "Always show window at primary screen center" to resolve. Especially suitable for T-shaped screen arrangements and other complex multi-screen configurations.
**Q: Image upload failure**
A: Check file format (PNG/JPG/JPEG/GIF/BMP/WebP). System supports any size image files.
**Q: Web UI cannot start**
A: Check firewall settings or try using different ports.
**Q: UV Cache occupies too much disk space**
A: Due to frequent use of `uvx` commands, cache may accumulate to tens of GB. Regular cleanup recommended:
```bash
# View cache size and detailed information
python scripts/cleanup_cache.py --size
# Preview cleanup content (no actual cleanup)
python scripts/cleanup_cache.py --dry-run
# Execute standard cleanup
python scripts/cleanup_cache.py --clean
# Force cleanup (attempts to close related programs, solving Windows file occupation issues)
python scripts/cleanup_cache.py --force
# Or directly use uv command
uv cache clean
```
For detailed instructions, refer to: [Cache Management Guide](docs/en/cache-management.md)
**Q: AI models cannot parse images**
A: Various AI models (including Gemini Pro 2.5, Claude, etc.) may have instability in image parsing, sometimes correctly recognizing and sometimes unable to parse uploaded image content. This is a known limitation of AI visual understanding technology. Recommendations:
1. Ensure good image quality (high contrast, clear text)
2. Try uploading multiple times, retries usually succeed
3. If parsing continues to fail, try adjusting image size or format
## 🙏 Acknowledgments
### 🌟 Support Original Author
**Fábio Ferreira** - [X @fabiomlferreira](https://x.com/fabiomlferreira)
**Original Project:** [noopstudios/interactive-feedback-mcp](https://github.com/noopstudios/interactive-feedback-mcp)
If you find it useful, please:
- ⭐ [Star the original project](https://github.com/noopstudios/interactive-feedback-mcp)
- 📱 [Follow the original author](https://x.com/fabiomlferreira)
### Design Inspiration
**sanshao85** - [mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector)
### Contributors
**penn201500** - [GitHub @penn201500](https://github.com/penn201500)
- 🎯 Auto-focus input box feature ([PR #39](https://github.com/NekoNuo/interactive-mcp-server/pull/39))
**leo108** - [GitHub @leo108](https://github.com/leo108)
- 🌐 SSH Remote Development Support (`MCP_WEB_HOST` environment variable) ([PR #113](https://github.com/NekoNuo/interactive-mcp-server/pull/113))
**Alsan** - [GitHub @Alsan](https://github.com/Alsan)
- 🍎 macOS PyO3 Compilation Configuration Support ([PR #93](https://github.com/NekoNuo/interactive-mcp-server/pull/93))
**fireinice** - [GitHub @fireinice](https://github.com/fireinice)
- 📝 Tool Documentation Optimization (LLM instructions moved to docstring) ([PR #105](https://github.com/NekoNuo/interactive-mcp-server/pull/105))
### Community Support
- **Discord:** [https://discord.gg/Gur2V67](https://discord.gg/Gur2V67)
- **Issues:** [GitHub Issues](https://github.com/NekoNuo/interactive-mcp-server/issues)
## 📄 License
MIT License - See [LICENSE](LICENSE) file for details
## 📈 Star History
[](https://star-history.com/#NekoNuo/interactive-mcp-server&Date)
---
**🌟 Welcome to Star and share with more developers!**
Raw data
{
"_id": null,
"home_page": null,
"name": "interactive-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "ai, cross-platform, desktop-app, development, dual-interface, feedback, interactive, mcp, tauri, web-ui",
"author": null,
"author_email": "NekoNuo <nekonuo@example.com>",
"download_url": "https://files.pythonhosted.org/packages/4f/8c/d83e30f78443862f2beeb022519a7794b2985c710bab4e4bafa1ee5e107e/interactive_mcp_server-2.7.5.tar.gz",
"platform": null,
"description": "# Interactive MCP Server\n\n**\ud83c\udf10 Language / \u8a9e\u8a00\u5207\u63db:** **English** | [\u7e41\u9ad4\u4e2d\u6587](README.zh-TW.md) | [\u7b80\u4f53\u4e2d\u6587](README.zh-CN.md)\n\n**Original Author:** [F\u00e1bio Ferreira](https://x.com/fabiomlferreira) | [Original Project](https://github.com/noopstudios/interactive-feedback-mcp) \u2b50\n**Enhanced Fork:** [NekoNuo](https://github.com/NekoNuo)\n**UI Design Reference:** [sanshao85/mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector)\n\n## \ud83c\udfaf Core Concept\n\nThis is an [MCP server](https://modelcontextprotocol.io/) that establishes **feedback-oriented development workflows**, providing **Web UI and Desktop Application** dual interface options, perfectly adapting to local, **SSH Remote environments**, and **WSL (Windows Subsystem for Linux) environments**. By guiding AI to confirm with users rather than making speculative operations, it can consolidate multiple tool calls into a single feedback-oriented request, dramatically reducing platform costs and improving development efficiency.\n\n**\ud83c\udf10 Dual Interface Architecture Advantages:**\n- \ud83d\udda5\ufe0f **Desktop Application**: Native cross-platform desktop experience, supporting Windows, macOS, Linux\n- \ud83c\udf10 **Web UI**: No GUI dependencies required, suitable for remote and WSL environments\n- \ud83d\udd27 **Flexible Deployment**: Choose the most suitable interface mode based on environment requirements\n- \ud83d\udce6 **Unified Functionality**: Both interfaces provide exactly the same functional experience\n\n**\ud83d\udda5\ufe0f Desktop Application:** v2.5.0 introduces cross-platform desktop application support based on Tauri framework, supporting Windows, macOS, and Linux platforms with native desktop experience.\n\n**Supported Platforms:** [Cursor](https://www.cursor.com) | [Cline](https://cline.bot) | [Windsurf](https://windsurf.com) | [Augment](https://www.augmentcode.com) | [Trae](https://www.trae.ai)\n\n### \ud83d\udd04 Workflow\n1. **AI Call** \u2192 `interactive-mcp-server` tool\n2. **Interface Launch** \u2192 Auto-open desktop application or browser interface (based on configuration)\n3. **Smart Interaction** \u2192 Prompt selection, text input, image upload, auto-submit\n4. **Real-time Feedback** \u2192 WebSocket connection delivers information to AI instantly\n5. **Session Tracking** \u2192 Auto-record session history and statistics\n6. **Process Continuation** \u2192 AI adjusts behavior or ends task based on feedback\n\n## \ud83c\udf1f Key Features\n\n### \ud83d\udda5\ufe0f Dual Interface Support\n- **Desktop Application**: Cross-platform native application based on Tauri, supporting Windows, macOS, Linux\n- **Web UI Interface**: Lightweight browser interface suitable for remote and WSL environments\n- **Automatic Environment Detection**: Intelligently recognizes SSH Remote, WSL and other special environments\n- **Unified Feature Experience**: Both interfaces provide exactly the same functionality\n\n### \ud83d\udcdd Smart Workflow\n- **Prompt Management**: CRUD operations for common prompts, usage statistics, intelligent sorting\n- **Auto-Timed Submit**: 1-86400 second flexible timer, supports pause, resume, cancel with new pause/resume button controls\n- **Auto Command Execution** (v2.6.0): Automatically execute preset commands after creating new sessions or commits for improved development efficiency\n- **Session Management & Tracking**: Local file storage, privacy controls, history export (supports JSON, CSV, Markdown formats), real-time statistics, flexible timeout settings\n- **Connection Monitoring**: WebSocket status monitoring, auto-reconnection, quality indicators\n- **AI Work Summary Markdown Display**: Support for rich Markdown syntax rendering including headers, bold text, code blocks, lists, links and other formats for enhanced content readability\n\n### \ud83c\udfa8 Modern Experience\n- **Responsive Design**: Adapts to different screen sizes, modular JavaScript architecture\n- **Audio Notifications**: Built-in multiple sound effects, custom audio upload support, volume control\n- **System Notifications** (v2.6.0): System-level real-time alerts for important events (like auto-commit, session timeout)\n- **Smart Memory**: Input box height memory, one-click copy, persistent settings\n- **Multi-language Support**: Traditional Chinese, English, Simplified Chinese, instant switching\n\n### \ud83d\uddbc\ufe0f Images & Media\n- **Full Format Support**: PNG, JPG, JPEG, GIF, BMP, WebP\n- **Convenient Upload**: Drag & drop files, clipboard paste (Ctrl+V)\n- **Unlimited Processing**: Support for any size images, automatic intelligent processing\n\n## \ud83c\udf10 Interface Preview\n\n### Web UI Interface (v2.5.0 - Desktop Application Support)\n\n<div align=\"center\">\n <img src=\"docs/en/images/web1.png\" width=\"400\" alt=\"Web UI Main Interface - Prompt Management & Auto Submit\" />\n</div>\n\n<details>\n<summary>\ud83d\udcf1 Click to view complete interface screenshots</summary>\n\n<div align=\"center\">\n <img src=\"docs/en/images/web2.jpeg\" width=\"800\" alt=\"Web UI Complete Interface - Session Management & Settings\" />\n</div>\n\n</details>\n\n*Web UI Interface - Supports desktop application and Web interface, providing prompt management, auto-submit, session tracking and other smart features*\n\n### Desktop Application Interface (v2.5.0 New Feature)\n\n<div align=\"center\">\n <img src=\"docs/en/images/desktop1.png\" width=\"600\" alt=\"Desktop Application - Native Cross-platform Desktop Experience\" />\n</div>\n\n*Desktop Application - Native cross-platform desktop application based on Tauri framework, supporting Windows, macOS, Linux with exactly the same functionality as Web UI*\n\n**Shortcut Support**\n- `Ctrl+Enter`\uff08Windows/Linux\uff09/ `Cmd+Enter`\uff08macOS\uff09\uff1aSubmit feedback (both main keyboard and numeric keypad supported)\n- `Ctrl+V`\uff08Windows/Linux\uff09/ `Cmd+V`\uff08macOS\uff09\uff1aDirect paste clipboard images\n- `Ctrl+I`\uff08Windows/Linux\uff09/ `Cmd+I`\uff08macOS\uff09\uff1aQuick focus input box (Thanks @penn201500)\n\n## \ud83d\ude80 Quick Start\n\n### 1. Installation & Testing\n```bash\n# Install uv (if not already installed)\npip install uv\n```\n\n### 2. Configure MCP\n**Basic Configuration** (suitable for most users):\n```json\n{\n \"mcpServers\": {\n \"interactive-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\"interactive-mcp-server@latest\"],\n \"timeout\": 600,\n \"autoApprove\": [\"interactive_feedback\"]\n }\n }\n}\n```\n\n**Advanced Configuration** (requires custom environment):\n```json\n{\n \"mcpServers\": {\n \"interactive-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\"interactive-mcp-server@latest\"],\n \"timeout\": 600,\n \"env\": {\n \"MCP_DEBUG\": \"false\",\n \"MCP_WEB_HOST\": \"127.0.0.1\",\n \"MCP_WEB_PORT\": \"8765\",\n \"MCP_LANGUAGE\": \"en\"\n },\n \"autoApprove\": [\"interactive_feedback\"]\n }\n }\n}\n```\n\n**Desktop Application Configuration** (v2.5.0 new feature - using native desktop application):\n```json\n{\n \"mcpServers\": {\n \"interactive-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\"interactive-mcp-server@latest\"],\n \"timeout\": 600,\n \"env\": {\n \"MCP_DESKTOP_MODE\": \"true\",\n \"MCP_WEB_HOST\": \"127.0.0.1\",\n \"MCP_WEB_PORT\": \"8765\",\n \"MCP_DEBUG\": \"false\"\n },\n \"autoApprove\": [\"interactive_feedback\"]\n }\n }\n}\n```\n\n**Configuration File Examples**:\n- Desktop Mode: [examples/mcp-config-desktop.json](examples/mcp-config-desktop.json)\n- Web Mode: [examples/mcp-config-web.json](examples/mcp-config-web.json)\n\n### 3. Prompt Engineering Setup\nFor optimal results, add the following rules to your AI assistant:\n\n```\n# MCP Interactive Feedback Rules\n\nfollow interactive-mcp-server instructions\n```\n\n## \u2699\ufe0f Advanced Settings\n\n### Environment Variables\n| Variable | Purpose | Values | Default |\n|----------|---------|--------|---------|\n| `MCP_DEBUG` | Debug mode | `true`/`false` | `false` |\n| `MCP_WEB_HOST` | Web UI host binding | IP address or hostname | `127.0.0.1` |\n| `MCP_WEB_PORT` | Web UI port | `1024-65535` | `8765` |\n| `MCP_DESKTOP_MODE` | Desktop application mode | `true`/`false` | `false` |\n| `MCP_LANGUAGE` | Force UI language | `zh-TW`/`zh-CN`/`en` | Auto-detect |\n\n**`MCP_WEB_HOST` Explanation**:\n- `127.0.0.1` (default): Local access only, higher security\n- `0.0.0.0`: Allow remote access, suitable for SSH remote development environments\n\n**`MCP_LANGUAGE` Explanation**:\n- Used to force the interface language, overriding automatic system detection\n- Supported language codes:\n - `zh-TW`: Traditional Chinese\n - `zh-CN`: Simplified Chinese\n - `en`: English\n- Language detection priority:\n 1. User-saved language settings in the interface (highest priority)\n 2. `MCP_LANGUAGE` environment variable\n 3. System environment variables (LANG, LC_ALL, etc.)\n 4. System default language\n 5. Fallback to default language (Traditional Chinese)\n\n### Testing Options\n```bash\n# Version check\nuvx interactive-mcp-server@latest version # Check version\n\n# Interface testing\nuvx interactive-mcp-server@latest test --web # Test Web UI (auto continuous running)\nuvx interactive-mcp-server@latest test --desktop # Test desktop application (v2.5.0 new feature)\n\n# Debug mode\nMCP_DEBUG=true uvx interactive-mcp-server@latest test\n\n# Specify language for testing\nMCP_LANGUAGE=en uvx interactive-mcp-server@latest test --web # Force English interface\nMCP_LANGUAGE=zh-TW uvx interactive-mcp-server@latest test --web # Force Traditional Chinese\nMCP_LANGUAGE=zh-CN uvx interactive-mcp-server@latest test --web # Force Simplified Chinese\n```\n\n### Developer Installation\n```bash\ngit clone https://github.com/NekoNuo/interactive-mcp-server.git\ncd interactive-mcp-server\nuv sync\n```\n\n**Local Testing Methods**\n```bash\n# Functional testing\nmake test-func # Standard functional testing\nmake test-web # Web UI testing (continuous running)\nmake test-desktop-func # Desktop application functional testing\n\n# Or use direct commands\nuv run python -m interactive_mcp_server test # Standard functional testing\nuvx --no-cache --with-editable . interactive-mcp-server test --web # Web UI testing (continuous running)\nuvx --no-cache --with-editable . interactive-mcp-server test --desktop # Desktop application testing\n\n# Desktop application build (v2.5.0 new feature)\nmake build-desktop # Build desktop application (debug mode)\nmake build-desktop-release # Build desktop application (release mode)\nmake test-desktop # Test desktop application\nmake clean-desktop # Clean desktop build artifacts\n\n# Unit testing\nmake test # Run all unit tests\nmake test-fast # Fast testing (skip slow tests)\nmake test-cov # Test and generate coverage report\n\n# Code quality checks\nmake check # Complete code quality check\nmake quick-check # Quick check and auto-fix\n```\n\n**Testing Descriptions**\n- **Functional Testing**: Test complete MCP tool functionality workflow\n- **Unit Testing**: Test individual module functionality\n- **Coverage Testing**: Generate HTML coverage report to `htmlcov/` directory\n- **Quality Checks**: Include linting, formatting, type checking\n\n## \ud83c\udd95 Version History\n\n\ud83d\udccb **Complete Version History:** [RELEASE_NOTES/CHANGELOG.en.md](RELEASE_NOTES/CHANGELOG.en.md)\n\n### Latest Version Highlights (v2.6.0)\n- \ud83d\ude80 **Auto Command Execution**: Automatically execute preset commands after creating new sessions or commits, improving workflow efficiency\n- \ud83d\udcca **Session Export Feature**: Support exporting session records to multiple formats for easy sharing and archiving\n- \u23f8\ufe0f **Auto-commit Control**: Added pause and resume buttons for better control over auto-commit timing\n- \ud83d\udd14 **System Notifications**: System-level notifications for important events with real-time alerts\n- \u23f1\ufe0f **Session Timeout Optimization**: Redesigned session management with more flexible configuration options\n- \ud83c\udf0f **I18n Enhancement**: Refactored internationalization architecture with full multilingual support for notifications\n- \ud83c\udfa8 **UI Simplification**: Significantly simplified user interface for improved user experience\n\n## \ud83d\udc1b Common Issues\n\n### \ud83c\udf10 SSH Remote Environment Issues\n**Q: Browser cannot launch or access in SSH Remote environment**\nA: Two solutions available:\n\n**Solution 1: Environment Variable Setting (v2.5.5 Recommended)**\nSet `\"MCP_WEB_HOST\": \"0.0.0.0\"` in MCP configuration to allow remote access:\n```json\n{\n \"mcpServers\": {\n \"interactive-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\"interactive-mcp-server@latest\"],\n \"timeout\": 600,\n \"env\": {\n \"MCP_WEB_HOST\": \"0.0.0.0\",\n \"MCP_WEB_PORT\": \"8765\"\n },\n \"autoApprove\": [\"interactive_feedback\"]\n }\n }\n}\n```\nThen open in local browser: `http://[remote-host-IP]:8765`\n\n**Solution 2: SSH Port Forwarding (Traditional Method)**\n1. Use default configuration (`MCP_WEB_HOST`: `127.0.0.1`)\n2. Set up SSH port forwarding:\n - **VS Code Remote SSH**: Press `Ctrl+Shift+P` \u2192 \"Forward a Port\" \u2192 Enter `8765`\n - **Cursor SSH Remote**: Manually add port forwarding rule (port 8765)\n3. Open in local browser: `http://localhost:8765`\n\nFor detailed solutions, refer to: [SSH Remote Environment Usage Guide](docs/en/ssh-remote/browser-launch-issues.md)\n\n**Q: Why am I not receiving new MCP feedback?**\nA: Likely a WebSocket connection issue. **Solution**: Directly refresh the browser page.\n\n**Q: Why isn't MCP being called?**\nA: Please confirm MCP tool status shows green light. **Solution**: Repeatedly toggle MCP tool on/off, wait a few seconds for system reconnection.\n\n**Q: Augment cannot start MCP**\nA: **Solution**: Completely close and restart VS Code or Cursor, reopen the project.\n\n### \ud83d\udd27 General Issues\n**Q: How to use desktop application?**\nA: v2.5.0 introduces cross-platform desktop application support. Set `\"MCP_DESKTOP_MODE\": \"true\"` in MCP configuration to enable:\n```json\n{\n \"mcpServers\": {\n \"interactive-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\"interactive-mcp-server@latest\"],\n \"timeout\": 600,\n \"env\": {\n \"MCP_DESKTOP_MODE\": \"true\",\n \"MCP_WEB_PORT\": \"8765\"\n },\n \"autoApprove\": [\"interactive_feedback\"]\n }\n }\n}\n```\n**Configuration File Example**: [examples/mcp-config-desktop.json](examples/mcp-config-desktop.json)\n\n**Q: How to use legacy PyQt6 GUI interface?**\nA: v2.4.0 completely removed PyQt6 GUI dependencies. To use legacy GUI, specify v2.3.0 or earlier: `uvx interactive-mcp-server@2.3.0`\n**Note**: Legacy versions don't include new features (prompt management, auto-submit, session management, desktop application, etc.).\n\n**Q: \"Unexpected token 'D'\" error appears**\nA: Debug output interference. Set `MCP_DEBUG=false` or remove the environment variable.\n\n**Q: Chinese character garbled text**\nA: Fixed in v2.0.3. Update to latest version: `uvx interactive-mcp-server@latest`\n\n**Q: Window disappears or positioning errors in multi-screen environment**\nA: Fixed in v2.1.1. Go to \"\u2699\ufe0f Settings\" tab, check \"Always show window at primary screen center\" to resolve. Especially suitable for T-shaped screen arrangements and other complex multi-screen configurations.\n\n**Q: Image upload failure**\nA: Check file format (PNG/JPG/JPEG/GIF/BMP/WebP). System supports any size image files.\n\n**Q: Web UI cannot start**\nA: Check firewall settings or try using different ports.\n\n**Q: UV Cache occupies too much disk space**\nA: Due to frequent use of `uvx` commands, cache may accumulate to tens of GB. Regular cleanup recommended:\n```bash\n# View cache size and detailed information\npython scripts/cleanup_cache.py --size\n\n# Preview cleanup content (no actual cleanup)\npython scripts/cleanup_cache.py --dry-run\n\n# Execute standard cleanup\npython scripts/cleanup_cache.py --clean\n\n# Force cleanup (attempts to close related programs, solving Windows file occupation issues)\npython scripts/cleanup_cache.py --force\n\n# Or directly use uv command\nuv cache clean\n```\nFor detailed instructions, refer to: [Cache Management Guide](docs/en/cache-management.md)\n\n**Q: AI models cannot parse images**\nA: Various AI models (including Gemini Pro 2.5, Claude, etc.) may have instability in image parsing, sometimes correctly recognizing and sometimes unable to parse uploaded image content. This is a known limitation of AI visual understanding technology. Recommendations:\n1. Ensure good image quality (high contrast, clear text)\n2. Try uploading multiple times, retries usually succeed\n3. If parsing continues to fail, try adjusting image size or format\n\n## \ud83d\ude4f Acknowledgments\n\n### \ud83c\udf1f Support Original Author\n**F\u00e1bio Ferreira** - [X @fabiomlferreira](https://x.com/fabiomlferreira)\n**Original Project:** [noopstudios/interactive-feedback-mcp](https://github.com/noopstudios/interactive-feedback-mcp)\n\nIf you find it useful, please:\n- \u2b50 [Star the original project](https://github.com/noopstudios/interactive-feedback-mcp)\n- \ud83d\udcf1 [Follow the original author](https://x.com/fabiomlferreira)\n\n### Design Inspiration\n**sanshao85** - [mcp-feedback-collector](https://github.com/sanshao85/mcp-feedback-collector)\n\n### Contributors\n**penn201500** - [GitHub @penn201500](https://github.com/penn201500)\n- \ud83c\udfaf Auto-focus input box feature ([PR #39](https://github.com/NekoNuo/interactive-mcp-server/pull/39))\n\n**leo108** - [GitHub @leo108](https://github.com/leo108)\n- \ud83c\udf10 SSH Remote Development Support (`MCP_WEB_HOST` environment variable) ([PR #113](https://github.com/NekoNuo/interactive-mcp-server/pull/113))\n\n**Alsan** - [GitHub @Alsan](https://github.com/Alsan)\n- \ud83c\udf4e macOS PyO3 Compilation Configuration Support ([PR #93](https://github.com/NekoNuo/interactive-mcp-server/pull/93))\n\n**fireinice** - [GitHub @fireinice](https://github.com/fireinice)\n- \ud83d\udcdd Tool Documentation Optimization (LLM instructions moved to docstring) ([PR #105](https://github.com/NekoNuo/interactive-mcp-server/pull/105))\n\n### Community Support\n- **Discord:** [https://discord.gg/Gur2V67](https://discord.gg/Gur2V67)\n- **Issues:** [GitHub Issues](https://github.com/NekoNuo/interactive-mcp-server/issues)\n\n## \ud83d\udcc4 License\n\nMIT License - See [LICENSE](LICENSE) file for details\n\n## \ud83d\udcc8 Star History\n\n[](https://star-history.com/#NekoNuo/interactive-mcp-server&Date)\n\n---\n**\ud83c\udf1f Welcome to Star and share with more developers!**\n",
"bugtrack_url": null,
"license": null,
"summary": "Interactive MCP server for user feedback and command execution in AI-assisted development, featuring dual interface support (Web UI and Desktop Application) with intelligent environment detection and cross-platform compatibility.",
"version": "2.7.5",
"project_urls": {
"Homepage": "https://github.com/NekoNuo/interactive-mcp-server",
"Issues": "https://github.com/NekoNuo/interactive-mcp-server/issues",
"Repository": "https://github.com/NekoNuo/interactive-mcp-server"
},
"split_keywords": [
"ai",
" cross-platform",
" desktop-app",
" development",
" dual-interface",
" feedback",
" interactive",
" mcp",
" tauri",
" web-ui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f49cdef3517b373393eee75c97d166652038b7a2a173ca7c8d24eda4a70ef95f",
"md5": "03aa3e76b8cde5e3a119cbf298e447f5",
"sha256": "cb2fb3e150553e9b22abe129ddbf2c1cdee975e05e81c4f89351d8a70b30a981"
},
"downloads": -1,
"filename": "interactive_mcp_server-2.7.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "03aa3e76b8cde5e3a119cbf298e447f5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 17153466,
"upload_time": "2025-07-24T09:41:06",
"upload_time_iso_8601": "2025-07-24T09:41:06.632340Z",
"url": "https://files.pythonhosted.org/packages/f4/9c/def3517b373393eee75c97d166652038b7a2a173ca7c8d24eda4a70ef95f/interactive_mcp_server-2.7.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4f8cd83e30f78443862f2beeb022519a7794b2985c710bab4e4bafa1ee5e107e",
"md5": "20032eaad7c5026b3120bc8c6a190b8d",
"sha256": "8824b1dfe80322eae7fb49d65cab943d243cbd5a098ef8e47f85708442d72fa4"
},
"downloads": -1,
"filename": "interactive_mcp_server-2.7.5.tar.gz",
"has_sig": false,
"md5_digest": "20032eaad7c5026b3120bc8c6a190b8d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 19453510,
"upload_time": "2025-07-24T09:41:08",
"upload_time_iso_8601": "2025-07-24T09:41:08.614773Z",
"url": "https://files.pythonhosted.org/packages/4f/8c/d83e30f78443862f2beeb022519a7794b2985c710bab4e4bafa1ee5e107e/interactive_mcp_server-2.7.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 09:41:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NekoNuo",
"github_project": "interactive-mcp-server",
"github_not_found": true,
"lcname": "interactive-mcp-server"
}
JSON
