MCP Waifu Queue (Gemini Edition)

MCP Waifu Queue

该项目实现了一个用于对话式 AI “waifu”角色的 MCP（Model Context Protocol）服务，通过 Redis 队列异步处理请求，并调用 OpenRouter API。项目使用 FastMCP 库简化服务的设置和管理。

目录

• 功能
• 架构
• 前置条件
• 安装
• 配置
• 运行服务
• MCP API
• 测试
• 故障排除
• 贡献
• 许可证

功能

• 使用 OpenRouter 生成文本，模型来自 ~/.model-openrouter 或 openrouter/free。
• 使用 Redis 队列处理并发请求，实现异步处理。
• 使用 FastMCP 提供符合 MCP 规范的 API。
• 通过 MCP 资源跟踪任务状态。
• 通过环境变量（.env 文件）进行配置。
• 加载 API 密钥：
  • OpenRouter：OPENROUTER_API_KEY 或 ~/.api-openrouter
• 在主目录中选择模型的文件：
  • OpenRouter 模型名称位于 ~/.model-openrouter

架构

该项目由几个关键组件组成：

• main.py：主入口，负责初始化 FastMCP 应用并定义 MCP 工具和资源。
• respond.py：包含使用 OpenRouter API 生成文本的核心逻辑。
• task_queue.py：处理与 Redis 队列的交互（使用 python-rq），并将生成请求加入队列。
• utils.py：包含实用函数，具体而言，call_predict_response 由工作进程执行，用于调用 respond.py 中的生成逻辑。
• worker.py：Redis 工作进程（python-rq），负责处理队列中的任务并调用 call_predict_response。
• config.py：使用 pydantic-settings 管理配置。
• models.py：定义用于验证 MCP 请求和响应的 Pydantic 模型。

请求流程如下：

1. 客户端向 generate_text MCP 工具（定义于 main.py）发送请求。
2. 工具将请求（提示词）加入 Redis 队列（由 task_queue.py 处理）。
3. worker.py 进程从队列中获取任务。
4. 工作进程执行 call_predict_response 函数（来自 utils.py）。
5. call_predict_response 调用 predict_response 函数（位于 respond.py），后者与 OpenRouter API 交互。
6. predict_response 返回生成的文本（或错误消息），RQ 将其存储为任务结果。
7. 客户端可以使用 job://{job_id} MCP 资源（定义于 main.py）获取任务状态和结果。

graph LR
    subgraph Client
        A[User/Client] -->|1. Send Prompt via MCP Tool| B(mcp-waifu-queue: main.py)
    end
    subgraph mcp-waifu-queue Server
        B -->|2. Enqueue Job (prompt)| C[Redis Queue]
        B -->|7. Return Job ID| A
        D[RQ Worker (worker.py)] --|>| C
        D -->|3. Dequeue Job & Execute| E(utils.call_predict_response)
        E -->|4. Call Generation Logic| F(respond.predict_response)
        F -->|5. Call OpenRouter API| G[OpenRouter API]
        G -->|6. Return Response| F
        F --> E
        E -->|Update Job Result in Redis| C
        A -->|8. Check Status via MCP Resource| B
        B -->|9. Fetch Job Status/Result| C
        B -->|10. Return Status/Result| A
    end

前置条件

• Python 3.7+
• pip 或 uv（Python 包安装程序）
• Redis 服务（已安装并运行）
• OpenRouter API 密钥

你可以在 Redis 官方网站上找到适用于你的系统的 Redis 安装说明：https://redis.io/docs/getting-started/ 你可以从此处获取 OpenRouter API 密钥：https://openrouter.ai/

安装

1. 克隆仓库：

   git clone <YOUR_REPOSITORY_URL>
   cd mcp-waifu-queue
   

2. 使用 uv 创建并激活虚拟环境：

   python -m uv venv .venv
   .venv/Scripts/python.exe -m ensurepip
   .venv/Scripts/python.exe -m pip install uv
   

3. 安装依赖：

   .venv/Scripts/python.exe -m uv pip install -r requirements.txt
   .venv/Scripts/python.exe -m uv pip install -r requirements-dev.txt
   

配置

1. 通过 $HOME 中的文件设置模型名称：

   • OpenRouter 模型文件：

     echo "openrouter/free" > ~/.model-openrouter
     

2. API 密钥： 首选通过环境变量设置，也可回退到文件：

   • OpenRouter：OPENROUTER_API_KEY 或 ~/.api-openrouter

   echo "YOUR_API_KEY_HERE" > ~/.api-openrouter
   

   （请将 YOUR_API_KEY_HERE 替换为你的实际密钥）

3. 其他设置： 将 .env.example 文件复制为 .env：

   cp .env.example .env
   

4. 修改 .env 文件以设置其余配置值：

   • MAX_NEW_TOKENS：响应的最大令牌数（默认值：2048）。
   • REDIS_URL：Redis 服务的 URL（默认值：redis://localhost:6379）。
   • FLASK_ENV、FLASK_APP：可选项，与在其他地方使用的 Flask 相关，不是 MCP 服务/工作进程运行的核心配置。

运行服务

1. 确保 Redis 正在运行。 如果你是在本地安装的，可能需要启动 Redis 服务进程（例如，运行 redis-server 命令，或通过服务管理器启动）。

2. 启动 RQ 工作进程： 打开终端，激活虚拟环境（source .venv/bin/activate 或类似命令），然后运行：

   python -m mcp_waifu_queue.worker
   

   此命令会启动工作进程，它将监听 .env 文件中定义的 Redis 队列任务。请保持此终端处于运行状态。

3. 启动 MCP 服务： 打开另一个终端，激活虚拟环境，然后使用 uvicorn 等工具运行 MCP 服务（你可能需要安装它：pip install uvicorn 或 uv pip install uvicorn）：

   uvicorn mcp_waifu_queue.main:app --reload --port 8000 # 示例端口
   

   将 8000 替换为你所需的端口。--reload 标志适用于开发环境。

   或者，你可以使用 start-services.sh 脚本（主要为 Linux/macOS 环境设计），该脚本会尝试在后台启动 Redis（如果尚未运行）和工作进程：

   # 确保脚本具有可执行权限：chmod +x ./scripts/start-services.sh
   ./scripts/start-services.sh
   # 然后按照上文所述手动启动 MCP 服务。
   

MCP API

该服务提供以下符合 MCP 规范的端点：

工具

• generate_text
  • 描述： 通过后台队列向 OpenRouter API 发送文本生成请求。
  • 输入： {"prompt": "Your text prompt here"}（类型：GenerateTextRequest）
  • 输出： {"job_id": "rq:job:..."}（已排队任务的唯一 ID）

资源

• job://{job_id}
  • 描述： 获取先前提交任务的状态和结果。
  • URI 参数： job_id（generate_text 工具返回的 ID）。
  • 输出： {"status": "...", "result": "..."}（类型：JobStatusResponse）
    • status：任务的当前状态（例如，“queued”“started”“finished”“failed”）。RQ 在内部使用的术语略有不同（“started” 对应 “processing”，“finished” 对应 “completed”）。该资源会进行映射。
    • result：如果任务状态为 “completed”，则为生成的文本；否则为 null。如果任务失败，结果可能为 null，也可能包含错误信息，具体取决于 RQ 的处理方式。

测试

项目包含测试。请确保已安装测试依赖项（pip install -e .[test] 或 uv pip install -e .[test]）。

使用 pytest 运行测试：

pytest tests

注意： 测试可能需要模拟 Redis（fakeredis），并且可能需要根据具体实现模拟 OpenRouter API 调用。

故障排除

• 错误：OpenRouter API key not available：请确保已设置 OPENROUTER_API_KEY，或 ~/.api-openrouter 文件中以单行形式（不含空格）保存了你的密钥。
• 作业卡在“queued”状态：请确认 RQ worker（python -m mcp_waifu_queue.worker）正在另一个终端中运行，并连接到 .env 中指定的同一 Redis 实例。检查 worker 日志中是否有错误。
• ConnectionRefusedError（Redis）：请确保 Redis 服务正在运行，且可通过 .env 中指定的 REDIS_URL 访问。
• MCP 服务连接问题：请确保 MCP 服务（uvicorn ...）正在运行，并且你连接的是正确的主机和端口。

贡献

1. Fork 此仓库。
2. 为你的功能或错误修复创建新分支（git checkout -b feature/your-feature-name）。
3. 进行更改并提交（git commit -am 'Add some feature'）。
4. 将分支推送到你 Fork 的仓库（git push origin feature/your-feature-name）。
5. 在原始仓库中创建 Pull Request。

请遵守项目的代码规范和 lint 规则（ruff）。

许可证

本项目采用 MIT-0 License 许可，详情请参阅 LICENSE 文件。