تكامل agents

QuokkaPix MCP Runner

محول MCP محلي يفتح QuokkaPix في متصفح محلي، يمرر الملفات عبر file input، يشغل recipes أو إعدادات مباشرة، ثم يحفظ الناتج وresult manifest.

agents.html agent-test.html GitHub npm Glama mcpservers.org

Image + Video local and remote MCP

Version 0.7.0 exposes one exact Image and Video quote/token flow through local stdio and the OAuth-protected remote MCP with a paired bridge. Use process_video with an official recipe or process_video_with_settings with direct settings. Video runs in local Chromium and never relays media bytes through the control plane.

{
  "recipeId": "tiktok_vertical",
  "inputFile": "/absolute/path/source.mp4",
  "outputDir": "/absolute/path/output"
}

MCP بعيد مع معالجة محلية

يمكن لـ Claude web وعملاء MCP السحابيين الآخرين الاتصال عبر OAuth، بينما ينفذ محول npm الحالي كل عمليات الصور على جهاز المستخدم.

npx quokkapix-mcp bridge --input-root /path/to/input --output-root /path/to/output

Remote MCP: https://quokkapix.com/mcp

يسمح النطاق mcp:tools بأدوات القراءة. تتطلب المعالجة وحفظ رمز إلغاء القفل أيضًا bridge:execute. يلغي --reset تفويض الجهاز السابق قبل إقران جهاز بديل.

تنقل طبقة التحكم الإعدادات وأسماء الملفات النسبية والحالة وresult manifest فقط. لا توفر endpoint لرفع الصور ولا تنقل بايتات الملفات الأصلية أو الناتجة.

دليل عملي لـ Claude وCursor وMCP المحلي

استخدم هذه الصفحة عندما يحتاج AI agent على سطح المكتب إلى معالجة صور محلية عبر QuokkaPix. MCP runner هو adapter محلي عبر stdio: يشغّل MCP client حزمة quokkapix-mcp، يفتح adapter متصفحاً محلياً، يرفع الملفات عبر browser file input، يطبق recipe أو إعدادات مباشرة، ثم يحفظ الناتج وquokkapix-result.json.

هذا ليس API مستضافة لمعالجة الصور. تبقى الصور المصدر في مسار المتصفح المحلي ولا تُرسل إلى خادم معالجة QuokkaPix.

إعداد Claude Desktop

أضف server entry في إعدادات MCP داخل Claude Desktop ثم أعد تشغيله. بعد ذلك تأكد من ظهور tools مثل list_recipes وprocess_images وprocess_with_settings.

{
  "mcpServers": {
    "quokkapix": {
      "command": "npx",
      "args": [
        "-y",
        "quokkapix-mcp"
      ],
      "env": {
        "QUOKKAPIX_APP_URL": "https://quokkapix.com/#agent=1"
      }
    }
  }
}

إعداد Cursor

استخدم إعدادات MCP في Cursor وأضف server entry نفسه. يشغّل Cursor adapter عبر stdio ويمكنه استدعاء الأدوات نفسها.

{
  "mcpServers": {
    "quokkapix": {
      "command": "npx",
      "args": [
        "-y",
        "quokkapix-mcp"
      ],
      "env": {
        "QUOKKAPIX_APP_URL": "https://quokkapix.com/#agent=1"
      }
    }
  }
}

أمر fallback في Windows

إذا لم يستطع MCP client في Windows العثور على npx مباشرة، شغّله عبر cmd /c. استخدم ذلك فقط عندما لا يكتشف العميل أمر npx البسيط.

{
  "mcpServers": {
    "quokkapix": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "quokkapix-mcp"
      ],
      "env": {
        "QUOKKAPIX_APP_URL": "https://quokkapix.com/#agent=1"
      }
    }
  }
}

عملاء MCP المحليون وLLM wrappers

أي عميل MCP محلي يستطيع تشغيل stdio server يمكنه استخدام الحزمة نفسها، بما في ذلك desktop clients وeditor agents وLM Studio أو Ollama wrappers.

القاعدة المهمة ثابتة: مرر مسارات ملفات محلية حقيقية إلى MCP tool call، وليس إلى URL الموقع العام. QuokkaPix يستقبل الملفات فقط عبر browser file input الذي يفتحه runner.

أول prompts مفيدة

صور المنتجات

Use QuokkaPix to prepare these local images for Shopify: white background, square product canvas, WebP output, max 300 KB, then save the ZIP and result manifest.

ضغط الموقع

Use QuokkaPix to convert this folder of JPG and PNG images to WebP for the website, keep reasonable visual quality, and report files that fail QA.

تنظيف metadata

Use QuokkaPix to remove EXIF, GPS, camera and software metadata from these images and return the cleaned ZIP plus the manifest.

تشغيل recipe رسمية

استخدم list_recipes أولاً، اختر recipe id، ثم استدع process_images. تغطي recipes الرسمية marketplace وsocial والضغط وmetadata وPDF وfavicon وسيناريوهات العلامة المائية.

{
  "recipeId": "shopify_product_pack",
  "inputFiles": [
    "/Users/me/products/photo-01.jpg",
    "/Users/me/products/photo-02.jpg"
  ],
  "outputDir": "/Users/me/quokkapix-output/shopify"
}

تشغيل إعدادات مباشرة

استخدم process_with_settings عندما يحتاج agent إلى سطح الإعدادات نفسه الذي تقبله window.QuokkaPixAgent.applySettings بدلاً من recipe باسم محدد.

{
  "settings": {
    "mode": "batch",
    "tool": "compress",
    "settings": {
      "compress": {
        "format": "webp",
        "quality": 0.82
      }
    }
  },
  "inputFiles": [
    "/Users/me/site/hero.jpg",
    "/Users/me/site/card.jpg"
  ],
  "outputDir": "/Users/me/quokkapix-output/webp"
}

ما الذي يجب التحقق منه بعد التشغيل

الفحص	لماذا يهم
وجود ملف output أو ZIP أو PDF داخل outputDir	يثبت أن تنزيل المتصفح اكتمل وأن adapter حفظ الناتج.
quokkapix-result.json يحتوي على status: done	يثبت أن QuokkaPix وصل إلى حالة نجاح نهائية ولم يفتح المحرر فقط.
outputs[] يحتوي على metadata المصدر والناتج	يسمح للـ agent بالإبلاغ عن الأبعاد والصيغ والأحجام والتحذيرات والأسماء.
qa.ok وqa.checks[] عند وجودها	يوضح إن كانت recipe الخاصة بـ marketplace أو social قد اجتازت القواعد المعروفة وما الذي يجب إصلاحه.

تشغيل مجاني ومدفوع للـ agents

Image: من 1 إلى 5 ملفات فعلية مجانًا، ومن 6 إلى 25 بسعر 0.01 USDC، ومن 26 إلى 50 بسعر 0.02. PDF مجاني حتى 20 صفحة، ثم 0.01 حتى 50 و0.02 حتى 300. سيناريو Image متعدد الخطوات بسعر 0.02. Video مجاني حتى 5 دقائق، ثم 0.01 / 0.02 / 0.03؛ والنسخ 0.02 / 0.04 / 0.06 حتى 45 دقيقة.

حمّل الملفات أولًا واحصل على التسعير المحلي الدقيق. ادفع للمنتج المحدد ثم أعد نفس التشغيل باستخدام unlockToken. يستهلكه المتصفح قبل بدء المعالجة مباشرة فقط؛ ولا تضيف WebMCP أو Bridge أي رسوم.

حل المشكلات

الأدوات غير ظاهرة

أعد تشغيل MCP client وتأكد من أن Node.js يستطيع تشغيل npx -y quokkapix-mcp من الطرفية.

المتصفح لا يفتح

تأكد أن البيئة المحلية تسمح بتشغيل Playwright/Chromium. يحتاج adapter إلى متصفح لأن QuokkaPix يعمل في المتصفح.

لا يظهر الناتج

افحص outputDir وذاكرة المتصفح والحالة النهائية وerrorCode داخل quokkapix-result.json.

Batch مدفوع محظور

اجلب payment options الحالية، احصل على x402 token صالح، وضعه قبل تشغيل دفعة تتجاوز الحد المجاني.

حد الأمان

استخدم URL الرسمي لـ QuokkaPix أو URL تطوير محلي موثوق. لا توجه runner إلى appUrl عشوائي تابع لطرف ثالث، لأن adapter يرفع ملفات محلية إلى الصفحة التي يفتحها. الموقع العام لا يستقبل مسارات الملفات المحلية، وadapter لا يحول QuokkaPix إلى server-side image API.

FAQ للـ agents والمطورين

هل يرفع QuokkaPix MCP الصور المصدر إلى خادم معالجة؟

لا. يفتح adapter QuokkaPix في متصفح محلي ويرفع الملفات عبر browser file input. مسارات الصور العادية تعمل داخل browser runtime.

هل توجد الآن نقطة MCP مستضافة؟

نعم، ولكن للتنسيق فقط. يتطلب MCP البعيد bridge محلياً مقترناً؛ تبقى المعالجة وبايتات الصور على جهاز المستخدم.

متى يلزم الدفع للـ agents؟

ما الذي يستطيع agents فعله

تشغيل recipes رسمية لـ Shopify وAmazon وGoogle Merchant وضغط WebP وتصدير PDF وتنظيف metadata وحزم social وavatars والعلامات المائية.
تشغيل custom settings مباشرة عبر process_with_settings باستخدام payload نفسه الذي تقبله window.QuokkaPixAgent.applySettings.
التحقق من result manifests والحصول على QA للصيغة والأبعاد وحدود الحجم ونوع الناتج وأسماء الملفات المطلوبة ومحتوى ZIP.
قراءة شروط x402 والتحقق من unlock tokens لتشغيل دفعات agents المدفوعة.
رفع asset files محلية لشعار العلامة المائية أو صورة خلفية بديلة.

قدرات المتصفح الحالية

يعرض الكائن الاختياري capabilities.backends مسارات المعالجة والترميز وAI للخلفية المخطط لها مع fallback واضح. حقول طلبات واستجابات MCP الحالية لم تتغير.
يمكن لمسار advanced export استخدام WASM encoders لـ JPEG وتحسين PNG وWebP وAVIF وJPEG XL التجريبي عندما تكون متاحة.
رفع ZIP يعمل في Batch فقط: يفك المتصفح الصور المدعومة محلياً قبل أن يبدأ runner المعالجة.
أدوات PDF تستخدم إعدادات مباشرة: split وextract يعملان على PDF واحد، merge يعمل على دفعة PDF، وimages-to-PDF يبقى مساراً للصور. يحافظ extract على ترتيب pdf-pages؛ استخدم pdf-extract-output=zip لملفات صفحات منفصلة.

متى تستخدم MCP runner المحلي

استخدم runner عندما يحتاج agent إلى معالجة صور محلية من دون إرسال الملفات المصدر إلى خادم QuokkaPix. يبدأ adapter جلسة متصفح محلية، يرفع الملفات عبر file input العادي، يطبق recipe رسمية أو إعدادات مباشرة، ثم يحفظ الناتج وquokkapix-result.json في مجلد الإخراج.

حد الأمان المحلي

يجب أن يفتح runner عنوان QuokkaPix الرسمي أو عنوان تطوير محلي موثوق. هو لا يحول QuokkaPix إلى API عامة لمعالجة الصور على الخادم؛ الملفات ما زالت تُختار داخل المتصفح وتُعالج على الجهاز الذي يشغل المتصفح.

ما الذي يجب فحصه بعد التشغيل

تأكد أن outputDir يحتوي على الصورة أو ZIP أو PDF الناتج مع quokkapix-result.json.
اقرأ qa.ok وqa.checks قبل قبول دفعة marketplace أو social.
احتفظ بالملفات المصدر منفصلة لأن QuokkaPix يكتب ملفات تسليم ولا يستبدل النسخ الأصلية.
في دفعات agents المدفوعة، اقرأ خيارات الدفع الحية قبل طلب x402 unlock token.

متى يكون التشغيل مقبولاً

MCP client شغّل adapter المحلي عبر stdio، وadapter فتح URL متوقعاً لـ QuokkaPix.
دخلت الملفات عبر browser file input، وليس عبر URL parameter عام.
manifest يحتوي على status: done، وqa.ok صحيح عندما تدعم recipe فحص QA، وتمت مراجعة warnings قبل استخدام الناتج.
حمّل الملفات أولًا واحصل على التسعير المحلي الدقيق. ادفع للمنتج المحدد ثم أعد نفس التشغيل باستخدام unlockToken. يستهلكه المتصفح قبل بدء المعالجة مباشرة فقط؛ ولا تضيف WebMCP أو Bridge أي رسوم.

أدوات MCP

list_recipes
get_recipe
validate_recipe
list_rule_profiles
get_rule_profile
validate_result_manifest
process_images
process_with_settings
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_payment_options
explain_payment_flow
verify_unlock_token

ملف واحد · zip

`watermark_product_batch`

Batch · zip

`favicon_app_icon_pack`

ملف واحد · zip

أمثلة

{
  "recipeId": "shopify_product_pack",
  "inputFiles": [
    "/Users/me/photo.jpg"
  ],
  "outputDir": "/Users/me/quokkapix-output"
}

ملاحظات مهمة

تدخل الملفات عبر اختيار الملفات المحلي في المتصفح. QuokkaPix لا يقدم API عامة لمعالجة الصور على الخادم.