@vardum/mcp 0.4.0 → 0.4.2

package/README.md

@@ -4,29 +4,32 @@ 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.
 
-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.
+This README describes [MCP **0.4.2**](https://www.npmjs.com/package/@vardum/mcp/v/0.4.2),
+including revision-guarded Vard editing and recipe help for backgrounds, safe
+area and SVG rendering. The matching client batch uses
+[CLI **0.8.3**](https://www.npmjs.com/package/@vardum/cli/v/0.8.3) and
+[shared **0.4.2**](https://www.npmjs.com/package/@vardum/shared/v/0.4.2).
+The same 11 tools and editor protocol remain; the MCP SDK is now 1.32.1.
+Older 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.
 
 ## Setup
 
 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
+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.
 
-**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).
+These configurations pin **MCP 0.4.2** and need no source-repository access.
+Deploy a server advertising `vardEditRevision: 1` from `GET /api/capabilities`
+before editable Vard reads or mutations; there is no legacy-edit fallback.
+Use a read key for inspection or a key with the required write permissions for
+mutation. Keep real keys in the client's private configuration, never in Git.
 
 Claude Code:
 
 ```sh
-claude mcp add vardum --env VARDUM_API_KEY=varda_... -- npx -y @vardum/mcp@0.4.0
+claude mcp add vardum --env VARDUM_API_KEY=varda_... -- npx -y @vardum/mcp@0.4.2
 ```
 
 Any client that reads a JSON config (Claude Desktop, Cursor, …):
@@ -36,17 +39,13 @@ Any client that reads a JSON config (Claude Desktop, Cursor, …):
   "mcpServers": {
     "vardum": {
       "command": "npx",
-      "args": ["-y", "@vardum/mcp@0.4.0"],
+      "args": ["-y", "@vardum/mcp@0.4.2"],
       "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 |
@@ -86,8 +85,9 @@ Use `set_asset_visibility` with `workspaceId`, `assetId`, and an explicit boolea
 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. The server must implement asset visibility, enforce workspace read access to
+private version/variant URLs, and require publish permission for visibility changes.
+Installing this package does not add those backend capabilities.
 
 ## Guarded editing
 
@@ -123,7 +123,35 @@ A stale write returns a structured MCP tool error (`isError: true`) with
 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).
+An unresolved preview never permits bypassing the revision check or writing
+expanded folder outputs as manual mappings.
+
+## Output recipes
+
+The `replace_vard_items` transformation help describes these optional fields:
+
+| Field | Contract |
+| --- | --- |
+| `bg` | Opaque six-digit `#rrggbb` output background; requires an explicit format |
+| `pad` | 0–45 percent inset on each edge, at most two decimals; positive values require `w`, `h`, a format and `fit: "contain"` |
+| `format: "svg"` | Vector output from a passive geometric SVG, with contain fit and no `q` |
+| `layer` | Existing SVG group ID; preserves the source canvas and ancestor transforms |
+| `darkLayer` + `darkColor` | Paired SVG-only dark-mode color change for filled shapes in one group |
+| `render: "v2"` | Explicit SVG-to-raster renderer; requires a raster format and `bg` |
+
+For example, use this transformation for a new background-backed PNG:
+
+```json
+{ "w": 256, "h": 256, "fit": "contain", "format": "png", "bg": "#f4f0e8", "pad": 12.5, "render": "v2" }
+```
+
+Copy existing transformations literally when editing. Omitting `render` retains
+the legacy renderer; do not add `"v2"` to existing mappings automatically.
+Use a matching server that implements these API and renderer features.
+`vardEditRevision: 1` proves the guarded-editor contract only; it does not
+advertise SVG, safe-area or v2 support. The server validates combinations and
+source types. Group selection and SVG output require the supported passive
+geometric SVG subset; unsupported inputs fail without a fallback.
 
 ## Folder rules
 
@@ -159,6 +187,20 @@ 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.
+The CLI snapshot records locked URLs and byte checksums, not an archive. Frozen
+restore needs those versions and URLs to remain reachable with the required read
+permission. Source-key or workspace-slug renames, deleted versions, signing-key
+rotation, expired signatures or changed transformation bytes can break an old
+snapshot; checksum failure never falls back to latest. Do not assume a rule removal
+or a successful live preview proves historical frozen restores.
+
+## Self-hosted backend
+
+The matching backend exposes `GET /api/capabilities` with `vardEditRevision: 1`
+and dedicated `/editor` endpoints. Guarded editing needs no migration beyond the
+upload/import baseline through `0015_upload_request_checksum.sql`. Folder rules
+need recursive ready-original resolution with the collision/limit rules above.
+Asset uploads need `GET /api/upload-limits`, accepted MIME validation and ready
+version processing. Images and videos have separate byte limits; video delivery
+keeps original bytes without transformation variants. Verify the actual instance
+before granting an agent write permissions.

package/dist/index.js

@@ -522,7 +522,7 @@ server.tool("replace_vard_items", "Replace manual items using the caller's origi
         transformation: z
             .record(z.unknown())
             .nullable()
-            .describe("Optional transformation parameters (w, h, fit, format, q) or null"),
+            .describe("Optional transformation parameters (w, h, fit, format, q, bg, pad, layer, darkLayer, darkColor, render) or null. bg is an opaque #rrggbb background and requires an explicit output format. For new SVG-to-raster recipes with bg, set render to v2 to rasterize vectors at the requested size before compositing. Omit render on existing recipes to preserve their renderer identity. render v2 requires an SVG source, raster format and bg. pad is a 0–45 percent inset per edge, with at most two decimals; positive pad requires w, h, a format and fit contain. SVG output requires a passive geometric SVG source, contain fit and no q. layer selects a named SVG group while preserving its canvas. darkLayer plus darkColor adapts one SVG group to dark mode. Omit bg for transparent padding."),
     })
         .strict())
         .describe("Complete manual item list only; folderRules are preserved"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vardum/mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "MCP server for workspace-scoped Vardum assets and Vards",
   "license": "MIT",
   "type": "module",
@@ -18,8 +18,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.31.0",
-    "@vardum/shared": "^0.4.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@vardum/shared": "^0.4.2",
     "zod": "^3.24.0"
   },
   "devDependencies": {
@@ -31,7 +31,7 @@
     "url": "git+https://github.com/f-tuma/vardum.git",
     "directory": "apps/mcp"
   },
-  "homepage": "https://github.com/f-tuma/vardum/tree/main/apps/mcp#readme",
+  "homepage": "https://vardum.com",
   "bugs": {
     "url": "https://github.com/f-tuma/vardum/issues"
   },