@collage-dam/mcp-server 0.1.0

package/dist/resources/portals.js

@@ -0,0 +1,81 @@
+// ── collage://portals  and  collage://portals/{id} ──────────────────
+// Both backed by `instance/get`. The endpoint returns the workspace
+// portal/instance configuration; the response shape is opaque (we keep
+// it as `unknown` at the client layer until a downstream consumer needs
+// specific fields). For `portals/{id}` we filter the portal list
+// client-side, mirroring how `getCollection` filters `collection/get-all`.
+import { createToolError } from '../conventions/errors.js';
+import { errorResource, jsonResource } from './helpers.js';
+export function buildPortalsListReader(client) {
+    return async (uri) => {
+        const result = await client.getInstance();
+        if (!result.ok) {
+            return errorResource(uri, result.error, result.request_id);
+        }
+        return jsonResource(uri, {
+            data: result.data,
+            request_id: result.request_id,
+        });
+    };
+}
+export function buildPortalByIdReader(client) {
+    return async (uri, variables) => {
+        const idVar = variables['id'];
+        const id = Array.isArray(idVar) ? idVar[0] : idVar;
+        if (id === undefined || id === '') {
+            return errorResource(uri, createToolError('VALIDATION', 'collage://portals/{id} requires an id'), 'no-request');
+        }
+        const result = await client.getInstance();
+        if (!result.ok) {
+            return errorResource(uri, result.error, result.request_id);
+        }
+        const match = findPortalById(result.data, id);
+        if (match === null) {
+            return errorResource(uri, createToolError('NOT_FOUND', `portal ${id} not found in workspace`), result.request_id);
+        }
+        return jsonResource(uri, {
+            portal: match,
+            request_id: result.request_id,
+        });
+    };
+}
+/**
+ * The instance/get response shape is opaque at the client layer. We probe
+ * a few likely structures to find a portal with a matching id without
+ * locking the resource to a specific schema yet.
+ */
+function findPortalById(raw, id) {
+    const candidates = collectPortalCandidates(raw);
+    for (const candidate of candidates) {
+        if (candidate === null || typeof candidate !== 'object')
+            continue;
+        const obj = candidate;
+        const candidateId = obj['id'];
+        if (candidateId !== undefined && String(candidateId) === id) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function collectPortalCandidates(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return [];
+    const obj = raw;
+    const out = [];
+    // Top-level array
+    if (Array.isArray(raw)) {
+        out.push(...raw);
+    }
+    // Common envelope shapes: `{ data: [...] }` or `{ data: { instances: [...] } }`
+    for (const key of ['data', 'instances', 'portals']) {
+        const v = obj[key];
+        if (Array.isArray(v)) {
+            out.push(...v);
+        }
+        else if (v !== null && typeof v === 'object') {
+            out.push(...collectPortalCandidates(v));
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=portals.js.map

package/dist/resources/portals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portals.js","sourceRoot":"","sources":["../../src/resources/portals.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,oEAAoE;AACpE,uEAAuE;AACvE,wEAAwE;AACxE,iEAAiE;AACjE,2EAA2E;AAI3E,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,UAAU,sBAAsB,CAAC,MAAqB;IAC1D,OAAO,KAAK,EAAE,GAAQ,EAA+B,EAAE;QACrD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,YAAY,CAAC,GAAG,EAAE;YACvB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,UAAU,EAAE,MAAM,CAAC,UAAU;SAC9B,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAqB;IACzD,OAAO,KAAK,EACV,GAAQ,EACR,SAA4C,EACf,EAAE;QAC/B,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QACnD,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAClC,OAAO,aAAa,CAClB,GAAG,EACH,eAAe,CAAC,YAAY,EAAE,uCAAuC,CAAC,EACtE,YAAY,CACb,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;QAC7D,CAAC;QAED,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC9C,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO,aAAa,CAClB,GAAG,EACH,eAAe,CAAC,WAAW,EAAE,UAAU,EAAE,yBAAyB,CAAC,EACnE,MAAM,CAAC,UAAU,CAClB,CAAC;QACJ,CAAC;QAED,OAAO,YAAY,CAAC,GAAG,EAAE;YACvB,MAAM,EAAE,KAAK;YACb,UAAU,EAAE,MAAM,CAAC,UAAU;SAC9B,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,GAAY,EAAE,EAAU;IAC9C,MAAM,UAAU,GAAG,uBAAuB,CAAC,GAAG,CAAC,CAAC;IAChD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ;YAAE,SAAS;QAClE,MAAM,GAAG,GAAG,SAAoC,CAAC;QACjD,MAAM,WAAW,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,WAAW,KAAK,SAAS,IAAI,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,EAAE,CAAC;YAC5D,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,uBAAuB,CAAC,GAAY;IAC3C,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACvD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAC3C,MAAM,GAAG,GAAc,EAAE,CAAC;IAE1B,kBAAkB;IAClB,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;IACnB,CAAC;IAED,gFAAgF;IAChF,KAAK,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,CAAU,EAAE,CAAC;QAC5D,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACnB,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YACrB,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACjB,CAAC;aAAM,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC/C,GAAG,CAAC,IAAI,CAAC,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/resources/recent-and-dashboard.d.ts

@@ -0,0 +1,5 @@
+import type { ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CollageClient } from '../client.js';
+export declare function buildRecentAssetsReader(client: CollageClient): (uri: URL) => Promise<ReadResourceResult>;
+export declare function buildDashboardReader(client: CollageClient): (uri: URL) => Promise<ReadResourceResult>;
+//# sourceMappingURL=recent-and-dashboard.d.ts.map

package/dist/resources/recent-and-dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recent-and-dashboard.d.ts","sourceRoot":"","sources":["../../src/resources/recent-and-dashboard.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAIlD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,IAC7C,KAAK,GAAG,KAAG,OAAO,CAAC,kBAAkB,CAAC,CAqBrD;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,IAC1C,KAAK,GAAG,KAAG,OAAO,CAAC,kBAAkB,CAAC,CAUrD"}

package/dist/resources/recent-and-dashboard.js

@@ -0,0 +1,42 @@
+// ── collage://assets/recent  and  collage://dashboard ────────────────
+// Backed by `get-recent-uploaded` and `dashboard/common-data`.
+//
+// Both endpoints have opaque (`z.unknown()`) response shapes at the
+// client layer. The resource handlers pass them through as-is so the
+// LLM can reason over Collage's native projection until we have a
+// downstream consumer that needs a narrower schema.
+import { clampPageSize } from '../conventions/pagination.js';
+import { decodeOffsetCursor, errorResource, jsonResource } from './helpers.js';
+export function buildRecentAssetsReader(client) {
+    return async (uri) => {
+        const pageSize = clampPageSize(Number(uri.searchParams.get('page_size') ?? undefined) || undefined);
+        const offset = decodeOffsetCursor(uri);
+        const page = Math.floor(offset / pageSize) + 1;
+        const result = await client.listRecentUploaded({
+            page,
+            totalRecord: pageSize,
+        });
+        if (!result.ok) {
+            return errorResource(uri, result.error, result.request_id);
+        }
+        return jsonResource(uri, {
+            data: result.data,
+            page,
+            page_size: pageSize,
+            request_id: result.request_id,
+        });
+    };
+}
+export function buildDashboardReader(client) {
+    return async (uri) => {
+        const result = await client.getDashboardCommonData();
+        if (!result.ok) {
+            return errorResource(uri, result.error, result.request_id);
+        }
+        return jsonResource(uri, {
+            data: result.data,
+            request_id: result.request_id,
+        });
+    };
+}
+//# sourceMappingURL=recent-and-dashboard.js.map

package/dist/resources/recent-and-dashboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recent-and-dashboard.js","sourceRoot":"","sources":["../../src/resources/recent-and-dashboard.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,+DAA+D;AAC/D,EAAE;AACF,oEAAoE;AACpE,qEAAqE;AACrE,kEAAkE;AAClE,oDAAoD;AAIpD,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE/E,MAAM,UAAU,uBAAuB,CAAC,MAAqB;IAC3D,OAAO,KAAK,EAAE,GAAQ,EAA+B,EAAE;QACrD,MAAM,QAAQ,GAAG,aAAa,CAC5B,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,SAAS,CAAC,IAAI,SAAS,CACpE,CAAC;QACF,MAAM,MAAM,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAE/C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC;YAC7C,IAAI;YACJ,WAAW,EAAE,QAAQ;SACtB,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,YAAY,CAAC,GAAG,EAAE;YACvB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI;YACJ,SAAS,EAAE,QAAQ;YACnB,UAAU,EAAE,MAAM,CAAC,UAAU;SAC9B,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAqB;IACxD,OAAO,KAAK,EAAE,GAAQ,EAA+B,EAAE;QACrD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,sBAAsB,EAAE,CAAC;QACrD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,YAAY,CAAC,GAAG,EAAE;YACvB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,UAAU,EAAE,MAAM,CAAC,UAAU;SAC9B,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/tools/asset-selection.d.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import type { CollageClient } from '../client.js';
+import { type McpToolError } from '../conventions/errors.js';
+/**
+ * Selection input. Exactly one of `query`, `ids`, or `collection_id` must be
+ * provided. The schema accepts all three and the resolver enforces the
+ * exclusivity at runtime so callers get a structured `VALIDATION` error
+ * instead of a Zod parse failure.
+ */
+export declare const AssetSelectionSchema: z.ZodEffects<z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    ids: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodNumber, z.ZodString]>, "many">>;
+    collection_id: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+}, "strip", z.ZodTypeAny, {
+    query?: string | undefined;
+    collection_id?: string | number | undefined;
+    ids?: (string | number)[] | undefined;
+}, {
+    query?: string | undefined;
+    collection_id?: string | number | undefined;
+    ids?: (string | number)[] | undefined;
+}>, {
+    query?: string | undefined;
+    collection_id?: string | number | undefined;
+    ids?: (string | number)[] | undefined;
+}, {
+    query?: string | undefined;
+    collection_id?: string | number | undefined;
+    ids?: (string | number)[] | undefined;
+}>;
+export type AssetSelection = z.infer<typeof AssetSelectionSchema>;
+/**
+ * Minimal per-asset projection used by Phase 1 tools to render diffs.
+ *
+ * Tools that need fuller detail (e.g. `update_asset_metadata` reading the
+ * description) call back into the client themselves keyed by `id`.
+ */
+export interface ResolvedAsset {
+    id: string;
+    display_file_name?: string;
+    /** Current tag names — used by `bulk_*_tags` to compute set differences. */
+    tags?: string[];
+}
+export interface ResolveSelectionResult {
+    ok: true;
+    asset_ids: string[];
+    /** Optional per-asset snapshot keyed by id. May be empty (e.g. `ids` path). */
+    snapshots: Map<string, ResolvedAsset>;
+}
+export type ResolveSelectionOutcome = ResolveSelectionResult | {
+    ok: false;
+    error: McpToolError;
+};
+/**
+ * Narrow surface the resolver depends on for the `query` path. Implementations
+ * can wrap Typesense, the Collage search REST endpoint, or — until the public
+ * Typesense host is provisioned — throw a typed `SEARCH_UNAVAILABLE` error.
+ */
+export interface AssetSearchAdapter {
+    searchAssets(query: string): Promise<{
+        ok: true;
+        assets: ResolvedAsset[];
+    } | {
+        ok: false;
+        error: McpToolError;
+    }>;
+}
+/**
+ * Default search adapter used when no Typesense host is configured. Always
+ * returns a typed `UPSTREAM` error (`SEARCH_UNAVAILABLE`) so callers can
+ * surface a clear, actionable failure message instead of crashing.
+ */
+export declare const unavailableSearchAdapter: AssetSearchAdapter;
+/**
+ * Narrow surface for the `collection_id` path. The default implementation
+ * is provided below and wraps `CollageClient.listCollections()` — but tests
+ * can substitute a fake without standing up the full client.
+ */
+export interface CollectionLookup {
+    getCollectionAssetIds(collectionId: string): Promise<{
+        ok: true;
+        asset_ids: string[];
+    } | {
+        ok: false;
+        error: McpToolError;
+    }>;
+}
+export declare function buildCollectionLookup(client: CollageClient): CollectionLookup;
+export interface ResolveSelectionDeps {
+    search: AssetSearchAdapter;
+    collections: CollectionLookup;
+}
+/**
+ * Resolve a selection envelope into a concrete list of asset IDs.
+ *
+ * - `ids`           — returned verbatim, deduplicated, coerced to string.
+ * - `collection_id` — looked up via the live Collage REST API.
+ * - `query`         — delegated to the search adapter; may return
+ *                     `SEARCH_UNAVAILABLE` until Typesense is provisioned.
+ */
+export declare function resolveAssetSelection(selection: AssetSelection, deps: ResolveSelectionDeps): Promise<ResolveSelectionOutcome>;
+//# sourceMappingURL=asset-selection.d.ts.map

package/dist/tools/asset-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-selection.d.ts","sourceRoot":"","sources":["../../src/tools/asset-selection.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAK9E;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;EAmB9B,CAAC;AAEJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,IAAI,CAAC;IACT,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,+EAA+E;IAC/E,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACvC;AAED,MAAM,MAAM,uBAAuB,GAC/B,sBAAsB,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CAAC;AAIvC;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,CACV,KAAK,EAAE,MAAM,GACZ,OAAO,CACN;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,aAAa,EAAE,CAAA;KAAE,GACrC;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,YAAY,CAAA;KAAE,CACrC,CAAC;CACH;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,kBAQtC,CAAC;AAIF;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qBAAqB,CACnB,YAAY,EAAE,MAAM,GACnB,OAAO,CACN;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,GACjC;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,YAAY,CAAA;KAAE,CACrC,CAAC;CACH;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,gBAAgB,CAqB7E;AAID,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,WAAW,EAAE,gBAAgB,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CA+ClC"}

package/dist/tools/asset-selection.js

@@ -0,0 +1,133 @@
+// ── Shared Asset Selection Resolver ──────────────────────────────────
+// Phase 1 metadata/tagging tools all share the same way to identify which
+// assets to operate on: a free-text search query, an explicit ID list, or
+// a collection ID whose member assets are resolved via the live API.
+//
+// The resolver is intentionally narrow: it returns a flat list of asset IDs
+// (as strings) plus a small per-id metadata map for diff display. Tools layer
+// their domain logic (tag/metadata math) on top.
+//
+// IMPORTANT: the public Typesense host is currently owed by Collage; the
+// `query` path therefore wires through to a search adapter that may throw a
+// typed `UPSTREAM` error (`SEARCH_UNAVAILABLE`) explaining the dependency
+// is not reachable yet. The `ids` and `collection_id` paths are end-to-end
+// against the live Collage REST API and are the recommended Phase 1 paths.
+import { z } from 'zod';
+import { createToolError } from '../conventions/errors.js';
+import { IdSchema } from '../types.js';
+// ── Selection Input Schema ───────────────────────────────────────────
+/**
+ * Selection input. Exactly one of `query`, `ids`, or `collection_id` must be
+ * provided. The schema accepts all three and the resolver enforces the
+ * exclusivity at runtime so callers get a structured `VALIDATION` error
+ * instead of a Zod parse failure.
+ */
+export const AssetSelectionSchema = z
+    .object({
+    query: z.string().min(1).optional(),
+    ids: z.array(IdSchema).min(1).max(5000).optional(),
+    collection_id: IdSchema.optional(),
+})
+    .refine((sel) => {
+    const present = [
+        sel.query !== undefined,
+        sel.ids !== undefined,
+        sel.collection_id !== undefined,
+    ].filter(Boolean).length;
+    return present === 1;
+}, {
+    message: 'Selection must specify exactly one of: query, ids, or collection_id.',
+});
+/**
+ * Default search adapter used when no Typesense host is configured. Always
+ * returns a typed `UPSTREAM` error (`SEARCH_UNAVAILABLE`) so callers can
+ * surface a clear, actionable failure message instead of crashing.
+ */
+export const unavailableSearchAdapter = {
+    searchAssets: async () => ({
+        ok: false,
+        error: createToolError('UPSTREAM', 'Asset search is not available: the public Typesense host has not been provisioned yet. Use `ids` or `collection_id` selection until search is wired up.'),
+    }),
+};
+export function buildCollectionLookup(client) {
+    return {
+        getCollectionAssetIds: async (collectionId) => {
+            const res = await client.listCollections();
+            if (!res.ok) {
+                return { ok: false, error: res.error };
+            }
+            const match = res.data.find((c) => String(c.id) === collectionId);
+            if (match === undefined) {
+                return {
+                    ok: false,
+                    error: createToolError('NOT_FOUND', `Collection ${collectionId} not found in workspace.`),
+                };
+            }
+            const ids = (match.assets_id ?? []).map((id) => String(id));
+            return { ok: true, asset_ids: ids };
+        },
+    };
+}
+/**
+ * Resolve a selection envelope into a concrete list of asset IDs.
+ *
+ * - `ids`           — returned verbatim, deduplicated, coerced to string.
+ * - `collection_id` — looked up via the live Collage REST API.
+ * - `query`         — delegated to the search adapter; may return
+ *                     `SEARCH_UNAVAILABLE` until Typesense is provisioned.
+ */
+export async function resolveAssetSelection(selection, deps) {
+    if (selection.ids !== undefined) {
+        const seen = new Set();
+        const out = [];
+        for (const raw of selection.ids) {
+            const id = String(raw);
+            if (!seen.has(id)) {
+                seen.add(id);
+                out.push(id);
+            }
+        }
+        return { ok: true, asset_ids: out, snapshots: new Map() };
+    }
+    if (selection.collection_id !== undefined) {
+        const res = await deps.collections.getCollectionAssetIds(String(selection.collection_id));
+        if (!res.ok)
+            return res;
+        return {
+            ok: true,
+            asset_ids: dedupe(res.asset_ids),
+            snapshots: new Map(),
+        };
+    }
+    if (selection.query !== undefined) {
+        const res = await deps.search.searchAssets(selection.query);
+        if (!res.ok)
+            return res;
+        const snapshots = new Map();
+        const ids = [];
+        for (const asset of res.assets) {
+            if (snapshots.has(asset.id))
+                continue;
+            snapshots.set(asset.id, asset);
+            ids.push(asset.id);
+        }
+        return { ok: true, asset_ids: ids, snapshots };
+    }
+    // Defensive — the schema's refine() should prevent us reaching here.
+    return {
+        ok: false,
+        error: createToolError('VALIDATION', 'Selection must specify exactly one of: query, ids, or collection_id.'),
+    };
+}
+function dedupe(input) {
+    const seen = new Set();
+    const out = [];
+    for (const id of input) {
+        if (!seen.has(id)) {
+            seen.add(id);
+            out.push(id);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=asset-selection.js.map

package/dist/tools/asset-selection.js.map

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

package/dist/tools/audit/audit-folder-structure.d.ts

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import { type McpToolError } from '../../conventions/errors.js';
+import { type AuditReport } from './types.js';
+export declare const AUDIT_FOLDER_STRUCTURE_DESCRIPTION: string;
+export declare const AuditFolderStructureInputSchema: z.ZodObject<{
+    /**
+     * Folders deeper than this value (root = depth 0) are flagged as a
+     * `folder_depth_anomaly` finding. Must be >= 0. Defaults to 5.
+     */
+    max_depth: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Collections holding fewer than this many assets are flagged as
+     * `low_asset_collections`. Required from caller — exposed as a tunable
+     * because what counts as "low" varies widely across libraries. Must be
+     * >= 1; defaults to 3.
+     */
+    min_assets: z.ZodDefault<z.ZodNumber>;
+    /** Per-finding asset / id sample cap. Defaults to 10. */
+    sample_limit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    sample_limit: number;
+    max_depth: number;
+    min_assets: number;
+}, {
+    sample_limit?: number | undefined;
+    max_depth?: number | undefined;
+    min_assets?: number | undefined;
+}>;
+export type AuditFolderStructureInput = z.input<typeof AuditFolderStructureInputSchema>;
+export type AuditFolderStructureInputResolved = z.output<typeof AuditFolderStructureInputSchema>;
+/** Minimal folder / category projection used by the audit. */
+export interface AuditFolder {
+    id: string;
+    /** Parent folder id, or null for a root. */
+    parent_id: string | null;
+    /** Human label for diagnostic messaging. */
+    name?: string;
+}
+/**
+ * Minimal asset projection — only `id` plus parent folder id (nullable so
+ * orphans surface naturally).
+ */
+export interface AuditAssetForStructure {
+    id: string;
+    category_id: string | null;
+}
+/** Minimal collection projection. */
+export interface AuditCollection {
+    id: string;
+    name?: string;
+    asset_count: number;
+}
+export interface FolderStructureEnumerator {
+    enumerateFolders(): Promise<{
+        ok: true;
+        folders: AuditFolder[];
+    } | {
+        ok: false;
+        error: McpToolError;
+    }>;
+    enumerateAssets(): Promise<{
+        ok: true;
+        assets: AuditAssetForStructure[];
+    } | {
+        ok: false;
+        error: McpToolError;
+    }>;
+    enumerateCollections(): Promise<{
+        ok: true;
+        collections: AuditCollection[];
+    } | {
+        ok: false;
+        error: McpToolError;
+    }>;
+}
+export interface AuditFolderStructureDeps {
+    enumerator: FolderStructureEnumerator;
+}
+export type AuditFolderStructureOutcome = {
+    ok: true;
+    report: AuditReport;
+} | {
+    ok: false;
+    error: McpToolError;
+};
+export declare class AuditFolderStructureTool {
+    private readonly deps;
+    readonly name = "audit_folder_structure";
+    readonly description: string;
+    constructor(deps: AuditFolderStructureDeps);
+    run(rawInput?: AuditFolderStructureInput): Promise<AuditFolderStructureOutcome>;
+}
+export declare function buildAuditFolderStructureTool(deps: AuditFolderStructureDeps): AuditFolderStructureTool;
+/**
+ * Compute the depth of every folder, indexed by id.
+ *
+ * Roots (parent_id === null) sit at depth 0. Folders whose parent does not
+ * appear in the supplied list are still rooted at depth 0 — a missing
+ * parent is treated as a graph oddity, not a fatal error, so audit runs
+ * never crash on partial workspace snapshots.
+ *
+ * Cycles (a folder whose parent chain returns to itself) are detected and
+ * the offending folder is clamped at depth `maxDepth + 1` so it still
+ * surfaces in the anomaly finding without blowing the stack.
+ */
+export declare function computeFolderDepths(folders: ReadonlyArray<AuditFolder>, maxDepth: number): Map<string, number>;
+export declare function buildReport(folders: ReadonlyArray<AuditFolder>, assets: ReadonlyArray<AuditAssetForStructure>, collections: ReadonlyArray<AuditCollection>, input: AuditFolderStructureInputResolved): AuditReport;
+//# sourceMappingURL=audit-folder-structure.d.ts.map

package/dist/tools/audit/audit-folder-structure.d.ts.map

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