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

6.5 KiB

Raw Blame History

API 參考文檔

📡 MCP 工具 API

interactive_feedback

AI 助手與用戶進行交互式回饋的核心 MCP 工具。

函數簽名

async def interactive_feedback(
    project_directory: str,
    summary: str,
    timeout: int = 600
) -> dict

參數說明

參數	類型	必需	預設值	描述
`project_directory`	`str`	✅	-	專案目錄路徑，用於上下文顯示
`summary`	`str`	✅	-	AI 助手的工作摘要，向用戶說明當前狀態
`timeout`	`int`	❌	`600`	等待用戶回饋的超時時間（秒）

返回值

{
    "command_logs": "",  # 命令執行日誌（保留字段）
    "interactive_feedback": str,  # 用戶回饋內容
    "images": List[str]  # 用戶上傳的圖片（Base64 編碼）
}

使用示例

# 基本調用
result = await interactive_feedback(
    project_directory="./my-web-app",
    summary="我已完成登入功能的實現，包括表單驗證和錯誤處理。請檢查代碼品質。"
)

# 自定義超時
result = await interactive_feedback(
    project_directory="./complex-project",
    summary="重構完成，請詳細測試所有功能模組。",
    timeout=1200  # 20分鐘
)

錯誤處理

try:
    result = await interactive_feedback(...)
except TimeoutError:
    print("用戶回饋超時")
except ValidationError as e:
    print(f"參數驗證錯誤: {e}")
except EnvironmentError as e:
    print(f"環境檢測錯誤: {e}")

🌐 Web API

HTTP 端點

GET /

主頁重定向到回饋頁面。

響應: 302 Redirect → /feedback

GET /feedback

回饋頁面主入口。

響應: 200 OK

<!DOCTYPE html>
<html>
<!-- 回饋頁面 HTML 內容 -->
</html>

GET /static/{path}

靜態資源服務（CSS、JS、圖片等）。

參數:

path: 靜態資源路徑

響應: 200 OK 或 404 Not Found

WebSocket API

連接端點

ws://localhost:{port}/ws

訊息格式

所有 WebSocket 訊息都使用 JSON 格式：

{
    "type": "message_type",
    "data": { /* 訊息數據 */ },
    "timestamp": "2024-12-XX 10:30:00"
}

📤 客戶端 → 服務器訊息

submit_feedback

提交用戶回饋。

{
    "type": "submit_feedback",
    "data": {
        "feedback": "這個功能很好，但建議增加輸入驗證。",
        "images": [
            "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
        ],
        "settings": {
            "language": "zh-TW",
            "compress_images": true
        }
    }
}

字段說明:

feedback: 用戶回饋文字內容
images: 圖片數組（Base64 編碼）
settings.language: 界面語言
settings.compress_images: 是否壓縮圖片

heartbeat

心跳檢測訊息。

{
    "type": "heartbeat",
    "data": {
        "timestamp": 1703123456789
    }
}

language_switch

切換界面語言。

{
    "type": "language_switch",
    "data": {
        "language": "en"
    }
}

📥 服務器 → 客戶端訊息

connection_established

WebSocket 連接建立確認。

{
    "type": "connection_established",
    "data": {
        "session_id": "550e8400-e29b-41d4-a716-446655440000",
        "server_time": "2024-12-XX 10:30:00"
    }
}

session_updated

會話更新通知（AI 再次調用時）。

{
    "type": "session_updated",
    "data": {
        "session_id": "new-session-id",
        "summary": "根據您的建議，我已修改了錯誤處理邏輯。",
        "project_directory": "./my-project",
        "timestamp": "2024-12-XX 10:35:00"
    }
}

feedback_received

回饋接收確認。

{
    "type": "feedback_received",
    "data": {
        "session_id": "session-id",
        "status": "success",
        "message": "回饋已成功接收"
    }
}

status_update

狀態更新通知。

{
    "type": "status_update",
    "data": {
        "status": "FEEDBACK_PROCESSING",
        "message": "正在處理您的回饋...",
        "progress": 50
    }
}

error

錯誤訊息。

{
    "type": "error",
    "data": {
        "error_code": "VALIDATION_ERROR",
        "message": "回饋內容不能為空",
        "details": {
            "field": "feedback",
            "value": ""
        }
    }
}

🔧 內部 API

WebUIManager API

create_session()

async def create_session(
    self,
    summary: str,
    project_directory: str
) -> WebFeedbackSession

創建新的回饋會話。

smart_open_browser()

async def smart_open_browser(self, url: str) -> bool

智能開啟瀏覽器，避免重複開啟。

返回值:

True: 檢測到活躍標籤頁，未開啟新視窗
False: 開啟了新瀏覽器視窗

WebFeedbackSession API

submit_feedback()

async def submit_feedback(
    self,
    feedback: str,
    images: List[str],
    settings: dict
) -> None

提交用戶回饋到會話。

wait_for_feedback()

async def wait_for_feedback(self, timeout: int = 600) -> dict

等待用戶回饋完成。

add_websocket()

def add_websocket(self, websocket: WebSocket) -> None

添加 WebSocket 連接到會話。

📊 狀態碼和錯誤碼

HTTP 狀態碼

200 OK: 請求成功
302 Found: 重定向
404 Not Found: 資源不存在
500 Internal Server Error: 服務器內部錯誤

WebSocket 錯誤碼

class ErrorCodes:
    VALIDATION_ERROR = "VALIDATION_ERROR"
    SESSION_NOT_FOUND = "SESSION_NOT_FOUND"
    TIMEOUT_ERROR = "TIMEOUT_ERROR"
    PROCESSING_ERROR = "PROCESSING_ERROR"
    CONNECTION_ERROR = "CONNECTION_ERROR"

會話狀態

class SessionStatus:
    WAITING = "FEEDBACK_WAITING"
    PROCESSING = "FEEDBACK_PROCESSING"
    SUBMITTED = "FEEDBACK_SUBMITTED"
    ERROR = "ERROR"

🔒 安全考慮

輸入驗證

回饋內容長度限制：最大 10,000 字符
圖片大小限制：單張最大 5MB
圖片數量限制：最多 10 張
支援的圖片格式：PNG, JPEG, GIF, WebP

資源保護

WebSocket 連接數限制：每會話最多 5 個連接
會話超時自動清理
內存使用監控和限制

跨域設置

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 開發環境，生產環境應限制
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

下一步: 查看部署指南了解部署配置和運維指南

6.5 KiB Raw Blame History Unescape Escape