@vardum/mcp 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vardum 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,19 +1,30 @@
 # @vardum/mcp
 
 MCP server for [Vardum](https://vardum.com): lets an AI agent manage assets,
-Vards, workspaces, members, API keys and custom domains through the same API
-the dashboard and the CLI use.
+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
 
 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 carries the permissions of whoever created it.
+key is restricted to that workspace and its selected read/write permissions.
+Copy the workspace ID from Settings → General for tool calls.
+
+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 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`.
 
 Claude Code:
 
 ```sh
-claude mcp add vardum --env VARDUM_API_KEY=varda_... -- npx -y @vardum/mcp
+claude mcp add vardum --env VARDUM_API_KEY=varda_... -- npx -y @vardum/mcp@0.3.0
 ```
 
 Any client that reads a JSON config (Claude Desktop, Cursor, …):
@@ -23,7 +34,7 @@ Any client that reads a JSON config (Claude Desktop, Cursor, …):
   "mcpServers": {
     "vardum": {
       "command": "npx",
-      "args": ["-y", "@vardum/mcp"],
+      "args": ["-y", "@vardum/mcp@0.3.0"],
       "env": { "VARDUM_API_KEY": "varda_..." }
     }
   }
@@ -43,11 +54,82 @@ client can start the binary at all.
 
 ## Tools
 
-Assets (`list_assets`, `create_asset`, `upload_asset_version`, `delete_asset`),
-Vards (`list_vards`, `create_vard`, `get_vard`, `update_vard`, `delete_vard`,
-`replace_vard_items`), workspaces (`list_organizations`, `create_workspace`,
-`get_workspace`, `update_workspace`), members and invitations, API keys, and
-custom domains (`get_domain`, `configure_domain`, `verify_domain`).
+The 11 tools are:
+
+| Area | Tools |
+| --- | --- |
+| Assets | `list_assets`, `create_asset`, `upload_asset_version`, `set_asset_visibility`, `delete_asset` |
+| 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.
+
+`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.
+
+## 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.
+
+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.
+
+## 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
+`folderRules` (defaults empty); it does not require a slug. `update_vard` changes
+only supplied fields. For example, call it with:
+
+```json
+{
+  "workspaceId": "your-workspace-id",
+  "vardId": "your-vard-id",
+  "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.
+
+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.

package/dist/index.js

@@ -2,7 +2,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { supportedMimeTypes } from "@vardum/shared";
+import { supportedMimeTypes, } from "@vardum/shared";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -87,7 +87,7 @@ async function api(path, init = {}) {
 // ── Server ─────────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: "Vardum",
-    version: "0.1.0",
+    version: VERSION,
 });
 // ── Resources ──────────────────────────────────────────────────────────────
 server.resource("constraints", "vardum://constraints", () => ({
@@ -97,7 +97,7 @@ server.resource("constraints", "vardum://constraints", () => ({
             text: `# Vardum Constraints
 
 ## Slug immutability
-Organization, workspace and Vard slugs are set at creation time and **cannot be changed**.
+Organization and workspace slugs are set at creation time and **cannot be changed**.
 Each slug must match \`[a-z0-9][a-z0-9._-]*\`.
 
 ## Asset key rules
@@ -111,9 +111,29 @@ Every asset has a unique key scoped to a workspace. Rules:
 - Image types: AVIF, GIF, JPEG, PNG, SVG, TIFF, WebP
 - Video types: MP4, WebM, MOV, AVI, MPEG
 - Max 100 megapixels per image; videos are stored as-is (no transcode)
-- Storage backend caps at 100 MiB per upload
+- Per-upload size ceiling is set by the server, and differs for images and videos (the API rejects anything over it)
 - Video assets cannot be resized or transformed into variants (images only)
 
+## Asset visibility
+New assets are private. Use set_asset_visibility with publish permission to change visibility.
+Public assets expose every ready version and its variants without authentication.
+A public Vard does not publish its assets: anonymous manifests require all mapped assets to be public.
+Making an asset private cannot revoke previously downloaded or cached copies.
+
+## Folder inclusion
+Vards support up to 64 literal recursive sourcePrefix → outputPrefix rules (255 characters each).
+Example: brand/ → assets/brand/. Empty prefixes mean root; empty/nonexistent folders are valid.
+Only ready current originals are included; pending files wait until ready. Generated outputs are
+read-only, unpinned, and untransformed. No globs or excludes. Manual + generated outputs must
+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.
+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.
+There is no background sync. Choose --delete on the membership-updating pull: without it,
+stale files remain but lose tracking, requiring deliberate manual cleanup later.
+
 ## Writable outputs
 Only Vard items explicitly marked "Writable" in the UI can be pushed to.
 Pinned and transformed outputs are always read-only.`,
@@ -156,7 +176,7 @@ Folders exist only as key prefixes — no need to "create" them.
 - **editor**: full CRUD on assets, Vards, and presets
 - **owner**: workspace administration (members, API keys, domain, deletion)
 
-A workspace API key carries the permissions of whoever created it, nothing more.
+MCP uses a workspace-scoped asset key. Members, invitations, keys, domains and workspace administration require a browser session and are managed in the web app.
 
 ## Video assets
 MP4, WebM, MOV, AVI and MPEG are accepted. They are stored and delivered as-is —
@@ -196,142 +216,42 @@ Everything an editor can do, plus:
 - Full audit log access
 
 ## API key scoping
-A workspace API key inherits the permissions of the person who created it.
-A key can never grant more access than its creator has. Self-revocation
+MCP exposes asset and Vard tools only. A read key can list/read; a write key adds
+create, update, delete and publish. Keys are restricted to one workspace and do
+not grant browser-session administration, even when created by an owner. Self-revocation
 (\`vardum logout\`) is available to CLI keys without workspace admin access.`,
         },
     ],
 }));
-// ── Tools: Workspace ────────────────────────────────────────────────────────
-server.tool("list_organizations", "List all organizations the authenticated user belongs to.", {}, async () => {
-    const data = await api("/api/organizations");
-    return {
-        content: [
-            { type: "text", text: JSON.stringify(data.organizations, null, 2) },
-        ],
-    };
-});
-server.tool("create_workspace", "Create a new workspace inside an organization.", {
-    organizationId: z.string().describe("Organization ID"),
-    name: z.string().min(1).max(64).describe("Display name for the workspace"),
-    slug: z
-        .string()
-        .regex(/^[a-z0-9][a-z0-9._-]*$/)
-        .describe("URL-safe slug (cannot be changed later)"),
-}, async ({ organizationId, name, slug }) => {
-    const data = await api(`/api/organizations/${encodeURIComponent(organizationId)}/workspaces`, { method: "POST", body: JSON.stringify({ name, slug }) });
-    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
-});
-server.tool("get_workspace", "Retrieve workspace details including name, slug, and member count.", { workspaceId: z.string().describe("Workspace ID") }, async ({ workspaceId }) => {
-    const [members, overview] = await Promise.all([
-        api(`/api/workspaces/${encodeURIComponent(workspaceId)}/members`),
-        api(`/api/workspaces/${encodeURIComponent(workspaceId)}/overview`),
-    ]);
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({ ...overview, members: members.members }, null, 2),
-            },
-        ],
-    };
-});
-server.tool("update_workspace", "Update the display name of a workspace. The slug cannot be changed.", {
-    workspaceId: z.string().describe("Workspace ID"),
-    name: z.string().min(1).max(64).describe("New display name"),
-}, async ({ workspaceId, name }) => {
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}`, { method: "PATCH", body: JSON.stringify({ name }) });
-    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
-});
-// ── Tools: Members & Invitations ────────────────────────────────────────────
-server.tool("list_members", "List all members of a workspace with their roles.", { workspaceId: z.string().describe("Workspace ID") }, async ({ workspaceId }) => {
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/members`);
-    return {
-        content: [{ type: "text", text: JSON.stringify(data.members, null, 2) }],
-    };
-});
-server.tool("change_member_role", "Change a member's role in the workspace.", {
-    workspaceId: z.string().describe("Workspace ID"),
-    memberId: z.string().describe("Member ID"),
-    role: z.enum(["owner", "editor", "viewer"]).describe("New role"),
-}, async ({ workspaceId, memberId, role }) => {
-    await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/members/${encodeURIComponent(memberId)}`, { method: "PATCH", body: JSON.stringify({ role }) });
-    return { content: [{ type: "text", text: `Role changed to ${role}.` }] };
-});
-server.tool("list_invitations", "List pending invitations for a workspace.", { workspaceId: z.string().describe("Workspace ID") }, async ({ workspaceId }) => {
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/invitations`);
-    return {
-        content: [
-            { type: "text", text: JSON.stringify(data.invitations, null, 2) },
-        ],
-    };
-});
-server.tool("create_invitation", "Invite someone by email to join a workspace with a specific role.", {
-    workspaceId: z.string().describe("Workspace ID"),
-    email: z.string().email().describe("Recipient email address"),
-    role: z
-        .enum(["editor", "viewer"])
-        .describe("Role to assign (owner cannot be invited directly)"),
-}, async ({ workspaceId, email, role }) => {
-    await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/invitations`, { method: "POST", body: JSON.stringify({ email, role }) });
-    return {
-        content: [
-            { type: "text", text: `Invitation sent to ${email} (${role}).` },
-        ],
-    };
-});
-server.tool("revoke_invitation", "Revoke a pending invitation before it expires.", {
-    workspaceId: z.string().describe("Workspace ID"),
-    invitationId: z.string().describe("Invitation ID"),
-}, async ({ workspaceId, invitationId }) => {
-    await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/invitations/${encodeURIComponent(invitationId)}`, { method: "DELETE" });
-    return { content: [{ type: "text", text: "Invitation revoked." }] };
-});
-// ── Tools: API Keys ─────────────────────────────────────────────────────────
-server.tool("list_api_keys", "List all API keys for a workspace.", { workspaceId: z.string().describe("Workspace ID") }, async ({ workspaceId }) => {
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/api-keys`);
-    return {
-        content: [{ type: "text", text: JSON.stringify(data.keys, null, 2) }],
-    };
-});
-server.tool("create_api_key", "Create a new API key for a workspace. The full key is shown only once.", {
-    workspaceId: z.string().describe("Workspace ID"),
-    name: z
-        .string()
-        .min(1)
-        .max(32)
-        .describe("Human-readable label for the key"),
-    access: z
-        .enum(["read", "write"])
-        .describe("Access level: read-only or read-write"),
-}, async ({ workspaceId, name, access }) => {
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/api-keys`, {
-        method: "POST",
-        body: JSON.stringify({ name, access }),
-    });
-    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
-});
-server.tool("revoke_api_key", "Revoke (delete) an API key by ID.", {
-    workspaceId: z.string().describe("Workspace ID"),
-    keyId: z.string().describe("API key ID to revoke"),
-}, async ({ workspaceId, keyId }) => {
-    await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/api-keys/${encodeURIComponent(keyId)}`, { method: "DELETE" });
-    return { content: [{ type: "text", text: "API key revoked." }] };
-});
 // ── Tools: Assets ───────────────────────────────────────────────────────────
-server.tool("list_assets", "List assets in a workspace, optionally filtered by prefix (virtual folder).", {
+server.tool("list_assets", "List one page of ready assets and visibility, optionally filtered by prefix. Pass nextCursor as cursor to continue; null means the end.", {
     workspaceId: z.string().describe("Workspace ID"),
     prefix: z
         .string()
         .optional()
         .describe("Prefix filter (e.g. 'icons/' to list only that folder)"),
-}, async ({ workspaceId, prefix = "" }) => {
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/sync/assets?prefix=${encodeURIComponent(prefix)}&limit=500`);
+    cursor: z
+        .string()
+        .max(255)
+        .optional()
+        .describe("nextCursor from the previous page"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .optional()
+        .describe("Page size, default 100"),
+}, async ({ workspaceId, prefix = "", cursor, limit = 100 }) => {
+    const query = new URLSearchParams({ prefix, limit: String(limit) });
+    if (cursor !== undefined)
+        query.set("cursor", cursor);
+    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/sync/assets?${query}`);
     return {
-        content: [{ type: "text", text: JSON.stringify(data.assets, null, 2) }],
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
     };
 });
-server.tool("create_asset", "Create a new asset record with a key. Use upload_version to attach image data.", {
+server.tool("create_asset", "Create a private asset record with a key. Use upload_asset_version to attach media, then set_asset_visibility to publish explicitly.", {
     workspaceId: z.string().describe("Workspace ID"),
     key: z
         .string()
@@ -340,7 +260,20 @@ server.tool("create_asset", "Create a new asset record with a key. Use upload_ve
         .describe("Asset key (use / for folder structure)"),
     displayName: z.string().min(1).describe("Human-readable filename"),
 }, async ({ workspaceId, key, displayName }) => {
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/assets`, { method: "POST", body: JSON.stringify({ key, displayName }) });
+    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/assets`, {
+        method: "POST",
+        body: JSON.stringify({ key, displayName }),
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("set_asset_visibility", "Set asset visibility with publish permission. Public exposes every ready version and variant. Private requires workspace read access but cannot revoke downloaded or cached copies. Vard visibility is independent.", {
+    workspaceId: z.string().min(1).describe("Workspace ID"),
+    assetId: z.string().uuid().describe("Asset ID"),
+    isPublic: z
+        .boolean()
+        .describe("True to publish; false to require workspace read access"),
+}, async ({ workspaceId, assetId, isPublic }) => {
+    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/assets/${encodeURIComponent(assetId)}/visibility`, { method: "PATCH", body: JSON.stringify({ isPublic }) });
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
 server.tool("delete_asset", "Delete an asset and all its versions permanently.", {
@@ -398,42 +331,69 @@ server.tool("list_vards", "List all Vards in a workspace.", { workspaceId: z.str
         content: [{ type: "text", text: JSON.stringify(data.vards, null, 2) }],
     };
 });
-server.tool("create_vard", "Create a new Vard in a workspace. The slug cannot be changed later.", {
-    workspaceId: z.string().describe("Workspace ID"),
-    name: z.string().min(1).max(128).describe("Display name"),
-    slug: z
+const folderRulesInput = z
+    .array(z
+    .object({
+    sourcePrefix: z
+        .string()
+        .max(255)
+        .describe("Literal recursive source directory, slash-terminated; empty means workspace root"),
+    outputPrefix: z
         .string()
-        .regex(/^[a-z0-9][a-z0-9._-]*$/)
-        .describe("URL-safe slug (immutable)"),
+        .max(255)
+        .describe("Relative destination directory, slash-terminated; empty means project root"),
+})
+    .strict())
+    .max(64)
+    .describe("Complete folder rule list; [] removes all rules. API validates safe prefixes. Ready current originals only, no globs; 1000 combined outputs maximum.");
+server.tool("create_vard", "Create a Vard with optional recursive folder rules, private by default. Rules generate read-only originals separately from manual items.", {
+    workspaceId: z.string().describe("Workspace ID"),
+    name: z.string().min(1).max(80).describe("Display name"),
     isPublic: z
         .boolean()
         .optional()
-        .describe("Whether the Vard is publicly accessible"),
-}, async ({ workspaceId, name, slug, isPublic }) => {
+        .describe("Public manifest; every resolved asset must also be public for anonymous access"),
+    folderRules: folderRulesInput.optional(),
+}, async ({ workspaceId, name, isPublic, folderRules }) => {
+    const body = { name };
+    if (isPublic !== undefined)
+        body.isPublic = isPublic;
+    if (folderRules !== undefined)
+        body.folderRules = folderRules;
     const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/vards`, {
         method: "POST",
-        body: JSON.stringify({ name, slug, isPublic }),
+        body: JSON.stringify(body),
     });
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
-server.tool("get_vard", "Retrieve a Vard and its full manifest (items, outputs, their versions and download URLs).", {
+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.", {
     workspaceId: z.string().describe("Workspace ID"),
     vardId: z.string().describe("Vard ID"),
-}, async ({ workspaceId, vardId }) => {
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/vards/${encodeURIComponent(vardId)}`);
+    resolved: z
+        .boolean()
+        .optional()
+        .describe("True: resolve current outputs, which may fail on collisions/limits. Omitted/false: editable configuration only."),
+}, async ({ workspaceId, vardId, resolved }) => {
+    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/vards/${encodeURIComponent(vardId)}${resolved ? "/manifest" : ""}`);
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 });
-server.tool("update_vard", "Update a Vard's metadata (name, public flag). The slug is immutable.", {
+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.", {
     workspaceId: z.string().describe("Workspace ID"),
     vardId: z.string().describe("Vard ID"),
-    name: z.string().min(1).max(128).optional().describe("New display name"),
-    isPublic: z.boolean().optional().describe("Public accessibility"),
-}, async ({ workspaceId, vardId, name, isPublic }) => {
+    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 = {};
     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) }] };
 });
@@ -444,11 +404,12 @@ server.tool("delete_vard", "Delete a Vard and all its output configurations perm
     await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/vards/${encodeURIComponent(vardId)}`, { method: "DELETE" });
     return { content: [{ type: "text", text: "Vard deleted." }] };
 });
-server.tool("replace_vard_items", "Replace every item in a Vard with a new set of item definitions. Each item maps an asset to an output path and optional transformation settings.", {
+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.", {
     workspaceId: z.string().describe("Workspace ID"),
     vardId: z.string().describe("Vard ID"),
     items: z
-        .array(z.object({
+        .array(z
+        .object({
         assetId: z.string().describe("The asset ID to include"),
         outputPath: z
             .string()
@@ -456,38 +417,23 @@ server.tool("replace_vard_items", "Replace every item in a Vard with a new set o
         writable: z
             .boolean()
             .describe("Whether this output can be pushed back"),
-        pinned: z
-            .boolean()
-            .describe("Whether the version is pinned (read-only)"),
+        versionId: z
+            .string()
+            .uuid()
+            .nullable()
+            .optional()
+            .describe("Exact ready version ID to pin; null/omitted 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"),
-    }))
-        .describe("Complete list of items to set (replaces all current items)"),
+    })
+        .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) }] };
 });
-// ── Domain ─────────────────────────────────────────────────────────────────
-server.tool("get_domain", "Get the current custom domain configuration for a workspace.", { workspaceId: z.string().describe("Workspace ID") }, async ({ workspaceId }) => {
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/domain`);
-    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
-});
-server.tool("configure_domain", "Configure a custom domain for a workspace. Requires DNS verification (TXT + CNAME).", {
-    workspaceId: z.string().describe("Workspace ID"),
-    domain: z.string().describe("Domain name (e.g. assets.example.com)"),
-}, async ({ workspaceId, domain }) => {
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/domain`, {
-        method: "PUT",
-        body: JSON.stringify({ domain }),
-    });
-    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
-});
-server.tool("verify_domain", "Trigger domain verification. The agent should first read the current domain config to show the required DNS records, then call this once they are in place.", { workspaceId: z.string().describe("Workspace ID") }, async ({ workspaceId }) => {
-    const data = await api(`/api/workspaces/${encodeURIComponent(workspaceId)}/domain/verify`, { method: "POST" });
-    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
-});
 // ── Main ────────────────────────────────────────────────────────────────────
 async function main() {
     if (!API_KEY) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vardum/mcp",
-  "version": "0.1.0",
-  "description": "MCP server for Vardum \u2014 let AI agents manage assets, Vards, workspaces, and more.",
+  "version": "0.3.0",
+  "description": "MCP server for workspace-scoped Vardum assets and Vards",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -14,21 +14,30 @@
   "engines": {
     "node": ">=22"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "pnpm build",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
-  },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.15.0",
-    "@vardum/shared": "workspace:^",
+    "@modelcontextprotocol/sdk": "1.31.0",
+    "@vardum/shared": "^0.3.0",
     "zod": "^3.24.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "typescript": "5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/f-tuma/vardum.git",
+    "directory": "apps/mcp"
+  },
+  "homepage": "https://github.com/f-tuma/vardum/tree/main/apps/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/f-tuma/vardum/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --import tsx --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   }
-}
+}