مقدمة

@dineug/erd-editor-mcp خادم MCP يتيح لوكيل برمجة تحرير مخططات erd-editor. يحصل Claude Code وCodex وأي عميل آخر لبروتوكول Model Context Protocol على أداة واحدة لكل عملية تُجرى على المستند: إضافة جدول، وإعادة تسمية عمود، وربط جدولين بعلاقة، واستيراد ملف تفريغ DDL، وقراءة المخطط بصيغة SQL.

عندما يكون المستند مفتوحًا في ERD Editor داخل VS Code أو Obsidian أو بيئة تطوير JetBrains، ينضم الوكيل إلى المحرر كما ينضم إليه أي متعاون. يظهر كل تغيير على لوحة الرسم لحظة حدوثه، ولا يُلغي تراجع الوكيل إلا تعديلاته هو. يُبقي VS Code تغييرات الوكيل غير محفوظة إلى أن يحفظها الوكيل أو تحفظها أنت، بينما يحفظها Obsidian وبيئة تطوير JetBrains كما يحفظان تغييراتك. وحين لا يكون المستند لدى أي محرر، تحرر الأدوات نفسها الملف ذاته.

ما يمكن للوكيل فعله

• بناء مخطط أو تغييره عبر المحادثة: الجداول، والأعمدة وكل خيار من خيارات العمود، والعلاقات مع تعدديتها وإجراءات ON DELETE وON UPDATE الخاصة بها، والفهارس، والملاحظات، والألوان، والمواضع على لوحة الرسم. راجع العلاقات.
• جمع الجداول في مجموعات الجداول: إضافة مجموعة حول الجداول التي يسمّيها أو فوق منطقة من لوحة الرسم، ثم إعادة تسميتها، وتلوينها، ونقلها مع جداولها، وتغيير حجمها، وإدخال الجداول إليها أو إخراجها منها، أو إزالتها، فتبقى جداولها حيث هي. راجع مجموعات الجداول.
• تسمية الجداول والأعمدة من كلمات علامة تبويب القاموس في المحرر ومصطلحاتها، وربط الأعمدة بمجالاتها، التي تعطيها أنواع بياناتها. فهو يضبط الأسماء المنطقية للجداول والأعمدة، وتشتق القواميس منها الأسماء المادية كما تفعل في المحرر، غير أن الاسم المادي المكتوب يدويًا يبقى ما لم يكن فارغًا. ويضيف المجالات والكلمات والمصطلحات ويغيّرها ويزيلها، وبعد تغيّر كلمة أو مصطلح، يعيد اشتقاق الأسماء المادية لعمود واحد أو جدول واحد أو المستند كله. ويسرد ما ترصده الورقة Checks في علامة التبويب: الكلمات المحظورة وغير المسجلة والمرادفة؛ والأسماء التي يشترك فيها صفان من قاموس واحد؛ والروابط بمجال لا يسرده المستند؛ والأسماء المادية التي تختلف عن الاسم الذي يعطيه مصطلحها؛ والأعمدة التي يختلف نوع بياناتها عن نوع بيانات مجالها. راجع القواميس وفحوصات القاموس.
• استبدال المستند بمخطط قاعدة بيانات مُحلَّل من SQL DDL أو GraphQL SDL أو DBML أو AML، أو بمستند .erd.json آخر. أو إضافة ذلك المخطط أو المستند أسفل المخطط الحالي مع الإبقاء على كل ما فيه بالفعل، كما يفعل Import and Add في المحرر. يصل TableGroup في DBML بوصفه مجموعة جداول في الحالتين. ومخطط قاعدة البيانات الذي يستبدل المستند يُبقي قواميس المستند، والمستند الذي يستبدله يجلب قواميسه الخاصة، والإضافة لا تجلب أيًّا منها. راجع الاستيراد.
• قراءة المخطط، مع أسمائه المنطقية وصفوف قواميسه، في صورة قائمة من المعرّفات، أو كيانات كاملة، أو نص .erd.json كما يكتبه الحفظ. أو قراءته بصيغة DDL لأيٍّ من قواعد البيانات الثماني، مع الخيارين Statements وHeader في علامة تبويب مخطط SQL ومفتاح التبديل Write logical names into empty comments فيها. وفي مخطط يضم آلاف الجداول، يقرأ صفحة واحدة، أو بضعة جداول، أو جداول بضع مجموعات جداول في كل مرة. راجع قراءة مستند.
• ضبط قاعدة البيانات، واسم قاعدة البيانات، والسكربتات التي تُكتب قبل الجداول وبعدها في مخطط SQL، مثل CREATE EXTENSION قبلها أو GRANT بعدها. تُرجع الأداة erd_read السكربتات وحدها، أو ضمن DDL المستند كله. راجع الإعدادات.
• تشغيل عدة تعديلات بوصفها تعديلًا واحدًا، تُطبَّق كلها أو لا يُطبَّق أيٌّ منها، ويُلغيها تراجع واحد. راجع erd_batch.
• التراجع عن تعديلاته هو وإعادتها، لا تعديلاتك أبدًا.

ما لا يفعله:

• تغيير مستوى التكبير، أو التمرير، أو التبديل بين علامات التبويب. فهذه تخص كل مشاهد على حدة، لذا لا تفعلها أي أداة. ومع ذلك، ينقل الاستيراد الذي يستبدل المستند العرض، حتى عندما يكون Viewport مقفلًا، كما يفعل Import في المحرر: يعيده إلى بداية لوحة الرسم بمستوى تكبير 100%، أو، مع erd_import_json، ينقله إلى عرض المستند الذي يحمّله، وإلى علامة تبويبه أيضًا ما لم يقفل ذلك المستند Canvas Type. راجع الاستيراد.
• تبديل عرض الأسماء بين Physical Names وLogical Names وBoth Names. فهو يخص كل مشاهد على حدة ما دام قفله مفعّلًا، كما يكون في مخطط جديد، ويعود إليك اختياره في المحرر بعد تعطيل القفل، لذا لا تفعله أي أداة. ويقرأ الوكيل الأسماء المنطقية ويكتبها أيًّا كان العرض. والأداة erd_import_json حين تستبدل المستند لا تجلب عرض الأسماء الخاص بالمستند الذي تحمّله إلا إذا كان القفل Name View معطّلًا في ذلك المستند.
• تغيير View Option، أو لغة منشئ التعليمات البرمجية وأنماط التسمية فيه، أو نوع علامات الاقتباس، أو Relationship DataType Sync وMaximum comment width وColumn Order في علامة تبويب الإعدادات. فضبط هذه متروك لك في المحرر، ويقرؤها الوكيل كما يحفظها الملف.
• تفعيل قفل أو تعطيله. الأداة erd_import_json وحدها، حين تستبدل المستند كله، تغيّر الأقفال أو الإعدادات المذكورة أعلاه إلى أقفال المستند الذي تحمّله وإعداداته. والمستند الذي ليس فيه الحقل lockSettings، مثل ملف حفظته إضافة VS Code قبل الإصدار 4.0.0 أو مكوّن Obsidian أو JetBrains الإضافي قبل الإصدار 1.0.0، يفعّل كل الأقفال. والتراجع عن أي استيراد استبدل المستند يعيد الإعدادات والأقفال التي كانت للمستند من قبل.
• إعادة تعيين علاقة إلى أعمدة أخرى، كما يفعل Map Columns. بدلًا من ذلك، يزيل الوكيل العلاقة، فتبقى أعمدة مفتاحها الخارجي في مكانها، ويربط الأعمدة التي يريدها باستخدام erd_link_columns، ضمن دفعة erd_batch واحدة يُلغيها تراجع واحد.
• استيراد قاموس أو تصديره بصيغة CSV، أو فرز ورقة، أو إدراج صفوف فوق صف أو تحته، كما تفعل علامة تبويب القاموس. يضيف الوكيل الصفوف ويغيّرها ويزيلها، وكثيرًا منها معًا ضمن دفعة erd_batch واحدة، ويُضاف الصف الجديد في نهاية ورقته.
• تشغيل منشئ التعليمات البرمجية. تُرجع الأداة erd_read نص DDL أو JSON، ويكتب الوكيل التعليمات البرمجية منه بنفسه.

طريقة العمل

الخادم عملية stdio يشغّلها عميل MCP لديك. وفي كل استدعاء، يبحث عن محرر يحتفظ بالمستند: نافذة VS Code، أو نافذة خزنة Obsidian، أو بيئة تطوير JetBrains، وفي كلٍّ منها إضافة ERD Editor أو مكوّنه الإضافي.

• مباشر — المستند موجود لدى محرر في مساحة عمله أو خزنته أو أحد مشاريعه المفتوحة، أو مفتوح فيه. ينضم الخادم إلى جلسة التحرير في ذلك المحرر، ويصل التعديل إلى المحرر: فيبقى غير محفوظ في VS Code، ويُحفظ كما تُحفظ تعديلاتك في Obsidian وبيئة تطوير JetBrains.
• بدون واجهة — لا يوجد محرر. يحمّل الخادم الملف، ويطبّق التعديل، ويعيد كتابة الملف.
• مرفوض — يحتفظ محرر بالمستند لكن محوره معطّل. يقرأ الخادم من القرص لكنه لا يكتب شيئًا، لأن المحرر المفتوح قد يكتب فوق الملف عند حفظه التالي. كما ترفض بيئة تطوير JetBrains التي يكون محورها مفعّلًا تغيير مستند لا تحتفظ به سوى مشاريع لا تثق بها، مع أن الوكيل يظل قادرًا على قراءته. وعندما يكون محور المحرر مفعّلًا لكن تستخدم إضافة ERD Editor فيه أو مكوّنه الإضافي بروتوكول محور مختلفًا عن بروتوكول الخادم، يُرفض كل استدعاء على المستند، بما في ذلك عمليات القراءة، بالرمز protocolMismatch ورسالة تذكر الطرف الذي يجب تحديثه، راجع التحديث.

لمعرفة التفاصيل، راجع الوضع المباشر والوضع بدون واجهة.

المتطلبات

Node.js	الإصدار 22.12 أو أحدث، لتشغيل الخادم
عميل MCP	Claude Code أو Codex أو أي عميل يمكنه تشغيل خادم stdio
VS Code، للتحرير المباشر	الإصدار 1.101.0 أو أحدث، مع إضافة ERD Editor بالإصدار 4.0.0 أو أحدث
Obsidian، للتحرير المباشر	تطبيق سطح المكتب بالإصدار 1.5.7 أو أحدث، مع المكوّن الإضافي ERD Editor بالإصدار 1.0.0 أو أحدث
بيئة تطوير JetBrains، للتحرير المباشر	بيئة تطوير مبنية على IntelliJ بالإصدار 2025.2 أو أحدث، مع المكوّن الإضافي ERD Editor بالإصدار 1.0.0 أو أحدث

يستخدم الخادم بالإصدار 1.0.0 أو أحدث والإصدارات المذكورة أعلاه بروتوكول المحور 2. وتستخدم الإصدارات السابقة التي تخدم الوكلاء البروتوكول 1: إضافة VS Code من الإصدار 3.0.0 حتى 3.1.0، ومكوّن Obsidian الإضافي بالإصدارين 0.1.0 و0.2.0، ومكوّن JetBrains الإضافي بالإصدارين 0.9.0 و0.10.0. ومثل هذا الإصدار والخادم بالإصدار 1.0.0 أو أحدث يرفض كلٌّ منهما الآخر، وكذلك الخادم بإصدار سابق والإصدارات المذكورة أعلاه، راجع التحديث. ولا تحتوي إضافة VS Code قبل الإصدار 3.0.0 أو مكوّن JetBrains الإضافي قبل الإصدار 0.9.0 على محور، لذا لا يرى الخادم أيًّا منهما ويحرر الملف على القرص، حتى المخطط المفتوح في أيٍّ منهما.

تحتاج أدوات الأسماء المنطقية والمجالات والقواميس إلى الخادم بالإصدار 1.1.0 أو أحدث، وحيثما كان المستند مفتوحًا، إلى إضافة VS Code بالإصدار 4.2.0 على الأقل أو مكوّن Obsidian أو JetBrains الإضافي بالإصدار 1.2.0 على الأقل. ومن بين الإصدارات المذكورة أعلاه، فإن الإضافة قبل الإصدار 4.2.0 أو المكوّن الإضافي قبل الإصدار 1.2.0 يظل يتيح للوكيل التحرير المباشر، لأنه يستخدم البروتوكول 2، لكنه يتجاهل الأسماء المنطقية وروابط المجالات وصفوف القواميس التي يكتبها الوكيل، ويستبعدها عند حفظ الملف. والخادم قبل الإصدار 1.1.0، حين يحرر ملفًا على القرص، يعيد كتابته دون أسمائه المنطقية وروابط المجالات وصفوف القواميس، راجع التحديث.

التعديلات التي تجريها أنت والوكيل في اللحظة نفسها على الاسم نفسه أو الحقل نفسه، أو على موضع جدول أو ملاحظة أو مجموعة جداول واحدة أو حجمها، تنتهي إلى النتيجة نفسها في المحرر وعند الوكيل مع الخادم 1.2.0 أو أحدث، وأينما كان المستند مفتوحًا، مع إضافة VS Code بالإصدار 4.3.0 أو أحدث أو مكوّن Obsidian أو JetBrains الإضافي بالإصدار 1.3.0 أو أحدث. واللون وقاعدة البيانات وترتيب الأعمدة في جدول أو فهرس هي الاستثناءات، راجع التعديلات التي تتم في اللحظة نفسها.

التالي: التثبيت.