@modudraft/mcp 0.20.0 → 0.21.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,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.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 +159,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 +178,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`)*
@@ -283,20 +293,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