用途
QuokkaPix MCP Runner 是一个面向 AI 智能体的本地优先 MCP（Model Context Protocol）适配器，同时提供云端到本地的桥接能力，用于在用户本机浏览器中运行私密的 QuokkaPix 图像与视频工作流。它让 AI 智能体能够处理本地图像和视频文件，而无需将源媒体字节上传到 QuokkaPix 处理服务器。
主要能力
该工具围绕两个浏览器界面运行：图像使用 window.QuokkaPixAgent，视频使用 window.QuokkaPixVideoAgent，通过 Playwright 驱动本地 Chromium。支持的能力包括：为 Shopify、Amazon、Google Merchant 等平台准备产品照片；对照来源规则配置文件验证市场与社交图片输出；将图片压缩为 WebP；移除 EXIF/GPS 元数据；生成社交媒体图片包；批量添加水印；生成 favicon 和应用图标包；以及运行自定义 QuokkaPix 设置而无需手动点击界面。视频方面支持剪辑、裁剪、调整大小、转换或压缩单个本地视频；提取、静音、混音或用本地音乐文件替换视频音频；在本地生成 TXT、SRT 或 VTT 转录，或将字幕烧录进 MP4；准备 YouTube、TikTok Ads 和 Meta Reels 的视频配置文件。
使用方式
工具提供两种兼容模式：local stdio 模式适用于 Claude Desktop、Cursor、LM Studio/Ollama 包装器及其他本地 MCP 客户端；bridge 模式面向 Claude web 等远程 MCP 客户端，但 Chromium 和所有媒体处理仍保留在用户计算机上。图像运行会写入 quokkapix-result.json，视频运行会写入 quokkapix-video-result.json。
使用前需要安装依赖，并配置 MCP 客户端（可直接使用已发布的 npm 包，或从源码配置）。桥接模式需要启动桥接、批准一次性配对 URL、将 https://quokkapix.com/mcp 添加为自定义远程 MCP 连接器、在浏览器中完成 OAuth 授权。远程处理路径相对于 --input-root 和 --output-root，桥接会拒绝路径遍历，且不向云端客户端返回绝对本地路径。
智能体通常先调用 list_recipes 选择最接近的官方配方，再调用 process_images；当所需工作流未被配方覆盖时，使用 process_with_settings 传入直接的 applySettings 载荷。相关工具还包括 get_recipe、validate_recipe、list_rule_profiles、get_rule_profile、validate_result_manifest，以及视频对应的 list_video_recipes、get_video_recipe、validate_video_recipe、list_video_rule_profiles、get_video_rule_profile、validate_video_result_manifest、process_video、process_video_with_settings。远程桥接工具还提供 get_bridge_status、get_billing_status、set_unlock_token 和远程 preflight-only 的 verify_unlock_token。
适用场景
适合需要可重复媒体工作流的 AI 智能体，例如电商产品图准备、市场与社交图片合规验证、网站图片压缩、元数据清理、社交图片包生成、批量水印、图标包生成、视频剪辑压缩、音频处理、本地转录与字幕烧录，以及在不手动操作界面的情况下运行自定义 QuokkaPix 设置。
限制
该包不是公开的服务器端媒体处理 API，不是托管媒体处理服务，不是 QuokkaPix 运行的 GPU/CPU 媒体处理后端，不是将本地文件路径通过 URL 传给 quokkapix.com 的方式，也不能替代浏览器内存限制。本地文件路径仅对用户机器上的本地 MCP 运行器可用。该本地 MCP 适配器自身不签署 x402 支付，需要具备 x402 能力的客户端或钱包调用付费解锁端点并返回 unlockToken。应用 URL 默认被限制为 quokkapix.com 及本地地址，以防止恶意提示或配方将浏览器运行器指向无关页面并上传本地文件。付费视频桥接调用需要 0.7.0 或更新版本。部分市场规则来源被标记为 secondary 或类别/国家特定。具体收费、价格细节以及未在此说明的内容暂未提供。
