@dineug/erd-editor-mcp 1.0.0 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +85 -172
- package/dist/erd-editor-mcp.js +70 -68
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -3,29 +3,27 @@
|
|
|
3
3
|
> An MCP server that lets a coding agent edit [ERD Editor](https://github.com/dineug/erd-editor)
|
|
4
4
|
> diagrams, live in VS Code, Obsidian or a JetBrains IDE, or straight on disk
|
|
5
5
|
|
|
6
|
-
Claude Code, Codex
|
|
7
|
-
|
|
8
|
-
ERD document (an `.erd.json` file, or an `.erd` file in an Obsidian vault): add a table, rename a
|
|
9
|
-
column, relate two tables, import a DDL dump, read the schema back as SQL. When VS Code with the
|
|
10
|
-
[ERD Editor extension](https://marketplace.visualstudio.com/items?itemName=dineug.vuerd-vscode),
|
|
11
|
-
Obsidian with the [ERD Editor plugin](https://community.obsidian.md/plugins/erd-editor) or an
|
|
12
|
-
IntelliJ-based IDE with the
|
|
13
|
-
[ERD Editor plugin](https://plugins.jetbrains.com/plugin/23594-erd-editor) has the document open,
|
|
14
|
-
or has open the folder, vault or project that holds it, the agent joins the editor as a
|
|
15
|
-
collaborator: every edit shows up on the canvas as it happens, with the agent's focus on the cell
|
|
16
|
-
it is editing. With no editor around, the same tools edit the file itself.
|
|
6
|
+
Ask Claude Code, Codex or any [Model Context Protocol](https://modelcontextprotocol.io) client to
|
|
7
|
+
change your schema, and watch the change land on the canvas.
|
|
17
8
|
|
|
18
9
|

|
|
19
10
|
|
|
20
|
-
|
|
11
|
+
- **One tool per edit** — add a table, rename a column, relate two tables, import a DDL dump, read
|
|
12
|
+
the schema back as SQL
|
|
13
|
+
- **Live in your editor** — when
|
|
14
|
+
[VS Code](https://marketplace.visualstudio.com/items?itemName=dineug.vuerd-vscode),
|
|
15
|
+
[Obsidian](https://community.obsidian.md/plugins/erd-editor) or a
|
|
16
|
+
[JetBrains IDE](https://plugins.jetbrains.com/plugin/23594-erd-editor) holds the diagram, the
|
|
17
|
+
agent joins as one more collaborator, and its undo reverts only its own edits
|
|
18
|
+
- **Headless on disk** — with no editor around, the same tools edit the file itself
|
|
19
|
+
- **Large schemas** — paged, searchable reads, and DDL of just the tables the agent needs
|
|
20
|
+
- **Self-contained** — one file with no runtime dependencies
|
|
21
21
|
|
|
22
22
|
## Install
|
|
23
23
|
|
|
24
|
-
The server needs Node.js 22.12 or later
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
Keep ERD Editor and the MCP server up to date together. When one speaks an older hub protocol than
|
|
28
|
-
the other, the server refuses to connect and says which one to update.
|
|
24
|
+
The server needs Node.js 22.12 or later; `npx` downloads it the first time the agent starts it.
|
|
25
|
+
Keep ERD Editor and the server up to date together: when one speaks an older hub protocol than the
|
|
26
|
+
other, the server refuses to connect and says which one to update.
|
|
29
27
|
|
|
30
28
|
### Claude Code
|
|
31
29
|
|
|
@@ -37,7 +35,13 @@ claude mcp add --transport stdio erd-editor -- npx -y @dineug/erd-editor-mcp
|
|
|
37
35
|
|
|
38
36
|
### Codex
|
|
39
37
|
|
|
40
|
-
|
|
38
|
+
Run once; the Codex CLI, app and IDE extension share the setting:
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
codex mcp add erd-editor -- npx -y @dineug/erd-editor-mcp
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Or add it to `~/.codex/config.toml`, or to `.codex/config.toml` in a trusted project:
|
|
41
45
|
|
|
42
46
|
```toml
|
|
43
47
|
[mcp_servers.erd-editor]
|
|
@@ -47,186 +51,95 @@ args = ["-y", "@dineug/erd-editor-mcp"]
|
|
|
47
51
|
|
|
48
52
|
### Any other MCP client
|
|
49
53
|
|
|
50
|
-
Run `npx -y @dineug/erd-editor-mcp` as a stdio server
|
|
54
|
+
Run `npx -y @dineug/erd-editor-mcp` as a stdio server, started in your project folder: it resolves
|
|
51
55
|
relative document paths against its working directory.
|
|
52
56
|
|
|
53
57
|
## Live and headless
|
|
54
58
|
|
|
55
|
-
For
|
|
56
|
-
|
|
57
|
-
the ERD Editor plugin, or an IntelliJ-based IDE with the ERD Editor plugin, which keeps one lock for
|
|
58
|
-
all its open projects.
|
|
59
|
+
For each call, the server looks in `~/.erd-editor/ide/` for an editor that holds the document: one
|
|
60
|
+
that has it open, or whose workspace, vault or project contains it.
|
|
59
61
|
|
|
60
62
|
| What it finds | What an edit does |
|
|
61
63
|
| --- | --- |
|
|
62
|
-
|
|
|
63
|
-
| No editor | **Headless.**
|
|
64
|
-
| An editor
|
|
65
|
-
| An editor
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
- **
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
off for the whole IDE, and the IDE still guards the files of its projects from headless writes. A
|
|
83
|
-
project you have not trusted, opened in safe mode, is kept the same way: agents read its diagrams
|
|
84
|
-
but never change them.
|
|
85
|
-
|
|
86
|
-
The server never falls back to the file on its own while an editor holds a document: if the
|
|
87
|
-
connection drops, it reconnects. Only once that editor has exited, or has closed the document and
|
|
88
|
-
stopped serving it, as VS Code does when you close a document from outside its workspace, Obsidian
|
|
89
|
-
when the plugin is disabled and a JetBrains IDE when a project closes or the plugin is disabled,
|
|
90
|
-
does it edit the file, and it says so in the result.
|
|
91
|
-
|
|
92
|
-
An editor in a Flatpak sandbox is the exception. Obsidian installed from Flathub and a JetBrains IDE
|
|
93
|
-
installed as a Flatpak run in a sandbox the server cannot reach, so they run no hub and write no
|
|
94
|
-
lock. There the agent edits the files on disk, even while a diagram is open, unless an editor
|
|
95
|
-
outside the sandbox, such as a VS Code window, has the document or a folder that holds it open.
|
|
96
|
-
Obsidian picks the change up as it picks up any change made outside it, and an edit of yours it has
|
|
97
|
-
not saved yet gives way to the agent's. A JetBrains IDE does not reload a diagram changed on disk
|
|
98
|
-
while it is open, and your next edit in it would overwrite the agent's, so close the diagram first.
|
|
64
|
+
| An editor that holds the document | **Live.** The change shows on the canvas at once. VS Code keeps it unsaved until you, Auto Save or `erd_save` save it; Obsidian and JetBrains IDEs save it as they save your own edits. |
|
|
65
|
+
| No editor | **Headless.** The change is written to the file. |
|
|
66
|
+
| An editor with its connection off, or an untrusted workspace or project | **Refused**, since the editor's next save would overwrite the change. Reads still come from disk. |
|
|
67
|
+
| An editor on another hub protocol | **Refused**, naming the side to update. |
|
|
68
|
+
|
|
69
|
+
The connection is on by default in each editor:
|
|
70
|
+
|
|
71
|
+
- **VS Code** — a hub per window, in trusted workspaces, off with `dineug.erd-editor.agentHub.enabled`.
|
|
72
|
+
The extension starts once the folder holds an `.erd.json` file or you open a diagram.
|
|
73
|
+
- **Obsidian** — a hub per vault window, off with **Settings → ERD Editor → Coding agents**.
|
|
74
|
+
- **JetBrains IDEs** — one hub for every open project, off with
|
|
75
|
+
**Settings | Tools | ERD Editor → Coding agents**.
|
|
76
|
+
|
|
77
|
+
Obsidian from Flathub and a JetBrains IDE installed as a Flatpak run no hub, so there the agent
|
|
78
|
+
edits the file on disk even while the diagram is open. Close it first in a JetBrains IDE, which
|
|
79
|
+
does not reload it and would overwrite the agent's change with your next edit; in Obsidian, an edit
|
|
80
|
+
you have not saved yet gives way to the agent's.
|
|
81
|
+
|
|
82
|
+
Windows paths, Flatpak sandboxes, reconnecting and conflicts on disk are in
|
|
83
|
+
[Live and Headless](https://docs.erd-editor.io/docs/mcp/live-and-headless).
|
|
99
84
|
|
|
100
85
|
## Documents
|
|
101
86
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
`CON.erd.json`, or a name ending in a dot or a space. It leaves such files and folders out when it
|
|
113
|
-
lists documents from disk too. Use `-` in place of `:`.
|
|
114
|
-
|
|
115
|
-
An agent finds ids with `erd_list`, which lists the settings, the counts and the tables by id, each
|
|
116
|
-
with its position and its size on the canvas (the width approximate, the height exact) and the table
|
|
117
|
-
group it is in, with their relationships and indexes, then the table groups and the memos. It reads
|
|
118
|
-
columns and other details with `erd_get`, then passes those ids to the edit tools. `erd_read`
|
|
119
|
-
answers the whole document at once: the `snapshot` format lists every entity with its id, the `sql`
|
|
120
|
-
format generates DDL for any of the eight supported databases, and the `json` format is the whole
|
|
121
|
-
document in the form a save writes to the file, with any unsaved live edits and a v2 document in its
|
|
122
|
-
v3 form. Its `scripts` format answers the document's before and after scripts alone, however large
|
|
123
|
-
the schema. Have the agent edit through these tools rather than write the JSON file itself.
|
|
124
|
-
|
|
125
|
-
The `sql` format writes plain `CREATE TABLE` statements and no header by default. Its `statements`
|
|
126
|
-
argument asks for `ifNotExists` (`CREATE TABLE IF NOT EXISTS` on MySQL, MariaDB, PostgreSQL, SQLite
|
|
127
|
-
and Databricks) or `recreate` (the tables dropped first, `CREATE OR REPLACE TABLE` on Snowflake),
|
|
128
|
-
and its `header` for `use`, which selects the database or schema the document's database name
|
|
129
|
-
gives, or `createAndUse`, which creates it first. As the options of the editor's Schema SQL tab do,
|
|
130
|
-
`ifNotExists` writes plain `CREATE TABLE` on the other databases, `createAndUse` writes `use` on
|
|
131
|
-
Oracle, which has `use` alone, `use` writes no header on PostgreSQL, which has `createAndUse` alone,
|
|
132
|
-
and SQLite writes no header; no database writes one while the name is empty or not a plain
|
|
133
|
-
identifier. The DDL of the whole document carries the document's before and after scripts; the DDL
|
|
134
|
-
of some tables carries none.
|
|
135
|
-
|
|
136
|
-
Schemas of hundreds or thousands of tables work too. A read answers at most 40,000 characters, under
|
|
137
|
-
the point where Claude Code sets a tool result aside in a file; only `erd_get` goes past it, when
|
|
138
|
-
the first entity it answers is larger on its own, which it gives whole with a note. `erd_list`
|
|
139
|
-
answers a page of 100 tables and says where the next one starts; its `query` finds tables by a word
|
|
140
|
-
in a table or column name or comment, and `namesOnly` lists the table names alone, 2,000 short names
|
|
141
|
-
in one answer. `erd_get` and `erd_read` take `tableNames` as well as ids, and `erd_read` takes
|
|
142
|
-
`groupNames`, the tables of those table groups, so an agent asked for a SQL query on a large schema
|
|
143
|
-
reads the DDL of just the tables it needs. `erd_read` refuses a read too large for one answer and
|
|
144
|
-
says how to narrow it. `erd_get` answers the entities that fit and lists the ids it had no room for
|
|
145
|
-
under `notReturned`, to ask for again, and refuses only a request for more ids than one answer can
|
|
146
|
-
name.
|
|
87
|
+
- `erd_open_document` with `create` makes a missing file, adding `.erd.json` to a name with no
|
|
88
|
+
extension. In an Obsidian vault, name it `.erd`, which the file explorer lists.
|
|
89
|
+
- `erd_list` lists the tables by id, 100 to a page, then the table groups, memos and dictionary
|
|
90
|
+
rows, and finds tables by name, logical name or comment with `query`. `erd_get` reads entities by
|
|
91
|
+
id or table name.
|
|
92
|
+
- `erd_read` answers the whole document as a `snapshot`, as `sql` for any of the eight databases,
|
|
93
|
+
as `json` or as its `scripts`, or the DDL of just the tables or table groups it names.
|
|
94
|
+
- A read answers at most 40,000 characters, or one larger entity whole: `erd_read` says how to
|
|
95
|
+
narrow a larger read, and `erd_get` lists the ids it had no room for.
|
|
96
|
+
- Have the agent edit through the tools rather than write the JSON file itself.
|
|
147
97
|
|
|
148
98
|
## Tools
|
|
149
99
|
|
|
150
100
|
| Group | Tools |
|
|
151
101
|
| --- | --- |
|
|
152
|
-
| Session | `erd_list_documents`, `erd_open_document`, `erd_list`, `erd_get`, `erd_read`, `erd_save`, `erd_undo`, `erd_redo` |
|
|
153
|
-
| Tables | `erd_add_table`, `erd_remove_table`, `erd_change_table_name`, `erd_change_table_comment`, `erd_change_table_color`, `erd_move_table`, `erd_move_tables`, `erd_sort_tables` |
|
|
154
|
-
| Columns | `erd_add_column`, `erd_remove_columns`, `erd_change_column_name`, `erd_change_column_data_type`, `erd_change_column_default`, `erd_change_column_comment`, `erd_set_column_primary_key`, `erd_set_column_unique`, `erd_set_column_not_null`, `erd_set_column_auto_increment`, `erd_move_column` |
|
|
102
|
+
| Session | `erd_list_documents`, `erd_open_document`, `erd_list`, `erd_get`, `erd_read`, `erd_list_checks`, `erd_save`, `erd_undo`, `erd_redo` |
|
|
103
|
+
| Tables | `erd_add_table`, `erd_remove_table`, `erd_change_table_name`, `erd_change_table_comment`, `erd_set_table_logical_name`, `erd_change_table_color`, `erd_move_table`, `erd_move_tables`, `erd_sort_tables` |
|
|
104
|
+
| Columns | `erd_add_column`, `erd_remove_columns`, `erd_change_column_name`, `erd_change_column_data_type`, `erd_change_column_default`, `erd_change_column_comment`, `erd_set_column_logical_name`, `erd_set_column_domain`, `erd_set_column_primary_key`, `erd_set_column_unique`, `erd_set_column_not_null`, `erd_set_column_auto_increment`, `erd_move_column` |
|
|
155
105
|
| Relationships | `erd_add_relationship`, `erd_link_columns`, `erd_remove_relationship`, `erd_change_relationship_type`, `erd_change_relationship_on_delete`, `erd_change_relationship_on_update` |
|
|
156
106
|
| Indexes | `erd_add_index`, `erd_remove_index`, `erd_change_index_name`, `erd_set_index_unique`, `erd_add_index_column`, `erd_remove_index_column`, `erd_move_index_column`, `erd_set_index_column_order` |
|
|
157
107
|
| Memos | `erd_add_memo`, `erd_remove_memo`, `erd_change_memo_value`, `erd_change_memo_color`, `erd_move_memo`, `erd_resize_memo` |
|
|
158
108
|
| Table groups | `erd_add_table_group`, `erd_remove_table_group`, `erd_change_table_group_name`, `erd_change_table_group_color`, `erd_move_table_group`, `erd_resize_table_group`, `erd_set_table_group` |
|
|
109
|
+
| Dictionaries | `erd_add_word`, `erd_update_word`, `erd_remove_word`, `erd_add_term`, `erd_update_term`, `erd_remove_term`, `erd_add_domain`, `erd_update_domain`, `erd_remove_domain`, `erd_derive_physical_names` |
|
|
159
110
|
| Settings | `erd_set_database`, `erd_set_database_name`, `erd_set_ddl_script` |
|
|
160
111
|
| Import | `erd_import_sql`, `erd_import_graphql`, `erd_import_dbml`, `erd_import_aml`, `erd_import_json` |
|
|
161
112
|
| Batch | `erd_batch` |
|
|
162
113
|
|
|
163
|
-
`erd_batch` runs up to 100
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
plugin released before referential actions ignores them when it serves the document, so update it.
|
|
183
|
-
|
|
184
|
-
A table group is a box drawn behind its tables, with the name and color it is given, and a table is
|
|
185
|
-
in one group at most. `erd_add_table_group` wraps the tables it is given, or takes a rect and the
|
|
186
|
-
tables in no group whose centre lies inside it, as drawing a group in the editor does.
|
|
187
|
-
`erd_move_table_group` moves a group with its tables, and only `erd_add_table_group`,
|
|
188
|
-
`erd_set_table_group` and `erd_remove_table_group` change which tables a group holds. An ERD Editor
|
|
189
|
-
extension or plugin released before table groups ignores these edits and the groups
|
|
190
|
-
`erd_import_dbml` and `erd_import_json` bring, except that it still moves the tables of a group
|
|
191
|
-
`erd_move_table_group` moves, and drops every group when it saves, so update it.
|
|
192
|
-
|
|
193
|
-
An agent sets the database and its name, the settings of the schema itself, and the Schema SQL
|
|
194
|
-
scripts. What the diagram shows, the column order, the maximum comment width, the relationship data
|
|
195
|
-
type sync, the code generation language, the name cases, the bracket type and the locks that keep
|
|
196
|
-
those last three at their saved values in the file are yours to set in the editor; `erd_list` and
|
|
197
|
-
`erd_read` read them as the file saves them.
|
|
198
|
-
|
|
199
|
-
`erd_set_ddl_script` sets the SQL the document keeps before or after the tables of its Schema SQL,
|
|
200
|
-
such as `CREATE EXTENSION` ahead of them or `GRANT` past them, written into the DDL as is for every
|
|
201
|
-
database (on MSSQL, ended with `GO`), up to 10,000 characters a call. A call replaces the whole
|
|
202
|
-
script, an empty string removes it, and `erd_undo` reverts it. The `erd_read` `scripts` format gives
|
|
203
|
-
both scripts alone, however large the schema, its snapshot gives them too, and its `sql` format of
|
|
204
|
-
the whole document writes them in place. An ERD Editor extension or plugin released before scripts
|
|
205
|
-
neither shows nor keeps them when it serves the document, so update it.
|
|
206
|
-
|
|
207
|
-
Every edit tool takes the document `path`. `erd_set_database`, `erd_set_database_name` and
|
|
208
|
-
`erd_resize_memo` make no undo entry in the editor, nor does an `erd_move_table_group` of under 20
|
|
209
|
-
pixels in all, so `erd_undo` passes over them, inside an `erd_batch` too, and the result says so. An
|
|
210
|
-
`erd_set_column_*`, `erd_set_index_*` or `erd_set_table_group` call that finds the value already set
|
|
211
|
-
sends nothing and makes no entry either, and its result says so.
|
|
212
|
-
|
|
213
|
-
The edit tools and the read tools (`erd_list`, `erd_get`, `erd_read`) refuse an argument they do not
|
|
214
|
-
declare, or one of the wrong type, with a JSON-RPC invalid params error (-32602) before touching the
|
|
215
|
-
document. `erd_batch` does the same for its own arguments and for an operation's `tool`, `as` and
|
|
216
|
-
`args` keys; it checks each operation's own arguments as the batch runs and refuses a bad one with
|
|
217
|
-
`invalidArgs`, naming the operation, before anything is applied. Either way a misspelled argument is
|
|
218
|
-
never silently dropped. The other session tools ignore arguments they do not know.
|
|
114
|
+
- `erd_batch` runs up to 100 edits in order as one, all or none, and one `erd_undo` reverts it. A
|
|
115
|
+
step named with `as` passes the ids it creates to later steps as `$name`, so a table and its
|
|
116
|
+
columns take one call.
|
|
117
|
+
- A logical name set with `erd_set_table_logical_name` or `erd_set_column_logical_name` gives the
|
|
118
|
+
physical name, and a column its domain, from the word, term and domain dictionaries, as in the
|
|
119
|
+
editor; a name set by hand stays while it is not empty. `erd_derive_physical_names` derives the
|
|
120
|
+
names of a column, a table or the whole document again, as the editor's Derive Physical Names
|
|
121
|
+
Again does, after a word or term changed.
|
|
122
|
+
- `erd_list_checks` lists what the dictionaries find, as the Dictionary tab's Checks sheet does:
|
|
123
|
+
forbidden words, words no dictionary lists, synonyms, names two rows share, links to a removed
|
|
124
|
+
domain, physical names other than a term gives and column types other than their domain's, with
|
|
125
|
+
what to use instead where the dictionaries have it.
|
|
126
|
+
- The import tools replace the diagram by default and add to it with `mode: "append"`. The SQL,
|
|
127
|
+
GraphQL, DBML and AML imports keep the dictionaries.
|
|
128
|
+
- The agent sets the database, its name and the Schema SQL scripts; the view and code settings stay
|
|
129
|
+
yours to set in the editor.
|
|
130
|
+
- The edit and read tools refuse an unknown or mistyped argument before the document changes.
|
|
131
|
+
|
|
132
|
+
Every tool with its arguments and results is in [Tools](https://docs.erd-editor.io/docs/mcp/tools).
|
|
219
133
|
|
|
220
134
|
## Documentation
|
|
221
135
|
|
|
222
|
-
- [Introduction](https://docs.erd-editor.io/docs/mcp/introduction) — what an agent can and
|
|
223
|
-
|
|
224
|
-
- [Install](https://docs.erd-editor.io/docs/mcp/installation) —
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
large schema, `erd_batch`, results and refusals
|
|
136
|
+
- [Introduction](https://docs.erd-editor.io/docs/mcp/introduction) — what an agent can do and how it
|
|
137
|
+
works
|
|
138
|
+
- [Install](https://docs.erd-editor.io/docs/mcp/installation) — each client and each editor
|
|
139
|
+
- [Live and Headless](https://docs.erd-editor.io/docs/mcp/live-and-headless) — where an edit lands,
|
|
140
|
+
saving, undo, conflicts
|
|
141
|
+
- [Tools](https://docs.erd-editor.io/docs/mcp/tools) — every tool, paging a large schema, results
|
|
142
|
+
and refusals
|
|
230
143
|
|
|
231
144
|
## Issues
|
|
232
145
|
|