quark-mcp

夸克 MCP Server — через встроенную страницу AI-чата браузера 夸克 (quark.cn/chat, 千问) предоставляет возможность работы с изображениями, вопросов-ответов и генерации изображений по тексту без затрат на API.

На базе CDP + Playwright управляет браузером 夸克 в отдельном профиле: на странице чата загружает изображения, задаёт вопрос и извлекает ответ; API-ключ не требуется.

Возможности

Related MCP server: Percepta MCP Server

Как это работает

Claude Code ──MCP stdio──> server.py ──> quark_mcp/quark_ai.py ──CDP──> 夸克浏览器（独立 profile）
                                         quark_mcp/video_analyze.py         │
                                                                  quark.cn/chat（网页版千问）

• 夸克 запускается с --remote-debugging-port=9224 в отдельном профиле, статус входа сохраняется.

• Изображения отправляются через DataTransfer-инъекцию (JS_DROP_IMAGE), а не filechooser; отправка происходит после появления списка вложений.

• Критерий завершения ответа: в card class AI-ответа [data-chat-answers-wrap] появляется completed.

Требования к окружению

• Python 3.10+

• браузер 夸克 (автоматически определяет переменную окружения QUARK_PATH или стандартные пути установки)

• Для video_analyze нужны ffmpeg/ffprobe (извлечение кадров) + pillow (надписи с таймкодом, сборка плиток) +

• Опционально: yt-dlp (загрузка онлайн-видео), faster-whisper (transcribe=True для транскрипции аудио)

Установка

pip install fastmcp playwright websocket-client
# 可选功能依赖
pip install pillow           # 视频帧时间戳烧录 + 拼图（video_analyze 必需）
pip install yt-dlp           # 在线视频下载（video_analyze 传 URL 时）
pip install faster-whisper   # 音频转写（transcribe=True）

yt-dlp.exe, установленный через pip, часто ложится в Scripts/ и не попадает в PATH; в коде уже есть подстраховка: если команда yt-dlp не найдена, автоматически используется python -m yt_dlp, так что настраивать PATH не обязательно.

Использование

1. Как MCP-сервер (Claude Code и т. п.)

{
  "mcpServers": {
    "quark-mcp": {
      "command": "python",
      "args": ["/path/to/quark-mcp/server.py"]
    }
  }
}

2. HTTP-режим (отладка)

python server.py --port 8080

3. Прямой запуск через CLI (без MCP)

# 启动 daemon（首次需手动登录一次，登录态持久化）
python quark_mcp/quark_ai.py --start
python quark_mcp/quark_ai.py --status

# 纯文本问答
python quark_mcp/quark_ai.py --ask "帮我解释一下 CDP 是什么"

# 图片识别
python quark_mcp/quark_ai.py --image photo.jpg --question "请描述这张图片"

# 文生图（默认存 ~/.claude/quark-images）
python quark_mcp/quark_ai.py --gen "一只橘猫坐在窗台看夕阳,插画风格"
python quark_mcp/quark_ai.py --gen "复古黄铜怀表" --outdir ./imgs --max-images 2

# 视频分析（本地文件或 URL）
python quark_mcp/video_analyze.py --video demo.mp4
python quark_mcp/video_analyze.py --video demo.mp4 --transcribe

Примечания по генерации изображений

• Модель: следует модели по умолчанию на странице диалога 夸克 (千问), её нельзя изменить.

• Запуск: отдельной кнопки/переключателя «генерации изображений» нет, генерация срабатывает от обычного словесного запроса (в промпте нужно явно написать, что рисовать).

• Пропорции: в веб-версии нет селектора пропорций, поэтому пропорции нужно описать словами в промпте (например, «горизонтальная композиция 16:9»).

• Результат: за раз получается примерно 4 картинки, примерно 960×1280.

• Загрузка: CDN-URL подписаны auth_key, поэтому картинки нужно тянуть через контекст браузера (page.request), обычный urllib даст 403.

# 返回结构
{"ok": True,
 "images": ["C:/Users/.../.claude/quark-images/quark_20260823-103519_1.png", ...],
 "text": "已生成 2 张图片, 保存至 ...",
 "meta": {"found": 4, "details": [{"path": ..., "bytes": ..., "width": 960, "height": 1280}],
          "model": "千问(夸克对话页默认)"}}

Конфигурация

• Путь к 夸克: установите переменную окружения QUARK_PATH с указанием исполняемого файла.

• Порт CDP: по умолчанию 9224 — см. CDP_PORT в quark_ai.py (порт разнесён с doubao-mcp, чтобы использовать 9223, можно сосуществовать).

• Вход: отдельный профиль находится в ~/.claude/quark-ai-profile; после первого daemon_start нужно один раз войти в систему вручную.

• Каталог для картинок: по умолчанию ~/.claude/quark-images, можно переопределить через outdir.

Часто задаваемые вопросы

• Код выхода 1 (CDP недоступен / не найден 夸克): демон не запущен — сначала выполните daemon_start; либо задайте QUARK_PATH.

• Код выхода 2 (не выполнен вход): откройте страницу диалога и один раз войдите вручную.

• Код выхода 3 (проблема с изображением): не существует указанного пути или не удалось загрузить изображение.

• Код выхода 4 (сбой взаимодействия): не найдено поле ввода / кнопка отправки, обычно из-за изменения страницы.

• Код выхода 5 (таймаут): ответ генерируется долго, увеличьте timeout (для генерации изображений по умолчанию 300 с).

• Код выхода 6 (пустой результат): ответ пуст или не создано ни одного изображения, возможно риск-контроль или фильтрация контента.

Зависимость от структуры страницы

Чисто веб-операции означают, что при изменении структуры страницы интерфейса 夸克 может сломаться. Проверено на текущем наборе зависимостей (SEL в quark_ai.py, на базе 夸克 7.1.2.956 / Chromium 144 + веб-версия 4.0.0):

Два подводных камня:

1. Признак завершения — это completed на карточке ответа, а не .qk-markdown -> qk-markdown-complete. Второй вариант на веб-версии отсутствует — он используется в клиентской панели; если скопировать его, результат всегда будет считаться «не завершённым».

2. В генерации изображений нужно ждать стабилизации набора подписанных URL картинок, а опираться только на completed нельзя: текст завершается раньше, а финальные изображения появляются ещё через ~45 секунд, когда заменяется плейсхолдер-анимация. Только если после completed подождать ещё IMAGE_GRACE (120 секунд) и картинки всё ещё нет, можно считать, что в этом раунде изображений нет.

License

MIT