mcp-feedback-enhanced

MCP Feedback Enhanced uses an innovative architecture based on a Single Active Session + Persistent Web UI to enable seamless interaction between AI assistants and users. It features real-time bidirectional communication via WebSockets and intelligent environment detection (Local, SSH Remote, or WSL).

Core Features

• Smart Environment Detection: Automatically identifies Local/SSH Remote/WSL environments.
• Single Active Session: Replaces traditional multi-session management for better performance.
• Persistent Web UI: Supports multiple cyclic calls without needing to reopen the browser.
• Real-time Bidirectional Communication: Uses WebSockets for frontend/backend state synchronization.
• Prompt Management System: CRUD operations and quick selection for common prompts.
• Automatic Submission: Includes a countdown timer and automatic feedback submission mechanism.
• Session Management: Tracks session history and provides statistical analysis.
• Sound Notification System: Intelligent audio alerts with customizable sound support.
• Smart Memory: Remembers input box height and provides one-click copying for project paths and session IDs.
• Multi-language Support: Dynamic switching between Traditional Chinese, Simplified Chinese, and English.

The Auto-Submit feature allows users to pre-set prompts and a countdown timer that automatically submits feedback when a new AI call is detected via WebSocket.

Setup Workflow:

1. Open the Settings tab in the UI.
2. Select a prompt from the list (prioritizing auto-submit prompts).
3. Set a countdown timeout.
4. The system calls updateSettings(enabled, timeout, promptId) to save settings to the server.

Execution Workflow: When a session_updated event is received via WebSocket, the AutoSubmitManager (ASM) checks if conditions are met. If enabled, it starts a countdown, displays it in the UI, retrieves the prompt via getPromptById(promptId), fills the input box, and executes submit_feedback automatically when the timer hits zero.

sequenceDiagram
    participant User as 用戶
    participant UI as 前端界面
    participant ASM as AutoSubmitManager
    participant PM as PromptManager
    participant WS as WebSocket

    Note over User,WS: 🔧 設定自動提交
    User->>UI: 開啟設定頁籤
    UI->>PM: 獲取提示詞列表
    PM-->>UI: 返回提示詞（自動提交優先）
    User->>UI: 選擇提示詞並設定倒數時間
    UI->>ASM: updateSettings(enabled, timeout, promptId)
    ASM->>WS: 保存設定到服務器

    Note over User,WS: ⏰ 自動提交執行
    WS->>UI: session_updated（AI 新調用）
    UI->>ASM: checkAutoSubmitConditions()
    ASM->>ASM: 檢查設定和狀態
    alt 條件滿足
        ASM->>ASM: start(timeout, promptId)
        ASM->>UI: 顯示倒數計時器
        loop 每秒更新
            ASM->>UI: updateCountdownDisplay(remaining)
        end
        ASM->>PM: getPromptById(promptId)
        PM-->>ASM: 返回提示詞內容
        ASM->>UI: 填入提示詞到輸入框
        ASM->>WS: submit_feedback（自動提交）
    else 條件不滿足
        ASM->>UI: 隱藏倒數計時器
    end

The audio notification system (v2.4.3) triggers sounds when session_updated events are received via WebSocket.

Configuration Options:

• Volume: Adjust via updateVolume(volume).
• Sound Selection: Choose specific audio IDs via selectAudio(audioId).
• Testing: Use testPlayAudio(audioId) to preview a sound.
• Custom Sounds: Users can upload custom files. The system validates the format, converts the file to Base64 using convertToBase64(), and saves it to localStorage via addCustomAudio(file).

sequenceDiagram
    participant WS as WebSocket
    participant AM as AudioManager
    participant ASU as AudioSettingsUI
    participant AUDIO as Web Audio API
    participant User as 用戶

    Note over WS,User: 🔊 音效通知觸發流程
    WS->>AM: session_updated 事件
    AM->>AM: checkNotificationEnabled()
    alt 音效通知已啟用
        AM->>AM: getSelectedAudio()
        AM->>AUDIO: 創建 Audio 物件
        AM->>AUDIO: 設定音量和來源
        AUDIO->>User: 播放通知音效
        AM->>AM: logPlaybackSuccess()
    else 音效通知已停用
        AM->>AM: logSkippedNotification()
    end

    Note over WS,User: 🎵 音效設定管理
    User->>ASU: 開啟音效設定
    ASU->>AM: getAudioSettings()
    AM-->>ASU: 返回當前設定
    ASU->>User: 顯示設定界面

    User->>ASU: 調整音量
    ASU->>AM: updateVolume(volume)
    AM->>AM: saveSettings()

    User->>ASU: 選擇音效
    ASU->>AM: selectAudio(audioId)
    AM->>AM: saveSettings()

    User->>ASU: 測試播放
    ASU->>AM: testPlayAudio(audioId)
    AM->>AUDIO: 播放測試音效
    AUDIO->>User: 播放音效

    Note over WS,User: 📁 自訂音效管理
    User->>ASU: 上傳自訂音效
    ASU->>ASU: validateAudioFile()
    ASU->>AM: addCustomAudio(file)
    AM->>AM: convertToBase64()
    AM->>AM: saveToLocalStorage()
    ASU->>User: 顯示上傳成功

When using MCP Feedback Enhanced in SSH Remote environments (like Cursor SSH Remote or VS Code Remote SSH), the browser cannot launch automatically because the remote server is headless. To access the Web UI, you must use port forwarding to connect from your local machine.

Configuration

Set the MCP_WEB_HOST environment variable to 0.0.0.0 to allow port forwarding. By default, the system uses port 8765, but this can be customized.

Correct Workflow

1. Do NOT manually start the Web UI (e.g., do not run uvx mcp-feedback-enhanced test --web). This prevents integration with the MCP system.
2. Wait for the AI model to call the interactive_feedback tool. This automatically starts the Web UI.
3. Check the port: If the browser doesn't open, find the port being used via your IDE's port forwarding settings or by checking the "MCP Log" in the "Output" tab (Debug mode).
4. Open in local browser: Copy the URL (typically http://localhost:8765) and paste it into your local browser.