@modudraft/mcp 0.21.0 → 0.22.1

package/README.md

@@ -96,6 +96,15 @@ Every MCP tool is listed by default. If that is too much context for your client
 - `load_toolset(name)` adds a group at runtime and sends a tools-changed notification. If your client doesn't refresh tools after `load_toolset`, set `MODUDRAFT_TOOLSETS` instead.
 - Calling any tool by name always works, even when it isn't listed: the server loads its group and runs it.
 
+### Upgrading to 0.22.1
+
+- `write_config` now adds the `$schema` line to `modudraft.json`, so editors validate and autocomplete the file.
+- A diagram that was imported on the web is only adopted by a Structurizr re-import when the workspace matches (the same entry file and most element names). Otherwise the web-imported items are left as they are, the workspace is imported beside them in the same diagram, and a warning says so.
+
+### Upgrading to 0.22.0
+
+- Adds Structurizr import: `import_file` and `import_directory` read a `workspace.dsl` (with its `!include`d files) or a Structurizr `workspace.json`, and re-importing updates the diagram in place. `sync_project`, `watch_project` and the `modudraft-mcp check` command also compare a `workspace.dsl` source. Nothing is removed.
+
 ### Upgrading to 0.21.0
 
 - Architecture diagrams have levels: a component can contain other items. New optional inputs: `inside` (a component id or label; empty or `null` means the top level) on `add_node`, `bulk_add_nodes`, `add_boundary`, `add_note` and `update_node`; `c4_kind` and `description` on `update_node`; `inside: "delete" | "lift"` on `delete_node`; `level` on `render_diagram_text`, `layout_diagram`, `export_mermaid`, `export_plantuml`, `export_drawio` and `export_to_file`.
@@ -104,6 +113,7 @@ Every MCP tool is listed by default. If that is too much context for your client
 - `get_diagram` returns a `levels` field (for example `Top: 2 items; Orders: 1`). `render_diagram_text` and the exports show the top level unless you pass `level`; items outside the level appear marked as outside, with arrows to them shown as implied.
 - `validate_diagram` reports broken levels as errors and C4 rule breaks as warnings.
 - Diagrams without levels behave as before. Deploy the web app and API first: a level written by this version needs a web app that reads file format 2.11.0.
+- More on levels and the C4 look: https://modudraft.com/docs/c4
 
 ### Upgrading to 0.20.0
 
@@ -282,7 +292,7 @@ The old `request_body`, `request_format`, `body`, `body_format` and top-level `r
 | `import_file` | Import a file into a diagram - auto-detects format. Re-importing the same file updates it in place (see [Re-import](#re-import)) |
 
 **Supported import formats:**
-- **Architecture:** `docker-compose.yml` → nodes + edges
+- **Architecture:** `docker-compose.yml` → nodes + edges; a Structurizr workspace (`workspace.dsl` with its `!include`d files, or `workspace.json`) → levels, groups, relationships and dynamic views as sequences, with deployment on the cloud tab and docs/ADRs in the notes
 - **Cloud:** Kubernetes YAML, Terraform `.tf`, AWS CloudFormation YAML/JSON
 - **DB schema:** SQL DDL, `schema.prisma`, DBML, `schema.rb` (Rails), TypeORM entities, SQLAlchemy models, dbt `schema.yml`
 - **API:** OpenAPI 2.x/3.x, GraphQL SDL, Protocol Buffers `.proto`, Postman collection, Insomnia export v4, AsyncAPI
@@ -413,6 +423,18 @@ A node with an explicit `x`/`y` (`add_node`, `add_boundary`) is pinned. Nodes th
 
 Items from other files are never touched. Existing items without import history whose name matches an item in the file (a table, endpoint, service or resource of the same name) are adopted and from then on kept in sync with the file; the response lists them under `adopted` in `changes`. Other items you made by hand are never touched. `import_directory` reports each file's `changes`, `also_removed` and `warnings`, plus a `removed` total. A parse that finds nothing is refused unless you pass `allow_empty: true`, so an empty or broken file cannot wipe a diagram. `target_tab` accepts `db-schema`, `api`, `cloud` or `network`. Terraform dependencies are recorded as `config.dependsOn`.
 
+**Structurizr workspaces.** Items are matched by their Structurizr canonical names (for example `Container://Shop.Web Store`), so matched items keep their id, position and pin. A few things follow from that:
+
+- Renaming a software system or container in the DSL gives it, and everything inside it, a new name: they are imported again as new items (the positions inside it start fresh) and the old ones are removed. Items you made by hand inside a removed system or container are moved up a level, not deleted.
+- A `runsOn` link stays when you remove the `containerInstance` that set it, as long as its deployment node still exists. Links you set by hand are kept too.
+- The workspace's documentation and ADRs go into one marked block of the notes per workspace, replaced on re-import. Changes to docs, ADRs or dynamic views only are not reported as drift by `sync_project` or the CI check (applying a sync still updates the notes block and the sequences).
+- A colour the workspace sets wins on re-import; a colour you set by hand on an item the workspace gives no colour stays, and is not drift.
+- A diagram made by importing the workspace on the web is picked up by the first `import_file` of the same workspace: its items are matched, not added a second time.
+- Only the files the workspace uses (`!include`, `!docs` and `!adrs` targets, and the `.json` files beside it, checked for a layout) are read from its folder, up to 50 MB in all; `node_modules` and `.git` are skipped. A Structurizr `workspace.json` may be up to 20 MB; other entry files are limited to 2 MB, and the files a workspace includes count toward the 50 MB total.
+- `watch_project` / `check_project_drift` track the workspace file itself (`workspace.dsl`), not the files it includes. After editing an included file, run `sync_project` (or the CI check), which reads the whole workspace, to see the change.
+
+More on importing a workspace: https://modudraft.com/docs/structurizr
+
 ## Project drift
 
 `check_project_drift` only reports; it no longer consumes the drift. Drift stays reported until you pass `acknowledge: true`. Re-importing a modified file with `import_file` also clears it for that file; a new file stays reported as added until you acknowledge. A truncated scan (too many files) is flagged in the result.
@@ -423,7 +445,7 @@ Items from other files are never touched. Existing items without import history
 
 **CI drift check.** The same engine powers `npx @modudraft/mcp check` and the `modudraft/drift-check` GitHub Action, which compare docker-compose, Kubernetes, Terraform, OpenAPI, Prisma, SQL and more with a diagram on every pull request (exit `0` in sync, `1` drift with `--on-drift fail`, `2` error). A file that fails to parse is reported and removes nothing. Supported files, `modudraft.json`, flags, keys and example workflows: https://modudraft.com/docs/ci
 
-**`sync_project`** inputs: `diagram_id`, `dir`, `files`, `dry_run` (default `true`), `remove_missing`, `write_config`. With `dry_run: false` it writes once through the normal save path, so the change is recorded in version history (it may merge with an earlier version from the same key within 10 minutes). Applying is refused when the sources came only from a scan. `write_config: true` writes `modudraft.json` (also during a preview), keeps existing entries, writes `{ path, node }` when a node was used, and skips files that errored. With no diagram id and no config the tool answers: "Pass diagram_id, or add modudraft.json (sync_project with write_config: true)".
+**`sync_project`** inputs: `diagram_id`, `dir`, `files`, `dry_run` (default `true`), `remove_missing`, `write_config`. With `dry_run: false` it writes once through the normal save path, so the change is recorded in version history (it may merge with an earlier version from the same key within 10 minutes). Applying is refused when the sources came only from a scan. `write_config: true` writes `modudraft.json` (also during a preview), keeps existing entries, writes `{ path, node }` when a node was used, and skips files that errored. It also adds `"$schema": "https://modudraft.com/schema/modudraft.json"` as the first key (kept if already present), which gives autocomplete and validation in VS Code and JetBrains. With no diagram id and no config the tool answers: "Pass diagram_id, or add modudraft.json (sync_project with write_config: true)".
 
 ## Workspaces and local files