Waifu Queue

🚀 MCP Waifu Queue

MCP Waifu Queue is a project that provides a background task queue and related API interfaces, enabling text generation requests and task status queries. It simplifies the process of interacting with the Gemini API and managing tasks.

🚀 Quick Start

📦 Installation

1. Clone the repository:

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

2. Install dependencies:

   • Create and activate a Python virtual environment.
   • Install project dependencies:

     pip install -r requirements.txt
     

⚙️ Environment Configuration

Create a .env file in the project's root directory and add the following content:

REDIS_URL=redis://localhost:6379/0

💻 Usage Examples

🔧 Background Task Queue

• Start the worker process:

  python -m mcp_waifu_queue.worker
  

• Start the MCP server:

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

  Or use the script (for Linux/macOS):

  ./scripts/start-services.sh
  

📚 Documentation

🛠️ MCP API Interfaces

Tools

• generate_text
  • Description: Send a text generation request to the Gemini API.
  • Input: {"prompt": "Your text prompt content"} (Type: GenerateTextRequest)
  • Output: {"job_id": "rq:job:..."} (A unique task ID)

Resources

• job://{job_id}
  • Description: Get the status and result of a previously submitted task.
  • Path parameter: job_id (The task ID returned by the generate_text tool).
  • Output: {"status": "...", "result": "..."} (Type: JobStatusResponse)
    • status: The current status of the task (e.g., "queued", "started", "finished", "failed"). Different terms are used internally by RQ, and the resource will perform mapping.
    • result: If the task status is "completed", it contains the generated text; otherwise, it is null. If the task fails, the result may be null or contain error information.

🧪 Testing

The project includes test cases. Make sure the test dependencies are installed:

pip install -e .[test]

Run the tests:

pytest tests

Note: Testing may require simulating Redis (using fakeredis) and Gemini API calls, depending on the implementation.

🐞 Troubleshooting

• Error: Gemini API key not found in.../.api-gemini or GEMINI_API_KEY environment variable: Ensure that a valid Gemini API key exists in the ~/.api-gemini file or set the GEMINI_API_KEY environment variable.
• Gemini API call errors (e.g., AuthenticationError, PermissionDenied): Check if the API key in ~/.api-gemini is correct and valid. Make sure the API is enabled in your Google Cloud project.
• Task stuck in the "queued" state: Confirm that the RQ worker (python -m mcp_waifu_queue.worker) is running in another terminal and connected to the same Redis instance specified in the .env file. Check the worker logs for error information.
• Connection refused error (Redis): Ensure that the Redis server is running and accessible at the REDIS_URL specified in the .env file.
• MCP server connection issues: Confirm that the MCP server (uvicorn ...) is running and you are connecting to the correct host and port.

🤝 Contribution Guidelines

1. Fork the repository:
   • Fork the project repository.
   • Create a feature or fix branch:

     git checkout -b feature/your-feature-name
     

2. Commit changes:
   • Commit your modifications:

     git add .
     git commit -m "Add feature: Your feature description"
     git push origin feature/your-feature-name
     

3. Create a pull request:
   • Navigate to the project's "Pull Request" page on GitHub and submit a pull request.

📝 Code Style

• Follow the PEP8 coding style.
• Use meaningful variable and function names.
• Ensure that code comments are clear and easy to understand.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Thank you for using MCP Waifu Queue! If you have any questions, please feel free to contact the maintainers.