@modudraft/mcp 0.19.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 |
 |---|---|---|
@@ -88,7 +88,7 @@ Every MCP tool is listed by default. If that is too much context for your client
 | `import` | Read and scan the repo, import files, apply env values | `read_file`, `scan_project`, `import_file`, `import_directory`, `apply_env_to_nodes` |
 | `export` | Mermaid, PlantUML, draw.io, Terraform, K8s, write files, generate docs and runbooks | `export_mermaid`, `export_plantuml`, `export_drawio`, `export_terraform`, `export_k8s_yaml`, `export_to_file`, `generate_docs`, `generate_runbook` |
 | `analysis` | Validate, diff, cross-diagram suggestions, clone | `validate_diagram`, `diff_diagram`, `find_shared_services`, `suggest_connections`, `clone_diagram`, `suggest_architecture` |
-| `project` | Watch a repo for drift, generate sequences from the API | `watch_project`, `check_project_drift`, `unwatch_project`, `generate_sequence_from_api` |
+| `project` | Watch a repo for drift, sync a diagram with the repo, generate sequences from the API | `watch_project`, `check_project_drift`, `unwatch_project`, `sync_project`, `generate_sequence_from_api` |
 | `history` | Server version history (snapshots) and the edit log | `snapshot_diagram`, `list_snapshots`, `restore_snapshot`, `get_edit_log` |
 
 - `MODUDRAFT_TOOLSETS="core"` lists the core tools only; `"sequences,api"` lists core plus those groups; `"all"` (or unset) lists everything.
@@ -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.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).
+
 ### Upgrading to 0.19.0
 
 - Snapshots are now server versions. `snapshot_diagram` saves a named version in the diagram's Version history (visible to teammates in the web app), `list_snapshots` lists the versions, and `restore_snapshot` restores one (`snapshot_id` is a version id or a version number). Parameter names are unchanged. The restore is saved as a new version and the state before it stays in the history (the previous version), so it can be undone.
@@ -146,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 |
@@ -165,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`)*
@@ -279,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
@@ -403,6 +417,14 @@ Items from other files are never touched. Existing items without import history
 
 `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.
 
+## Repo sync and CI drift check
+
+`sync_project` compares the files in your repo with a diagram and brings the diagram up to date. It previews by default; the same engine powers the `check` command and the GitHub Action, so CI can tell you when the diagram has drifted from the code.
+
+**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)".
+
 ## Workspaces and local files
 
 `list_diagrams`, `search_diagrams` and `get_org_context` cover every workspace you belong to; `create_diagram` and `clone_diagram` accept `workspace_id`. The API lists at most 500 diagrams (newest first); when `list_diagrams` hits that cap it returns `{ diagrams, truncated: true, note }`.