@modudraft/mcp 0.17.0 → 0.19.0

package/README.md

@@ -69,8 +69,53 @@ Without it, all diagram tools work as usual. The file tools fall back to your cl
 | `MODUDRAFT_API_URL` | No | Override API base URL (default: `https://api.modudraft.com`) |
 | `MODUDRAFT_PROJECT_ROOTS` | No | Your source-code folder(s): the repo or git worktree the file tools (`scan_project`, `read_file`, `import_file`, `export_to_file`, ...) may read from and write to. Separate several with `:` (`;` on Windows); `~` is allowed. Used when your MCP client doesn't share its workspace folders. Your home directory or `/` is never accepted, so point it at the repo itself. |
 | `MODUDRAFT_AUTO_TIDY_MS` | No | Quiet period, in milliseconds, before the architecture tab is auto-tidied after nodes or edges are added or removed (default `8000`; `0` turns auto-tidy off). See [Auto-tidy](#auto-tidy) |
+| `MODUDRAFT_TOOLSETS` | No | Which tool groups to list: unset or `all` lists every tool (the default), `core` lists only the core tools, `"sequences,api"` lists core plus those groups. See [Toolsets](#toolsets) |
 
 
+## 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`.
+
+| Toolset | Purpose | Tools |
+|---|---|---|
+| `modeling` | Bulk create and node metadata | `apply_architecture`, `bulk_add_nodes`, `bulk_add_edges`, `set_node_metadata`, `suggest_metadata` |
+| `sequences` | Sequence diagrams: sequences, lanes, messages, fragments | `list_sequences`, `add_sequence`, `update_sequence`, `delete_sequence`, `add_sequence_participant`, `add_sequence_message`, `bulk_add_sequence_messages`, `update_sequence_message`, `delete_sequence_message`, `get_sequence`, `clear_sequence`, `add_sequence_fragment`, `update_sequence_fragment`, `delete_sequence_fragment` |
+| `database` | DB tables and ER export | `add_db_table`, `update_db_table`, `delete_db_table`, `export_er_diagram` |
+| `api` | API endpoints, contracts, OpenAPI export | `add_api_endpoint`, `bulk_add_api_endpoints`, `update_api_endpoint`, `delete_api_endpoint`, `export_openapi` |
+| `infra` | Cloud resources and network devices | `add_cloud_resource`, `update_cloud_resource`, `delete_cloud_resource`, `add_network_device`, `update_network_device`, `delete_network_device` |
+| `data_flows` | Data-flow pipelines and stages | `list_data_flows`, `add_data_flow`, `add_data_flow_stage`, `update_data_flow_stage`, `delete_data_flow_stage`, `reorder_data_flow_stages` |
+| `views` | Show and hide tabs, the Notes tab | `get_enabled_tabs`, `enable_tab`, `disable_tab`, `get_notes`, `set_notes`, `append_to_notes`, `replace_in_notes` |
+| `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` |
+| `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.
+- A value made only of unknown names keeps the default (everything) and prints a warning on stderr.
+- `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.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.
+- Versions are pruned oldest first by plan: 10 per diagram on Free, 50 on Pro, 200 on Team. Pending edits from this MCP are saved before a snapshot or restore.
+- `delete_snapshot` is removed (versions are pruned automatically by plan); calling it returns an explanatory error.
+- Snapshots saved by older versions in `~/.modudraft/snapshots.v2.json` are still listed (with `source: "local"`) and can be restored, but are read-only: no new local snapshots are written.
+- Requires a Modudraft API with version history.
+
+### Upgrading to 0.18.0
+
+- New `load_toolset` tool and the `MODUDRAFT_TOOLSETS` environment variable (see [Toolsets](#toolsets)). Nothing was removed or renamed, and the default is unchanged: every tool is listed.
+- New MCP resources and prompts (see [Resources and prompts](#resources-and-prompts)).
+
+### Resources and prompts
+
+Besides tools, the server offers MCP resources and prompts, for clients that support them.
+
+- **Resources:** each diagram is readable as plain-text line art at `modudraft://diagram/<id>` (the architecture tab, the same output as `render_diagram_text`). `resources/list` returns your 50 most recently edited diagrams; any diagram id you can reach can be read by URI.
+- **Prompts:** `map_repo` (optional `path`) scans a repository and imports what it finds; `check_drift` (`diagram_id`) checks a diagram against the project code; `review_diagram` (`diagram_id`) validates a diagram and lists its issues. Each is one message that names the toolset to load.
+
 ### Upgrading to 0.17.0
 
 - More importers now report a `warnings` list for what they skipped or could not map (most formats already did; dbml, schema-rb, typeorm, sqlalchemy, dbt, cloudformation and asyncapi return none). `import_file` refuses a SQL file that only has `ALTER TABLE` statements (no `CREATE TABLE`) with a reason.
@@ -95,6 +140,8 @@ Without it, all diagram tools work as usual. The file tools fall back to your cl
 ## Tools
 
 ### Diagram management
+*(toolset: `core`)*
+
 | Tool | Description |
 |---|---|
 | `list_diagrams` | List your diagrams from every workspace you belong to |
@@ -106,6 +153,8 @@ Without it, all diagram tools work as usual. The file tools fall back to your cl
 | `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
+*(toolset: `core`)*
+
 | Tool | Description |
 |---|---|
 | `add_node` | Add a component (compute, database, queue, gateway, etc.). `tool` takes a catalog key or a common name and is resolved to the catalog key (see [Tool names](#tool-names)). Optional `runs_on` links the node to a Cloud-tab resource (its id or name; a bad value is refused with the valid names) |
@@ -118,6 +167,8 @@ Without it, all diagram tools work as usual. The file tools fall back to your cl
 | `add_note` | Add a sticky note annotation |
 
 ### Node metadata
+*(toolset: `modeling`, except `get_node_schema`, which is in `core`)*
+
 | Tool | Description |
 |---|---|
 | `set_node_metadata` | Set a configuration property on a node (host, port, framework, region, etc.) |
@@ -125,6 +176,8 @@ Without it, all diagram tools work as usual. The file tools fall back to your cl
 | `get_node_schema` | Get expected metadata fields for an archetype |
 
 ### Sequence diagram
+*(toolset: `sequences`)*
+
 A diagram can hold many named sequences. Each has its own lanes (architecture nodes, in order), messages and fragments. Message and fragment tools take `sequence_id`, which may be left out only when the diagram has exactly one sequence.
 
 | Tool | Description |
@@ -145,6 +198,8 @@ A diagram can hold many named sequences. Each has its own lanes (architecture no
 | `delete_sequence_fragment` | Remove a fragment |
 
 ### DB schema (ER diagram)
+*(toolset: `database`)*
+
 | Tool | Description |
 |---|---|
 | `add_db_table` | Add a database table with columns; rejects duplicate table names (case-insensitive) |
@@ -153,6 +208,8 @@ A diagram can hold many named sequences. Each has its own lanes (architecture no
 | `export_er_diagram` | Export schema as SQL DDL |
 
 ### API schema (OpenAPI)
+*(toolset: `api`)*
+
 | Tool | Description |
 |---|---|
 | `add_api_endpoint` | Add an http (including HEAD and OPTIONS), graphql, grpc, websocket or event endpoint; rejects duplicate endpoints. Its request and response shapes go in `contract`: per-protocol slots holding JSON Schema (as an object or YAML), where fields are required unless marked `optional: true`. Omit `contract` to start from an empty one |
@@ -164,6 +221,8 @@ A diagram can hold many named sequences. Each has its own lanes (architecture no
 The old `request_body`, `request_format`, `body`, `body_format` and top-level `responses` arguments were removed; they now return an error naming their replacement in `contract`.
 
 ### Notes
+*(toolset: `views`)*
+
 | Tool | Description |
 |---|---|
 | `get_notes` | Return the diagram's Markdown notes |
@@ -172,6 +231,8 @@ The old `request_body`, `request_format`, `body`, `body_format` and top-level `r
 | `replace_in_notes` | Literal find-and-replace inside the notes (must match exactly once unless `replace_all`), so one checkbox or sentence can change without resending everything |
 
 ### Cloud diagram
+*(toolset: `infra`)*
+
 | Tool | Description |
 |---|---|
 | `add_cloud_resource` | Add a cloud resource (cluster, VPC, service, database, queue, etc.) |
@@ -179,6 +240,8 @@ The old `request_body`, `request_format`, `body`, `body_format` and top-level `r
 | `delete_cloud_resource` | Remove a cloud resource. Nodes that ran on it (or a child) keep existing; only their `runs_on` link is cleared |
 
 ### Network diagram
+*(toolset: `infra`)*
+
 | Tool | Description |
 |---|---|
 | `add_network_device` | Add a network device (router, switch, firewall, etc.) |
@@ -186,6 +249,8 @@ The old `request_body`, `request_format`, `body`, `body_format` and top-level `r
 | `delete_network_device` | Remove a network device |
 
 ### Data flow diagram
+*(toolset: `data_flows`)*
+
 | Tool | Description |
 |---|---|
 | `add_data_flow_stage` | Add a pipeline stage (source, transform, sink, etc.). Optional `node_id` links it to an Architecture-tab node (its id or label; a bad value is refused with the valid names) |
@@ -194,6 +259,8 @@ The old `request_body`, `request_format`, `body`, `body_format` and top-level `r
 | `reorder_data_flow_stages` | Set the order of all stages in a data flow diagram |
 
 ### File import
+*(toolset: `import`)*
+
 | Tool | Description |
 |---|---|
 | `scan_project` | Scan a directory and list all importable files (docker-compose, K8s, Terraform, SQL, Prisma, OpenAPI, etc.) |
@@ -208,6 +275,8 @@ The old `request_body`, `request_format`, `body`, `body_format` and top-level `r
 - **Context (no diagram change):** `.env` files (sensitive values always redacted), `package.json`, `go.mod`, `requirements.txt`, `Gemfile`, `pom.xml`, `Cargo.toml`
 
 ### Export
+*(toolset: `export`, except `render_diagram_text`, which is in `core`)*
+
 | Tool | Description |
 |---|---|
 | `export_mermaid` | Export as Mermaid flowchart or ER diagram (paste into GitHub Markdown) |
@@ -219,12 +288,16 @@ The old `request_body`, `request_format`, `body`, `body_format` and top-level `r
 | `export_to_file` | Write any export format directly to a local file |
 
 ### Validation & diff
+*(toolset: `analysis`)*
+
 | Tool | Description |
 |---|---|
 | `validate_diagram` | Check a diagram for issues: dangling edges, orphaned nodes, FK integrity, missing PKs, duplicate routes, etc. |
 | `diff_diagram` | Compare two diagrams and return a structured list of what changed (added/removed/modified) |
 
 ### Cross-diagram intelligence
+*(toolset: `analysis`)*
+
 | Tool | Description |
 |---|---|
 | `find_shared_services` | Find nodes that appear in multiple diagrams - useful for shared infrastructure audits |
@@ -233,6 +306,8 @@ The old `request_body`, `request_format`, `body`, `body_format` and top-level `r
 | `clone_diagram` | Deep-copy a diagram as a starting template |
 
 ### Discovery (static, no API call)
+*(toolset: `core`)*
+
 | Tool | Description |
 |---|---|
 | `list_archetypes` | All component archetypes with metadata field schemas |
@@ -240,6 +315,8 @@ The old `request_body`, `request_format`, `body`, `body_format` and top-level `r
 | `list_protocols` | Valid edge protocol values |
 
 ### Org context
+*(toolset: `core`)*
+
 | Tool | Description |
 |---|---|
 | `get_org_context` | Get cached org context - existing tools, protocols, naming patterns |