Nano Banana MCP في Cursor و Codex: الإعداد والأمثلة

كتابة أمر نصي في نافذة محادثة، وتنزيل ملف PNG، ثم سحبه إلى مستودعك، حلقة بطيئة حين يكون الكود أصلًا داخل Cursor أو Codex. يلغي خادم MCP هذا الالتفاف: يستدعي وكيل البرمجة Nano Banana بنفسه، ويحفظ الملف في المكان الذي يستطيع مشروعك استخدامه، ويواصل تعديل الصورة نفسها عبر الجولات المتتالية. يبني هذا المقال Nano Banana MCP في Cursor و Codex من ملف إعداد فارغ حتى استدعاء صورة يعمل، مع الملفات الدقيقة، والأوامر النصية التي تعطي نتائج جيدة، والأخطاء التي تظهر في اليوم الأول. تتبع إعدادات Cursor و Codex وثائقهما الحالية، وتأتي تفاصيل الخادم من ملف README العام للحزمة. وحين تعتمد تفصيلة ما على الخادم الذي تختاره، يوضح النص ذلك.

ما الذي يفعله الخادم فعلًا

MCP (بروتوكول سياق النموذج) طريقة قياسية يستدعي بها عميل الذكاء الاصطناعي أدوات خارجية. يعرض خادم الصور عددًا محدودًا منها، مثل generate_image أو edit_image، ويقرر النموذج داخل Cursor أو Codex متى يستدعي إحداها بحسب ما تطلبه في المحادثة. Nano Banana هو الاسم المستعار لنموذج Gemini لتوليد الصور من Google، ويتوفر باسم Nano Banana على PicassoIA، مع Nano Banana Pro كمستوى أعلى من الدقة. خادم MCP نفسه عملية Node صغيرة تعمل على جهازك. يحتفظ برمز Gemini الخاص بك، ويرسل الأمر النصي إلى Google، ويكتب النتيجة على القرص.

إليك ما يمنحه خادم Nano Banana النموذجي لوكيلك:

• تحويل النص إلى صورة: صف مشهدًا، واحصل على ملف PNG.
• التعديل عبر مسار الملف: أشر إلى صورة موجودة وصف التغيير المطلوب.
• متابعة التعديل: حسّن الصورة الأخيرة دون تكرار الأمر النصي كاملًا.
• أدوات الحالة: تُبلغ عما إذا كان الرمز مضبوطًا قبل أن تهدر استدعاءً.

لماذا يستحق الأمر تشغيل الخادم داخل المحرر؟ لأن المحادثة نفسها التي تكتب فيها مكوّن الواجهة الرئيسي تستطيع أيضًا إنتاج صورة الواجهة، وتسمية الملف، وتحديث وسم <img>. يبقى الأمر النصي في سجل المحادثة بجوار الإيداع (commit)، وتكلّف كل مراجعة جملة واحدة بدلًا من جولة في المتصفح.

💡 يعمل الخادم محليًا ويستهلك حصتك أنت من Gemini. لا تفرض عليك Cursor ولا Codex رسومًا على استدعاءات الصور.

المتطلبات وفحص الثقة

خمس دقائق من التحضير تمنع معظم الأعطال المذكورة لاحقًا في هذا المقال.

قائمة التحقق

شغّل node --version أولًا. إذا أظهر أي رقم أقل من 18، فحدّث Node.js قبل أن تلمس أي ملف إعدادات، لأن بيئة التشغيل القديمة جدًا تتسبب في أخطاء تبدو غير مرتبطة بالمشكلة.

اختر خادمًا تثق به

تدّعي عدة حزم npm أنها تحمل اسم Nano Banana. تُوثّق nano-banana-mcp ستة أدوات هي: generate_image، وedit_image، وcontinue_editing، وget_last_image_info، وconfigure_gemini_token، وget_configuration_status. وتسرد @saroby/nanobanana-mcp اثنتين فقط هما generate_image وlist_images. و@mindstone/mcp-server-nano-banana خيار ثالث. تختلف أسماء الأدوات بينها، لذلك لا تنطبق الأوامر المكتوبة لخادم منها على غيره دائمًا.

خادم npx يشغّل كودًا على حاسوبك بصلاحيات مستخدمك، ويرى الرمز الذي تعطيه إياه. اقرأ المستودع، وتحقق من تاريخ آخر إصدار، وثبّت نسخة محددة بعد أن يعمل كل شيء. يستخدم هذا الدليل nano-banana-mcp لأن قائمة أدواته موثقة للعموم.

إعداد Nano Banana MCP في Cursor

يقرأ Cursor خوادم MCP من مكانين: .cursor/mcp.json داخل المشروع، و~/.cursor/mcp.json في مجلدك الشخصي للخوادم التي تريدها في كل مكان. وإذا عرّف الملفان الاسم نفسه للخادم، فإن ملف المشروع يغلب.

كتابة ملف mcp.json

أنشئ .cursor/mcp.json في جذر مشروعك:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "nano-banana-mcp"],
      "env": {
        "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
      }
    }
  }
}

نسخ الأمر النصي

ثم اتبع الخطوات التالية:

1. احفظ الملف. يلتقطه Cursor دون حاجة إلى إعادة تثبيت كاملة.
2. افتح لوحة Customize في الشريط الجانبي، وابحث عن nano-banana في قائمة MCP.
3. فعّل المفتاح. الخوادم المعطّلة لا تُحمَّل ولا تظهر في المحادثة.
4. اسأل الوكيل: "تحقق من حالة إعداد Nano Banana." خادم أخضر وردّ واضح على الحالة يعنيان أن الربط يعمل.

يطلب Cursor افتراضيًا موافقتك قبل تشغيل أي أداة MCP. انقر على السهم بجوار اسم الأداة لفحص المعاملات، ويستحق ذلك في أول بضعة استدعاءات حتى ترى بدقة الأمر النصي الذي كتبه الوكيل.

💡 على Windows، إذا فشل تشغيل الخادم، فاستبدل الأمر بالقيمة cmd والمعاملات بالقيمة ["/c", "npx", "-y", "nano-banana-mcp"]. بعض الإعدادات لا تستطيع تشغيل npx مباشرة.

أبقِ الأسرار خارج Git

تخبر صيغة ${env:GEMINI_API_KEY} Cursor بقراءة القيمة من متغيرات البيئة لديك حين يشغّل الخادم، فلا يحتوي الملف نفسه على أي سر، ويمكن إيداعه بأمان. يحل Cursor عدة متغيرات بهذه الطريقة، و${env:NAME} و${userHome} و${workspaceFolder} هي الأكثر استخدامًا.

اضبط المتغير مرة واحدة في مكان يراه Cursor:

• macOS و Linux: صدّره في ملف إعدادات الصدفة لديك، ثم شغّل Cursor من طرفية جديدة. قد لا يرى التطبيق المشغّل من الرصيف متغيرات معرّفة في ملف الصدفة وحده.
• Windows: أضفه كمتغير بيئة للمستخدم، ثم أغلق Cursor وأعد فتحه.

إعداد Nano Banana MCP في Codex

يحفظ Codex كل شيء في ملف TOML واحد هو ~/.codex/config.toml، ويوفر أمرًا لتعديله، لذلك نادرًا ما تحتاج إلى فتح الملف بنفسك.

التسجيل عبر CLI

شغّل هذا الأمر مرة واحدة في الطرفية:

codex mcp add nano-banana --env GEMINI_API_KEY=your-token-here -- npx -y nano-banana-mcp

نسخ الأمر النصي

كل ما يأتي بعد الشرطتين المزدوجتين هو الأمر الذي يشغّل الخادم. تحقق من الإدخال عبر codex mcp list، ثم ابدأ جلسة Codex واكتب /mcp لرؤية الخوادم النشطة وحالتها. الأوامر الفرعية الأخرى هي login لخوادم OAuth، وremove لحذف إدخال.

المشكلة: هذه الصيغة تكتب رمزك في config.toml كنص عادي. قد يكون ذلك مقبولًا على حاسوب شخصي. أما لأي شيء مشترك فاستخدم الطريقة التالية.

تعديل config.toml يدويًا

الخادم نفسه، والرمز موروث من صدفتك بدلًا من أن يُخزَّن:

[mcp_servers.nano-banana]
command = "npx"
args = ["-y", "nano-banana-mcp"]
env_vars = ["GEMINI_API_KEY"]
startup_timeout_sec = 60
tool_timeout_sec = 120

نسخ الأمر النصي

ثلاثة حقول مهمة هنا:

• env_vars يسرد أسماء المتغيرات التي ينسخها Codex من العملية الأم، فلا يلمس الرمز الملف أبدًا.
• startup_timeout_sec مهم في التشغيل الأول، حين يحمّل npx الحزمة قبل أن يستطيع الخادم الرد. إن انتهت المهلة في المرة الأولى، فارفعها.
• tool_timeout_sec يحدّ من استدعاء أداة واحدة. يستغرق توليد الصور وقتًا أطول من معظم الأدوات، فامنحه متسعًا.

Cursor و Codex جنبًا إلى جنب

الفرق العملي يكمن في المشاركة. يمكن إيداع .cursor/mcp.json على مستوى المشروع، فيحصل الفريق كله على التعريف نفسه للخادم، ولا يحتاج إلا إلى رمزه الخاص. يحتفظ Codex بقائمته في مجلدك الشخصي، وهذا مناسب لإعداد فردي، لكنه يحتاج إلى سطر قصير في ملف README إن أراد زملاؤك نسخه.

أوامر نصية تستحق النسخ

الخادم العامل نصف المهمة فقط. الأمر النصي هو ما يحدد هل تحصل على أصل قابل للاستخدام أم على نتيجة تُترك للصدفة. ثلاث عادات تساعد في العميلين: سمِّ الملف الذي تريده، واطلب صورة واحدة في كل استدعاء، وصف الصورة الفوتوغرافية لا المزاج.

صورة واجهة لصفحة الهبوط

الصق هذا في المحادثة:

استخدم أداة generate_image من Nano Banana لإنشاء صورة واجهة بنسبة 16:9 لصفحة الأسعار: حاسوب محمول نحيف على مكتب من خشب البلوط المتآكل في ضوء صباحي دافئ قادم من نافذة على اليسار، وكوب خزفي في المقدمة، وعمق ميداني ضحل، دون نص ودون شعارات. ثم انقل الملف إلى public/images/ باسم pricing-hero.png، وحدّث وسم الصورة في Hero.tsx.

تحفظ معظم الخوادم في مجلدها الافتراضي الخاص، مثل nano-banana-images في مجلد Documents على Windows، أو generated_imgs في مجلد العمل على macOS و Linux. لهذا يطلب الأمر النصي من الوكيل نقل الملف. ينفذ الوكيل النقل بأمر طرفية عادي.

لقطات المنتجات والتعديلات

ولّد صورة أساسية أولًا، ثم عدّلها في مكانها:

ولّد صورة استوديو لحذاء رياضي من الجلد الأبيض على كتلة خرسانية فاتحة أمام خلفية رمادية متصلة، مع إضاءة softbox من الأعلى على اليسار. احفظها باسم shoe.png.

تابع بتغيير مستهدف:

استخدم edit_image على shoe.png: غيّر الخلفية إلى رمل دافئ، واحتفظ بالخياطة والأربطة والنعل كما هي تمامًا.

إن كان خادمك يضم أداة continue_editing، تصبح التعديلات الصغيرة جملة واحدة: "اجعل الظل أنعم." وبعض الخوادم تقبل أيضًا عدة صور مرجعية في استدعاء واحد، وهذا يفيد حين تحتاج إلى أسلوب متسق عبر مجموعة من صور المنتجات. تحقق من ملف README لخادمك قبل الاعتماد على ذلك.

أوامر يكتبها النموذج

لست مضطرًا إلى كتابة كل أمر بنفسك. اطلب من الوكيل قراءة صفحة واقتراح ثلاثة أوامر نصية للصور تطابق نصها، ثم اعتمد واحدًا. يجيد النموذج الذي يقود Cursor أو Codex هذه المهمة لأنه يرى المكوّن المحيط، وألوان العلامة التجارية في ملف التنسيق لديك، ونسبة العرض إلى الارتفاع للمساحة المخصصة.

إن أردت رأيًا ثانيًا خارج المحرر، فإن PicassoIA يستضيف نماذج لغوية يمكنك استخدامها للمهمة نفسها، ومنها Claude Sonnet 5 وGPT 5.6 Sol. الصق نص صفحتك، واطلب أوامر بالصيغة الضعيفة مقابل الأفضل كما في الجدول أعلاه، وأعد الأمر الفائز إلى الوكيل.

إصلاح الأخطاء الشائعة

تقع معظم الأعطال في ثلاث مجموعات: الخادم لا يبدأ أبدًا، أو الرمز مفقود، أو تنتهي الملفات في مكان غير متوقع.

الخادم لا يبدأ أبدًا

شغّل الأمر الدقيق من إعدادك في طرفية عادية. إن طبع خطأ هناك، فالمشكلة في الخادم أو في بيئتك، لا في Cursor أو Codex.

أخطاء الرمز والحصة

خطأ المصادقة يعني في الغالب أن المتغير غير موجود في العملية التي تشغّل الخادم، حتى لو كان موجودًا في صدفتك. اطبعه في الطرفية نفسها التي تشغّل منها العميل. وإن كنت تستخدم أداة حالة مثل get_configuration_status، فاستدعها أولًا واقرأ ردها قبل أن تلوم النموذج.

ردود الحصة أو حد المعدل تأتي من Google لا من MCP. أبطئ، واطلب صورة واحدة في كل مرة، وافحص استهلاكك في Google AI Studio. إعادة المحاولة في حلقة ضيقة تطيل أمد التقييد فقط.

شغّل Nano Banana على PicassoIA

لا تحتاج كل صورة إلى خادم محلي. حين تريد تجربة أمر نصي بسرعة، أو مشاركة نتيجة، أو تجنب إدارة رمز، يكون مسار المتصفح أسرع.

استخدم النموذج في المتصفح

طريقة استخدام Nano Banana على PicassoIA:

1. افتح صفحة النموذج واكتب أمرك. استخدم الصياغة الفوتوغرافية نفسها التي تعطيها لوكيل MCP.
2. اختر نسبة العرض إلى الارتفاع التي تناسب مساحتك. تناسب 16:9 لافتات الواجهة، و1:1 شبكات المنتجات.
3. ولّد، وراجع، وحسّن الأمر بدلًا من إعادة التوليد عشوائيًا. غيّر شيئًا واحدًا في كل مرة.
4. نزّل النتيجة وأسقطها في مشروعك، أو احتفظ بها مرجعًا للوكيل.

نموذجان شقيقان يستحقان التجربة حين تكون النتيجة الأولى قريبة لكنها غير مناسبة. Nano Banana 2 هو الجيل الأحدث، وNano Banana 2 Lite يضحّي ببعض الجودة مقابل السرعة، وهذا مناسب للمسودات. وNano Banana Pro هو الخيار للأصول النهائية التي تحتاج دقة أعلى.

حوّل الصور الثابتة إلى فيديو

يمكن أن تتحول صورة ثابتة من سير عملك في المحرر إلى مقطع قصير. خذ صورة الواجهة، وافتح نموذج تحويل الصورة إلى فيديو، وصف الحركة: دفعة كاميرا بطيئة، وبخار يتصاعد من كوب، وضوء ينساب على جدار. يولّد Seedance 2.0 فيديو مع صوت مدمج، ويُنتج Seedance 2.5 Lite مقاطع تصل إلى 10 ثوانٍ، وVeo 3.1 خيار آخر حين تريد نموذج فيديو من Google إلى جانب نموذج الصور من Google.

استدعِ PicassoIA من الكود

تتيح PicassoIA أيضًا واجهة API للمطوّرين وموصِّل MCP. تقع واجهة API على https://api.picassoia.com/v1 وتستخدم رمز Bearer يبدأ بالمقطع pia_sk_. يتبع تدفقها نهج Replicate: أنشئ تنبؤًا باستخدام POST /v1/models/{owner}/{name}/predictions، ثم استعلم عنه عبر GET /v1/predictions/{id}، ثم اقرأ النتيجة. تشمل الحدود 5 طلبات تشغيل متزامنة لكل حساب، و4,000 حرف لكل أمر نصي.

تنبيه صريح: النماذج المتاحة عبر API وموصِّل MCP هي picassoia/picassoia-image وpicassoia/picassoia-image-editor-pro وpicassoia/picassoia-video وpicassoia/seedance-2.5-lite. لا يظهر Nano Banana في هذه القائمة القصيرة، لذا استخدم صفحة المتصفح لتشغيله. ما زال بإمكانك الاطلاع على صفحتي PicassoIA Image Editor Pro وPicassoIA Image لترى ما تفعله كل منهما. يعتمد الوصول إلى API على خطتك، والصياغة في صفحتي الأسعار و API مختلفة، لذا تأكد من خطتك قبل أن تبني عليها.

جرّبه على مشروعك

صار لديك الآن الحلقة كاملة: خادم يبدأ، ورمز يبقى خارج git، وأوامر نصية تسمّي الملفات والكاميرات، وحلول للأعطال التي توقف معظم الناس في الخطوة الأولى. اختر مساحة حقيقية واحدة في مشروعك الحالي، كشريط واجهة أو بلاطة منتج، وشغّل إعداد Cursor أو Codex أعلاه اليوم.

إن أردت رؤية ما يفعله النموذج قبل أن تلمس ملف إعداد، افتحه على Picasso IA، والصق أحد الأوامر النصية من هذا المقال، وقارن النتيجة بما ينتجه وكيلك. جرّب Nano Banana أولًا، ثم انتقل إلى نماذج الصور والفيديو الأخرى على picassoia.com/en/all-models. جرّب الإضاءة والعدسة ونسبة العرض إلى الارتفاع، واحتفظ بالأوامر التي تنجح في ملف بجوار كودك.