Waifu Queue

🚀 MCP Waifu隊列

MCP Waifu隊列是一個用於處理後臺任務的工具，藉助Redis和RQ實現任務隊列功能，同時提供與Gemini API交互的接口，可實現文本生成等功能。

🚀 快速開始

安裝項目

1. 獲取代碼倉庫：

   git clone https://github.com/your-username/mcp_waifu_queue.git
   cd mcp_waifu_queue
   

2. 安裝依賴項：

   • 創建並激活Python虛擬環境。
   • 安裝項目依賴：

     pip install -r requirements.txt
     

環境配置

在項目的根目錄下創建一個.env文件，並添加以下內容：

REDIS_URL=redis://localhost:6379/0

啟動服務

• 啟動工作者進程：

  python -m mcp_waifu_queue.worker
  

• 啟動MCP服務器：

  uvicorn mcp_waifu_queue.main:app --reload --port 8000
  

  或使用腳本（針對Linux/macOS）：

  ./scripts/start-services.sh
  

📦 安裝指南

克隆倉庫

git clone https://github.com/your-username/mcp_waifu_queue.git
cd mcp_waifu_queue

安裝依賴

pip install -r requirements.txt

安裝測試依賴

pip install -e .[test]

💻 使用示例

基本使用

啟動工作者進程

python -m mcp_waifu_queue.worker

啟動MCP服務器

uvicorn mcp_waifu_queue.main:app --reload --port 8000

高級使用

使用腳本啟動服務（針對Linux/macOS）

./scripts/start-services.sh

📚 詳細文檔

MCP API接口

工具

• generate_text
  • 描述：向Gemini API發送文本生成請求。
  • 輸入：{"prompt": "您的文本提示內容"}（類型：GenerateTextRequest）
  • 輸出：{"job_id": "rq:job:..."}（一個唯一的任務ID）

資源

• job://{job_id}
  • 描述：獲取之前提交的任務的狀態和結果。
  • 路徑參數：job_id（由generate_text工具返回的任務ID）。
  • 輸出：{"status": "...", "result": "..."}（類型：JobStatusResponse）
    • status：任務當前狀態（例如："queued"，"started"，"finished"，"failed"）。RQ內部使用不同的術語，資源會進行映射。
    • result：如果任務狀態為"completed"，則包含生成的文本；否則為null。如果任務失敗，結果可能為null或包含錯誤信息。

測試

運行測試用例：

pytest tests

注意：測試可能需要模擬Redis（使用fakeredis）和Gemini API調用，具體取決於實現方式。

故障排除

• 錯誤：Gemini API密鑰未在.../.api-gemini或GEMINI_API_KEY環境變量中找到：確保在~/.api-gemini文件中存在有效的Gemini API密鑰，或者設置GEMINI_API_KEY環境變量。
• Gemini API調用錯誤（例如AuthenticationError，PermissionDenied）：檢查~/.api-gemini中的API密鑰是否正確且有效。確保API在您的Google Cloud項目中已啟用。
• 任務卡在"queued"狀態：確認RQ工作者（python -m mcp_waifu_queue.worker）在另一個終端運行，並且連接到.env文件指定的相同Redis實例。檢查工作者日誌以獲取錯誤信息。
• 連接被拒絕錯誤（Redis）：確保Redis服務器正在運行並且可以在.env文件指定的REDIS_URL下訪問。
• MCP服務器連接問題：確認MCP服務器（uvicorn ...）正在運行，並且您連接到正確的主機和端口。

貢獻指南

1. 獲取代碼倉庫：
   • Fork項目倉庫。
   • 創建功能或修復分支：

     git checkout -b feature/your-feature-name
     

2. 提交更改：
   • 提交修改：

     git add .
     git commit -m "添加功能：你的功能描述"
     git push origin feature/your-feature-name
     

3. 創建拉取請求：
   • 在GitHub上導航到項目的“Pull Request”頁面，提交拉取請求。

代碼規範

• 遵循PEP8編碼規範。
• 使用有意義的變量名和函數命名。
• 確保代碼註釋清晰易懂。

📄 許可證

項目遵循MIT許可證。查看LICENSE文件以獲取詳細信息。

感謝使用MCP Waifu隊列！如果有任何問題，請隨時聯繫維護人員。