MCP/mcp-feedback-enhanced

Fork 0

mirror of https://github.com/Minidoracat/mcp-feedback-enhanced.git synced 2025-07-27 10:42:25 +08:00

Minidoracat 3ed676cf29 📝 新增專案架構文檔

2025-06-10 09:01:53 +08:00

7.2 KiB

Raw Blame History

組件詳細說明

🏗️ 四層架構組件

MCP Feedback Enhanced 採用清晰的四層架構設計，每層負責特定的功能領域。

組件關係圖

graph TB
    subgraph "第一層：MCP 服務層"
        SERVER[server.py<br/>MCP 服務器]
        TOOL[interactive_feedback<br/>核心工具]
        I18N[i18n.py<br/>國際化支援]
    end
    
    subgraph "第二層：Web UI 管理層"
        MANAGER[WebUIManager<br/>單例管理器]
        SESSION[WebFeedbackSession<br/>會話模型]
        RESULT[FeedbackResult<br/>結果模型]
    end
    
    subgraph "第三層：Web 服務層"
        MAIN[main.py<br/>FastAPI 應用]
        ROUTES[main_routes.py<br/>路由處理]
        WS[WebSocket<br/>實時通信]
    end
    
    subgraph "第四層：前端交互層"
        HTML[feedback.html<br/>主頁面]
        JS[app.js<br/>交互邏輯]
        CSS[樣式文件]
    end
    
    subgraph "工具層"
        BROWSER[browser.py<br/>瀏覽器控制]
        NETWORK[network.py<br/>網路工具]
        PORT[port_manager.py<br/>埠管理]
        CLEANUP[session_cleanup_manager.py<br/>清理管理]
        COMPRESS[compression_*.py<br/>壓縮工具]
    end
    
    SERVER --> MANAGER
    TOOL --> SESSION
    MANAGER --> MAIN
    SESSION --> ROUTES
    ROUTES --> HTML
    HTML --> JS
    
    BROWSER --> MANAGER
    NETWORK --> MAIN
    PORT --> MAIN
    CLEANUP --> SESSION
    COMPRESS --> ROUTES

🔧 第一層：MCP 服務層

server.py - MCP 服務器核心

# 核心功能架構
class MCPServer:
    def __init__(self):
        self.app = FastMCP("mcp-feedback-enhanced")
        self.setup_tools()
    
    @self.app.tool()
    async def interactive_feedback(
        project_directory: str,
        summary: str,
        timeout: int = 600
    ) -> dict:
        # 環境檢測與驗證
        # Web UI 啟動
        # 會話管理
        # 回饋等待與處理

主要職責:

MCP 協議實現和工具註冊
環境檢測 (Local/SSH/WSL)
Web UI 生命週期管理
與 AI 助手的接口層

interactive_feedback 工具

flowchart TD
    START[工具調用] --> VALIDATE[參數驗證]
    VALIDATE --> ENV[環境檢測]
    ENV --> LAUNCH[啟動 Web UI]
    LAUNCH --> SESSION[創建/更新會話]
    SESSION --> WAIT[等待用戶回饋]
    WAIT --> TIMEOUT{超時檢查}
    TIMEOUT -->|未超時| FEEDBACK[接收回饋]
    TIMEOUT -->|超時| ERROR[超時錯誤]
    FEEDBACK --> RETURN[返回結果]
    ERROR --> RETURN

i18n.py - 國際化支援

多語言支援: 繁體中文、簡體中文、英文
動態語言切換: 基於用戶偏好自動選擇
模組化翻譯: 分離的語言包管理

🎛️ 第二層：Web UI 管理層

WebUIManager - 核心管理器

class WebUIManager:
    def __init__(self):
        self.current_session: Optional[WebFeedbackSession] = None
        self.global_active_tabs: Dict[str, dict] = {}
        self.app: Optional[FastAPI] = None
        self.server_process: Optional[subprocess.Popen] = None

關鍵特性:

單例模式: 確保全局唯一實例
會話生命週期: 創建、更新、清理會話
智能瀏覽器開啟: 避免重複開啟視窗
資源管理: 自動清理和錯誤處理

WebFeedbackSession - 會話模型

stateDiagram-v2
    [*] --> WAITING: 會話創建
    WAITING --> FEEDBACK_PROCESSING: 用戶提交
    FEEDBACK_PROCESSING --> FEEDBACK_SUBMITTED: 處理完成
    FEEDBACK_SUBMITTED --> WAITING: 新會話更新
    FEEDBACK_SUBMITTED --> [*]: 會話結束
    
    note right of WAITING
        等待用戶輸入
        顯示 AI 摘要
    end note
    
    note right of FEEDBACK_PROCESSING
        處理回饋數據
        圖片壓縮等
    end note

狀態管理:

WAITING: 等待用戶回饋
FEEDBACK_PROCESSING: 處理回饋中
FEEDBACK_SUBMITTED: 回饋已提交

🌐 第三層：Web 服務層

main.py - FastAPI 應用

class FastAPIApp:
    def __init__(self):
        self.app = FastAPI()
        self.setup_middleware()
        self.setup_routes()
        self.setup_websocket()
    
    def setup_middleware(self):
        # CORS 設定
        # 靜態文件服務
        # 錯誤處理中間件

核心功能:

HTTP 路由處理
WebSocket 連接管理
靜態資源服務
中間件配置

main_routes.py - 路由處理

graph LR
    subgraph "HTTP 路由"
        GET[GET /]
        FEEDBACK[GET /feedback]
        STATIC[靜態資源]
    end
    
    subgraph "WebSocket 路由"
        WS[/ws]
        MSG[訊息處理]
        BROADCAST[廣播機制]
    end
    
    GET --> FEEDBACK
    FEEDBACK --> STATIC
    WS --> MSG
    MSG --> BROADCAST

WebSocket 訊息類型:

connection_established: 連接建立
session_updated: 會話更新
submit_feedback: 提交回饋
feedback_received: 回饋確認
status_update: 狀態更新

🎨 第四層：前端交互層

feedback.html - 主頁面

<!-- 核心結構 -->
<div id="app">
    <header><!-- 標題和狀態 --></header>
    <main>
        <section id="ai-summary"><!-- AI 摘要顯示 --></section>
        <section id="feedback-form"><!-- 回饋表單 --></section>
        <section id="image-upload"><!-- 圖片上傳 --></section>
    </main>
    <footer><!-- 狀態指示器 --></footer>
</div>

app.js - 交互邏輯

class FeedbackApp {
    constructor() {
        this.websocket = null;
        this.currentSession = null;
        this.feedbackState = 'WAITING';
    }
    
    // WebSocket 管理
    initWebSocket() { /* ... */ }
    handleWebSocketMessage(data) { /* ... */ }
    
    // 用戶交互
    submitFeedback() { /* ... */ }
    handleImageUpload() { /* ... */ }
    
    // UI 更新
    updateSessionDisplay() { /* ... */ }
    updateFeedbackState() { /* ... */ }
}

前端特性:

響應式設計: 適配不同螢幕尺寸
實時狀態同步: WebSocket 雙向通信
圖片上傳: 拖拽上傳和自動壓縮
多語言支援: 動態語言切換

🛠️ 工具層組件

browser.py - 瀏覽器控制

class BrowserManager:
    @staticmethod
    def open_browser(url: str, environment: str):
        if environment == "local":
            webbrowser.open(url)
        elif environment == "ssh":
            # SSH 隧道處理
        elif environment == "wsl":
            # WSL 特殊處理

port_manager.py - 埠管理

動態埠分配: 自動尋找可用埠
埠衝突檢測: 避免埠佔用問題
埠範圍配置: 可配置的埠範圍

session_cleanup_manager.py - 清理管理

graph TD
    TIMER[定時器啟動] --> CHECK[檢查會話狀態]
    CHECK --> TIMEOUT{會話超時?}
    TIMEOUT -->|是| CLEANUP[執行清理]
    TIMEOUT -->|否| WAIT[等待下次檢查]
    CLEANUP --> WEBSOCKET[關閉 WebSocket]
    WEBSOCKET --> PROCESS[終止進程]
    PROCESS --> MEMORY[釋放內存]
    MEMORY --> WAIT
    WAIT --> CHECK

清理策略:

超時清理: 會話超時自動清理
資源回收: WebSocket、進程、內存
優雅關閉: 確保資源正確釋放

下一步: 查看交互流程文檔了解完整的交互機制

7.2 KiB Raw Blame History Unescape Escape