@vardum/mcp 0.3.0 → 0.4.0

package/README.md

@@ -1,30 +1,32 @@
 # @vardum/mcp
 
-MCP server for [Vardum](https://vardum.com): lets an AI agent manage assets,
+MCP server for [Vardum](https://vardum.com): lets an AI agent manage assets and
 Vards using a key scoped to one workspace. Workspace creation, membership,
 API-key management and domains are managed in the web app with a signed-in session.
 
-## Setup
+This README describes **MCP 0.4.0**, including revision-guarded Vard editing.
+Check the [0.8 client release notes](https://github.com/f-tuma/vardum/blob/main/docs/client-release-0.8.md)
+and [release status and compatibility](https://github.com/f-tuma/vardum/blob/main/docs/npm-release.md)
+to confirm npm availability before installing this version. Published MCP 0.3.0
+uses the legacy editing contract; installing it does not enable revision guards.
+The published 0.1.0 artifact has a broken workspace dependency.
 
-The server speaks MCP over stdio, so the client starts it — there is nothing to
-run by hand. Create a workspace API key in **Settings // API keys** first; the
-key is restricted to that workspace and its selected read/write permissions.
-Copy the workspace ID from Settings → General for tool calls.
+## Setup
 
-This README describes **MCP 0.3.0**. The 11-tool surface is unchanged. Check the
-[release notes](https://github.com/f-tuma/vardum/blob/main/docs/client-release-0.7.md)
-and [release status and compatibility](https://github.com/f-tuma/vardum/blob/main/docs/npm-release.md).
-The published 0.1.0 artifact has a broken workspace dependency.
+The server speaks MCP over stdio, so the client starts it. Create a workspace
+API key in **Settings // API keys** first; it is restricted to that workspace
+and its selected permissions. Copy the workspace ID from Settings → General
+for tool calls. Use Node.js 22 or newer.
 
-The configurations below pin **0.3.0**. Verify its availability in your registry
-before installing, or build from source with
-`pnpm --filter "@vardum/mcp..." build` and configure the client to run
-`node /absolute/path/to/vardum/apps/mcp/dist/index.js`.
+**These configurations target MCP 0.4.0**; use them once the release-status page
+confirms that exact package is available. Deploy the matching server advertising
+`vardEditRevision: 1` before editing Vards. For current published setup, see the
+[MCP guide](../../docs/guide/mcp.md).
 
 Claude Code:
 
 ```sh
-claude mcp add vardum --env VARDUM_API_KEY=varda_... -- npx -y @vardum/mcp@0.3.0
+claude mcp add vardum --env VARDUM_API_KEY=varda_... -- npx -y @vardum/mcp@0.4.0
 ```
 
 Any client that reads a JSON config (Claude Desktop, Cursor, …):
@@ -34,13 +36,17 @@ Any client that reads a JSON config (Claude Desktop, Cursor, …):
   "mcpServers": {
     "vardum": {
       "command": "npx",
-      "args": ["-y", "@vardum/mcp@0.3.0"],
+      "args": ["-y", "@vardum/mcp@0.4.0"],
       "env": { "VARDUM_API_KEY": "varda_..." }
     }
   }
 }
 ```
 
+For a source checkout, build with `pnpm --filter "@vardum/mcp..." build` and
+configure the client to run `node /absolute/path/to/vardum/apps/mcp/dist/index.js`.
+This does not establish npm availability.
+
 ## Configuration
 
 | Setting | Flag | Environment | Default |
@@ -49,12 +55,11 @@ Any client that reads a JSON config (Claude Desktop, Cursor, …):
 | Workspace API key | `--api-key KEY` | `VARDUM_API_KEY` | — (required) |
 
 Point `--server` at your own host when self-hosting. `vardum-mcp --version` and
-`--help` answer without needing a key, which is the quickest way to check that a
-client can start the binary at all.
+`--help` answer without needing a key.
 
 ## Tools
 
-The 11 tools are:
+The 11 tools remain:
 
 | Area | Tools |
 | --- | --- |
@@ -62,74 +67,98 @@ The 11 tools are:
 | Vards | `list_vards`, `create_vard`, `get_vard`, `update_vard`, `delete_vard`, `replace_vard_items` |
 
 A read key can list/read. A write key also permits create, update, delete and
-publish. Tools for browser-only administration were removed in 0.2.0; creating
-an asset key as an owner does not make it an administration credential.
+publish within its scope. `update_vard` and `replace_vard_items` require API read
+and update permission because they return the full definition. `delete_vard`
+requires delete permission. Tools for browser-only administration were removed
+in 0.2.0; an owner-created workspace key is still not an administration credential.
 
 `list_assets` returns `{ workspaceSlug, assets, nextCursor }`. It lists ready
 assets in pages of 100 by default (`limit`: 1–500); pass `nextCursor` as `cursor`
-until it is null. Pending/failed versions are not listed.
-
-`replace_vard_items` pins with `versionId: "<ready-version-uuid>"` and
-`writable: false`. Omit `versionId` or send null to follow latest. The old
-`pinned` boolean is rejected: it never identified a specific version for the API.
-
-Images and video are accepted; video is stored and delivered as-is, and cannot
-be resized or transformed into variants.
+until it is null. Pending/failed versions are not listed. Images and video are
+accepted; video is stored and delivered as-is without variants.
 
 ## Asset visibility
 
 New assets are private. `list_assets` reports `isPublic` for each ready asset.
 Use `set_asset_visibility` with `workspaceId`, `assetId`, and an explicit boolean
-`isPublic` to publish or make an asset private. The API requires asset publish
-permission; read-only keys cannot change visibility.
+`isPublic` to publish or make an asset private. This requires publish permission.
 
 Publishing exposes every ready version and its variants. A public Vard does not
 publish its files: its anonymous manifest remains unavailable while any mapped
 asset is private. Making a file private cannot revoke downloaded or cached
-copies. These tools require the matching visibility-capable API in the compatibility table.
+copies. These tools require the matching visibility-capable API in the
+compatibility table.
+
+## Guarded editing
+
+Read `get_vard` first. Its editable definition contains `revision`, saved
+`folderRules` and **manual mappings only**, including stable mapping `id` values
+and literal `pinnedVersionId`. A separate `get_vard` with `resolved: true` returns
+a live preview without an editor revision. It can fail on collisions or limits
+without blocking configuration inspection or repair. Never persist resolved
+folder outputs as manual mappings.
+
+`update_vard`, `replace_vard_items` and `delete_vard` require the caller's
+**original `expectedRevision`**. It is an opaque `v1:<64 lowercase hex digits>`
+equality token for saved state, not a counter. Keep it unchanged. After a
+successful update or replacement, retain the full returned definition and its
+revision for the next edit.
+
+`replace_vard_items` takes the complete intended manual list. Each item must
+contain `id` (its existing manual UUID, or `null` for a new mapping), `assetId`,
+`outputPath`, `writable`, `transformation` (object or `null`) and an explicit
+`versionId` (UUID or `null`). Keep existing IDs; omitting an existing item removes
+it. Copy each saved `pinnedVersionId` into `versionId` literally, including an
+unavailable saved pin. A resolved delivery `versionId` is not the saved pin.
+`null` follows latest; pinned items must be read-only. Omitting `id` or
+`versionId`, or supplying the old `pinned` boolean, is invalid.
+
+These editor tools check `vardEditRevision: 1` and use dedicated `/editor`
+endpoints. An unsupported server, missing revision or missing editor endpoint
+stops the operation; there is no fallback to a legacy mutation.
+
+A stale write returns a structured MCP tool error (`isError: true`) with
+`status: 409`, `code: "vard_revision_conflict"`,
+`error: "Vard changed; reload before saving."`, `currentRevision` and an
+instruction to reload. Keep the intended edit, read `get_vard` again, review the
+current definition, then reapply the edit with that reviewed definition's
+revision. Do not automatically repeat a stale replacement list with a new token.
+See the [guarded editor protocol](../../docs/vard-editor-concurrency.md).
 
 ## Folder rules
 
-MCP 0.3.0 retains the folder-rule behavior introduced in 0.2.0 and requires the
-matching folder-aware API.
-`get_vard` with `workspaceId` and `vardId` returns editable configuration:
-`items` contains **manual mappings only**, and `folderRules` contains saved rules.
-For a separate current live preview use `get_vard` with `resolved: true`; this is
-not a committed frozen snapshot and can fail on collisions or limits without
-blocking configuration inspection or repair.
-
-`create_vard` accepts `name`, optional `isPublic` (defaults private), and optional
+`create_vard` accepts `name`, optional `isPublic` (defaults private) and optional
 `folderRules` (defaults empty); it does not require a slug. `update_vard` changes
-only supplied fields. For example, call it with:
+only supplied fields. After reading `get_vard`, update rules with:
 
 ```json
 {
   "workspaceId": "your-workspace-id",
   "vardId": "your-vard-id",
+  "expectedRevision": "v1:<copy the original revision from get_vard>",
   "folderRules": [{ "sourcePrefix": "brand/", "outputPrefix": "assets/brand/" }]
 }
 ```
 
-This preserves the Vard's name, public flag and manual item IDs. Send
-`folderRules: []` to remove all rules. `replace_vard_items` replaces only manual
-mappings and does not change rules: **never copy resolved folder outputs into it**.
-The API remains authoritative for workspace permissions and validation; tools
-forward validation, authorization and resolution errors.
+Replace the illustrative token with the unchanged revision from your read. This
+preserves the Vard's name, public flag and manual mappings. Send `folderRules: []`
+to remove all rules. `replace_vard_items` preserves rules.
 
 Rules include ready current originals recursively: `brand/icons/logo.svg` becomes
 `assets/brand/icons/logo.svg`. Generated outputs are read-only, unpinned and
-untransformed; pending files are excluded until ready. Empty prefixes mean workspace
-or project root. Empty/nonexistent folders are valid. Prefixes must be safe literal
-relative directories ending in `/` (or empty), at most 255 characters; no globs or
-excludes. Maximum 64 rules and 1,000 total manual + generated outputs, with paths
-up to 500 characters. Explicit + rule and rule + rule collisions fail, including
-case/Unicode equivalents and file/directory overlaps; no precedence or truncation.
-A new private folder member makes the entire anonymous public manifest unavailable.
-
-Normal `vardum pull` intentionally adopts membership changes; `--frozen` consumes
-the committed snapshot without live resolution. There is no background sync.
-Removing rules leaves source assets/manual mappings intact. Choose `--delete` on
-the membership-updating pull: a normal no-delete pull keeps stale disk files but
-drops their tracking, so a later `--delete` cannot remove them; deliberate manual
-cleanup is then required. See [CLI snapshot limitations](https://github.com/f-tuma/vardum/tree/main/apps/cli#reproducible-asset-consumption)
-and [operations](https://github.com/f-tuma/vardum/blob/main/docs/operations.md#folder-rule-upgrade) before upgrading or rolling back.
+untransformed; pending files are excluded until ready. Empty prefixes mean
+workspace or project root. Empty/nonexistent folders are valid. Prefixes are
+safe literal relative directories ending in `/` (or empty), at most 255
+characters; no globs or excludes. Maximum 64 rules and 1,000 total manual +
+generated outputs, with paths up to 500 characters. Explicit + rule and rule +
+rule collisions fail, including case/Unicode equivalents and file/directory
+overlaps. A new private member blocks the entire anonymous public manifest.
+
+Normal `vardum pull` intentionally adopts membership changes; `--frozen`
+consumes the committed snapshot without live resolution. There is no background
+sync. Removing rules leaves source assets/manual mappings intact. Choose
+`--delete` on the membership-updating pull: a normal no-delete pull keeps stale
+disk files but drops their tracking, so a later `--delete` cannot remove them.
+See [CLI snapshot limitations](https://github.com/f-tuma/vardum/tree/main/apps/cli#reproducible-asset-consumption)
+and [operations](https://github.com/f-tuma/vardum/blob/main/docs/operations.md#folder-rule-upgrade)
+before upgrading or rolling back.

package/dist/index.js

@@ -53,6 +53,19 @@ const headers = {
 };
 if (API_KEY)
     headers["x-api-key"] = API_KEY;
+class VardumHttpError extends Error {
+    responseError;
+    status;
+    code;
+    currentRevision;
+    constructor(responseError, status, code, currentRevision) {
+        super(`${responseError} (${status})`);
+        this.responseError = responseError;
+        this.status = status;
+        this.code = code;
+        this.currentRevision = currentRevision;
+    }
+}
 async function api(path, init = {}) {
     const merged = new Headers(init.headers);
     for (const [k, v] of Object.entries(headers))
@@ -68,14 +81,20 @@ async function api(path, init = {}) {
     const text = await res.text();
     if (!res.ok) {
         let msg = text || res.statusText;
+        let code;
+        let currentRevision;
         try {
             const parsed = JSON.parse(text);
+            if (typeof parsed.code === "string")
+                code = parsed.code;
+            if (typeof parsed.currentRevision === "string")
+                currentRevision = parsed.currentRevision;
             msg = parsed.message ?? parsed.error ?? msg;
         }
         catch {
             /* use body text */
         }
-        throw new Error(`${msg} (${res.status})`);
+        throw new VardumHttpError(msg, res.status, code, currentRevision);
     }
     try {
         return JSON.parse(text);
@@ -84,6 +103,57 @@ async function api(path, init = {}) {
         throw new Error("Invalid JSON response");
     }
 }
+const vardRevision = (value) => typeof value === "string" && /^v1:[a-f0-9]{64}$/.test(value);
+const editorUuid = (value) => typeof value === "string" && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(value);
+async function requireVardEditRevision() {
+    const capabilities = await api("/api/capabilities");
+    if (!capabilities || typeof capabilities !== "object" ||
+        capabilities.vardEditRevision !== 1)
+        throw new Error("This server does not support revision-guarded Vard editing (vardEditRevision: 1); upgrade the server before editing Vards");
+}
+function editorPath(workspaceId, vardId) {
+    return `/api/workspaces/${encodeURIComponent(workspaceId)}/vards/${encodeURIComponent(vardId)}/editor`;
+}
+function validateVardEditor(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid Vard editor definition; upgrade the server and reload before editing");
+    const definition = value;
+    if (definition.schema !== 1 || !vardRevision(definition.revision) ||
+        typeof definition.id !== "string" || typeof definition.workspaceId !== "string" ||
+        typeof definition.name !== "string" || typeof definition.isPublic !== "boolean" ||
+        typeof definition.updatedAt !== "string" || !Array.isArray(definition.folderRules) ||
+        !Array.isArray(definition.items) || definition.items.some((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            return true;
+        const mapping = item;
+        return !editorUuid(mapping.id) || !(mapping.pinnedVersionId === null || editorUuid(mapping.pinnedVersionId));
+    }))
+        throw new Error("Invalid Vard editor definition or missing revision/literal pins; upgrade the server and reload before editing");
+    return value;
+}
+async function editorResult(action) {
+    try {
+        const data = await action();
+        return { content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }] };
+    }
+    catch (error) {
+        if (error instanceof VardumHttpError && error.status === 409 && error.code === "vard_revision_conflict") {
+            const data = {
+                status: error.status,
+                code: error.code,
+                error: error.responseError,
+                currentRevision: error.currentRevision,
+                instruction: "Reload with get_vard, review the current definition, and reapply the intended edit with its revision. Do not retry the stale save.",
+            };
+            return {
+                isError: true,
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                structuredContent: data,
+            };
+        }
+        throw error;
+    }
+}
 // ── Server ─────────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: "Vardum",
@@ -128,6 +198,12 @@ read-only, unpinned, and untransformed. No globs or excludes. Manual + generated
 not collide (including case/Unicode or file/directory overlaps) and total at most 1000.
 get_vard returns editable manual items and folderRules, even if resolution fails. Use
 get_vard with resolved=true for a separate live preview; never persist expanded items.
+get_vard supplies an opaque revision and literal pinnedVersionId for each manual item.
+update_vard, replace_vard_items and delete_vard require the original expectedRevision; a stale
+revision returns vard_revision_conflict. Reload and review before reapplying; never retry blindly.
+replace_vard_items requires each existing manual UUID or null for a new item. Copy the stored
+pinnedVersionId to versionId, including unavailable pins; resolved versionId is not the saved pin.
+These editor tools require vardEditRevision: 1; unsupported servers are refused without legacy writes.
 update_vard replaces only supplied fields; folderRules: [] removes rules without changing manual items.
 A new private folder member makes the whole anonymous public manifest unavailable.
 Normal vardum pull intentionally updates membership; --frozen consumes the committed snapshot.
@@ -366,50 +442,71 @@ server.tool("create_vard", "Create a Vard with optional recursive folder rules,
     });
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
-server.tool("get_vard", "Retrieve editable Vard configuration (manual items and folderRules), even when expansion fails. Set resolved=true for a separate live manifest preview, not a committed frozen snapshot. Never write resolved items back as manual items.", {
+const expectedRevisionInput = z
+    .string()
+    .regex(/^v1:[a-f0-9]{64}$/)
+    .describe("Original opaque revision from get_vard; reload and review after a conflict before reapplying the edit");
+server.tool("get_vard", "Retrieve editable Vard configuration with its revision, manual item IDs and literal pinnedVersionId, even when expansion fails. Requires vardEditRevision: 1. Set resolved=true for a separate live manifest preview without an editing revision; never write resolved items back as manual items.", {
     workspaceId: z.string().describe("Workspace ID"),
     vardId: z.string().describe("Vard ID"),
     resolved: z
         .boolean()
         .optional()
-        .describe("True: resolve current outputs, which may fail on collisions/limits. Omitted/false: editable configuration only."),
+        .describe("True: resolve current outputs, which may fail on collisions/limits. Omitted/false: editable definition and revision only."),
 }, async ({ workspaceId, vardId, resolved }) => {
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/vards/${encodeURIComponent(vardId)}${resolved ? "/manifest" : ""}`);
+    if (resolved) {
+        const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/vards/${encodeURIComponent(vardId)}/manifest`);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+    await requireVardEditRevision();
+    const data = validateVardEditor(await api(editorPath(workspaceId, vardId)));
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
-server.tool("update_vard", "Update only supplied metadata or folderRules; omitted fields and manual item IDs are preserved. folderRules: [] removes rules. Saving valid configuration may still leave a collision/limit error in the live preview; repair rules or manual paths. Requires API update permission.", {
+server.tool("update_vard", "Update supplied metadata or folderRules using the caller's original expectedRevision; returns the full manual-only definition and revision. Omitted fields and manual IDs are preserved; folderRules: [] removes rules. Requires API read+update permission and vardEditRevision: 1. On conflict reload, review and reapply the intended edit; never retry a stale save automatically.", {
     workspaceId: z.string().describe("Workspace ID"),
     vardId: z.string().describe("Vard ID"),
+    expectedRevision: expectedRevisionInput,
     name: z.string().min(1).max(80).optional().describe("New display name"),
     isPublic: z
         .boolean()
         .optional()
         .describe("Public manifest only; does not publish resolved assets"),
     folderRules: folderRulesInput.optional(),
-}, async ({ workspaceId, vardId, name, isPublic, folderRules }) => {
-    const body = {};
+}, async ({ workspaceId, vardId, expectedRevision, name, isPublic, folderRules }) => editorResult(async () => {
+    const body = { expectedRevision };
     if (name !== undefined)
         body.name = name;
     if (isPublic !== undefined)
         body.isPublic = isPublic;
     if (folderRules !== undefined)
         body.folderRules = folderRules;
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/vards/${encodeURIComponent(vardId)}`, { method: "PATCH", body: JSON.stringify(body) });
-    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
-});
-server.tool("delete_vard", "Delete a Vard and all its output configurations permanently.", {
+    await requireVardEditRevision();
+    return validateVardEditor(await api(editorPath(workspaceId, vardId), {
+        method: "PATCH", body: JSON.stringify(body),
+    }));
+}));
+server.tool("delete_vard", "Delete a Vard and all output configurations permanently using the caller's original expectedRevision. Requires API delete permission and vardEditRevision: 1. On conflict reload and review before deciding to delete again.", {
     workspaceId: z.string().describe("Workspace ID"),
     vardId: z.string().describe("Vard ID"),
-}, async ({ workspaceId, vardId }) => {
-    await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/vards/${encodeURIComponent(vardId)}`, { method: "DELETE" });
-    return { content: [{ type: "text", text: "Vard deleted." }] };
-});
-server.tool("replace_vard_items", "Replace only manual items in a Vard; folderRules are unchanged. Never pass expanded folder outputs here. Each manual item maps an asset to an output path and optional transformation settings.", {
+    expectedRevision: expectedRevisionInput,
+}, async ({ workspaceId, vardId, expectedRevision }) => editorResult(async () => {
+    await requireVardEditRevision();
+    const query = new URLSearchParams({ expectedRevision });
+    await api(editorPath(workspaceId, vardId) + `?${query}`, { method: "DELETE" });
+    return "Vard deleted.";
+}));
+server.tool("replace_vard_items", "Replace manual items using the caller's original expectedRevision; returns the full definition and revision. Keep existing manual IDs, use null for new IDs, and copy pinnedVersionId to versionId literally, including unavailable pins; never infer a pin from resolved versionId or pass expanded folder outputs. Requires API read+update permission and vardEditRevision: 1. On conflict reload, review and reapply the intended edit; never retry a stale list automatically.", {
     workspaceId: z.string().describe("Workspace ID"),
     vardId: z.string().describe("Vard ID"),
+    expectedRevision: expectedRevisionInput,
     items: z
         .array(z
         .object({
+        id: z
+            .string()
+            .uuid()
+            .nullable()
+            .describe("Existing manual item UUID to preserve identity, or null to create a new manual item"),
         assetId: z.string().describe("The asset ID to include"),
         outputPath: z
             .string()
@@ -421,19 +518,20 @@ server.tool("replace_vard_items", "Replace only manual items in a Vard; folderRu
             .string()
             .uuid()
             .nullable()
-            .optional()
-            .describe("Exact ready version ID to pin; null/omitted follows latest. Pinned outputs must not be writable."),
+            .describe("Literal saved pin: copy pinnedVersionId from get_vard, never resolved versionId. Null follows latest. Pinned outputs must not be writable."),
         transformation: z
             .record(z.unknown())
             .nullable()
             .describe("Optional transformation parameters (w, h, fit, format, q) or null"),
     })
         .strict())
-        .describe("Complete list of manual items to set (replaces manual items only)"),
-}, async ({ workspaceId, vardId, items }) => {
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/vards/${encodeURIComponent(vardId)}/items`, { method: "PUT", body: JSON.stringify({ items }) });
-    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
-});
+        .describe("Complete manual item list only; folderRules are preserved"),
+}, async ({ workspaceId, vardId, expectedRevision, items }) => editorResult(async () => {
+    await requireVardEditRevision();
+    return validateVardEditor(await api(editorPath(workspaceId, vardId) + "/items", {
+        method: "PUT", body: JSON.stringify({ expectedRevision, items }),
+    }));
+}));
 // ── Main ────────────────────────────────────────────────────────────────────
 async function main() {
     if (!API_KEY) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vardum/mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "MCP server for workspace-scoped Vardum assets and Vards",
   "license": "MIT",
   "type": "module",
@@ -19,7 +19,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.31.0",
-    "@vardum/shared": "^0.3.0",
+    "@vardum/shared": "^0.4.0",
     "zod": "^3.24.0"
   },
   "devDependencies": {