@collage-dam/mcp-server 0.1.0

package/dist/tools/update-collection.js

@@ -0,0 +1,142 @@
+// ── update_collection ────────────────────────────────────────────────
+// Updates the metadata (name, description) on an existing Collage
+// collection. Does NOT touch membership — use add_to_collection /
+// remove_from_collection for that.
+//
+// Upstream surface:
+//   POST digital-assets/collection/update/{id}
+//     body: { name?, description?, workspace_id }
+//     returns: { data: { id, name, description, ... }, message }
+import { z } from 'zod';
+import { MutatingTool, } from '../conventions/dry-run/index.js';
+import { createToolError } from '../conventions/errors.js';
+import { IdSchema } from '../types.js';
+// ── Tool I/O Schema ──────────────────────────────────────────────────
+export const UpdateCollectionInputSchema = z
+    .object({
+    collection_id: IdSchema,
+    name: z.string().min(1).max(255).optional(),
+    description: z.string().max(10_000).nullable().optional(),
+})
+    .refine((input) => input.name !== undefined || input.description !== undefined, {
+    message: 'At least one of `name` or `description` must be provided to update_collection.',
+});
+export const UPDATE_COLLECTION_DESCRIPTION = 'Update name and/or description on a single Collage collection. Does NOT ' +
+    'modify membership — use add_to_collection / remove_from_collection for ' +
+    'that. Two-step: first call returns a preview plus a confirmation_token; ' +
+    'second call (with the token) applies the change and returns a per-item ' +
+    'ledger.';
+export class UpdateCollectionTool extends MutatingTool {
+    name = 'update_collection';
+    chunkSize = 1;
+    client;
+    constructor(deps) {
+        super(deps);
+        this.client = deps.client;
+    }
+    async plan(input) {
+        const id = String(input.collection_id);
+        const snapshot = await this.client.getCollectionMetadata(id);
+        if (!snapshot.ok) {
+            throw new Error(`failed to read current metadata for collection ${id}: ${snapshot.error.code} — ${snapshot.error.message}`);
+        }
+        const before = {};
+        const after = {};
+        const fieldsChanged = [];
+        let nameOverwrite = false;
+        let descriptionOverwrite = false;
+        if (input.name !== undefined) {
+            before['name'] = snapshot.snapshot.name;
+            after['name'] = input.name;
+            if (snapshot.snapshot.name !== input.name) {
+                fieldsChanged.push('name');
+                if (snapshot.snapshot.name !== null &&
+                    snapshot.snapshot.name !== '' &&
+                    snapshot.snapshot.name !== input.name) {
+                    nameOverwrite = true;
+                }
+            }
+        }
+        if (input.description !== undefined) {
+            before['description'] = snapshot.snapshot.description;
+            after['description'] = input.description;
+            if (snapshot.snapshot.description !== input.description) {
+                fieldsChanged.push('description');
+                if (snapshot.snapshot.description !== null &&
+                    snapshot.snapshot.description !== '' &&
+                    snapshot.snapshot.description !== input.description) {
+                    descriptionOverwrite = true;
+                }
+            }
+        }
+        const change = {
+            id,
+            operation: 'update',
+            before,
+            after,
+            metadata: {
+                ...(input.name !== undefined ? { name: input.name } : {}),
+                ...(input.description !== undefined
+                    ? { description: input.description }
+                    : {}),
+            },
+        };
+        const riskFlags = [];
+        if (fieldsChanged.length === 0) {
+            riskFlags.push({
+                code: 'noop_collection_update',
+                severity: 'info',
+                message: 'all proposed values match current values (no-op)',
+                count: 1,
+            });
+        }
+        const overwriteCount = (nameOverwrite ? 1 : 0) + (descriptionOverwrite ? 1 : 0);
+        if (overwriteCount > 0) {
+            riskFlags.push({
+                code: 'collection_metadata_overwrite',
+                severity: 'warning',
+                message: 'will overwrite existing values on this collection',
+                count: overwriteCount,
+            });
+        }
+        return {
+            changes: [change],
+            riskFlags,
+            extraAggregates: {
+                fields_changed: fieldsChanged.length,
+                overwrites: overwriteCount,
+            },
+        };
+    }
+    apply = async (change) => {
+        const meta = (change.metadata ?? {});
+        const patch = {};
+        const fieldsUpdated = [];
+        if (meta.name !== undefined) {
+            patch.name = meta.name;
+            fieldsUpdated.push('name');
+        }
+        if (meta.description !== undefined) {
+            patch.description = meta.description;
+            fieldsUpdated.push('description');
+        }
+        if (fieldsUpdated.length === 0) {
+            return {
+                ok: false,
+                error: createToolError('VALIDATION', `change ${change.id} carries no metadata patch`),
+            };
+        }
+        const result = await this.client.updateCollectionMetadata(change.id, patch);
+        if (!result.ok) {
+            return { ok: false, error: result.error };
+        }
+        return {
+            ok: true,
+            result: { collection_id: change.id, fields_updated: fieldsUpdated },
+        };
+    };
+}
+export function buildUpdateCollectionTool(deps) {
+    return new UpdateCollectionTool(deps);
+}
+//# sourceMappingURL=update-collection.js.map

package/dist/tools/update-collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-collection.js","sourceRoot":"","sources":["../../src/tools/update-collection.ts"],"names":[],"mappings":"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"}

package/dist/tools/view-category-contents.d.ts

@@ -0,0 +1,231 @@
+import { z } from 'zod';
+import type { CollageClient } from '../client.js';
+export declare const ViewCategoryContentsInputSchema: z.ZodObject<{
+    category_id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+    cursor: z.ZodOptional<z.ZodString>;
+    page_size: z.ZodOptional<z.ZodNumber>;
+    sort_by: z.ZodOptional<z.ZodEnum<["ASC", "DESC"]>>;
+    sort_value: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    category_id: string | number;
+    sort_by?: "ASC" | "DESC" | undefined;
+    sort_value?: string | undefined;
+    cursor?: string | undefined;
+    page_size?: number | undefined;
+}, {
+    category_id: string | number;
+    sort_by?: "ASC" | "DESC" | undefined;
+    sort_value?: string | undefined;
+    cursor?: string | undefined;
+    page_size?: number | undefined;
+}>;
+export type ViewCategoryContentsInput = z.infer<typeof ViewCategoryContentsInputSchema>;
+export declare const ViewCategoryContentsOutputSchema: z.ZodObject<{
+    category_id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+    subcategories: z.ZodArray<z.ZodObject<{
+        id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+        workspace_id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+        user_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodNumber, z.ZodString]>>>;
+        parent_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodNumber, z.ZodString]>>>;
+        folder_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        category_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        integration_type: z.ZodOptional<z.ZodNumber>;
+        created_at: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodString]>>>;
+        updated_at: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodString]>>>;
+    }, "strip", z.ZodTypeAny, {
+        workspace_id: string | number;
+        id: string | number;
+        folder_name?: string | null | undefined;
+        parent_id?: string | number | null | undefined;
+        user_id?: string | number | null | undefined;
+        created_at?: string | null | undefined;
+        updated_at?: string | null | undefined;
+        category_path?: string | null | undefined;
+        integration_type?: number | undefined;
+    }, {
+        workspace_id: string | number;
+        id: string | number;
+        folder_name?: string | null | undefined;
+        parent_id?: string | number | null | undefined;
+        user_id?: string | number | null | undefined;
+        created_at?: string | null | undefined;
+        updated_at?: string | null | undefined;
+        category_path?: string | null | undefined;
+        integration_type?: number | undefined;
+    }>, "many">;
+    assets: z.ZodArray<z.ZodObject<{
+        id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+        display_file_name: z.ZodOptional<z.ZodString>;
+        file_name: z.ZodOptional<z.ZodString>;
+        category_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodNumber, z.ZodString]>>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+            tag_name: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string | number;
+            tag_name: string;
+        }, {
+            id: string | number;
+            tag_name: string;
+        }>, "many">>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+        display_file_name: z.ZodOptional<z.ZodString>;
+        file_name: z.ZodOptional<z.ZodString>;
+        category_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodNumber, z.ZodString]>>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+            tag_name: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string | number;
+            tag_name: string;
+        }, {
+            id: string | number;
+            tag_name: string;
+        }>, "many">>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+        display_file_name: z.ZodOptional<z.ZodString>;
+        file_name: z.ZodOptional<z.ZodString>;
+        category_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodNumber, z.ZodString]>>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+            tag_name: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string | number;
+            tag_name: string;
+        }, {
+            id: string | number;
+            tag_name: string;
+        }>, "many">>;
+    }, z.ZodTypeAny, "passthrough">>, "many">;
+    next_cursor: z.ZodNullable<z.ZodString>;
+    total_estimate: z.ZodNullable<z.ZodNumber>;
+    request_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    request_id: string;
+    category_id: string | number;
+    assets: z.objectOutputType<{
+        id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+        display_file_name: z.ZodOptional<z.ZodString>;
+        file_name: z.ZodOptional<z.ZodString>;
+        category_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodNumber, z.ZodString]>>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+            tag_name: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string | number;
+            tag_name: string;
+        }, {
+            id: string | number;
+            tag_name: string;
+        }>, "many">>;
+    }, z.ZodTypeAny, "passthrough">[];
+    next_cursor: string | null;
+    total_estimate: number | null;
+    subcategories: {
+        workspace_id: string | number;
+        id: string | number;
+        folder_name?: string | null | undefined;
+        parent_id?: string | number | null | undefined;
+        user_id?: string | number | null | undefined;
+        created_at?: string | null | undefined;
+        updated_at?: string | null | undefined;
+        category_path?: string | null | undefined;
+        integration_type?: number | undefined;
+    }[];
+}, {
+    request_id: string;
+    category_id: string | number;
+    assets: z.objectInputType<{
+        id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+        display_file_name: z.ZodOptional<z.ZodString>;
+        file_name: z.ZodOptional<z.ZodString>;
+        category_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodNumber, z.ZodString]>>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+            tag_name: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string | number;
+            tag_name: string;
+        }, {
+            id: string | number;
+            tag_name: string;
+        }>, "many">>;
+    }, z.ZodTypeAny, "passthrough">[];
+    next_cursor: string | null;
+    total_estimate: number | null;
+    subcategories: {
+        workspace_id: string | number;
+        id: string | number;
+        folder_name?: string | null | undefined;
+        parent_id?: string | number | null | undefined;
+        user_id?: string | number | null | undefined;
+        created_at?: string | null | undefined;
+        updated_at?: string | null | undefined;
+        category_path?: string | null | undefined;
+        integration_type?: number | undefined;
+    }[];
+}>;
+export type ViewCategoryContentsOutput = z.infer<typeof ViewCategoryContentsOutputSchema>;
+export type ViewCategoryContentsClient = Pick<CollageClient, 'listSubCategories' | 'listAssetsByCategory'>;
+export declare const VIEW_CATEGORY_CONTENTS_DESCRIPTION: string;
+export declare function buildViewCategoryContentsHandler(client: ViewCategoryContentsClient): (args: ViewCategoryContentsInput) => Promise<{
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        error: {
+            code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+            message: string;
+            retriable: boolean;
+            cause?: z.objectOutputType<{
+                upstream_status: z.ZodOptional<z.ZodNumber>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
+        };
+        request_id: string;
+    };
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        request_id: string;
+        category_id: string | number;
+        assets: z.objectOutputType<{
+            id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+            display_file_name: z.ZodOptional<z.ZodString>;
+            file_name: z.ZodOptional<z.ZodString>;
+            category_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodNumber, z.ZodString]>>>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+                tag_name: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                id: string | number;
+                tag_name: string;
+            }, {
+                id: string | number;
+                tag_name: string;
+            }>, "many">>;
+        }, z.ZodTypeAny, "passthrough">[];
+        next_cursor: string | null;
+        total_estimate: number | null;
+        subcategories: {
+            workspace_id: string | number;
+            id: string | number;
+            folder_name?: string | null | undefined;
+            parent_id?: string | number | null | undefined;
+            user_id?: string | number | null | undefined;
+            created_at?: string | null | undefined;
+            updated_at?: string | null | undefined;
+            category_path?: string | null | undefined;
+            integration_type?: number | undefined;
+        }[];
+    };
+    isError?: undefined;
+}>;
+//# sourceMappingURL=view-category-contents.d.ts.map

package/dist/tools/view-category-contents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-category-contents.d.ts","sourceRoot":"","sources":["../../src/tools/view-category-contents.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAalD,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;EAM1C,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,+BAA+B,CACvC,CAAC;AAEF,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAO3C,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,gCAAgC,CACxC,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAC3C,aAAa,EACb,mBAAmB,GAAG,sBAAsB,CAC7C,CAAC;AAEF,eAAO,MAAM,kCAAkC,QAGc,CAAC;AAE9D,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,0BAA0B,IAEpB,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2E9C"}

package/dist/tools/view-category-contents.js

@@ -0,0 +1,97 @@
+// ── view_category_contents (read-only) ──────────────────────────────
+// Lists the immediate sub-categories AND paginated assets inside a given
+// category id. Backed by:
+//   - GET /digital-assets/category/sub-category-list (full child list)
+//   - GET /digital-assets/category/view-files-with-category (paginated)
+//
+// Sub-categories are returned in full on every call (folder children are
+// typically small). Assets are upstream-paginated (1-based pages); we map
+// our base64 offset cursor onto upstream page numbers the same way
+// list_share_links does.
+import { z } from 'zod';
+import { buildPaginatedResponse, clampPageSize, decodeCursor, } from '../conventions/pagination.js';
+import { CategorySchema, PaginatedAssetRowSchema, } from '../types.js';
+export const ViewCategoryContentsInputSchema = z.object({
+    category_id: z.union([z.number().int().positive(), z.string().min(1)]),
+    cursor: z.string().optional(),
+    page_size: z.number().int().min(1).max(500).optional(),
+    sort_by: z.enum(['ASC', 'DESC']).optional(),
+    sort_value: z.string().optional(),
+});
+export const ViewCategoryContentsOutputSchema = z.object({
+    category_id: z.union([z.number(), z.string()]),
+    subcategories: z.array(CategorySchema),
+    assets: z.array(PaginatedAssetRowSchema),
+    next_cursor: z.string().nullable(),
+    total_estimate: z.number().nullable(),
+    request_id: z.string(),
+});
+export const VIEW_CATEGORY_CONTENTS_DESCRIPTION = 'Browse one folder. Returns the folder\'s immediate sub-folders (full ' +
+    'list) and a cursor-paginated page of assets that live directly inside ' +
+    'it. Pass `category_id` from `list_categories`. Read-only.';
+export function buildViewCategoryContentsHandler(client) {
+    return async (args) => {
+        const pageSize = clampPageSize(args.page_size);
+        const offset = args.cursor !== undefined ? decodeCursor(args.cursor) : 0;
+        const page = Math.floor(offset / pageSize) + 1;
+        const subResult = await client.listSubCategories(args.category_id);
+        if (!subResult.ok) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `view_category_contents failed: ${subResult.error.code} — ${subResult.error.message}`,
+                    },
+                ],
+                structuredContent: {
+                    error: subResult.error,
+                    request_id: subResult.request_id,
+                },
+            };
+        }
+        const assetOpts = {};
+        if (args.sort_by !== undefined)
+            assetOpts.sortBy = args.sort_by;
+        if (args.sort_value !== undefined)
+            assetOpts.sortValue = args.sort_value;
+        const assetResult = await client.listAssetsByCategory(args.category_id, page, assetOpts);
+        if (!assetResult.ok) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `view_category_contents failed: ${assetResult.error.code} — ${assetResult.error.message}`,
+                    },
+                ],
+                structuredContent: {
+                    error: assetResult.error,
+                    request_id: assetResult.request_id,
+                },
+            };
+        }
+        const subcategories = subResult.data;
+        const assets = assetResult.data.assets;
+        const total = assetResult.data.total;
+        const paged = buildPaginatedResponse(assets, offset, pageSize, total);
+        const output = {
+            category_id: args.category_id,
+            subcategories,
+            assets: paged.items,
+            next_cursor: paged.next_cursor,
+            total_estimate: paged.total_estimate,
+            request_id: assetResult.request_id,
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(output, null, 2),
+                },
+            ],
+            structuredContent: output,
+        };
+    };
+}
+//# sourceMappingURL=view-category-contents.js.map

package/dist/tools/view-category-contents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-category-contents.js","sourceRoot":"","sources":["../../src/tools/view-category-contents.ts"],"names":[],"mappings":"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"}