MCP/mcp-feedback-enhanced
1
0
Fork 0
mirror of https://github.com/Minidoracat/mcp-feedback-enhanced.git synced 2025-07-27 10:42:25 +08:00
Code Issues Packages Projects Releases Wiki Activity
mcp-feedback-enhanced/docs/architecture/api-reference.md
Minidoracat e6bf5f74ec 📝 更新架構文檔
2025-06-13 17:03:59 +08:00

13 KiB
Raw Blame History

API 參考文檔

本文檔提供 MCP Feedback Enhanced 的完整 API 參考，包括 MCP 工具、Web API、WebSocket 通信協議和內部 API 接口。

📡 MCP 工具 API

MCP Feedback Enhanced 基於 FastMCP 框架實現，提供標準的 MCP 協議支援。

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

GET /api/translations

獲取多語言翻譯資源。

響應: 200 OK

{
    "zh-TW": {
        "app": {
            "title": "MCP Feedback Enhanced"
        }
    },
    "en": {
        "app": {
            "title": "MCP Feedback Enhanced"
        }
    },
    "zh-CN": {
        "app": {
            "title": "MCP Feedback Enhanced"
        }
    }
}

GET /api/session-status

獲取當前會話狀態。

響應: 200 OK

{
    "has_session": true,
    "status": "active",
    "session_info": {
        "project_directory": "./my-project",
        "summary": "代碼審查完成",
        "feedback_completed": false
    }
}

GET /api/current-session

獲取當前會話詳細信息。

響應: 200 OK

{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "project_directory": "./my-project",
    "summary": "代碼審查完成",
    "feedback_completed": false,
    "command_logs": "",
    "images_count": 0
}

錯誤響應: 404 Not Found

{
    "error": "沒有活躍會話"
}

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"
    }
}

prompt_management

提示詞管理操作。

{
    "type": "prompt_management",
    "data": {
        "action": "add|update|delete|use",
        "prompt": {
            "id": "prompt_1_1703123456789",
            "name": "代碼審查提示",
            "content": "請檢查這段代碼的邏輯正確性和性能優化建議。",
            "isAutoSubmit": false
        }
    }
}

字段說明:

  • action: 操作類型（add=新增, update=更新, delete=刪除, use=使用）
  • prompt.id: 提示詞唯一標識符
  • prompt.name: 提示詞名稱
  • prompt.content: 提示詞內容
  • prompt.isAutoSubmit: 是否為自動提交提示詞

auto_submit_control

自動提交功能控制。

{
    "type": "auto_submit_control",
    "data": {
        "action": "start|stop|update_settings",
        "settings": {
            "enabled": true,
            "timeout": 30,
            "promptId": "prompt_1_1703123456789"
        }
    }
}

字段說明:

  • action: 控制動作（start=啟動, stop=停止, update_settings=更新設定）
  • settings.enabled: 是否啟用自動提交
  • settings.timeout: 自動提交倒數時間（秒）
  • settings.promptId: 自動提交使用的提示詞 ID

session_management

會話管理操作。

{
    "type": "session_management",
    "data": {
        "action": "get_history|get_stats|clear_history",
        "sessionId": "550e8400-e29b-41d4-a716-446655440000"
    }
}

字段說明:

  • action: 管理動作（get_history=獲取歷史, get_stats=獲取統計, clear_history=清除歷史）
  • sessionId: 會話 ID（可選）

📥 服務器 → 客戶端訊息

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
    }
}

auto_submit_status

自動提交狀態更新。

{
    "type": "auto_submit_status",
    "data": {
        "enabled": true,
        "countdown": 25,
        "promptId": "prompt_1_1703123456789",
        "promptName": "代碼審查提示"
    }
}

字段說明:

  • enabled: 自動提交是否啟用
  • countdown: 剩餘倒數時間（秒）
  • promptId: 當前自動提交提示詞 ID
  • promptName: 當前自動提交提示詞名稱

session_history

會話歷史數據。

{
    "type": "session_history",
    "data": {
        "sessions": [
            {
                "session_id": "session-1",
                "summary": "代碼審查完成",
                "status": "completed",
                "created_at": "2024-12-13T10:30:00Z",
                "feedback_length": 150
            }
        ],
        "stats": {
            "total": 10,
            "completed": 8,
            "average_feedback_length": 120
        }
    }
}

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 連接到會話。

PromptManager API

addPrompt()

def addPrompt(self, name: str, content: str) -> dict

新增提示詞到管理器。

參數:

  • name: 提示詞名稱（必須唯一）
  • content: 提示詞內容

返回值: 新建的提示詞對象

updatePrompt()

def updatePrompt(self, id: str, name: str, content: str) -> dict

更新現有提示詞。

deletePrompt()

def deletePrompt(self, id: str) -> bool

刪除指定提示詞。

usePrompt()

def usePrompt(self, id: str) -> dict

使用提示詞（更新最近使用記錄）。

getPromptsSortedByUsage()

def getPromptsSortedByUsage(self) -> List[dict]

獲取按使用頻率排序的提示詞列表，自動提交提示詞優先顯示。

SessionManager API

getCurrentSession()

def getCurrentSession(self) -> dict

獲取當前活躍會話信息。

getSessionHistory()

def getSessionHistory(self) -> List[dict]

獲取會話歷史記錄。

getSessionStats()

def getSessionStats(self) -> dict

獲取會話統計信息。

AutoSubmitManager API

start()

def start(self, timeoutSeconds: int, promptId: str) -> None

啟動自動提交倒數計時器。

stop()

def stop(self) -> None

停止自動提交倒數計時器。

updateSettings()

def updateSettings(self, enabled: bool, timeout: int, promptId: str) -> None

更新自動提交設定。

📊 狀態碼和錯誤碼

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"

提示詞狀態

class PromptStatus:
    ACTIVE = "active"           # 活躍提示詞
    AUTO_SUBMIT = "auto_submit" # 自動提交提示詞
    ARCHIVED = "archived"       # 已歸檔提示詞

自動提交狀態

class AutoSubmitStatus:
    DISABLED = "disabled"       # 已停用
    ENABLED = "enabled"         # 已啟用
    COUNTDOWN = "countdown"     # 倒數計時中
    COMPLETED = "completed"     # 已完成提交

🔒 安全考慮

輸入驗證

  • 回饋內容長度限制：最大 10,000 字符
  • 圖片大小限制：單張最大 5MB
  • 圖片數量限制：最多 10 張
  • 支援的圖片格式：PNG, JPEG, GIF, WebP
  • 提示詞名稱長度限制：最大 100 字符
  • 提示詞內容長度限制：最大 5,000 字符
  • 提示詞數量限制：最多 50 個

資源保護

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

跨域設置

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

📚 相關文檔

版本: 2.4.0 最後更新: 2025年6月 維護者: Minidoracat API 版本: v1 協議支援: MCP 2.0+, WebSocket, HTTP/1.1 新功能: 自動提交、提示詞管理、會話管理、語系切換優化