@modudraft/mcp 0.20.0 → 0.22.0

package/README.md

@@ -74,7 +74,7 @@ Without it, all diagram tools work as usual. The file tools fall back to your cl
 
 ## Toolsets
 
-Every MCP tool is listed by default. If that is too much context for your client, set `MODUDRAFT_TOOLSETS` to list fewer: `core` lists a much smaller set, and the core group covers diagram management, nodes and edges, rendering, discovery, org context and `search_diagrams`. The core tools are: `list_diagrams`, `create_diagram`, `get_diagram`, `rename_diagram`, `delete_diagram`, `clear_diagram`, `layout_diagram`, `get_share_link`, `add_node`, `get_node`, `update_node`, `delete_node`, `add_edge`, `update_edge`, `delete_edge`, `add_boundary`, `add_note`, `render_diagram_text`, `list_archetypes`, `list_tools`, `list_protocols`, `get_node_schema`, `get_org_context`, `refresh_org_context`, `search_diagrams`.
+Every MCP tool is listed by default. If that is too much context for your client, set `MODUDRAFT_TOOLSETS` to list fewer: `core` lists a much smaller set, and the core group covers diagram management, nodes and edges, rendering, discovery, org context and `search_diagrams`. The core tools are: `list_diagrams`, `create_diagram`, `get_diagram`, `rename_diagram`, `delete_diagram`, `clear_diagram`, `layout_diagram`, `get_share_link`, `add_node`, `get_node`, `update_node`, `delete_node`, `add_edge`, `update_edge`, `delete_edge`, `add_boundary`, `add_note`, `move_to_level`, `render_diagram_text`, `list_archetypes`, `list_tools`, `list_protocols`, `get_node_schema`, `get_org_context`, `refresh_org_context`, `search_diagrams`.
 
 | Toolset | Purpose | Tools |
 |---|---|---|
@@ -96,6 +96,19 @@ 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.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`.
+- New tool `move_to_level` (core) moves components into another component or back to the top level.
+- `delete_node` now asks before deleting a component that has items inside: pass `inside: "delete"` to delete them too or `inside: "lift"` to move them up one level.
+- `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.
+
 ### Upgrading to 0.20.0
 
 - Adds the `sync_project` tool and the `modudraft-mcp check` command. Nothing is removed. See [Repo sync and CI drift check](#repo-sync-and-ci-drift-check).
@@ -150,7 +163,7 @@ Besides tools, the server offers MCP resources and prompts, for clients that sup
 |---|---|
 | `list_diagrams` | List your diagrams from every workspace you belong to |
 | `create_diagram` | Create a new diagram (optional `workspace_id`) |
-| `get_diagram` | Get full diagram state + missing-metadata hints. Large diagrams are paged: pass `tab_id`, `offset` and `limit` to read one tab in slices |
+| `get_diagram` | Get full diagram state + missing-metadata hints, plus a `levels` summary (items per level). Large diagrams are paged: pass `tab_id`, `offset` and `limit` to read one tab in slices |
 | `delete_diagram` | Move diagram to Bin |
 | `clear_diagram` | Remove all content from a diagram |
 | `layout_diagram` | Auto-arrange the architecture tab now, with the same layout as the editor's Tidy button (LR/TB/RL/BT); boundaries are refitted around their nodes. Pinned nodes keep their place; pass `include_pinned: true` to lay out everything and clear all pins |
@@ -169,6 +182,7 @@ Besides tools, the server offers MCP resources and prompts, for clients that sup
 | `delete_edge` | Remove a connection |
 | `add_boundary` | Add a grouping boundary box |
 | `add_note` | Add a sticky note annotation |
+| `move_to_level` | Move items (`items`: ids, or labels for components) into another component (`inside`: id or label) or back to the top level (`inside: null`); refused when it would put a component inside itself |
 
 ### Node metadata
 *(toolset: `modeling`, except `get_node_schema`, which is in `core`)*
@@ -272,7 +286,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
@@ -283,20 +297,20 @@ The old `request_body`, `request_format`, `body`, `body_format` and top-level `r
 
 | Tool | Description |
 |---|---|
-| `export_mermaid` | Export as Mermaid flowchart or ER diagram (paste into GitHub Markdown) |
-| `render_diagram_text` | Draw the architecture, sequence, DB schema (ER), cloud, network or data-flow tab as plain-text line art, the whole tab or a part of it (see [Viewing diagrams as text](#viewing-diagrams-as-text)) |
-| `export_plantuml` | Export as PlantUML component diagram |
-| `export_drawio` | Export as draw.io / diagrams.net XML |
+| `export_mermaid` | Export as Mermaid flowchart or ER diagram (paste into GitHub Markdown). `level` exports one level of the architecture |
+| `render_diagram_text` | Draw the architecture (`level` shows one level; outside items are marked "(outside)"), sequence, DB schema (ER), cloud, network or data-flow tab as plain-text line art, the whole tab or a part of it (see [Viewing diagrams as text](#viewing-diagrams-as-text)) |
+| `export_plantuml` | Export as PlantUML component diagram. `level` exports one level |
+| `export_drawio` | Export as draw.io / diagrams.net XML. `level` exports one level |
 | `export_terraform` | Generate Terraform resource stubs from the cloud tab |
 | `export_k8s_yaml` | Generate Kubernetes YAML manifests from the cloud tab |
-| `export_to_file` | Write any export format directly to a local file |
+| `export_to_file` | Write any export format directly to a local file (`level` picks the architecture level for mermaid, plantuml and drawio) |
 
 ### Validation & diff
 *(toolset: `analysis`)*
 
 | Tool | Description |
 |---|---|
-| `validate_diagram` | Check a diagram for issues: dangling edges, orphaned nodes, FK integrity, missing PKs, duplicate routes, etc. |
+| `validate_diagram` | Check a diagram for issues: dangling edges, orphaned nodes, FK integrity, missing PKs, duplicate routes, broken levels (errors) and C4 rule breaks (warnings), etc. |
 | `diff_diagram` | Compare two diagrams and return a structured list of what changed (added/removed/modified) |
 
 ### Cross-diagram intelligence
@@ -403,6 +417,16 @@ 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 files: 2 MB).
+- `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.
+
 ## 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.