@meltemi/diagrams-cli 1.11.12 → 1.11.13

package/dist/cli.d.ts

@@ -7,7 +7,7 @@ export declare const CLI_NAME = "meltemi-diagrams";
 export declare const CLI_ALIAS = "mdg";
 /** Extension of `.meltemi` sources (decision 0002). */
 export declare const MELTEMI_EXTENSION = ".meltemi";
-export declare const CLI_VERSION = "1.11.12";
+export declare const CLI_VERSION = "1.11.13";
 export declare const EXIT_OK = 0;
 export declare const EXIT_FINDINGS = 1;
 export declare const EXIT_USAGE = 2;

package/dist/cli.js

@@ -30,7 +30,7 @@ export const CLI_NAME = "meltemi-diagrams";
 export const CLI_ALIAS = "mdg";
 /** Extension of `.meltemi` sources (decision 0002). */
 export const MELTEMI_EXTENSION = ".meltemi";
-export const CLI_VERSION = "1.11.12";
+export const CLI_VERSION = "1.11.13";
 export const EXIT_OK = 0;
 export const EXIT_FINDINGS = 1;
 export const EXIT_USAGE = 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meltemi/diagrams-cli",
-  "version": "1.11.12",
+  "version": "1.11.13",
   "description": "Command line interface (meltemi-diagrams, alias mdg) for .meltemi projects.",
   "license": "MIT",
   "repository": {
@@ -33,31 +33,31 @@
     "templates"
   ],
   "dependencies": {
-    "@meltemi/diagrams-assist": "1.11.12",
-    "@meltemi/diagrams-capture": "1.11.12",
-    "@meltemi/diagrams-catalog": "1.11.12",
-    "@meltemi/diagrams-edit": "1.11.12",
-    "@meltemi/diagrams-editor": "1.11.12",
-    "@meltemi/diagrams-assets": "1.11.12",
-    "@meltemi/diagrams-fonts": "1.11.12",
-    "@meltemi/diagrams-i18n": "1.11.12",
-    "@meltemi/diagrams-import": "1.11.12",
-    "@meltemi/diagrams-language": "1.11.12",
-    "@meltemi/diagrams-layout-elk": "1.11.12",
-    "@meltemi/diagrams-model": "1.11.12",
-    "@meltemi/diagrams-project": "1.11.12",
-    "@meltemi/diagrams-motion": "1.11.12",
-    "@meltemi/diagrams-layout": "1.11.12",
-    "@meltemi/diagrams-player": "1.11.12",
-    "@meltemi/diagrams-render": "1.11.12"
+    "@meltemi/diagrams-assets": "1.11.13",
+    "@meltemi/diagrams-assist": "1.11.13",
+    "@meltemi/diagrams-capture": "1.11.13",
+    "@meltemi/diagrams-catalog": "1.11.13",
+    "@meltemi/diagrams-edit": "1.11.13",
+    "@meltemi/diagrams-editor": "1.11.13",
+    "@meltemi/diagrams-fonts": "1.11.13",
+    "@meltemi/diagrams-import": "1.11.13",
+    "@meltemi/diagrams-i18n": "1.11.13",
+    "@meltemi/diagrams-layout": "1.11.13",
+    "@meltemi/diagrams-language": "1.11.13",
+    "@meltemi/diagrams-layout-elk": "1.11.13",
+    "@meltemi/diagrams-model": "1.11.13",
+    "@meltemi/diagrams-player": "1.11.13",
+    "@meltemi/diagrams-motion": "1.11.13",
+    "@meltemi/diagrams-project": "1.11.13",
+    "@meltemi/diagrams-render": "1.11.13"
   },
   "publishConfig": {
     "access": "public"
   },
   "meltemiRelease": {
     "repository": "askenaz-dev/meltemi-diagrams",
-    "sha": "80ccdb9ad445a502ed54193eb97cb26aaed0a374",
-    "tag": "v1.11.12"
+    "sha": "dec86922755b8fc171d2979170bd389baae6702e",
+    "tag": "v1.11.13"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/skills/meltemi-diagrams/SKILL.md

@@ -3,7 +3,7 @@ name: meltemi-diagrams
 description: Use when asked to draw, document or convert a system or software architecture, sketch a whiteboard or kanban board, turn a diagram or a screenshot into code, or change a `.meltemi` file. Creates, edits, converts and exports Meltemi diagrams as code (`.meltemi` files) - flow sheets with groups, plain containers, data stores, decisions, notes, tags and boxes in 24 shapes with icons, laid out by ELK, assisted or by hand, with ports, constraints, styles and themes; free compositions (slides with boxes, text, icons, images, layers and links to flow views, and whiteboards with pen strokes, stickies and kanban lists); sequence diagrams (participants, calls, replies, activations, notes, alt/opt/loop/par fragments, scenarios); C4 models with context, container and component views; motion effects and stories that walk through a diagram scene by scene; SVG, PNG, PDF and HTML-player exports with export profiles. Imports Mermaid and PlantUML instead of retyping them, and turns draw.io, HTML or SVG pictures into sheets.
 license: MIT
 metadata:
-  version: 1.11.12
+  version: 1.11.13
 ---
 
 # Meltemi Diagrams
@@ -19,7 +19,9 @@ Before you start: `pnpm mdg --version` says which version of the command line is
 sheets go under `diagrams/`, or where the project keeps them (the `sources` of its
 `project.json`). Cloud commands run only when the person asks
 ([reference/cloud.md](reference/cloud.md)), and a token (`mdg_…`) is never printed, read, copied
-or committed.
+or committed. Connected to the hosted service's MCP endpoint instead (tools such as `write_files`
+and `preview` act on the person's projects), follow [reference/mcp.md](reference/mcp.md): the same
+steps, through the tools.
 
 1. Collect the pieces from the request or the source material: elements (boxes, data stores,
    decisions), bands (groups), arrows with their labels, annotations (notes, tags), what is
@@ -223,6 +225,8 @@ fontWeight 600 }`, also in classes and rules (`rule note { font "Caveat" }`); ic
   their diagnostics and frame exports.
 - [reference/cloud.md](reference/cloud.md): sharing a project in the optional cloud service, only
   when the person asks, and where its token lives.
+- [reference/mcp.md](reference/mcp.md): the MCP endpoint's tools on the person's projects, how to
+  connect, and the workflow of read, write with `ifRevision`, validate, preview and `open_url`.
 - [examples/platform.meltemi](examples/platform.meltemi): a complete sheet using every construct.
 - [examples/slide.meltemi](examples/slide.meltemi): a flow view and a free slide linked to it.
 - [examples/sequence.meltemi](examples/sequence.meltemi): a payment sequence with a group, an

package/skills/meltemi-diagrams/reference/mcp.md

@@ -0,0 +1,93 @@
+# The MCP endpoint (projects in the person's account)
+
+When the person connects you to `https://diagrams.meltemi.dev/mcp`, its tools act on the Meltemi
+Diagrams projects of their account in the hosted service: you create projects, write `.meltemi`
+files, look at the drawings and share the result, without a folder or the command line. The
+language is the same as everywhere else in this skill; only where the files live changes.
+
+## Connecting
+
+The person connects once; never connect for them without being asked.
+
+- Codex with OAuth (the person signs in and approves the scopes in the browser):
+  `codex mcp add meltemi --url https://diagrams.meltemi.dev/mcp`, then `codex mcp login meltemi`.
+- With an API token instead, made by the person in the app's **API tokens** dialog and kept in
+  `MELTEMI_TOKEN`: in `~/.codex/config.toml`, a `[mcp_servers.meltemi]` table with
+  `url = "https://diagrams.meltemi.dev/mcp"` and `bearer_token_env_var = "MELTEMI_TOKEN"`.
+
+Never ask for, print, read, copy or write the token (`mdg_…`); it stays in the environment. The
+scopes are `projects:read`, `projects:write`, `sharing`, `live` and `publish`: a refusal
+`scope.insufficient` names the one the connection lacks, and the person grants it, not you. A scope
+never adds a role: in a project shared with the account, an editor writes but only the owner shares,
+runs live sessions and publishes (`access.denied`).
+
+## The tools
+
+- The account: `whoami` (the account, its scopes, usage and limits).
+- Projects: `list_projects`, `create_project` (empty, from a template `flow`, `c4`, `sequence`,
+  `free` or `purchase`, or from files), `get_project` (its revision, its file paths and its address),
+  `rename_project`.
+- Files: `read_files` (the texts and the images' hashes, at a revision), `write_files` (texts by
+  path, `null` deletes; images and fonts by the hash `upload_image` answered), `validate` (the
+  diagnostics `meltemi-diagrams validate` prints), `upload_image` (PNG, JPEG, GIF, WebP, SVG or a
+  font, base64, at most 10 MiB).
+- Versions: `list_versions`, `create_version` (a label of at most 80 characters),
+  `restore_version`.
+- The app: `open_url` (the address that opens the project in the browser).
+- Pictures: `preview` (a diagram, or a story's frame, drawn on the server with the command line's
+  engine).
+- Sharing: `get_sharing`, `set_link_access` (`private`, `view` or `edit`), `invite`,
+  `list_invitations`, `revoke_invitation`, `set_member_role`, `remove_member`.
+- Live sessions: `get_live`, `start_live`, `end_live`.
+- Publishing: `list_publications`, `publish`, `unpublish`.
+
+Every result carries its JSON; a refusal is an error result `{ code, message, … }` with a stable
+code. Ids are never guessed: take a project's id from `list_projects` or `create_project`.
+
+## The workflow
+
+1. Read before you write: `get_project` or `read_files` gives the `revision`. A person may be editing
+   the same project in the browser, and what they changed is in this read.
+2. Write with `write_files` and `ifRevision` set to that revision, one logical change per call, with
+   an `idempotencyKey` of your own for the change (1 to 64 visible ASCII characters, such as
+   `checkout-add-retry-1`): when a call times out, send the same call with the same key, and it is
+   applied once. `create_project` takes a key too.
+3. Every `.meltemi` file you write is compiled with the project first. `diagram.invalid` means
+   nothing was written: fix every error its `diagnostics` list (the codes are in
+   [language.md](language.md)) and write again. Warnings come back with a successful write.
+4. `revision.mismatch` means the project changed since your read (its `revision` is the current
+   one): read again, keep the person's change, apply yours on top and write with the new revision.
+   Never write the old text back over theirs.
+5. `validate` the project, then `preview` what you changed: a PNG 1280 pixels wide by default
+   (`width` from 16 to 2048), or `format: "svg"` for the SVG as text. The report beside the picture
+   gives the revision drawn, the size, the elements and relations, the warnings
+   (`layout.text-overflow`, `layout.overlap`, …) and the fonts the server estimated. Look at the
+   picture when you can, read the report always, and fix what it shows as you would after an
+   export.
+6. Give the person `open_url`'s address. An open page shows every write at once, without a reload.
+
+A preview that fails (`request.invalid`, `rate.limited`) never undoes a write that succeeded: say
+what was saved, at which revision, and ask for the picture again. Thirty previews and three hundred
+calls a minute per account are allowed; `rate.limited` gives `retryAfter` in seconds.
+
+## Sharing, live sessions and publishing: only when asked
+
+These change who can see the project, so run them only on the person's explicit request, and say
+exactly what happened.
+
+- `set_link_access` answers the project's link: `view` lets anybody with it read, `edit` lets a
+  signed-in person edit. Saying so is part of the answer.
+- `invite` makes an invitation and answers its link and `emailSent: false`. No email is sent: never
+  say one was. Tell the person that the invitation exists, for whom and with which role, and give
+  them its link only if they ask for it, to pass on themselves.
+- `start_live` starts a session of 24 hours; anybody with its link joins without an account, editing
+  unless `guestsEdit` is false. Give its term (`until`); give the link only when asked.
+  `end_live` ends it.
+- `publish` makes the project's catalog a public page at the account's handle and the `slug` you
+  give, and answers only once that address has served it; `unpublish` removes one slug and leaves
+  the others. `handle.required` means the person chooses a handle in the app first.
+  `publish.unverified` means the page was published but its address did not answer yet: try the
+  address again in a moment before saying it is live.
+
+Never print, in your answer or a file, a token, or an invitation's or a live session's link that
+the person did not ask for.