مقدمة

@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 الخاصة بها، والفهارس، والملاحظات، والألوان، والمواضع على لوحة الرسم. راجع العلاقات.
• جمع الجداول في مجموعات الجداول: إضافة مجموعة حول الجداول التي يسمّيها أو فوق منطقة من لوحة الرسم، ثم إعادة تسميتها، وتلوينها، ونقلها مع جداولها، وتغيير حجمها، وإدخال الجداول إليها أو إخراجها منها، أو إزالتها، فتبقى جداولها حيث هي. راجع مجموعات الجداول.
• استبدال المستند بمخطط قاعدة بيانات مُحلَّل من SQL DDL أو GraphQL SDL أو DBML أو AML، أو بمستند .erd.json آخر. أو إضافة ذلك المخطط أو المستند أسفل المخطط الحالي مع الإبقاء على كل ما فيه بالفعل، كما يفعل Import and Add في المحرر. يصل TableGroup في DBML بوصفه مجموعة جداول في الحالتين. راجع الاستيراد.
• قراءة المخطط في صورة قائمة من المعرّفات، أو كيانات كاملة، أو نص .erd.json كما يكتبه الحفظ، أو DDL لأيٍّ من قواعد البيانات الثماني، مع الخيارين Statements وHeader في علامة تبويب مخطط SQL. وفي مخطط يضم آلاف الجداول، يقرأ صفحة واحدة، أو بضعة جداول، أو جداول بضع مجموعات جداول في كل مرة. راجع قراءة مستند.
• ضبط قاعدة البيانات، واسم قاعدة البيانات، والسكربتات التي تُكتب قبل الجداول وبعدها في مخطط SQL، مثل CREATE EXTENSION قبلها أو GRANT بعدها. تُرجع الأداة erd_read السكربتات وحدها، أو ضمن DDL المستند كله. راجع الإعدادات.
• تشغيل عدة تعديلات بوصفها تعديلًا واحدًا، تُطبَّق كلها أو لا يُطبَّق أيٌّ منها، ويُلغيها تراجع واحد. راجع erd_batch.
• التراجع عن تعديلاته هو وإعادتها، لا تعديلاتك أبدًا.

ما لا يفعله:

• تغيير مستوى التكبير، أو التمرير، أو التبديل بين علامات التبويب. فهذه تخص كل مشاهد على حدة، لذا لا تفعلها أي أداة. ومع ذلك، ينقل الاستيراد الذي يستبدل المستند العرض، حتى عندما يكون Viewport مقفلًا، كما يفعل Import في المحرر: يعيده إلى بداية لوحة الرسم بمستوى تكبير 100%، أو، مع erd_import_json، ينقله إلى عرض المستند الذي يحمّله، وإلى علامة تبويبه أيضًا ما لم يقفل ذلك المستند Canvas Type. راجع الاستيراد.
• تغيير 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 واحدة يُلغيها تراجع واحد.
• تشغيل منشئ التعليمات البرمجية. تُرجع الأداة 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 على محور، لذا لا يرى الخادم أيًّا منهما ويحرر الملف على القرص، حتى المخطط المفتوح في أيٍّ منهما.

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