@meltemi/diagrams-mcp 0.0.0-stage → 1.11.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Architecture Studio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @meltemi/diagrams-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Model Context Protocol tools of Meltemi Diagrams, defined once: the catalogue of twenty-seven
+tools (projects, files, versions, previews, sharing, live sessions and publishing), the wrapper
+that answers every call with stable error codes, the stateless Streamable HTTP handler, and the
+engine that checks a project and draws its previews. The hosted endpoint
+(`https://diagrams.meltemi.dev/mcp`) and the command line's local server (`mdg mcp`) are both
+built from it, so they list the same tools and draw the same pictures.
+
+It is part of [Meltemi Diagrams](https://github.com/askenaz-dev/meltemi-diagrams#readme), diagrams as code with a canvas, motion and
+exports. Every package of the product has the same version. To give an agent these tools, run
+`mdg mcp` from [`@meltemi/diagrams-cli`](https://www.npmjs.com/package/@meltemi/diagrams-cli)
+rather than this package.
+
+## Install
+
+```bash
+npm install @meltemi/diagrams-mcp
+```
+
+Node 22.12.0 or later. The package is an ES module with type declarations.
+
+## Use
+
+```ts
+import { nodeRenderer } from "@meltemi/diagrams-mcp/node";
+
+const renderer = nodeRenderer();
+const outcome = await renderer.render({
+  revision: 1,
+  files: { "shop.meltemi": 'language "0.2"\n\ndiagram shop: flow {\n  web -> api\n}\n' },
+  file: "shop.meltemi",
+  format: "png",
+});
+console.log(outcome.ok && outcome.contentType, outcome.ok && outcome.report.elements); // image/png 2
+```
+
+- `@meltemi/diagrams-mcp`: `TOOLS` and `CATALOGUE`, `buildServer`, `statelessHandler`, `Refusal`
+  and the shapes.
+- `@meltemi/diagrams-mcp/preview`: `RendererCore`, `PreviewEngine`, the rasteriser and the bounds
+  of a picture, with nothing of the platform.
+- `@meltemi/diagrams-mcp/node`: the engine over the installed fonts, icons and resvg.
+
+## Documentation
+
+- [Agents](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/agents.md)
+- [The command line](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/cli.md)
+- [All documentation](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/README.md)
+
+## Licence
+
+MIT. Third-party components and their licences are listed in [THIRD_PARTY_LICENSES.md](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/THIRD_PARTY_LICENSES.md).
+`@resvg/resvg-wasm` (MPL-2.0) is a dependency, used unmodified.

package/dist/catalogue/folder.d.ts

@@ -0,0 +1,64 @@
+import * as z from "zod";
+/** The two tools of a folder, by name. */
+export declare const FOLDER_TOOLS: {
+    readonly validate: import("../serve.js").ToolDefinition<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        errors: z.ZodNumber;
+        warnings: z.ZodNumber;
+        diagnostics: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            code: z.ZodString;
+            severity: z.ZodEnum<{
+                error: "error";
+                warning: "warning";
+                info: "info";
+            }>;
+            message: z.ZodString;
+            line: z.ZodNumber;
+            column: z.ZodNumber;
+        }, z.core.$strip>>;
+        truncated: z.ZodBoolean;
+    }, z.core.$strip>>;
+    readonly preview: import("../serve.js").ToolDefinition<z.ZodObject<{
+        path: z.ZodString;
+        diagram: z.ZodOptional<z.ZodString>;
+        story: z.ZodOptional<z.ZodString>;
+        at: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodEnum<{
+            png: "png";
+            svg: "svg";
+        }>>;
+        width: z.ZodOptional<z.ZodNumber>;
+        theme: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        format: z.ZodEnum<{
+            png: "png";
+            svg: "svg";
+        }>;
+        diagnostics: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            code: z.ZodString;
+            severity: z.ZodEnum<{
+                error: "error";
+                warning: "warning";
+                info: "info";
+            }>;
+            message: z.ZodString;
+            line: z.ZodNumber;
+            column: z.ZodNumber;
+        }, z.core.$strip>>;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        elements: z.ZodNumber;
+        relations: z.ZodNumber;
+        estimatedFonts: z.ZodArray<z.ZodString>;
+        truncated: z.ZodBoolean;
+        fitted: z.ZodOptional<z.ZodBoolean>;
+        cached: z.ZodBoolean;
+    }, z.core.$strip>>;
+};
+export type FolderToolName = keyof typeof FOLDER_TOOLS;
+/** What `initialize` answers for a folder. */
+export declare function folderInstructions(): string;
+//# sourceMappingURL=folder.d.ts.map

package/dist/catalogue/folder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder.d.ts","sourceRoot":"","sources":["../../src/catalogue/folder.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAazB,0CAA0C;AAC1C,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4Cf,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,YAAY,CAAC;AAEvD,8CAA8C;AAC9C,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C"}

package/dist/catalogue/folder.js

@@ -0,0 +1,69 @@
+// The tools of a folder (`mcp-local-server`, "A folder with no account"): `mdg mcp --folder <dir>`
+// checks and draws the `.meltemi` files of a folder on disk, with no account and no network, so an
+// agent working in a repository gets the same pictures as tool results. Two tools, with the cloud
+// tools' names, words and reports, without a project or a revision.
+import * as z from "zod";
+import { MAX_PNG_WIDTH, MIN_PNG_WIDTH } from "../preview/bounds.js";
+import { define } from "../serve.js";
+import { diagnosticSchema } from "../shapes.js";
+import { reportSchema } from "./preview.js";
+/** A file's path from the folder's root. */
+const folderPathArg = z
+    .string()
+    .min(1)
+    .max(1024)
+    .describe("A file's path from the folder's root, such as `flows/checkout.meltemi`.");
+/** The two tools of a folder, by name. */
+export const FOLDER_TOOLS = {
+    validate: define({
+        name: "validate",
+        title: "Validate",
+        description: "The diagnostics of a file of the folder, or of the whole folder as a project, as `meltemi-diagrams validate` prints them (the layout's warnings included), read from disk now. Images and fonts are checked by preview.",
+        scope: "projects:read",
+        input: z.object({ path: folderPathArg.optional() }),
+        output: z.object({
+            errors: z.number(),
+            warnings: z.number(),
+            diagnostics: z.array(diagnosticSchema).describe("The first fifty."),
+            truncated: z.boolean(),
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }),
+    preview: define({
+        name: "preview",
+        title: "Preview",
+        description: `A picture of a diagram (the file's first, or the one named) or of a story's frame (at \`at\`, its end by default) of the folder as it is on disk now, drawn on this machine with the command line's engine: a PNG ${MIN_PNG_WIDTH} to ${MAX_PNG_WIDTH} pixels wide (1280 by default), or with format svg the SVG as text. A report beside it says the size, the elements and relations drawn, the warnings and the fonts that were estimated, so the drawing can be judged without seeing it.`,
+        scope: "projects:read",
+        preview: true,
+        input: z.object({
+            path: folderPathArg.describe("The .meltemi file to draw."),
+            diagram: z.string().optional().describe("The diagram's id; the file's first when left out."),
+            story: z.string().optional().describe("A story's id: its frame at `at` is drawn instead."),
+            at: z
+                .string()
+                .optional()
+                .describe("The story's time, such as 2.4s or 1500ms; its end by default."),
+            format: z.enum(["png", "svg"]).optional(),
+            width: z
+                .number()
+                .int()
+                .optional()
+                .describe(`A PNG's width in pixels, ${MIN_PNG_WIDTH} to ${MAX_PNG_WIDTH}.`),
+            theme: z
+                .string()
+                .optional()
+                .describe("A theme over the diagram's own, as the command line's --theme."),
+        }),
+        output: reportSchema.omit({ revision: true }),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }),
+};
+/** What `initialize` answers for a folder. */
+export function folderInstructions() {
+    return [
+        "These tools check and draw the Meltemi Diagrams files of a folder on this machine, where diagrams are `.meltemi` text files: validate reports their diagnostics and preview answers a picture of a diagram or of a story's frame, read from disk at each call.",
+        "Write the files with your own file tools, then validate and preview to judge the drawing.",
+        "The language and its rules are taught by the Meltemi Diagrams skill (https://diagrams.meltemi.dev/agent-setup).",
+    ].join(" ");
+}
+//# sourceMappingURL=folder.js.map

package/dist/catalogue/folder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder.js","sourceRoot":"","sources":["../../src/catalogue/folder.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,mGAAmG;AACnG,kGAAkG;AAClG,oEAAoE;AAEpE,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,4CAA4C;AAC5C,MAAM,aAAa,GAAG,CAAC;KACpB,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,IAAI,CAAC;KACT,QAAQ,CAAC,yEAAyE,CAAC,CAAC;AAEvF,0CAA0C;AAC1C,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,UAAU;QACjB,WAAW,EACT,yNAAyN;QAC3N,KAAK,EAAE,eAAe;QACtB,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,aAAa,CAAC,QAAQ,EAAE,EAAE,CAAC;QACnD,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;YACf,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;YAClB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;YACpB,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC;YACnE,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;SACvB,CAAC;QACF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;KAC1D,CAAC;IACF,OAAO,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,qNAAqN,aAAa,OAAO,aAAa,yOAAyO;QAC5e,KAAK,EAAE,eAAe;QACtB,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;YACd,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,4BAA4B,CAAC;YAC1D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;YAC5F,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;YAC1F,EAAE,EAAE,CAAC;iBACF,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,+DAA+D,CAAC;YAC5E,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE;YACzC,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,QAAQ,EAAE;iBACV,QAAQ,CAAC,4BAA4B,aAAa,OAAO,aAAa,GAAG,CAAC;YAC7E,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,gEAAgE,CAAC;SAC9E,CAAC;QACF,MAAM,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAC7C,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;KAC1D,CAAC;CACM,CAAC;AAIX,8CAA8C;AAC9C,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,gQAAgQ;QAChQ,2FAA2F;QAC3F,iHAAiH;KAClH,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC"}