إعداد MCP في Windsurf: توليد الصور في Cascade

خادم MCP في Windsurf هو صندوق أدوات خارجي يمكن للوكيل استدعاؤه أثناء المحادثة: تقوم بتعريفه مرة واحدة في mcp_config.json، فيكتسب Cascade قدرات غير متوفرة في النموذج الأساسي. توليد الصور هو النقص الأكثر وضوحاً. يستطيع Windsurf بناء شاشة إعدادات وربط المسارات وكتابة الاختبارات بكل سهولة، لكنه يترك ثلاثة مستطيلات رمادية مكان الرسومات التوضيحية.

الخلاصة السريعة لمن يريد البدء فوراً: أنشئ مفتاحاً في حساب BananaBanana، ثم أضف هذا المقطع إلى ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "bananabanana": {
      "serverUrl": "https://bananabanana.pro/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BB_API_KEY}"
      }
    }
  }
}

قم بتصدير المتغير BB_API_KEY=bb_live_YOUR_KEY، ثم أعد تحميل خوادم MCP، وستظهر عشر أدوات في Cascade. تبدأ أسعار الصور من $0.03 للصورة الواحدة تُخصم من رصيد مسبق الدفع، والفيديو من $0.10، بدون اشتراكات شهرية ودون الحاجة لإنشاء مشروع سحابي خاص بك. تنبيه قبل اللصق: في الإصدارات الحديثة، قد لا يكون هذا الملف هو الملف الذي يقرأه وكيلك. سنوضح ذلك بعد قليل.

لماذا تمنح Cascade أداة لتوليد الصور؟

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

تعليمة واحدة تختصر كل هذا العناء. يقوم Cascade بصياغة البرومبت، واستدعاء generate_image، ونقل الملف إلى المجلد الصحيح، وكتابة وسم <img> مع النص البديل (alt). وأنت تكتفي بمراجعة الـ diff.

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

البديل لخادم بعيد هو تشغيل خادم MCP محلي للصور، مما يعني تشغيل عملية Node أو Python على جهازك مع استخدام مفتاح موفر خارجي وحساب فواتيرك بنفسك. الخادم البعيد يغنيك عن الأمرين. نقطة النهاية تعمل لدينا بنفس البنية التحتية المستخدمة في مولد الويب، ومفتاحك الوحيد هو نص bb_live_ يمكنك إبطاله متى شئت من صفحة الحساب.

رسم توضيحي لشاشة عريضة تعرض هياكل تطبيقات حيث يتم ملء الإطارات الفارغة بفرشاة رسم صغيرة طافية

أين يحفظ Windsurf إعدادات MCP الآن؟

هذه النقطة يقع فيها الكثيرون في أغسطس 2026، ويجب التحقق منها قبل تعديل أي ملف. أصبح Windsurf الآن جزءاً من Devin Desktop التابع لشركة Cognition: يُعاد توجيه windsurf.com إلى devin.ai/desktop، والمسار القديم docs.windsurf.com/windsurf/cascade/mcp يعيد التوجيه 307 إلى docs.devin.ai/desktop/cascade/mcp. يظل التطبيق باسم Windsurf على القرص، ومخطط الروابط windsurf://، ومجلد الإعدادات ~/.codeium/windsurf/. ما تغير هو الاسم التجاري فقط.

التغيير الجوهري هو وجود وكيلين بنظامي إعدادات مختلفين، وتوضح وثائق Cascade MCP ذلك في تنبيه بأعلى الصفحة: ينطبق ملف mcp_config.json على وكيل Cascade التقليدي، بينما يقرأ وكيل Devin Local (الافتراضي للألسنة الجديدة) إعدادات Devin CLI. تم التحقق في 20 أغسطس 2026.

لذلك اختر الملف وفقاً للوكيل الذي تستخدمه بالفعل.

وكيل Cascade التقليدي يقرأ ~/.codeium/windsurf/mcp_config.json (أو %USERPROFILE%\.codeium\windsurf\mcp_config.json على Windows). تقبل الخوادم البعيدة هناك حقل serverUrl أو url بالإضافة إلى headers، وهو المقطع الموضح في بداية المقال.

وكيل Devin Local يقرأ ملفات إعدادات واجهة الأوامر (CLI): ~/.config/devin/mcp_config.json للمستخدم، و .devin/mcp_config.json للمشاريع المشتركة عبر git، و .devin/mcp_config.local.json للمفاتيح الشخصية (يتم تجاهله تلقائياً في git). تختلف أسماء الحقول قليلاً:

{
  "mcpServers": {
    "bananabanana": {
      "url": "https://bananabanana.pro/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer ${env:BB_API_KEY}"
      }
    }
  }
}

أو يمكنك تجاوز التعديل اليدوي: ينشئ الأمر devin mcp add bananabanana https://bananabanana.pro/api/mcp الإدخال في النطاق المحلي، ثم تضيف قسم headers. كما يعرض لك الأمران devin mcp list و devin mcp get bananabanana ما تم تحميله بدقة.

في كلتا الحالتين، نقطة النهاية هي https://bananabanana.pro/api/mcp. وليست /mcp (صفحة التوثيق المخصصة للقراءة البشرية)، إذ سيعيد إرسال POST إليها صفحة HTML مما يربك الوكيل. توفر صفحة خادم MCP المقاطع البرمجية وجدول التوافق لجميع التطبيقات المدعومة:

قسم إعدادات Windsurf في صفحة توثيق BananaBanana MCP يعرض مقطع mcp_config.json مع serverUrl وترويسة Authorization

بمجرد الاتصال، تكون استدعاءات list_models و get_account مجانية — اطلب من Cascade تشغيل إحداها لاختبار الاتصال. تعيد get_account رصيدك واسم المفتاح والحد اليومي، وهي طريقة ممتازة للتحقق من المصادقة دون استهلاك تكلفة توليد صورة.

حالة استخدام: مجموعة حالات فارغة لتطبيق بناه Cascade للتو

السيناريو العملي الذي بنيت عليه هذه العينات: يقوم Cascade بإنشاء هيكل لأداة داخلية، وتظهر الشاشات الفارغة الثلاث كعناصر div رمادية مؤقتة، وبدلاً من فتح برنامج تصميم، تزود الوكيل بصيغة أسلوب موحدة ليقوم بتوليد المجموعة كاملة.

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

→ generate_image {"prompt": "A flat vector illustration for an app empty
   state: an open cardboard box floating above a soft shadow with three small
   paper envelopes drifting out of it, muted teal and warm coral palette on an
   off-white background, thin confident outlines, generous negative space,
   centered composition, no text", "model": "nano-banana-pro",
   "aspect_ratio": "4:3"}
← {"job_id": "…", "status": "processing", "cost_charged_usd": 0.11}

رسم متجهي مسطح لحالة تطبيق فارغة يظهر صندوقاً مفتوحاً تخرج منه أظرف ورقية، تم توليده في Windsurf عبر خادم MCP

ثم نستخدم الجملة نفسها مع تغيير الموضوع لشاشة «لا توجد نتائج»:

النتيجتان متناسقتان كزوج متطابق كعناصر نائبة. وإذا أردت دقة وتطابقاً أكبر، يقبل generate_image معامل seed، واستخدام نفس الـ seed مع جملة الأسلوب يقرب النتائج أكثر. بالنسبة للشخصيات أو الشعارات التي تتطلب ثباتاً عبر عشرات الصور، فإن صياغة البرومبت أهم من إعدادات التطبيق، وهو ما يفصله دليل اتساق الشخصيات.

ملاحظتان للشفافية: قمت بتوليد هذه النماذج بنموذج Nano Banana Pro بسعر $0.11 للحصول على أقصى دقة للصفحة. أما للصور المؤقتة التي سيستبدلها المصمم بعد أسبوعين، فإن نموذج nano-banana-2-lite بسعر $0.03 هو الخيار الأمثل، ويوضح دليل Lite حدود استخدام هذا النموذج الاقتصادي. كما أنه النموذج الافتراضي للأداة، وسيعتمده الوكيل تلقائياً ما لم تطلب غير ذلك.

يمكن توليد الفيديو من نفس المحادثة أيضاً. أداة generate_video لا تخصم أي مبالغ في الاستدعاء الأول: بل تعيد عرض أسعار، ويجب على الوكيل تكرار الطلب مع تمرير confirm_cost مساوياً لذلك المبلغ لبدء المعالجة. يبدأ مقطع 4 ثوانٍ صامت بجودة 720p على Veo 3.1 Lite من $0.10؛ بينما يبلغ سعر Omni Flash $0.10 لكل ثانية مع صوت مدمج دائماً، أي $0.30 لمقطع مدته 3 ثوانٍ.

ملاحظات هامة في Windsurf ينبغي معرفتها

خمس نصائح عملية جمعتها أثناء الإعداد:

رسم توضيحي لدرجي حفظ ملفات مفتوحين بأحجام مختلفة مع مفتاح طافٍ بينهما وقفل قريب

1. متغير البيئة غير المعرف يفشل بصمت. تنص الوثائق بوضوح على أن ${env:VAR_NAME} يُستبدل بقيمة المتغير، وإذا لم يكن معيناً، يُستبدل بنص فارغ دون إظهار أي خطأ أو تحذير. تُرسل الترويسة على شكل Bearer فارغة، ويرد الخادم برمز 401، فيبدو الأمر كخلل في الخادم وليس نقصاً في المتغير. التطبيقات المشغلة عبر الواجهة الرسومية لا تقرأ إعدادات الطرفية، لذا فإن التصدير في .zshrc غير مرئي ما لم تفتح Windsurf من الطرفية. إذا أعاد list_models خطأ مصادقة، تحقق من المتغير أولاً.

2. صيغة ${file:…} أكثر أماناً وتعتبر ميزة خاصة بـ Windsurf. يدعم الإعداد استدعاء ${file:/path/to/file} حيث يتم تضمين محتوى الملف بعد تنظيف المسافات مع دعم مسارات ~. لذلك يعمل السطر "Authorization": "Bearer ${file:~/.secrets/bb_key.txt}" بدون أي متغيرات بيئة ويتجاوز مشاكل الواجهة الرسومية. أفضل هذا الخيار دائماً في Windsurf، وهو غير متوفر في Cursor أو VS Code.

3. الحد الأقصى للأدوات في Cascade هو 100 أداة. هذا سقف ثابت لجميع خوادم MCP المتصلة معاً. تتيح لك صفحة الإعدادات تعطيل الأدوات غير المطلوبة. خادمنا يضيف عشر أدوات. إذا كنت تستخدم خوادم ضخمة أخرى (مثل GitHub الذي يضم العشرات)، يمكنك تعطيل ما لا تحتاجه: generate_speech و edit_video و list_generations خيارات سهلة الإيقاف إذا كنت تحتاج الصور فقط.

4. رابط التثبيت السريع لا يرسل مفتاحك، وتلك ميزة أمان. يدعم Windsurf روابط بصيغة windsurf://windsurf-mcp-registry?serverName=<name> تفتح صفحة الدليل لمراجعتها قبل التثبيت. لاحظ الميزة: لا توجد إعدادات مشفرة، فبخلاف الروابط التي تحول الإعدادات إلى base64، لا يوجد خطر لتسريب المفاتيح عبر الروابط المشتركة. وحيث أننا لسنا في الدليل العام بعد، يتم التثبيت عبر JSON يدوياً.

5. في خطط الفرق، اسم الخادم حساس لحالة الأحرف. بمجرد قيام المشرف بوضع أي خادم MCP في القائمة البيضاء، يتم حظر كافة الخوادم غير المدرجة للفريق بأكمله، ويجب أن يطابق المعرف المعتمد اسم المفتاح في mcp_config.json بدقة تامة في حالة الأحرف. أي إذا اعتمد المشرف bananabanana وكتبت في ملفك BananaBanana، فلن يعمل الاتصال دون توضيح السبب. يمكن للشركات أيضاً توجيه Windsurf لسجل MCP الخاص بها.

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

ماذا عن OAuth بدلاً من مفتاح API؟

كلا المسارين متاح، وكل منهما يناسب وكيلاً مختلفاً.

تدعم واجهة Devin CLI (أي وكيل Devin Local) بروتوكول OAuth بشكل كامل: يفتح الأمر devin mcp login <name> نافذة المتصفح لتسجيل الدخول ويخزن الرموز محلياً ويجددها تلقائياً عبر التسجيل الديناميكي للعملاء (DCR) دون إعداد يدوي مسبق. خادمنا عبارة عن خادم تخويل OAuth 2.1 يدعم DCR ومؤشرات موارد RFC 8707. وتؤكد وثائق Cascade دعم OAuth لكافة أنواع النقل.

تم اختبار مسار مفتاح API في هذا المقال (initialize و get_account و list_models بمفتاح bb_live_ حقيقي). إذا جربت OAuth وواجهت أي تعارض، فالخيار المطلوب هو oauthResource لتجاوز معامل resource في RFC 8707، حيث يتوقع خادمنا الجمهور https://bananabanana.pro/api/mcp.

وهناك سبب عملي لتفضيل المفاتيح: فهي مجانية ويمكنك إنشاء عدة مفاتيح مع سجل استخدام مستقل لكل منها (الأداة، النموذج، التكلفة، ملخص البرومبت) وحد يومي بالدولار من صفحة الحساب. يعد هذا الحد اليومي أفضل حماية قبل منح وكيل ذكاء اصطناعي صلاحية إنفاق الرصيد.

أما عن الصلاحيات: تدعم إعدادات Devin CLI وضع قواعد لكل أداة عبر محددات mcp__<server>__<tool>، وهو أمر رائع مع الخوادم المدفوعة:

{
  "permissions": {
    "allow": ["mcp__bananabanana__list_models", "mcp__bananabanana__get_result"],
    "ask": ["mcp__bananabanana__generate_video"]
  }
}

ستعمل الاستعلامات المجانية دون مقاطعتك، بينما تتوقف عمليات الريدر وتطلب موافقتك.

ما هي تكلفة وسائط هذا المقال؟

الأسعار القياسية المعتادة لكل توليد، وهي نفس الأرقام التي يرجعها list_models للوكيل:

العنصر	النموذج	السعر
حالة فارغة، البريد الوارد	Nano Banana Pro, 1K	$0.11
حالة فارغة، البحث	Nano Banana Pro, 1K	$0.11
الغلاف + رسمتان توضيحيتان	Nano Banana Pro, 1K	$0.33
لقطة شاشة التوثيق	متصفح، بدون توليد	$0.00
الإجمالي		$0.55

نجحت الحالتان الفارغتان من المحاولة الأولى — بفضل التوفيق ولأن الأسلوب المتجهي المسطح دقيق بطبيعته. أما للصور الواقعية للمنتجات فيفضل وضع ميزانية لمحاولات إضافية.

إذا كنت تستخدم هذا الخادم بالفعل في محرر آخر، فإن إعدادات Windsurf أعلاه هي الجزء الجديد فقط: نفس المفتاح والرصيد وسجل التوليد. يشرح دليل Cursor وإعدادات VS Code كيفية استخدام الخادم في تلك البيئات. هل أنت مستعد؟ أنشئ مفتاحاً واطلب من Cascade تصميم أول صورة لك.

الأسئلة الشائعة

هل يدعم Windsurf خوادم MCP البعيدة مع ترويسة Authorization؟

نعم. تقبل خوادم HTTP البعيدة في mcp_config.json حقل serverUrl (أو url) وكائن headers اختياري. يدعم Cascade بروتوكولات stdio و Streamable HTTP و SSE. ويدعم الحقلان التعويض بالمتغيرات ${env:VAR} و ${file:/path} حتى لا يبقى المفتاح كنص صريح. تم التحقق من الإعداد وفقاً للوثائق الرسمية في 20 أغسطس 2026.

أي ملف إعدادات يقرأه وكيل Windsurf الخاص بي فعلياً؟

يعتمد ذلك على الوكيل. يقرأ وكيل Cascade التقليدي ~/.codeium/windsurf/mcp_config.json. بينما يقرأ وكيل Devin Local (الافتراضي في الألسنة الجديدة) ملفات Devin CLI: ~/.config/devin/mcp_config.json أو .devin/mcp_config.json أو .devin/mcp_config.local.json للمفاتيح الشخصية. إذا لم يظهر الخادم بعد التعديل، فهذا هو أول شيء يجب التحقق منه.

هل أحتاج إلى حساب سحابي خاص لتوليد الصور في Windsurf؟

لا. تتطلب خوادم الصور المحلية مفاتيح موفرين خارجيين مع اشتراكات خاصة بك. بينما ينفذ الخادم البعيد عمليات التوليد عبر بنيتنا التحتية المدارة، وكل ما تحتاجه هو مفتاح bb_live_ من حسابك. تبدأ الحسابات الجديدة برصيد ترحيبي $0.20، وهو ما يكفي لتوليد ست صور على النموذج الاقتصادي قبل دفع أي مبلغ.

هل يستطيع Cascade توليد الفيديو عبر نفس الخادم؟

نعم، مع خطوة تأكيد إلزامية. تُرجع أداة generate_video عرض تكلفة في الاستدعاء الأول دون خصم أي رصيد؛ ويجب على الوكيل تكرار الطلب مع تمرير confirm_cost مساوياً لذلك المبلغ لبدء الرندر. تبدأ الأسعار من $0.10 لمقطع مدته 4 ثوانٍ بدون صوت بجودة 720p على Veo 3.1 Lite وتصل إلى $4.40 لأعلى جودة على Veo 3.1 مع صوت؛ وتبلغ تكلفة Omni Flash $0.10 لكل ثانية مع صوت دائم. يستغرق المقطع من دقيقة إلى عشر دقائق، ويقوم الوكيل خلالها بالاستعلام الدوري عبر get_result.

لماذا يظهر خادم MCP خطأ في المصادقة في Windsurf؟

في تسع حالات من أصل عشر يكون السبب في المفتاح وليس في صحة ملف الإعداد. يتم استبدال متغير ${env:BB_API_KEY} غير المعرف بنص فارغ دون إطلاق خطأ، فيرسل الطلب برمز فارغ ويرد الخادم بـ 401. تأكد من إتاحة المتغير لعملية Windsurf (التشغيل عبر الواجهة الرسومية لا يقرأ ملف الطرفية)، أو استخدم ${file:~/.secrets/bb_key.txt} لتجاوز الأمر. وإذا كان المفتاح صحيحاً، تأكد أن الرابط ينتهي بـ /api/mcp وأن قائمة الأمان للفريق لا تحظر معرف الخادم.