@modudraft/mcp 0.14.3 → 0.15.0

package/README.md

@@ -83,13 +83,13 @@ Without it, all diagram tools work as usual. The file tools fall back to your cl
 ### Diagram management
 | Tool | Description |
 |---|---|
-| `list_diagrams` | List all your diagrams |
-| `create_diagram` | Create a new diagram |
-| `get_diagram` | Get full diagram state + missing-metadata hints |
+| `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 |
 | `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 |
-| `get_share_link` | Get or create a share link |
+| `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 |
+| `get_share_link` | Get or create a share link. If a link exists with a different permission it is returned as is; pass `replace: true` to rotate it (the old link stops working) |
 
 ### Architecture nodes & edges
 | Tool | Description |
@@ -184,7 +184,7 @@ The old `request_body`, `request_format`, `body`, `body_format` and top-level `r
 |---|---|
 | `scan_project` | Scan a directory and list all importable files (docker-compose, K8s, Terraform, SQL, Prisma, OpenAPI, etc.) |
 | `read_file` | Read any file from the filesystem |
-| `import_file` | Import a file into a diagram - auto-detects format |
+| `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
@@ -286,6 +286,38 @@ Proprietary software. Copyright © 2026 [Modudraft](https://modudraft.com). All
 
 You may install and run this package to connect your own AI tools to the Modudraft service under a valid Modudraft account. Copying, modifying, redistributing, and reverse-engineering it are not permitted. The full terms are in the `LICENSE` file included in this package, and use of the service is governed by the [Terms of Service](https://modudraft.com/terms). Questions: security@modudraft.com.
 
+## Where agent edits go
+
+Agent edits (`add_node`, `add_edge`, ...) target the **architecture** tab. The exporters (Terraform, Kubernetes, Mermaid, ...) read the cloud, network and data-flow tabs, so build those with their own tools or import into them with `target_tab` (`db-schema`, `api`, `cloud` or `network`).
+
+## Concurrent edits
+
+Every write sends the diagram version it was based on in the `x-modudraft-base-version` header. If someone edits the same diagram in the web app meanwhile, the server refuses the stale write instead of overwriting their edit; the MCP then re-reads the diagram, re-applies the agent's change and retries (at most 3 attempts). If the diagram keeps changing, the call fails with a clear message and nothing from that call is saved, so just try again. This needs a Modudraft API that supports the precondition; against an older API the header is ignored.
+
+## Pinned nodes
+
+A node with an explicit `x`/`y` (`add_node`, `add_boundary`) is pinned. Nodes that people drag or nudge in the web editor are pinned too. The editor's Tidy button and the node menu's "Unpin" clear pins. Auto-tidy and `layout_diagram` keep pinned nodes where they are; `layout_diagram` with `include_pinned: true` lays out every node and clears all pins.
+
+## Re-import
+
+`import_file` and `import_directory` remember where each imported item came from: the repository (its `origin` remote without credentials, such as `github.com/acme/shop`, or else the repo folder's name) plus the file path relative to the git root, scoped to the target node for DB and API imports. Two repos that both have a root `docker-compose.yml` therefore never overwrite each other's items. Importing the same file again:
+
+- updates items that came from that file (columns, labels and types are replaced by the file's content),
+- adds new items,
+- removes items the importer created earlier that no longer exist in the file.
+
+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`.
+
+## 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.
+
+## 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 }`.
+
+Local state lives in `~/.modudraft`: `snapshots.v2.json`, `edit-log.v2.json`, `watch.v2.json` and `org-context-v2.v2.json` (the org context cache, which holds org and team labels). These files are private to you (files `0600`, folder `0700`), locked against concurrent MCP processes, and kept separately per API key. The first write imports the data of an older MCP's `snapshots.json`, `edit-log.json` or `watch.json`; those older files are never written again, so an older MCP still running cannot wipe the new ones.
+
 ## Auto-tidy
 
 Agents build a diagram with many small calls, and the layout only makes sense once the nodes *and* the edges between them exist. So adding or removing a node or an edge (`add_node`, `add_edge`, `delete_node`, `delete_edge`, `bulk_add_nodes`, `bulk_add_edges`) does not tidy immediately. Each change restarts a per-diagram timer, and the diagram is tidied **once, after the changes stop** - never between the ten adds of a ten-element build. It is the same layout as the editor's Tidy button.