موقع ملف mcp.json في VS Code: إعداد خوادم MCP وسجلها خطوة بخطوة

تضيف خادم MCP إلى VS Code، وتعيد تحميل النافذة، وتفتح Copilot Chat، فلا تجد الأدوات الجديدة في أي مكان. في أغلب الحالات يكون الخادم سليمًا والمشكلة في الملف: إما أنه موجود في المجلد الخطأ، أو يستخدم اسم الخاصية الجذرية الخطأ، أو أن VS Code يقرأ نسخة مختلفة عن النسخة التي عدّلتها للتو. يحدد هذا المقال موقع ملف mcp.json في VS Code لكل إعداد، ويعرض الشكل الذي يتوقعه المحرر لبنية JSON، ويوضح كيف يتناسب سجل MCP معها حتى تضيف الخوادم دون نسخ أوامر من ملفات README عشوائية.

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

أين يقع ملف mcp.json

يقرأ VS Code تعريفات خوادم MCP من مكانين رئيسيين، بالإضافة إلى صيغة محمولة سنشرحها لاحقًا. فكّر فيهما كرفّ مشترك للفريق ورفّ شخصي.

ملف مساحة العمل: .vscode/mcp.json

يقع ملف مساحة العمل داخل مجلد المشروع في .vscode/mcp.json. أنشئ المجلد .vscode إن لم يكن موجودًا، وضع الملف فيه، وسيلتقطه VS Code. ولأن الملف يُنقل مع المستودع، يحصل كل من يستنسخ المشروع على قائمة الخوادم نفسها.

يمكنك أيضًا فتحه من لوحة الأوامر (Ctrl+Shift+P على Windows وLinux، وCmd+Shift+P على macOS) عبر الأمر MCP: Open Workspace Folder Configuration، أو إنشاء مدخل عبر MCP: Add Server واختيار خيار مساحة العمل.

ملف المستخدم حسب نظام التشغيل

ينطبق ملف المستخدم على كل نافذة تفتحها. أسرع طريقة للوصول إليه هي الأمر MCP: Open User Configuration في لوحة الأوامر، وهو يفتح النسخة التابعة لملفك الشخصي النشط. في التثبيت القياسي يقع الملف في مجلد بيانات المستخدم في VS Code:

💡 نصيحة: يحتفظ VS Code Insiders بمجلد بيانات خاص به، واسمه عادةً Code - Insiders بدلًا من Code. إذا لم يُحدث التعديل أي فرق، فتحقق من أنك لا تعدّل النسخة المستقرة أثناء تشغيل Insiders. وعند الشك، ثق بأمر لوحة الأوامر أكثر من أي مسار كتبته من الذاكرة.

أيهما تختار

يتوقف الاختيار على من يحتاج إلى الخادم، وهل يحمل توكنًا شخصيًا.

تجنّب تعريف الاسم نفسه للخادم في الملفين معًا. مع وجود نسختين لن تعرف أيهما يعمل فعلًا، وتتحول تقارير الأخطاء التي تقول "الخادم معطل" إلى ظهيرة كاملة من التخمين.

كتابة صيغة الملف بشكل صحيح

يضم الملف حتى ثلاثة أقسام جذرية: servers (مطلوب، وهو خريطة من أسماء الخوادم إلى إعداداتها)، و**inputs** (اختياري، ويضم أوامر لقيم لا تريد تخزينها)، و**sandbox** (اختياري، ويضم قواعد الملفات والشبكة على macOS وLinux). كل شيء آخر يتفرع من هذه الأقسام الثلاثة.

خادم stdio بسيط

خادم stdio هو برنامج يشغّله VS Code على جهازك ويتواصل معه عبر المدخل والمخرج القياسيين. تُشحن معظم الخوادم المجتمعية بهذه الطريقة، غالبًا عبر npx أو uvx.

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    }
  }
}

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

يتوسع المتغير ${workspaceFolder} ليشير إلى المشروع المفتوح، فيعمل الملف نفسه على جهاز كل زميل في الفريق. يمكنك إضافة cwd لمجلد العمل، وenv لمتغيرات البيئة، وenvFile لتحميل المتغيرات من ملف.

خادم HTTP بعيد

يعمل الخادم البعيد في مكان آخر، ويتصل VS Code بعنوان URL الخاص به. لا توجد عملية محلية، ولا npx، ولا مشكلات في إصدار Node.

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

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

استخدم "type": "http" للخوادم البعيدة الحديثة، و"type": "sse" للخوادم التي ما زالت تستخدم ناقل الأحداث المرسلة من الخادم (server-sent events) القديم. ويمكن للمدخلات البعيدة أيضًا أن تحمل headers للمصادقة، وكائن oauth عندما يدعم الخادم تسجيل الدخول عبر المتصفح.

فخ servers مقابل mcpServers

هذا هو السبب الأكثر شيوعًا لعدم عمل إعداد منسوخ.

لماذا لا يظهر الخادم أبدًا

تعرض أغلب ملفات README مقتطفات مكتوبة من أجل Claude Desktop أو Claude Code أو Cursor. تستخدم هذه العملاء خاصية جذرية اسمها mcpServers. أما mcp.json الخاص بمحرر VS Code فيتوقع servers. إذا لصقت الشكل الخاطئ في .vscode/mcp.json فقد يفشل الملف بصمت: قد يُظهر المحرر تحذيرًا عن الخاصية، لكن التحذير سهل التجاهل، ولن تظهر أي أدوات.

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }
  }
}

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

هذه الكتلة تخص عميلًا آخر. في VS Code، أعد تسمية الخاصية الجذرية إلى servers وأضف "type": "stdio" حتى يتطابق المدخل مع الصيغة الموضحة سابقًا.

يوثّق VS Code أيضًا صيغة محمولة: ملف .mcp.json في جذر المشروع، أو ~/.copilot/mcp-config.json للمستخدم. تستخدم هذه الملفات المحمولة فعلًا mcpServers. والقاعدة بسيطة: servers داخل mcp.json الخاص بمحرر VS Code، وmcpServers داخل الملفات المحمولة.

أسماء الخصائص حسب العميل

راجع هذه القائمة القصيرة كلما اختفت الأدوات:

• تحقق من اسم الخاصية أولًا. servers بدلًا من mcp.json، وmcpServers للملفات المحمولة.
• تحقق من type. البرنامج المحلي يحتاج stdio، والعنوان يحتاج http أو sse.
• تحقق من الملف الذي فتحته. شغّل MCP: List Servers وتأكد من ظهور خادمك هناك.
• أعد تحميل النافذة بعد تعديل كبير إذا بدت قائمة الخوادم قديمة.

أبقِ الأسرار خارج الملف

ينتهي ملف mcp.json الخاص بمساحة العمل عادةً في Git. وكل ما تكتبه فيه، بما في ذلك التوكن، ينتهي هناك أيضًا.

اطلب التوكنات عبر المدخلات

يحدد القسم inputs قيمًا يطلبها VS Code بدلًا من تخزينها. أشِر إلى أي قيمة داخل مدخل خادم باستخدام ${input:id}.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "api-token",
      "description": "API token for the image service",
      "password": true
    }
  ],
  "servers": {
    "image-service": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${input:api-token}" }
    }
  }
}

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

عنوان URL أعلاه مجرد نموذج. الأهم هو النمط: promptString مع password: true يعرض حقلًا مخفيًا، ويطلب VS Code القيمة عند بدء الخادم، فلا يضطر التوكن إلى البقاء في الملف. يوجد نوعان آخران من المدخلات: pickString لقائمة ثابتة من الخيارات، وcommand لقيمة تُنتَج بتشغيل أمر.

💡 نصيحة: يناسب النمط نفسه أي خدمة REST تستخدم توكن Bearer، بما في ذلك واجهة برمجة التطبيقات (API) للمطورين في Picasso IA على العنوان api.picassoia.com/v1، والتي تبدأ توكناتها بالقيمة pia_sk_. احتفظ بهذا التوكن في مدخل أو متغير بيئة، وليس في ملف مُلتزَم به أبدًا.

envFile واعتماد مساحة العمل

بالنسبة لخوادم stdio، يحمّل envFile المتغيرات من ملف مثل ${workspaceFolder}/.env. أضف هذا الملف إلى .gitignore قبل أول commit، لا بعده.

يعمل الاعتماد على طبقتين. الخوادم المعرّفة داخل مساحة العمل ترث Workspace Trust، فلا يشغّلها مجلد غير موثوق. أما الخوادم المعرّفة خارج مساحة العمل فتطلب نافذة الثقة الخاصة بها في أول تشغيل. يتحكم الإعداد chat.mcp.autostart في إعادة التشغيل عند تغيّر الإعداد، ومن قيمه never وonlyNew وnewAndOutdated (وهي الافتراضية).

البحث عن الخوادم في السجل

كتابة كل مدخل بيدك تصبح مرهقة بسرعة. يمنحك VS Code طريقتين لتجاوز ذلك.

تصفح @mcp من عرض الامتدادات

افتح عرض الامتدادات (Ctrl+Shift+X) واكتب @mcp في مربع البحث. القائمة التي تظهر هي معرض خوادم MCP داخل المحرر. اختر خادمًا، واختر ما إذا كنت تريد تثبيته في الملف الشخصي للمستخدم أو في مساحة العمل، وسيضيف VS Code المدخل إلى mcp.json المطابق. افتح الملف بعد ذلك واقرأ ما كُتب. إنها طريقة جيدة لمعرفة الصياغة الصحيحة للخوادم التي تضيفها لاحقًا يدويًا.

ما يضيفه السجل الرسمي

سجل MCP الرسمي هو الدليل العام الذي ينشر فيه مؤلفو الخوادم خوادمهم. يسمّي كل مدخل الحزمة أو عنوان URL البعيد، وهذا بالضبط ما كنت ستلصقه في mcp.json بنفسك. استخدمه عندما لا يكون الخادم موجودًا في معرض الامتدادات، وتحقق من اسم الحزمة مقابل مدخل السجل قبل تشغيل أي شيء. قد يثبّت خطأ مطبعي في وسيطة npx حزمة مختلفة.

الاكتشاف التلقائي للخوادم من التطبيقات الأخرى

يستطيع VS Code أيضًا استيراد الخوادم التي أعددتها بالفعل في أدوات أخرى. افتح الإعدادات، وابحث عن chat.mcp، وابحث عن الإعداد الذي يتحكم في الاكتشاف التلقائي من التطبيقات الأخرى. إذا أردت بداية نظيفة فأوقفه. وإذا انتقلت من Claude Desktop فإبقاؤه مفعّلًا يوفر عليك إعادة الكتابة.

إصلاح خادم لا يبدأ

عندما يُظهر الخادم خطأ، فالجواب تقريبًا دائمًا موجود في سجله الخاص.

اقرأ سجل المخرجات

شغّل MCP: List Servers، واختر الخادم، وافتح مخرجاته. يمكنك أيضًا فتح mcp.json والنظر فوق اسم الخادم، حيث يعرض VS Code إجراءات مضمّنة لبدء الخادم وإيقافه وإعادة تشغيله وعرض المخرجات. يطبع السجل الأمر الدقيق الذي شغّله VS Code وكل ما كتبته العملية في الخطأ القياسي. اقرأ الخطأ الأول، لا الأخير.

أنماط الأعطال الشائعة

وضع التطوير والصندوق الرملي

إذا كنت تبني الخوادم، فإن كائن dev في مدخل stdio مفيد. يأخذ watch نمط glob ويعيد تشغيل الخادم عندما تتغير الملفات المطابقة له، ويربط debug مصحّحًا للأخطاء (يدعم Node.js وPython لخوادم stdio). وعلى macOS وLinux، يقيّد كائن sandbox ما يحق للخادم لمسه: filesystem.allowWrite، وfilesystem.denyRead، وfilesystem.denyWrite، وnetwork.allowedDomains، وnetwork.deniedDomains. اضبط sandboxEnabled على خادم بعينه لتطبيقه. ابدأ بتقييد شديد، ولا تفتح إلا ما يثبت الخادم حاجته إليه.

صياغة إعدادك باستخدام Claude Sonnet 5

إذا كان نموذج لغوي سيساعدك في JSON، فاختر نموذجًا مصمّمًا للشيفرة. يكتب Claude Sonnet 5 على Picasso IA الشيفرة ويصحح أخطاءها، ويقرأ لقطات الشاشة، ويتيح لك اختيار مقدار التفكير الذي يبذله. هذا هو سير العمل الذي يعمل مع mcp.json.

1. افتح صفحة النموذج. انتقل إلى Claude Sonnet 5 على Picasso IA.
2. املأ System Prompt مرة واحدة. مثلًا: You write VS Code mcp.json files. Use the servers property, never mcpServers. Always set type. Output JSON only.
3. صف الإعداد في Prompt. اذكر الخوادم التي تريدها، ونظام التشغيل، وهل يكون كل خادم من نوع stdio أو بعيدًا.
4. اضبط effort. اتركه على low لإصلاح من سطر واحد. استخدم medium أو high عندما يجمع الملف عدة خوادم ومدخلات. الإعداد low يوقف التفكير، لذلك هو الأسرع والأرخص.
5. أبقِ Max Tokens على القيمة الافتراضية 8192. ملف الإعداد يحتاج أقل بكثير من ذلك.
6. أرفق لقطة شاشة إذا كان لديك خطأ. يقبل الحقل الاختياري Image صورة واحدة، والقيمة الافتراضية للخيار Max Image Resolution هي 0.5 ميغابكسل للإبقاء على التكلفة منخفضة.
7. شغّله، ثم تحقق. ألصق النتيجة في mcp.json، وقارن كل اسم حزمة وكل عنوان URL مع مدخل السجل، وراقب سجل المخرجات عند أول تشغيل.

أمر نصي يعطي مسودة أولى قابلة للاستخدام:

Create a VS Code mcp.json for Windows with two servers: a stdio filesystem
server limited to the workspace folder, and a remote HTTP server at
https://mcp.example.com/mcp that needs a Bearer token. Ask for the token
with an input so it is never stored in the file.

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

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

توجد نماذج محادثة وبرمجة أخرى على المنصة تؤدي المهمة نفسها، فجرّب بعضها واحتفظ بالنموذج الذي يلتزم أفضل بموجّه النظام الخاص بك:

أنشئ صورك الخاصة مع Picasso IA

يستحق إعداد MCP العامل توثيقًا يقرؤه الناس فعلًا. ملف README بصورة رئيسية واضحة، أو مخطط يوضح كيف تتصل خوادمك، أو صورة مصغرة لدرس قصير يجعل صفحة الإعداد تبدو مكتملة. يستطيع Picasso IA إنتاج كل ذلك.

ابدأ مع Picasso IA Image للحصول على مسودة أولى سريعة، وجرّب GPT Image 2 عندما تحتاج صورتك إلى نص واضح القراءة، واستخدم Picasso IA Image Editor Pro لتعديل صورة تملكها بالفعل. أما للمشاهد الواقعية كالصور الفوتوغرافية، فيستحق Seedream 4.5 تجربة. كما تضم المنصة تحويل النص إلى فيديو ومولّدات أخرى، ويمكنك تصفح كل الخيارات في صفحة كل النماذج.

اكتب أمرًا نصيًا واحدًا، وولّد عدة تنويعات، واختر التنويعة التي تناسب صفحتك، وضعها في وثائقك. أفضل طريقة لمعرفة ما ينجح في مشروعك هي تجربته، لذا افتح Picasso IA، واكتب مشهدًا تريد رؤيته، وأنشئ أول صورة لك اليوم.