إعداد Antigravity MCP: موقع الملف والمتجر والأخطاء الشائعة

تلصق خادمًا جديدًا في Antigravity وتضغط Refresh، فتبقى قائمة الأدوات فارغة. غالبًا ما يكون الخادم سليمًا. المشكلة في الملف: أيّ mcp_config.json يقرؤه التطبيق، وأين يقع على القرص، وهل يستخدم JSON أسماء الحقول التي يتوقعها Antigravity. صفحات Google الرسمية تشير إلى مسارين مختلفين، وتعليقات المنتديات تُظهر أشخاصًا يعدّلون النسخة الخاطئة، ورسائل الخطأ قصيرة إلى درجة تجعلها أشبه بالألغاز.

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

أين يقع mcp_config.json

يحتفظ Antigravity بتعريف كل خادم MCP في ملف JSON واحد اسمه mcp_config.json. تسرد صفحة MCP الرسمية ملفًا عامًا ينطبق على كل المشاريع، وملفًا لمساحة العمل ينطبق على مستودع واحد.

المسار العام حسب نظام التشغيل

على Windows، يتوسع %USERPROFILE% إلى شيء مثل C:\Users\YourName. يبدأ المجلد .gemini بنقطة، لذلك يُخفيه Finder ومعظم مديري الملفات على Linux. في Finder اضغط Cmd+Shift+. لإظهار العناصر المخفية، وفي مدير الملفات على Windows فعّل العناصر المخفية من قائمة عرض، أو تجاوز التصفح والصق المسار الكامل في شريط العنوان أو في مربع الانتقال إلى المجلد.

إعداد مساحة العمل لمشروع واحد

داخل المستودع، تسمّي الوثائق .agents/mcp_config.json موقعًا لمساحة العمل. تناسب هذه الإعدادات الخوادم المرتبطة بقاعدة شيفرة واحدة فقط، مثل خادم قاعدة بيانات موجَّه إلى مخطط التطوير الخاص بذلك المشروع. يذكر شرح ياباني لاستكشاف الأخطاء وإصلاحها أن إعدادات مساحة العمل يمكن أن تتجاوز الملف العام، لذا تحقّق من هذا المسار أولًا حين يتصرف خادم بشكل مختلف داخل مستودع واحد.

💡 نصيحة: إذا كان ملف مساحة العمل يحتوي على توكنات، فأضف .agents/mcp_config.json إلى .gitignore قبل الإيداع التالي.

لماذا تختلف الوثائق في المسار

تستخدم الوثائق الحالية وصفحة إعداد CloudBees Unify المسار ~/.gemini/config/mcp_config.json. وتستخدم الدروس القديمة، وكثير من ملفات README الخاصة بالخوادم، وتقرير خلل PATH على macOS المسار ~/.gemini/antigravity/mcp_config.json. ويقع ملف توكنات OAuth أيضًا في مجلد antigravity، وهذا جزء من سبب ظهور اسم ذلك المجلد باستمرار.

لا تحدد أي صفحة الملف الذي يُعتمد إذا وُجد الملفان. احسم الأمر باختبار: أضف إدخالًا غير ضار إلى أحد الملفين، واضغط Refresh، وانظر هل يظهر في قائمة الخوادم. إن لم يظهر، فأنت عدّلت الملف الخطأ. ثم أبقِ ملفًا واحدًا فعّالًا، وأعد تسمية النسخة الزائدة إلى mcp_config.json.bak حتى لا ينحرف الملفان عن بعضهما أبدًا. وفتح الملف عبر View raw config في IDE هو أسرع طريقة لمعرفة الملف الذي يستخدمه إصدار بنائك.

ثلاث طرق لفتح الملف

لا حاجة للبحث في المجلدات المخفية. لكل سطح من أسطح Antigravity بابه الخاص إلى الإعداد نفسه.

من لوحة الوكيل في IDE

في Antigravity IDE، انقر قائمة … في أعلى اللوحة الجانبية للوكيل، ثم اختر MCP Servers، ثم Manage MCP Servers، ثم View raw config. يفتح الملف في المحرر. احفظه، وارجع إلى شاشة Manage MCP Servers واضغط Refresh. هذه النقرة الأخيرة هي الخطوة التي تكررها خيوط استكشاف الأخطاء مرارًا.

من إعدادات Antigravity 2.0

في Antigravity 2.0 يكون المسار Settings (أسفل يسار الشاشة)، ثم Customizations، ثم Installed MCP Servers. لكل خادم مفتاح تشغيل وسلة حذف وزر Refresh مشترك. وللأداة سطر الأوامر بابها الخاص: اكتب /mcp في لوحة الإدخال لفتح MCP Manager التفاعلي. كما يعرض سجلات الاتصال، بما فيها رموز الاستجابة مثل 401 و403 و404 وانتهاء المهلة، ما يجعله أفضل مكان لقراءة سبب المشكلة الفعلي.

كيف يعمل متجر MCP

متجر MCP قائمة قابلة للبحث من الخوادم الجاهزة. تصف الوثائق 76 تكاملًا أو أكثر تشمل قواعد البيانات وأدوات المطورين ومنصات التصميم والأمان والتحليلات. تصل إليه من Installed MCP Servers بالنقر على Add MCP، أو من قائمة MCP Servers في لوحة الوكيل داخل IDE.

أضف خادمًا من المتجر

1. افتح Settings، ثم Customizations، ثم Installed MCP Servers.
2. انقر Add MCP لفتح المتجر.
3. ابحث عن الخادم الذي تريده أو مرّر إليه، ثم انقر Add.
4. أكمل تسجيل الدخول إن طلب الخادم ذلك.
5. تأكد من أن المفتاح مفعّل، ثم اضغط Refresh.

افتح الإعداد الخام مرة واحدة بعد أول تثبيت من المتجر. الإدخال الذي كتبه المتجر قالب جاهز للإدخالات التي ستكتبها يدويًا لاحقًا.

💡 نصيحة: استخدم المتجر للخوادم التي تحتاج إلى OAuth، لأنه يتولى شاشة تسجيل الدخول. واستخدم JSON المكتوب يدويًا للسكربتات المحلية والخوادم الخاصة وأي شيء يحتاج إلى headers مخصصة.

أين تنتهي رموز OAuth

بحسب الوثائق، تُحفظ رموز OAuth في ~/.gemini/antigravity/mcp_oauth_tokens.json. تعامل مع هذا الملف كخزنة كلمات مرور: أبقِه خارج مستودعات الملفات المخفية ومجلدات المزامنة السحابية. وعندما يستمر فشل تسجيل الدخول، استخدم زر Sign out في IDE أولًا، أو تحقّق من حالة Authed في عرض CLI /mcp. حذف ملف الرموز حل أخير، وقد يسجّل خروجك من كل الخوادم البعيدة دفعة واحدة.

إعداد يعمل فعلًا

يحتوي الملف على كائن واحد على المستوى الأعلى هو mcpServers، وكل خادم هو إدخال مسمّى داخله. ينبغي ألا تحتوي الأسماء على مسافات. ذكر منتدى حول خادم Figma أن الاسم المقترح "Figma Desktop" احتاج إلى أن يصبح FigmaDesktop، وأن حقل الرابط يجب أن يكون serverUrl لا url.

الخوادم المحلية باستخدام command وargs

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/Users/you/projects"],
      "env": { "NODE_ENV": "production" },
      "cwd": "C:/Users/you/projects"
    }
  }
}

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

على Windows، اكتب المسارات بشرطات مائلة للأمام، أو ضاعف الشرطات المائلة للخلف (C:\\Users\\you)، لأن الشرطة المائلة الواحدة للخلف محرف هروب في JSON. هذا ما يفعله كل حقل:

الخوادم البعيدة باستخدام serverUrl

{
  "mcpServers": {
    "remote-example": {
      "serverUrl": "https://api.example.com/mcp/",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

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

تقول الوثائق إن حقول url العادية غير مدعومة للخوادم البعيدة، لذلك يحتاج المقطع المنسوخ من محرر آخر إلى إعادة تسمية واحدة. الخوادم التي تستخدم OAuth تأخذ كتلة oauth بدلًا من header، وتعرض صفحة CloudBees المثال "oauth": { "clientId": "public-mcp-client" }. أما مع خوادم Google Workspace فيجب عليك إنشاء عميل OAuth من نوع Web application في Google Cloud Console، وإضافة https://antigravity.google/oauth-callback بوصفه redirect URI، ووضع clientId وclientSecret في قسم oauth. والخوادم التي تقبل بيانات اعتماد Google الافتراضية للتطبيقات تستخدم "authProviderType": "google_credentials".

قبل الحفظ، تحقّق من ثلاثة أشياء تكسر JSON أكثر من أي خلل في Antigravity: الفواصل الزائدة في النهاية، والتعليقات (لا يسمح JSON بأي تعليق)، والاقتباسات المنحنية المنسوخة من صفحة ويب.

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

Context Deadline Exceeded

يظهر هذا عند بدء التشغيل مع رسالة المقبس ENOENT، حين لا ينتهي خادم من التهيئة في الوقت المحدد. الإصلاح المذكور بسيط: افتح Manage MCP Servers واضغط Refresh. وإن عاد الخطأ عند كل إعادة تشغيل، فالحل العملي هو تثبيت حزمة الخادم عامةً، وتوجيه command إلى الملف التنفيذي المثبّت، حتى لا يُحمَّل شيء أثناء إقلاع IDE.

Executable Not Found in PATH

تظهر رسائل مثل exec: "npx": executable file not found in $PATH عند تشغيل Antigravity من Dock أو Spotlight على macOS. يرث التطبيق مسار PATH النظامي المحدود (/usr/bin:/bin:/usr/sbin:/sbin) بدلًا من المسار الموجود في ملف إعداد الطرفية لديك. ويذكر الخيط أن هذا يحدث في الإصدار 1.22.2، ويسرد هذه الحلول البديلة:

• ابدأ التطبيق من الطرفية بالأمر agy.
• ضع المسار المطلق في command. شغّل which npx والصق النتيجة، مثل /opt/homebrew/bin/npx في إعداد Homebrew نموذجي على Apple Silicon.
• أنشئ سكربت غلافًا صغيرًا يحمّل مدير إصدارات Node لديك قبل تشغيل الخادم.

على مستخدمي Windows أن يشغّلوا where npx في الطرفية أولًا. فإن لم يطبع شيئًا، فالمشكلة في تثبيت Node وليست في الإعداد.

Unauthorized on Initialize

يعني خطأ Unauthorized على initialize أن خادمًا بعيدًا تلقى الطلب الأول دون رمز صالح للاستخدام. حدّث Antigravity، وسجّل الخروج من الخادم، ثم سجّل الدخول مرة أخرى. وإن كنت تستخدم رمز header، فتأكد من أن الحقل اسمه Authorization، وأن القيمة تبدأ بالكلمة Bearer ، وأن الرمز لم تنتهِ صلاحيته. وتضيّق رموز الحالة في سجلات CLI /mcp الاحتمالات: 401 يشير إلى بيانات اعتماد مفقودة أو خاطئة، و403 إلى رمز بلا الصلاحيات المناسبة، و404 إلى مسار URL خاطئ.

أكثر من 100 أداة

يرفض Antigravity الاتصال عندما يتجاوز عدد الأدوات المفعّلة في كل الخوادم الرقم 100. قد تعرض الخوادم الكبيرة مثل GitHub أو قواعد البيانات عشرات الأدوات لكل منها، فيكفي ثلاثة أو أربعة منها للوصول إلى الحد. عطّل الخوادم التي لا تستخدمها، أو أخفِ أدوات بعينها باستخدام الخاصية disabledTools المذكورة في الوثائق.

يستحق نمط آخر أن تعرفه. يصف تقرير في منتدى مطوّري Google AI خادم Roblox Studio يُشغَّل عبر ملف دفعي، ويفشل مع رسالة EOF في Hub 2.4.3 و2.5.0 و2.8.0، ولا يعمل إلا بعد الرجوع إلى Hub 2.2.1. عندما يفشل خادم محلي بهذه الطريقة، شغّل أمره الدقيق في الطرفية. فإن فشل هناك أيضًا، فالإعداد سليم والمشكلة في الخادم. وإن نجح هناك، فاشتبه في تراجع في الإصدار، وراجع المنتدى قبل أن تغيّر JSON.

استخدم Gemini 3.1 Pro على PicassoIA

عندما يرفض JSON أن يتصرف، يصبح النموذج اللغوي مدقق نصوص سريعًا. يعمل Gemini 3.1 Pro في المتصفح على PicassoIA، ويقبل نصًا مع ما يصل إلى 10 صور، ويتيح لك ضبط مقدار التفكير قبل الإجابة.

الخطوات

1. افتح صفحة Gemini 3.1 Pro على PicassoIA.
2. استبدل كل رمز حقيقي في إعدادك بالنص YOUR_TOKEN قبل لصق أي شيء.
3. الصق JSON في حقل Prompt بعد تعليمة واضحة، مثل: "تحقّق من ملف Antigravity mcp_config.json هذا بحثًا عن أخطاء في الصياغة وأسماء حقول خاطئة. يجب أن تستخدم الخوادم البعيدة serverUrl لا url. ولا يجوز أن تحتوي أسماء الخوادم على مسافات. اذكر كل مشكلة، ثم أعد JSON المصحح فقط."
4. اختياري: أرفق لقطة شاشة للوحة الخطأ في حقل Images (حتى 10 صور، بحجم 7 ميغابايت لكل صورة).
5. شغّل النموذج، والصق JSON المصحح في View raw config، واحفظ، واضغط Refresh.

نصائح للمعاملات

• thinking_level: القيمة الافتراضية هي high. احتفظ بها لإعداد طويل فيه خوادم كثيرة. وlow يكفي لفحص صياغة بسيط.
• temperature: القيمة الافتراضية هي 1. اخفضها إلى نحو 0.2 حتى يعيد النموذج JSON نفسه في كل مرة بدل أن يبدع.
• system_instruction: اضبطها على شيء مثل "أنت مدقق JSON صارم لملفات إعداد MCP" لجعل الرد موجزًا.
• max_output_tokens: القيمة الافتراضية كافية لأي إعداد ستكتبه، فاتركها كما هي.

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

قائمة تحقق قبل إعادة التشغيل

راجع هذه القائمة قبل أن تلوم الخادم:

• يُحلَّل JSON بنجاح: لا فواصل زائدة في النهاية، ولا تعليقات، واقتباسات مستقيمة فقط.
• تستخدم الخوادم البعيدة serverUrl، وتستخدم الخوادم المحلية command مع args.
• لا تحتوي أسماء الخوادم على مسافات.
• يعمل الأمر في الطرفية، أو يحتوي command على مسار مطلق.
• تُحفظ الرموز في env أو headers، والملف خارج نظام التحكم بالإصدارات إن كان يحتوي على أسرار.
• تبقى الأدوات المفعّلة في كل الخوادم أقل من 100.
• عدّلت الملف الذي يقرؤه التطبيق فعلًا، وهو ما تستطيع تأكيده عبر View raw config.
• ضغطت Refresh، ثم تحققت من المفاتيح أو من عرض CLI /mcp.

💡 نصيحة: الخادم الذي يعمل في الطرفية لكنه يفشل داخل Antigravity يشير عادةً إلى اختلاف في البيئة، وغالبًا في PATH. قارن مخرجات which أو where بما يراه التطبيق.

جرّب Picasso IA بنفسك

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

ابدأ مع Seedream 4.5 للمشاهد التفصيلية واقعية كالصور الفوتوغرافية، أو مع P-Image للمسودات السريعة. صف الشخص، والمكان، واتجاه الضوء، وعدسة الكاميرا، كما تصف الأمر لمصوّر محترف. تصفّح قائمة النماذج الكاملة، واختر النموذج الذي يناسب مشروعك القادم، وأنشئ أول صورة لك اليوم.