@collage-dam/mcp-server 0.1.0

package/dist/tools/insights/report-top-assets.js

@@ -0,0 +1,407 @@
+// ── report_top_assets (T3, read-only) ────────────────────────────────
+//
+// Read-only distribution-insights tool. Ranks the workspace's "top
+// performing" assets by composite distribution metrics — total views,
+// share-link count, distinct creators, distinct collections — within an
+// optional date / collection / creator scope.
+//
+// Differentiation from sibling tools:
+//   * `analyze_share_links` (T1) aggregates SHARE LINKS (the row itself).
+//   * `report_asset_activation` (T2) measures WORKSPACE COVERAGE
+//     (activation rate vs dormant count).
+//   * `report_top_assets` (T3) ranks PER-ASSET PERFORMANCE — which assets
+//     are the workhorses of distribution.
+//
+// Signal source:
+//   * Same as T2 — each share-link row references one or more `asset_ids`
+//     and carries `view_count`. Per-asset events are not exposed by the
+//     upstream surface, so views are inferred from the share-link
+//     view_count attributed to each covered asset.
+//   * Attribution choice: each share link's `view_count` is added in FULL
+//     to every asset it covers. This is the same convention T2 uses, and
+//     it matches the "demo collection" mental model — the share link is
+//     the unit of distribution; every asset in it benefits from the
+//     traffic.
+//
+// Type discipline: never uses `any`. Mirrors the T1/T2 enumerator/
+// dashboard-reader factoring exactly so a cache wrapper (T5) can plug in
+// around `reportTopAssets(...)` without touching the aggregation logic.
+import { z } from 'zod';
+import { createToolError } from '../../conventions/errors.js';
+import { estimateTokens, HARD_CAP_TOKENS } from '../../conventions/response-budget.js';
+// ── Tool description ────────────────────────────────────────────────
+export const REPORT_TOP_ASSETS_DESCRIPTION = 'Read-only report ranking workspace assets by distribution performance. ' +
+    'For each asset that has been shared, returns total views, share-link ' +
+    'count, distinct creators / collections, first- and last-shared ' +
+    'timestamps, and mean views-per-share. Buckets the matching asset ' +
+    'population into high / medium / low performance tiers using P80 / ' +
+    'P50 view-count thresholds so the LLM can describe the long-tail ' +
+    'shape. Filters: optional date range (defaults to last 90 days), ' +
+    'collection scope, creator scope, sort_by, top_n. No mutation, no AI ' +
+    'prose.';
+// ── Input schema ────────────────────────────────────────────────────
+export const DEFAULT_TOP_N = 10;
+export const MAX_TOP_N = 100;
+/** Default look-back window when neither `date_from` nor `date_to` is set. */
+export const DEFAULT_LOOKBACK_DAYS = 90;
+export const SORT_BY_VALUES = [
+    'total_views',
+    'share_link_count',
+    'mean_views_per_share',
+];
+/**
+ * `date_from` / `date_to` are inclusive ISO-8601 date or datetime
+ * strings. If only a date is supplied (e.g. `2026-04-14`) it is
+ * interpreted as the start (00:00:00Z) for `date_from` or the end
+ * (23:59:59.999Z) for `date_to`. When BOTH are omitted, the analyzer
+ * defaults to the last {@link DEFAULT_LOOKBACK_DAYS} days — wider than
+ * T2's 30-day default because "top performers" is more interesting over
+ * a quarter than a month.
+ */
+export const ReportTopAssetsInputSchema = z
+    .object({
+    date_from: z
+        .string()
+        .min(1)
+        .refine((v) => !Number.isNaN(Date.parse(v)), {
+        message: 'date_from must be a valid ISO-8601 date or datetime string',
+    })
+        .optional(),
+    date_to: z
+        .string()
+        .min(1)
+        .refine((v) => !Number.isNaN(Date.parse(v)), {
+        message: 'date_to must be a valid ISO-8601 date or datetime string',
+    })
+        .optional(),
+    collection_id: z.string().min(1).optional(),
+    created_by_user_id: z.string().min(1).optional(),
+    sort_by: z.enum(SORT_BY_VALUES).default('total_views'),
+    top_n: z.number().int().min(1).max(MAX_TOP_N).default(DEFAULT_TOP_N),
+})
+    .strict();
+export class ReportTopAssetsTool {
+    deps;
+    name = 'report_top_assets';
+    description = REPORT_TOP_ASSETS_DESCRIPTION;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async run(rawInput = {}) {
+        let parsed;
+        try {
+            parsed = ReportTopAssetsInputSchema.parse(rawInput);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: createToolError('VALIDATION', err instanceof Error ? err.message : 'invalid input'),
+            };
+        }
+        // Cross-field validation: when both bounds are set, from <= to.
+        if (parsed.date_from !== undefined && parsed.date_to !== undefined) {
+            const fromMs = Date.parse(parsed.date_from);
+            const toMs = Date.parse(parsed.date_to);
+            if (fromMs > toMs) {
+                return {
+                    ok: false,
+                    error: createToolError('VALIDATION', 'date_from must be <= date_to'),
+                };
+            }
+        }
+        const enumerated = await this.deps.enumerator.enumerate();
+        if (!enumerated.ok) {
+            return { ok: false, error: enumerated.error };
+        }
+        const report = buildReport(enumerated.rows, enumerated.truncated, parsed);
+        return { ok: true, report };
+    }
+}
+export function buildReportTopAssetsTool(deps) {
+    return new ReportTopAssetsTool(deps);
+}
+// ── Aggregation (pure) ──────────────────────────────────────────────
+/**
+ * Build the top-assets report from a flat list of share-link rows. Pure
+ * function, exported for direct test access.
+ */
+export function buildReport(rows, enumeratorTruncated, input) {
+    // ── Resolve effective date range (defaults to last DEFAULT_LOOKBACK_DAYS) ──
+    const { effectiveFrom, effectiveTo } = resolveDateRange(input.date_from, input.date_to);
+    // ── Filter share-link rows ──
+    const matching = rows.filter((row) => {
+        if (input.collection_id !== undefined) {
+            if (row.collection_id !== input.collection_id)
+                return false;
+        }
+        if (input.created_by_user_id !== undefined) {
+            if (row.created_by_user_id !== input.created_by_user_id)
+                return false;
+        }
+        if (row.created_at === null)
+            return false;
+        const createdMs = Date.parse(row.created_at);
+        if (Number.isNaN(createdMs))
+            return false;
+        if (effectiveFrom !== null && createdMs < effectiveFrom)
+            return false;
+        if (effectiveTo !== null && createdMs > effectiveTo)
+            return false;
+        return true;
+    });
+    const assets = new Map();
+    for (const row of matching) {
+        if (row.created_at === null)
+            continue;
+        const createdMs = Date.parse(row.created_at);
+        if (Number.isNaN(createdMs))
+            continue;
+        for (const assetId of row.asset_ids) {
+            const existing = assets.get(assetId);
+            if (existing === undefined) {
+                const creators = new Set();
+                if (row.created_by_user_id !== null)
+                    creators.add(row.created_by_user_id);
+                const collections = new Set();
+                if (row.collection_id !== null)
+                    collections.add(row.collection_id);
+                assets.set(assetId, {
+                    total_views: row.view_count,
+                    share_link_count: 1,
+                    creators,
+                    collections,
+                    first_shared_ms: createdMs,
+                    first_shared_iso: row.created_at,
+                    last_shared_ms: createdMs,
+                    last_shared_iso: row.created_at,
+                    title: row.title,
+                });
+                continue;
+            }
+            existing.total_views += row.view_count;
+            existing.share_link_count += 1;
+            if (row.created_by_user_id !== null) {
+                existing.creators.add(row.created_by_user_id);
+            }
+            if (row.collection_id !== null) {
+                existing.collections.add(row.collection_id);
+            }
+            if (createdMs < existing.first_shared_ms) {
+                existing.first_shared_ms = createdMs;
+                existing.first_shared_iso = row.created_at;
+            }
+            if (createdMs >= existing.last_shared_ms) {
+                existing.last_shared_ms = createdMs;
+                existing.last_shared_iso = row.created_at;
+                // Prefer non-null titles from the most-recent row.
+                if (row.title !== null)
+                    existing.title = row.title;
+            }
+        }
+    }
+    // ── Project entries (full list, before sort + slice) ──
+    const allEntries = [...assets.entries()].map(([id, state]) => ({
+        id,
+        title: state.title,
+        total_views: state.total_views,
+        share_link_count: state.share_link_count,
+        distinct_creators_count: state.creators.size,
+        distinct_collections_count: state.collections.size,
+        mean_views_per_share: state.share_link_count > 0
+            ? state.total_views / state.share_link_count
+            : 0,
+        first_shared_at: state.first_shared_iso,
+        last_shared_at: state.last_shared_iso,
+    }));
+    // ── Totals ──
+    const matchedAssets = allEntries.length;
+    const totalShares = matching.length;
+    const totalViews = matching.reduce((acc, r) => acc + r.view_count, 0);
+    const meanViewsPerAsset = matchedAssets === 0 ? null : sumViews(allEntries) / matchedAssets;
+    const medianViewsPerAsset = matchedAssets === 0
+        ? null
+        : computeMedian(allEntries.map((e) => e.total_views));
+    const totals = {
+        matched_assets: matchedAssets,
+        total_views: totalViews,
+        total_shares: totalShares,
+        mean_views_per_asset: meanViewsPerAsset,
+        median_views_per_asset: medianViewsPerAsset,
+    };
+    // ── Performance buckets ──
+    // Compute P80/P50 over the matched-asset total_views distribution.
+    const performanceBuckets = computePerformanceBuckets(allEntries.map((e) => e.total_views));
+    // ── Sort + top-N ──
+    const sorted = [...allEntries].sort((a, b) => compareEntries(a, b, input.sort_by));
+    const topAssets = sorted.slice(0, input.top_n);
+    const initial = {
+        filters: {
+            date_from: isoFromMs(effectiveFrom),
+            date_to: isoFromMs(effectiveTo),
+            collection_id: input.collection_id ?? null,
+            created_by_user_id: input.created_by_user_id ?? null,
+            sort_by: input.sort_by,
+            top_n: input.top_n,
+        },
+        totals,
+        performance_buckets: performanceBuckets,
+        top_assets: topAssets,
+        truncated: enumeratorTruncated,
+    };
+    if (enumeratorTruncated) {
+        initial.truncation_reason =
+            'Share-link enumerator stopped at its internal cap; report reflects a partial dataset.';
+    }
+    return enforceResponseBudget(initial);
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+function sumViews(entries) {
+    let total = 0;
+    for (const e of entries)
+        total += e.total_views;
+    return total;
+}
+function compareEntries(a, b, sortBy) {
+    // Primary key per `sort_by`, descending. Ties broken by total_views
+    // desc, then share_link_count desc, then id ascending so output is
+    // stable across runs.
+    const primaryDiff = primaryDiffFor(a, b, sortBy);
+    if (primaryDiff !== 0)
+        return primaryDiff;
+    if (b.total_views !== a.total_views)
+        return b.total_views - a.total_views;
+    if (b.share_link_count !== a.share_link_count) {
+        return b.share_link_count - a.share_link_count;
+    }
+    return a.id.localeCompare(b.id);
+}
+function primaryDiffFor(a, b, sortBy) {
+    if (sortBy === 'total_views')
+        return b.total_views - a.total_views;
+    if (sortBy === 'share_link_count') {
+        return b.share_link_count - a.share_link_count;
+    }
+    // mean_views_per_share
+    return b.mean_views_per_share - a.mean_views_per_share;
+}
+function resolveDateRange(rawFrom, rawTo) {
+    // Defaults: when both omitted, look back DEFAULT_LOOKBACK_DAYS from now.
+    if (rawFrom === undefined && rawTo === undefined) {
+        const nowMs = Date.now();
+        const fromMs = nowMs - DEFAULT_LOOKBACK_DAYS * 24 * 60 * 60 * 1000;
+        return { effectiveFrom: fromMs, effectiveTo: nowMs };
+    }
+    return {
+        effectiveFrom: parseLowerBound(rawFrom),
+        effectiveTo: parseUpperBound(rawTo),
+    };
+}
+function parseLowerBound(value) {
+    if (value === undefined)
+        return null;
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return Date.parse(`${value}T00:00:00.000Z`);
+    }
+    return Date.parse(value);
+}
+function parseUpperBound(value) {
+    if (value === undefined)
+        return null;
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return Date.parse(`${value}T23:59:59.999Z`);
+    }
+    return Date.parse(value);
+}
+function isoFromMs(ms) {
+    if (ms === null)
+        return null;
+    return new Date(ms).toISOString();
+}
+function computeMedian(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const n = sorted.length;
+    if (n === 0)
+        return 0;
+    const mid = Math.floor(n / 2);
+    if (n % 2 === 1)
+        return sorted[mid] ?? 0;
+    const left = sorted[mid - 1] ?? 0;
+    const right = sorted[mid] ?? 0;
+    return (left + right) / 2;
+}
+/**
+ * Linear-interpolation percentile (matches the Excel `PERCENTILE` /
+ * NumPy default convention). Returns `null` when the input is empty.
+ *
+ * `q` is in [0, 1].
+ */
+function percentile(values, q) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    if (sorted.length === 1)
+        return sorted[0] ?? null;
+    const rank = q * (sorted.length - 1);
+    const lo = Math.floor(rank);
+    const hi = Math.ceil(rank);
+    if (lo === hi)
+        return sorted[lo] ?? null;
+    const loVal = sorted[lo] ?? 0;
+    const hiVal = sorted[hi] ?? 0;
+    return loVal + (hiVal - loVal) * (rank - lo);
+}
+function computePerformanceBuckets(views) {
+    if (views.length === 0) {
+        return {
+            high: 0,
+            medium: 0,
+            low: 0,
+            thresholds: { p80_views: null, p50_views: null },
+        };
+    }
+    const p80 = percentile(views, 0.8);
+    const p50 = percentile(views, 0.5);
+    let high = 0;
+    let medium = 0;
+    let low = 0;
+    for (const v of views) {
+        if (p80 !== null && v >= p80) {
+            high += 1;
+        }
+        else if (p50 !== null && v >= p50) {
+            medium += 1;
+        }
+        else {
+            low += 1;
+        }
+    }
+    return {
+        high,
+        medium,
+        low,
+        thresholds: { p80_views: p80, p50_views: p50 },
+    };
+}
+// ── Response-budget enforcement ─────────────────────────────────────
+const REDUCED_TOP_LIMIT = 10;
+/**
+ * Aggregate reports tend to be small (totals + top-N + bucket counts),
+ * but a very large `top_n` could push us over budget. If the serialised
+ * report exceeds {@link HARD_CAP_TOKENS}, trim the top-asset list and
+ * mark `truncated: true`.
+ */
+function enforceResponseBudget(report) {
+    if (estimateTokens(JSON.stringify(report)) <= HARD_CAP_TOKENS) {
+        return report;
+    }
+    const trimmed = {
+        ...report,
+        top_assets: report.top_assets.slice(0, REDUCED_TOP_LIMIT),
+        truncated: true,
+        truncation_reason: report.truncation_reason !== undefined
+            ? `${report.truncation_reason} Additionally, the top-assets list was trimmed to fit the response budget.`
+            : 'Top-assets list was trimmed to fit the response budget.',
+    };
+    return trimmed;
+}
+//# sourceMappingURL=report-top-assets.js.map

package/dist/tools/insights/report-top-assets.js.map

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

package/dist/tools/list-categories.d.ts

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+import type { CollageClient } from '../client.js';
+export declare const ListCategoriesInputSchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    page_size: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    cursor?: string | undefined;
+    page_size?: number | undefined;
+}, {
+    cursor?: string | undefined;
+    page_size?: number | undefined;
+}>;
+export type ListCategoriesInput = z.infer<typeof ListCategoriesInputSchema>;
+export declare const ListCategoriesOutputSchema: z.ZodObject<{
+    items: 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">;
+    next_cursor: z.ZodNullable<z.ZodString>;
+    total_estimate: z.ZodNullable<z.ZodNumber>;
+    request_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    request_id: string;
+    items: {
+        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;
+    }[];
+    next_cursor: string | null;
+    total_estimate: number | null;
+}, {
+    request_id: string;
+    items: {
+        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;
+    }[];
+    next_cursor: string | null;
+    total_estimate: number | null;
+}>;
+export type ListCategoriesOutput = z.infer<typeof ListCategoriesOutputSchema>;
+/**
+ * Narrow client surface so tests can stub without the full CollageClient.
+ */
+export type ListCategoriesClient = Pick<CollageClient, 'listAllCategoriesRecursive'>;
+export declare const LIST_CATEGORIES_DESCRIPTION: string;
+export declare function buildListCategoriesHandler(client: ListCategoriesClient): (args: ListCategoriesInput) => 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;
+        items: {
+            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;
+        }[];
+        next_cursor: string | null;
+        total_estimate: number | null;
+    };
+    isError?: undefined;
+}>;
+//# sourceMappingURL=list-categories.d.ts.map

package/dist/tools/list-categories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-categories.d.ts","sourceRoot":"","sources":["../../src/tools/list-categories.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAQlD,eAAO,MAAM,yBAAyB;;;;;;;;;EAGpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CACrC,aAAa,EACb,4BAA4B,CAC7B,CAAC;AAEF,eAAO,MAAM,2BAA2B,QAK1B,CAAC;AAEf,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,oBAAoB,IACvD,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CxC"}

package/dist/tools/list-categories.js

@@ -0,0 +1,68 @@
+// ── list_categories (read-only) ──────────────────────────────────────
+// Returns the workspace folder tree as a flat list with `parent_id`
+// populated on every row (null for roots). Backed by
+// CollageClient.listAllCategoriesRecursive(), which combines
+// GET /digital-assets/category/all-category-list (roots only — upstream
+// is flat-by-design) with GET /digital-assets/category/sub-category-list
+// (per-parent children) so callers see the full tree, not just roots.
+//
+// Client-side cursor pagination keeps very large trees within the
+// response token budget.
+import { z } from 'zod';
+import { buildPaginatedResponse, clampPageSize, decodeCursor, } from '../conventions/pagination.js';
+import { CategorySchema } from '../types.js';
+export const ListCategoriesInputSchema = z.object({
+    cursor: z.string().optional(),
+    page_size: z.number().int().min(1).max(500).optional(),
+});
+export const ListCategoriesOutputSchema = z.object({
+    items: z.array(CategorySchema),
+    next_cursor: z.string().nullable(),
+    total_estimate: z.number().nullable(),
+    request_id: z.string(),
+});
+export const LIST_CATEGORIES_DESCRIPTION = 'List the full workspace folder tree (categories) as a flat list. Each ' +
+    'row carries the folder id, parent_id (null for roots), folder_name, and ' +
+    'category_path — sub-folders are included, not just roots. ' +
+    'Cursor-paginated so very large trees stay within the response budget. ' +
+    'Read-only.';
+export function buildListCategoriesHandler(client) {
+    return async (args) => {
+        const pageSize = clampPageSize(args.page_size);
+        const offset = args.cursor !== undefined ? decodeCursor(args.cursor) : 0;
+        const result = await client.listAllCategoriesRecursive();
+        if (!result.ok) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `list_categories failed: ${result.error.code} — ${result.error.message}`,
+                    },
+                ],
+                structuredContent: {
+                    error: result.error,
+                    request_id: result.request_id,
+                },
+            };
+        }
+        const all = result.data;
+        const paged = buildPaginatedResponse(all.slice(offset, offset + pageSize), offset, pageSize, all.length);
+        const output = {
+            items: paged.items,
+            next_cursor: paged.next_cursor,
+            total_estimate: paged.total_estimate,
+            request_id: result.request_id,
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(output, null, 2),
+                },
+            ],
+            structuredContent: output,
+        };
+    };
+}
+//# sourceMappingURL=list-categories.js.map

package/dist/tools/list-categories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-categories.js","sourceRoot":"","sources":["../../src/tools/list-categories.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,oEAAoE;AACpE,qDAAqD;AACrD,6DAA6D;AAC7D,wEAAwE;AACxE,yEAAyE;AACzE,sEAAsE;AACtE,EAAE;AACF,kEAAkE;AAClE,yBAAyB;AAEzB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,sBAAsB,EACtB,aAAa,EACb,YAAY,GACb,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,cAAc,EAAiB,MAAM,aAAa,CAAC;AAE5D,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;CACvD,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC;IAC9B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAWH,MAAM,CAAC,MAAM,2BAA2B,GACtC,wEAAwE;IACxE,0EAA0E;IAC1E,4DAA4D;IAC5D,wEAAwE;IACxE,YAAY,CAAC;AAEf,MAAM,UAAU,0BAA0B,CAAC,MAA4B;IACrE,OAAO,KAAK,EAAE,IAAyB,EAAE,EAAE;QACzC,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAEzE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,0BAA0B,EAAE,CAAC;QAEzD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,2BAA2B,MAAM,CAAC,KAAK,CAAC,IAAI,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE;qBAC/E;iBACF;gBACD,iBAAiB,EAAE;oBACjB,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,UAAU,EAAE,MAAM,CAAC,UAAU;iBAC9B;aACF,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,GAAe,MAAM,CAAC,IAAI,CAAC;QACpC,MAAM,KAAK,GAAG,sBAAsB,CAClC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,EACpC,MAAM,EACN,QAAQ,EACR,GAAG,CAAC,MAAM,CACX,CAAC;QACF,MAAM,MAAM,GAAyB;YACnC,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,UAAU,EAAE,MAAM,CAAC,UAAU;SAC9B,CAAC;QAEF,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;iBACtC;aACF;YACD,iBAAiB,EAAE,MAAM;SAC1B,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}