إنشاء الصور في VS Code: دليل إعداد Copilot MCP

خادم MCP لـ VS Code عبارة عن صندوق أدوات خارجي يمكن لـ GitHub Copilot في وضع agent استدعاؤه من الدردشة: ملف JSON واحد في مستودع الكود الخاص بك، ليحصل Copilot على أدوات لا تمتلكها نماذجه، بما في ذلك توليد الصور. يكتب Copilot المكونات ويعيد هيكلة الاختبارات (refactors) طوال اليوم، ولكن لا يوجد نموذج خلفه يمكنه إنتاج ملف صورة. أضف خادم توليد لتتحول تعليمة "make a 16:9 banner for this README" إلى أمر دردشة ينتهي بملف حقيقي في assets/ِ.

إليك الإعداد الكامل، إذا كان هذا كل ما تبحث عنه. قم بإنشاء مفتاح API في ملف BananaBanana الشخصي، ثم ضع هذا الكود في ملف .vscode/mcp.json في جذر المستودع:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "bb-api-key",
      "description": "BananaBanana API key (bb_live_...)",
      "password": true
    }
  ],
  "servers": {
    "bananabanana": {
      "type": "http",
      "url": "https://bananabanana.pro/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:bb-api-key}"
      }
    }
  }
}

ابدأ تشغيل الخادم (يظهر VS Code تلميح Start مباشرة داخل الملف)، ثم الصق مفتاحك مرة واحدة عند طلب إدخاله، وانتهى الأمر. لا يحتوي الملف على أي معلومات سرية، لذا فمن الآمن عمل commit له. لا توجد عمليات محلية، ولا حساب على Google Cloud، ولا اشتراك شهري: يتم احتساب تكلفة الصور بدءاً من $0.03 من رصيد مدفوع مقدماً، والفيديو من $0.10. تم توليد كلتا الصورتين التجريبيتين أدناه باستخدام مفتاح نشط عبر نفس نقطة نهاية HTTP التي يشير إليها هذا التكوين، بينما كنت أكتب النص؛ تتوفر تفاصيل التتبع وفاتورة الوسائط بقيمة $0.55 في الأسفل.

لماذا نعلم GitHub Copilot توليد الصور؟

لأن مستودعات الكود تحتاج إلى صور في أكثر الأوقات حرجاً. صورة بارزة (README hero) حتى لا تفتح صفحة المشروع بجدار من شارات الحماية والروابط. أو لافتة لموقع التوثيق. وبغض النظر عن لقطات الشاشة، كان كل من هذه المتطلبات يعني اتخاذ مسار طويل ومعقد: فتح علامة تبويب جديدة في المتصفح، كتابة الـ prompt، تنزيل الصورة، إعادة تسميتها، سحبها إلى المستودع، والعودة مجدداً إلى المحرر. يستغرق ذلك عشر دقائق لكل أصل إذا سارت الأمور على ما يرام.

باستخدام خادم MCP، يقوم Copilot بتشغيل تلك الحلقة بالكامل في وضع agent. فهو يكتب الـ prompt، ويستدعي generate_image، ويسحب الملف إلى المجلد الذي حددته، ويعدل مرجع markdown. وكل ما عليك فعله هو مراجعة الـ diff.

السبب الأكبر يتعلق بالعمل الجماعي وتنسيق الفريق، وهو السبب في وجود هذا الدليل كمقالة منفصلة بدلاً من كونه مجرد فقرة في دليل Cursor. يعتبر .vscode/mcp.json ملفاً خاصاً بمساحة العمل (workspace). قم بعمل commit له مرة واحدة، وسيحصل كل مطور يقوم بعمل clone للمستودع على صندوق أدوات الصور عند أول فتح للمشروع، حيث سيطلب VS Code من كل شخص إدخال مفتاحه الخاص. تكوين واحد، مفتاح واحد لكل مطور، وصفر أسرار في git.

توجد أيضاً خوادم MCP محلية لتوليد الصور، وهي خيار جيد إذا كنت تفضل تشغيل عملية Node وإحضار مفتاح Google API الخاص بك مع كوتة الاستخدام الخاصة بك. لكن الخيار البعيد يتجاوز كل هذا العناء: نقطة النهاية تعمل بالفعل من جانبنا، على نفس المسار البرمجي لـ BananaBanana web generator، ووثيقة اعتمادك الوحيدة هي مفتاح bb_live_ قابل للإلغاء.

كيف تقوم بإعداد mcp.json في VS Code؟

تم التحقق من تفاصيل الإعداد بمطابقتها مع وثائق VS Code MCP الرسمية اعتبارا من 11 يوليو 2026. ثلاث خطوات.

أولاً، قم بـ التسجيل وافتح الملف الشخصي ← MCP API Keys. يتم عرض المفتاح مرة واحدة فقط ويتم تخزينه مشفراً من جانبنا، لذا انسخه على الفور. تبدأ الحسابات الجديدة برصيد ترحيبي قدره $0.20، وهو ما يكفي لتوليد ست صور تجريبية على أرخص نموذج.

ثانياً، قم بإنشاء ملف التكوين. هناك موقعان مناسبان للعمل:

• ملف .vscode/mcp.json في المستودع، وهو الملف الذي يستحق عمل commit له؛
• ملف mcp.json على مستوى المستخدم (لوحة الأوامر Command Palette ← MCP: Open User Configuration) والذي يرافقك في كل مساحة عمل تفتحها.

تستخدم الشيفرة البرمجية الموضحة في الأعلى آلية inputs، وهي حقاً الطريقة الأكثر تميزاً لإدارة البيانات السرية بين جميع عملاء MCP الذين قمت بإعدادهم. تخبر العبارة ${input:bb-api-key} محرر VS Code بطلب القيمة عند تشغيل الخادم لأول مرة. وتعمل الخاصية "password": true على إخفاء ما تكتبه، لتذهب القيمة مباشرة إلى مساحة تخزين مشفرة، وليس داخل الملف. قارن ذلك بمحرر Cursor، حيث يعتمد إدخال المتغيرات ${env:…} على رؤية المحرر الفعلية لبيئة الصدفة (shell environment) الخاصة بنظامك (وهو فشل صامت معتاد في التطبيقات التي يتم تشغيلها عبر الواجهة الرسومية GUI). يتفادى VS Code هذه المشكلة تماماً.

ثالثاً، ابدأ تشغيل الخادم: لوحة الأوامر Command Palette ← MCP: List Servers ← bananabanana ← Start، أو انقر على التلميح المضمن داخل ملف JSON. افتح Copilot Chat في وضع agent، وتحقق من قائمة الأدوات المفعلة لتجد سبع أدوات تبدأ من list_models وحتى list_generations. تحتوي صفحة خادم MCP الخاصة بنا على جدول توافق لكل عميل قمنا باختباره؛ والسطر الخاص بـ VS Code هو ما تفصله هذه المقالة بالتحديد:

ألا يظهر أي شيء؟ يغطي قسم العقبات الأسباب الثلاثة الأكثر شيوعاً، وأحدها يتعلق بسياسة مؤسسة GitHub والتي لا يمكنك إصلاحها من داخل المحرر نفسه.

حالة استخدام: إدراج أصول README والتوثيق مباشرة في المستودع

السيناريو الذي بنيت هذه المقالة حوله: يقوم فريقك بنشر أداة واجهة أوامر (CLI) كأداة مفتوحة المصدر، ويحتاج المستودع إلى صورة بارزة لملف README بالإضافة إلى صورة لدليل البدء السريع للتوثيق. في Copilot Chat (وضع agent)، تطلب لافتة إعلانية، فيقوم الـ agent بإنشاء prompt بأسلوب فوتوغرافي مستدعياً الأداة. هذا هو سجل التتبع الفعلي، متضمناً معرف العمل الحقيقي وكل التفاصيل:

→ generate_image {"prompt": "A wide photorealistic hero banner for a GitHub
   README of an open-source terminal application: a sleek dark laptop on a
   light oak desk showing colorful command-line output, soft morning window
   light from the left, shallow depth of field, 50mm lens, generous clean
   negative space on the right side for a project title, no text, no logos",
   "model": "nano-banana-pro", "aspect_ratio": "16:9"}
← {"job_id": "cmrgq90ou00036k7f86f0y54w", "status": "processing",
   "cost_charged_usd": 0.11, "balance_remaining_usd": 1554.18}
→ get_result {"job_id": "cmrgq90ou00036k7f86f0y54w"}
← {"status": "completed", "files": [{"url": "https://bananabanana.pro/api/files/…"}]}

حوالي عشرين ثانية من وقت الاستدعاء إلى تسليم الملف. إليك المخرج الفعلي الناتج من المحاولة الأولى وبدون أي تعديل:

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

تتبع صورة البدء السريع للتوثيق نفس الأسلوب ولكن بتوجيهات أكثر هدوءاً: لقطة علوية مسطحة (flat-lay)، لوحة مفاتيح، مخطط معماري مطبوع مع ملاحظات لاصقة، وكوب من الشاي. استدعاء واحد بتكلفة $0.11:

تم تشغيل كلا العرضين التجريبيين على نموذج Nano Banana Pro لأنهما يظهران في هذه الصفحة. بالنسبة لمواقع الويكي الداخلية وقوالب المشكلات (issue templates)، كنت سأتحول إلى استخدام nano-banana-2-lite بتكلفة $0.03 دون تردد؛ حيث يوضح دليل Lite الحالات التي يكون فيها النموذج الاقتصادي كافياً. تظل روابط الملفات الموقعة صالحة لمدة 24 hours، ويعيد استدعاء جديد لـ get_result إصدارها مرة أخرى.

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

عقبات في VS Code يجدر معرفتها قبل البدء في الاستخدام

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

1. المفتاح الرئيسي ذو المستوى الأعلى هو servers وليس mcpServers. يستخدم كل عميل رئيسي آخر (مثل Claude و Cursor و Windsurf) المفتاح mcpServers، لذا فإن الإعدادات المنسوخة من وثائق الأدوات الأخرى ستفشل في محرر VS Code، ومن السهل تجاهل تلميحات مخطط JSON. وينطبق نفس الفخ العكسي عند نسخ مقتطفات VS Code إلى برامج أخرى. ويستحق حقل type: "http" الإبقاء عليه واضحاً ومحدداً بالنسبة للخوادم البعيدة.

2. تغيير قيمة المدخلات المخزنة صعب للغاية بشكل غريب. يطلب المحرر الإدخال لأول مرة ليقوم بحفظ المفتاح في مساحة تخزين مشفرة، ولا يوجد زر واضح لـ "تعديل البيانات السرية" بعد ذلك. الطريقة البديلة المتاحة: افتح ملف .vscode/mcp.json، ومرر مؤشر الفأرة فوق الخادم، ثم استخدم عناصر التحكم المضمنة لإعادة التشغيل مع مسح المدخلات، أو امسح القيم المخزنة من خلال الانتقال إلى MCP: List Servers ← الخادم ← قطع الاتصال (disconnect) وإعادة الإضافة. وتزداد الصعوبة عند العمل عبر Remote SSH، حيث تعاني عملية إعادة طلب الإدخال من مشكلات معروفة وفقاً لـ مستكشف مشكلات VS Code. لذا فإن استبدال مفتاح ملغى يتطلب بضع دقائق من النقر لم تكن تخطط لها.

3. في خطط Copilot Business أو Enterprise، يتم إيقاف ميزة MCP حتى يقوم المدير بتفعيل السياسة. يتم إلغاء تفعيل سياسة "MCP servers in Copilot" بشكل افتراضي للمقاعد الممنوحة من الشركات والمؤسسات، وذلك وفقاً لـ وثائق سياسة GitHub. الجزء المربك هو طبيعة حدوث الفشل: حيث يبدأ تشغيل الخادم بشكل طبيعي تماماً، ويتم التحقق من صحة التكوين، ولكن الأدوات ببساطة لا تظهر أبداً في الدردشة. إذا كنت تستخدم خطة شخصية من Copilot (بما في ذلك الخطة المجانية Free)، فلا ينطبق عليك أي من هذا القيود.

4. هناك حد أقصى صارم يبلغ 128 أداة لكل طلب دردشة. تُحتسب الأدوات المضمنة وأدوات الإضافات وكل خادم MCP مفعل ضمن هذا الحد، وذلك وفقاً لـ وثائق أدوات الـ agent. يضيف خادمنا سبع أدوات فقط، وهو عدد ضئيل بمفرده، ولكن عند تكديس بعض الخوادم التي تقدم أدوات كثيرة، ستبدأ الطلبات بالفشل حتى تقوم بإلغاء تحديد خوادم كاملة في منتقي الأدوات. يمكن لـ VS Code تجميع الأدوات الزائدة خلف أدوات افتراضية؛ لكن من واقع تجربتي، لا يزال من الأفضل إبقاء الخوادم التي تستخدمها بالفعل فقط مفعلة.

5. تعمل الأدوات في وضع agent، وكل استدعاء يتطلب تأكيداً. لا يتم تشغيل أدوات MCP في وضع السؤال العادي (ask mode)، لذا إذا استمر النموذج في وصف الصور بدلاً من إنشائها، فتحقق من القائمة المنسدلة للوضع أولاً. تحتوي طلبات التأكيد على قائمة منسدلة للسماح للأداة بالعمل للجلسة الحالية، أو لمساحة العمل، أو دائماً. بالنسبة للأدوات المجانية مثل list_models و get_result فإن خيار "always" ممتاز. أما بالنسبة لـ generate_image فإنني أفضل إبقاء التأكيد لكل استدعاء مفعلاً لأن كل طلب يستهلك رصيداً مالياً حقيقياً؛ ويأتي الفيديو محمياً بقفل إضافي عبر خطوة confirm_cost من جانبنا في جميع الأحوال.

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

الأسعار القياسية لكل توليد، وهي نفس الأرقام التي يبلغ بها الأمر list_models الـ agent الخاص بك:

نجحت جميع المحاولات من المرة الأولى هذه المرة. لن يحدث هذا دائماً بالطبع، لذا ضع في اعتبارك ميزانية إضافية لإعادة التوليد عند التعامل مع شاشات معروضة أو أشكال هندسية معقدة، وافحص النتائج بحجمها الكامل قبل دمجها في الفرع الرئيسي للمستودع (main branch).

إذا كنت تستخدم هذا الخادم بالفعل في محرر آخر، فإن ملف .vscode/mcp.json الموضح أعلاه هو الجزء الجديد الوحيد: نفس المفتاح، ونفس الرصيد، ونفس تاريخ عمليات التوليد السابقة. أما إذا كنت تبدأ من الصفر، فإن دليل Claude Code يحتوي على أربع حالات استخدام إضافية يمكن تطبيقها بشكل مطابق تقريباً. ابدأ متى شئت: قم بإنشاء مفتاح واطلب من Copilot لافتة README الأولى الخاصة بك.

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

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

نعم، بشكل أصيل وتلقائي. يكون إعداد الخادم البعيد بـ type: "http" بالإضافة إلى الـ url وكائن headers اختياري في ملف mcp.json؛ وتضمن مراجع ${input:…} بقاء البيانات السرية خارج الملف، وهو ما تم التحقق منه بمطابقة وثائق VS Code MCP الرسمية في 11 يوليو 2026. كما يدعم VS Code بروتوكول OAuth للخوادم البعيدة؛ وتقوم نقطة النهاية الخاصة بنا حالياً بالتحقق باستخدام مفاتيح Bearer، مع التخطيط لإضافة دعم OAuth 2.1 كخيار ثانٍ قريباً.

هل من الآمن عمل commit لملف .vscode/mcp.json إلى git؟

نعم، طالما أن المفتاح يعتمد على مرجع inputs بدلاً من كتابته مباشرة في الملف. يحمل ملف JSON الذي يتم عمل commit له مجرد عنصر نائب فقط؛ ويقوم VS Code بمطالبة كل مطور بإدخال قيمته الخاصة عند بدء التشغيل لأول مرة ويحفظها في مساحة تخزين مشفرة. هذا التقسيم الفردي مفيد للغاية ومستحب في كل الأحوال: يحصل كل مفتاح على سجل استخدام خاص به وحد أقصى اختياري للتكلفة اليومية بالدولار الأمريكي عبر الملف الشخصي ← MCP API Keys، كما أن إلغاء الصلاحية يتم بنقرة واحدة لتعطيل مفتاح دون التأثير على أي شخص آخر.

لماذا لا تظهر أدوات MCP في Copilot Chat؟

هناك ثلاثة أسباب شائعة تفسر معظم الحالات. إما أنك لست في وضع agent، حيث لا تتيح أوضاع الدردشة الأخرى أدوات MCP. أو أنه لم يتم تشغيل الخادم مطلقاً، لذا يرجى تشغيل الأمر MCP: List Servers والتحقق من حالته. أو أن حساب Copilot الخاص بك تم توفيره عبر مؤسستك ولا تزال سياسة "MCP servers in Copilot" معطلة، وهو ما يفشل بشكل صامت ولا يمكن تفعيلها إلا من قبل مسؤول المؤسسة. وإذا ظهرت الأدوات ولكن الاستدعاءات ترجع خطأ 401، فإن المفتاح نفسه خاطئ أو ملغى، وسيقوم طلب مباشر باستخدام المقتطف البرمجي المتوفر في صفحة خادم MCP بتأكيد ذلك في ثوانٍ معدودة.

هل أحتاج إلى مفتاح Google API لتوليد الصور في VS Code؟

لا. تتحدث خوادم MCP لتوليد الصور التي تعمل محلياً مع واجهة برمجة تطبيقات Gemini مباشرة، مما يعني استخدام مفتاح Google الخاص بك والكوتة ونظام الفوترة الخاص بك. أما الخادم البعيد فيقوم بتشغيل التوليد عبر تجمع مدار بواسطة BananaBanana من مفاتيح Vertex AI، ووثيقة اعتمادك الوحيدة هي مفتاح bb_live_ من ملفك الشخصي: أسعار لكل عملية توليد، وبدون حد أدنى للإنفاق، ورصيد مدفوع مقدماً مشترك مع تطبيق الويب.

هل يمكن لـ GitHub Copilot توليد الفيديو عبر نفس الخادم؟

نعم، مع وجود خطوة تأكيد التكلفة. يقوم الاستدعاء generate_video أولاً بإرجاع عرض سعر، ويجب على الـ agent تكرار الاستدعاء مع تمرير قيمة confirm_cost مطابقة للمبلغ المحدد تماماً قبل خصم أي شيء. تتراوح الأسعار من $0.10 لمقطع صامت قصير بدقة 720p إلى $4.40 لتوليد فائق الجودة باستخدام Veo 3.1 مع الصوت، ويبلغ سعر Omni Flash مع الصوت $0.10 لكل ثانية ($0.30–$1.00 للمقطع). تستغرق المقاطع من دقيقة إلى عشر دقائق، لذا يستمر الـ agent في فحص حالة الإنتاج عبر get_result بشكل دوري بينما تواصل أنت العمل على الكود الخاص بك.