关键词

Gemini APIRedis队列异步处理文本生成对话AI

项目简介

Waifu Queue MCP服务器是一个基于 Model Context Protocol (MCP) 构建的后端服务，专为 conversational AI "waifu" 角色设计。它利用 Google Gemini API 进行文本生成，并通过 Redis 队列实现异步请求处理，确保在高并发场景下的稳定性和响应速度。该服务器使用 'FastMCP' 库简化了 MCP 服务器的搭建和管理，提供标准的 MCP 接口，方便 LLM 客户端集成和调用。

主要功能点

  • 文本生成: 使用 Google Gemini API ('gemini-2.5-flash-preview-04-17') 生成高质量的对话文本。
  • 异步处理: 通过 Redis 队列管理和处理文本生成请求，避免阻塞主线程，提高并发处理能力。
  • MCP 协议兼容: 基于 'FastMCP' 库，完全兼容 MCP 协议，提供标准的工具 (Tools) 和资源 (Resources) 接口。
  • 任务状态追踪: 通过 MCP 资源 'job://{job_id}' 实时查询文本生成任务的状态和结果。
  • 灵活配置: 支持通过环境变量和配置文件 '.env' 进行服务器参数配置，API 密钥安全存储在 '~/.api-gemini' 文件中。

安装步骤

  1. 克隆仓库

    git clone https://github.com/waifuai/mcp-waifu-queue
cd mcp-waifu-queue

  2. 创建并激活虚拟环境

    python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate  # Windows

  3. 安装依赖

    pip install -e .
pip install uvicorn

    如果需要运行测试，请安装测试依赖：

    pip install -e .[test]

  4. 配置 Gemini API 密钥

    创建文件 '~/.api-gemini'，并将您的 Google Gemini API 密钥粘贴到文件中。

    echo "YOUR_API_KEY_HERE" > ~/.api-gemini

  5. 配置 Redis 连接

    复制 '.env.example' 文件为 '.env'，并根据您的 Redis 服务器配置修改 '.env' 文件中的 'REDIS_URL'。如果 Redis 服务器运行在本地默认端口，则无需修改。

    cp .env.example .env

服务器配置

MCP 客户端需要配置以下信息以连接到 Waifu Queue MCP 服务器。以下是服务器的启动命令和参数配置示例（JSON 格式）：

{
  "serverName": "waifu-queue-mcp-server",
  "command": "uvicorn",
  "args": [
    "mcp_waifu_queue.main:app",
    "--reload",  // 开启热重载 (开发环境建议开启，生产环境关闭)
    "--port",
    "8000"     // 指定服务器端口，默认为 8000
  ]
}

配置参数说明:

  • 'serverName': MCP 服务器的名称，客户端用于标识和管理连接。可以自定义。
  • 'command': 启动 MCP 服务器的命令，这里使用 'uvicorn' 启动 ASGI 应用。
  • 'args': 启动命令的参数列表。
    • 'mcp_waifu_queue.main:app': 指定要运行的 ASGI 应用入口点，'mcp_waifu_queue.main' 是 'main.py' 文件，'app' 是 'main.py' 中创建的 'FastMCP' 应用实例。
    • '--reload': 开启代码热重载，修改代码后服务器自动重启，仅用于开发环境，生产环境不建议开启。
    • '--port': 指定服务器监听的端口号，默认为 '8000'，可以根据需要修改。

注意: MCP 客户端不需要配置 '.env' 文件或 Gemini API 密钥。这些配置是 Waifu Queue MCP 服务器自身运行所需要的。MCP 客户端只需要配置上述 JSON 信息，以便连接到正在运行的 MCP 服务器。

基本使用方法

  1. 启动 Redis 服务器

    确保 Redis 服务器已安装并运行。

  2. 启动 RQ Worker

    打开一个终端，激活虚拟环境，运行 RQ Worker 进程：

    python -m mcp_waifu_queue.worker

  3. 启动 MCP 服务器

    打开另一个终端，激活虚拟环境，运行 MCP 服务器：

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

    或者使用 'start-services.sh' 脚本 (Linux/macOS 环境):

    chmod +x ./scripts/start-services.sh
./scripts/start-services.sh
uvicorn mcp_waifu_queue.main:app --reload --port 8000

  4. 使用 MCP 客户端

    使用任何 MCP 客户端，根据上述 服务器配置 中的 JSON 信息连接到 Waifu Queue MCP 服务器。

    • 调用 'generate_text' 工具: 发送包含 'prompt' 字段的 JSON-RPC 请求到 'generate_text' 工具，例如：

      {
  "jsonrpc": "2.0",
  "method": "generate_text",
  "params": {"prompt": "你好，请自我介绍一下。"},
  "id": 1
}

      服务器会返回包含 'job_id' 的响应，例如：

      {
  "jsonrpc": "2.0",
  "result": {"job_id": "rq:job:xxxxxxxxxxxxxxxxxxxxx"},
  "id": 1
}

    • 查询任务状态: 使用返回的 'job_id' 构建 MCP 资源 URI 'job://{job_id}'，例如 'job://rq:job:xxxxxxxxxxxxxxxxxxxxx'，发送 JSON-RPC 请求获取任务状态和结果。例如：

      {
  "jsonrpc": "2.0",
  "method": "job://rq:job:xxxxxxxxxxxxxxxxxxxxx",
  "params": {},
  "id": 2
}

      服务器会返回包含 'status' 和 'result' 的响应，例如：

      {
  "jsonrpc": "2.0",
  "result": {"status": "completed", "result": "你好！我是一个 Waifu AI 模型。很高兴为你服务！"},
  "id": 2
}

关键词

Gemini API, Redis队列, 异步处理, 文本生成, 对话AI

信息

分类

AI与计算

访问项目