🚀 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队列！如果有任何问题，请随时联系维护人员。