تكامل agents

QuokkaPix MCP Runner

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

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

دليل عملي لـ 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

تشغيل صورة واحدة وسيناريو صورة واحدة ودفعات agents حتى 5 ملفات مجانية. دفعات أو batch-scenario runs من 6 إلى 50 ملفاً تستخدم x402 unlock flow. يجب أن يقرأ العميل الشروط الحية من /api/agent-payment/options قبل طلب paid unlock.

عندما تكون هناك حاجة للدفع يحصل agent على unlockToken، يضعه في QuokkaPix قبل المعالجة، ويُستهلك unlock فقط عند بدء Batch أو batch scenario مدفوع.

حل المشكلات

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

أعد تشغيل 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.

هل هذا hosted MCP endpoint؟

لا. quokkapix-mcp هو adapter محلي عبر stdio. صفحات الاكتشاف العامة والكتالوجات توجه المطورين إلى الحزمة المحلية.

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

تشغيل صورة واحدة والسيناريوهات الفردية والدفعات حتى 5 ملفات مجانية. الدفعات الأكبر من 6 إلى 50 ملفاً تستخدم x402 unlock flow.

ما الذي يستطيع 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 محلية لشعار العلامة المائية أو صورة خلفية بديلة.

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

يمكن لمسار 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 قبل استخدام الناتج.
في الدفعات المدفوعة، يتم التحقق من unlock token قبل البدء ويُستهلك فقط في paid run فوق حد small-batch المجاني.

أدوات MCP

list_recipes
get_recipe
validate_recipe
list_rule_profiles
get_rule_profile
validate_result_manifest
process_images
process_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 عامة لمعالجة الصور على الخادم.