مقدمه

@dineug/erd-editor-mcp یک سرور MCP است که به یک عامل کدنویسی امکان می‌دهد نمودارهای erd-editor را ویرایش کند. Claude Code، Codex و هر کلاینت دیگر Model Context Protocol برای هر عملیات روی سند یک ابزار در اختیار دارند: افزودن یک جدول، تغییر نام یک ستون، ایجاد رابطه میان دو جدول، وارد کردن یک دامپ DDL، بازخوانی طرح‌واره به‌صورت SQL.

وقتی سند در VS Code، Obsidian یا یک IDE از JetBrains در ERD Editor باز است، عامل مانند یک همکار به ویرایشگر می‌پیوندد. هر تغییر همان لحظه که رخ می‌دهد روی بوم نمایان می‌شود، و واگرد عامل فقط ویرایش‌های خودش را برمی‌گرداند. VS Code تغییرات عامل را تا وقتی که عامل یا خودتان ذخیره کنید ذخیره‌نشده نگه می‌دارد، در حالی که Obsidian و یک IDE از 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 یا یک IDE از JetBrains، هر کدام با افزونه یا پلاگین ERD Editor.

• زنده — ویرایشگری سند را در فضای کاری، خزانه یا یکی از پروژه‌های باز خود دارد، یا آن را باز کرده است. سرور به نشست ویرایش آن ویرایشگر می‌پیوندد و ویرایش در ویرایشگر اعمال می‌شود: در VS Code ذخیره‌نشده، و در Obsidian و یک IDE از JetBrains ذخیره‌شده، همان‌طور که ویرایش‌های خودتان ذخیره می‌شوند.
• بدون رابط کاربری — هیچ ویرایشگری در کار نیست. سرور فایل را بارگذاری می‌کند، ویرایش را اعمال می‌کند و فایل را دوباره می‌نویسد.
• ردشده — ویرایشگری سند را در اختیار دارد اما هابش خاموش است. سرور از روی دیسک می‌خواند اما هیچ چیز نمی‌نویسد، زیرا ویرایشگر باز ممکن است در ذخیرهٔ بعدی خود فایل را بازنویسی کند. یک IDE از 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 یا بالاتر
یک IDE از JetBrains، برای ویرایش زنده	یک IDE مبتنی بر 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 یا بالاتر، در ویرایشگر و برای عامل یکسان تمام می‌شوند. رنگ، پایگاه داده و ترتیب ستون‌ها در یک جدول یا شاخص استثنا هستند؛ ویرایش‌های هم‌لحظه را ببینید.

بعدی: نصب.