@strapi/upload 5.52.3 → 5.54.0

package/dist/server/mcp/handlers/folder-handlers.mjs

@@ -0,0 +1,303 @@
+import { errors } from '@strapi/utils';
+import { assertAmbientInstance, getFolderService } from '../ambient-instance.mjs';
+import { FOLDER_MODEL_UID, FILE_MODEL_UID, ACTIONS } from '../../constants.mjs';
+import { isFolderOrChild } from '../../controllers/utils/folders.mjs';
+import { assertMediaPermission } from '../permissions.mjs';
+import { sanitizeMediaFolder } from '../sanitizers/sanitize-media.mjs';
+import { MCP_NOT_FOUND_FOLDER, MCP_DELETE_FOLDER_UNRESOLVED_IDS, MCP_PARENT_FOLDER_NOT_FOUND, MCP_FOLDER_NAME_TAKEN, MCP_FOLDER_MOVE_INTO_SELF } from './constants.mjs';
+import { ok } from '../utils.mjs';
+
+/**
+ * `withParent` populates the parent relation in the same round trip. Rename needs the parent id
+ * to scope its sibling-uniqueness check, so it would otherwise read the same row twice; the
+ * subtree and cascade callers do not, and skip the join.
+ */ const findFolderById = async (strapi, id, { withParent = false } = {})=>strapi.db.query(FOLDER_MODEL_UID).findOne({
+        select: [
+            'id',
+            'name',
+            'path'
+        ],
+        where: {
+            id
+        },
+        ...withParent ? {
+            populate: {
+                parent: {
+                    select: [
+                        'id'
+                    ]
+                }
+            }
+        } : {}
+    });
+/**
+ * Re-reads a folder with its parent populated, so the write tools can echo back the same shape
+ * regardless of what the service returned.
+ *
+ * `folder.update()` resolves the row it wrote without the `parent` relation, and on a pure rename
+ * it never touches the join table at all — so the parent has to be read back to be reported.
+ */ const readFolderForOutput = async (strapi, id, fallback)=>{
+    const row = await strapi.db.query(FOLDER_MODEL_UID).findOne({
+        where: {
+            id
+        },
+        populate: {
+            parent: {
+                select: [
+                    'id',
+                    'name'
+                ]
+            }
+        }
+    });
+    // The write succeeded, so report it even if the read-back comes back empty rather than
+    // failing a completed operation on a follow-up query.
+    return sanitizeMediaFolder(row ?? fallback);
+};
+/**
+ * Replicates the admin folder controller's `parent` check: a named parent must exist.
+ *
+ * null is the media library root and always valid, so only a numeric id is looked up.
+ */ const assertParentExists = async (strapi, parent)=>{
+    if (parent === null || parent === undefined) {
+        return;
+    }
+    const exists = await getFolderService(strapi).exists({
+        id: parent
+    });
+    if (!exists) {
+        throw new errors.ValidationError(MCP_PARENT_FOLDER_NOT_FOUND);
+    }
+};
+/**
+ * Replicates `is-folder-unique` from the admin folder validation: a folder name must be unique
+ * among its siblings.
+ *
+ * `excludeId` is the folder being renamed — without it a rename to the folder's current name
+ * would collide with itself.
+ */ const assertNameAvailable = async (strapi, name, parent, excludeId)=>{
+    const filters = {
+        name,
+        parent: parent ?? null
+    };
+    if (excludeId !== undefined) {
+        filters.id = {
+            $ne: excludeId
+        };
+    }
+    if (await getFolderService(strapi).exists(filters)) {
+        throw new errors.ValidationError(MCP_FOLDER_NAME_TAKEN);
+    }
+};
+/**
+ * Replicates `dont-move-inside-self`: a folder cannot become its own descendant.
+ *
+ * Without this the folder service would rewrite the subtree's materialized paths into a cycle,
+ * orphaning every descendant — the tree has no root to walk back to afterwards.
+ */ const assertNotMovedIntoOwnSubtree = async (strapi, folder, parent)=>{
+    if (parent === null) {
+        return;
+    }
+    const destination = await findFolderById(strapi, parent);
+    // A missing destination is already reported by `assertParentExists`.
+    if (destination === null) {
+        return;
+    }
+    if (isFolderOrChild(destination, folder)) {
+        throw new errors.ValidationError(MCP_FOLDER_MOVE_INTO_SELF);
+    }
+};
+/**
+ * Counts the folders and files a `deleteByIds` of these paths would remove.
+ *
+ * Mirrors the two `$or` predicates in `folder.deleteByIds` exactly — self path plus the
+ * `${path}/` prefix — so the dry-run number is the same set the destructive branch acts on
+ * rather than an independent estimate that could drift from it.
+ */ const countCascade = async (strapi, paths)=>{
+    const pathPredicate = (field)=>({
+            $or: paths.flatMap((path)=>[
+                    {
+                        [field]: {
+                            $eq: path
+                        }
+                    },
+                    {
+                        [field]: {
+                            $startsWith: `${path}/`
+                        }
+                    }
+                ])
+        });
+    const [totalFolderNumber, totalFileNumber] = await Promise.all([
+        strapi.db.query(FOLDER_MODEL_UID).count({
+            where: pathPredicate('path')
+        }),
+        strapi.db.query(FILE_MODEL_UID).count({
+            where: pathPredicate('folderPath')
+        })
+    ]);
+    return {
+        totalFolderNumber,
+        totalFileNumber
+    };
+};
+/**
+ * `media_create_folder` — a new folder, optionally nested.
+ *
+ * Gated on `plugin::upload.assets.create` and mirrors `POST /upload/folders`: the same
+ * permission, the same uniqueness and parent-existence validation, the same `folder.create()`
+ * call, and the same `createdBy` attribution from the session user.
+ *
+ * `create` rather than the `update` the other folder tools use: creating a folder is the one
+ * folder operation whose admin route gates on `assets.create`.
+ */ const createMediaCreateFolderHandler = (strapi, context)=>{
+    assertAmbientInstance(strapi);
+    return async ({ args })=>{
+        const { name, parent = null } = args;
+        assertMediaPermission(strapi, context, ACTIONS.create, FOLDER_MODEL_UID);
+        await assertParentExists(strapi, parent);
+        await assertNameAvailable(strapi, name, parent);
+        const created = await getFolderService(strapi).create({
+            name,
+            parent
+        }, {
+            user: context.user
+        });
+        return ok({
+            data: await readFolderForOutput(strapi, created.id, created)
+        });
+    };
+};
+/**
+ * `media_rename_folder` — changes a folder's name and nothing else.
+ *
+ * Deliberately does not forward `parent` to `folder.update()`: the service branches on
+ * `isUndefined(parent)`, and the name-only branch skips the transaction that rewrites descendant
+ * paths. Passing the folder's existing parent would take the move branch and rewrite the whole
+ * subtree to compute the identical paths.
+ */ const createMediaRenameFolderHandler = (strapi, context)=>{
+    assertAmbientInstance(strapi);
+    return async ({ args })=>{
+        const { id, name } = args;
+        assertMediaPermission(strapi, context, ACTIONS.update, FOLDER_MODEL_UID);
+        const folder = await findFolderById(strapi, id, {
+            withParent: true
+        });
+        if (folder === null) {
+            throw new errors.NotFoundError(MCP_NOT_FOUND_FOLDER);
+        }
+        // Siblings are the folders sharing this folder's parent, so uniqueness is checked against
+        // the current location — a rename never changes it.
+        const parentId = folder.parent?.id ?? null;
+        await assertNameAvailable(strapi, name, parentId, id);
+        // `parent` is omitted on purpose — see the note above.
+        const renamed = await getFolderService(strapi).update(id, {
+            name
+        }, {
+            user: context.user
+        });
+        return ok({
+            data: await readFolderForOutput(strapi, id, renamed ?? {
+                ...folder,
+                name
+            })
+        });
+    };
+};
+/**
+ * `media_move_folder` — re-parents a folder, carrying its whole subtree with it.
+ *
+ * `folder.update()` recalculates the materialized `path` of every descendant folder and the
+ * `folderPath` of every contained file inside a transaction, so the move is atomic and no
+ * separate bookkeeping is needed here.
+ */ const createMediaMoveFolderHandler = (strapi, context)=>{
+    assertAmbientInstance(strapi);
+    return async ({ args })=>{
+        const { id, parent } = args;
+        assertMediaPermission(strapi, context, ACTIONS.update, FOLDER_MODEL_UID);
+        const folder = await findFolderById(strapi, id);
+        if (folder === null) {
+            throw new errors.NotFoundError(MCP_NOT_FOUND_FOLDER);
+        }
+        await assertParentExists(strapi, parent);
+        await assertNotMovedIntoOwnSubtree(strapi, folder, parent);
+        // A folder keeps its name across a move, so uniqueness must hold in the destination.
+        await assertNameAvailable(strapi, folder.name, parent, id);
+        const moved = await getFolderService(strapi).update(id, {
+            name: folder.name,
+            parent
+        }, {
+            user: context.user
+        });
+        return ok({
+            data: await readFolderForOutput(strapi, id, moved ?? folder)
+        });
+    };
+};
+/**
+ * `media_delete_folder` — previews or performs a cascading folder deletion.
+ *
+ * Two branches behind one tool, because the preview and the deletion must agree on what the
+ * cascade covers; splitting them across tools would let the two drift apart, and an agent could
+ * reach the destructive one without ever seeing a count.
+ *
+ * `dryRun` defaults to true (see the input schema): omitting the flag previews, and deleting
+ * takes an explicit `dryRun: false`.
+ */ const createMediaDeleteFolderHandler = (strapi, context)=>{
+    assertAmbientInstance(strapi);
+    return async ({ args })=>{
+        const { ids, dryRun = true } = args;
+        assertMediaPermission(strapi, context, ACTIONS.update, FOLDER_MODEL_UID);
+        const matched = await strapi.db.query(FOLDER_MODEL_UID).findMany({
+            select: [
+                'id',
+                'name',
+                'path'
+            ],
+            where: {
+                id: {
+                    $in: ids
+                }
+            }
+        });
+        /**
+     * All-or-nothing: any id that does not resolve to a folder rejects the whole call, before
+     * anything is deleted.
+     *
+     * Folder ids and asset ids are indistinguishable integers, so a list mixing the two is the
+     * mistake this tool exists to catch — and deleting the folders that did match while
+     * reporting the rest back would be exactly the silent confusion that requirement forbids,
+     * with the cascade already gone by the time the agent reads the response.
+     *
+     * An unresolvable id cannot be diagnosed further from here (an asset id and a deleted
+     * folder id look identical), and it does not need to be: either way it is unusable.
+     *
+     * The dry run rejects on the same rule. A preview that reported a cascade for a request the
+     * executing call would refuse is worse than no preview — it is a confirmation an agent
+     * cannot act on.
+     */ const matchedIds = new Set(matched.map((folder)=>folder.id));
+        const unresolvedIds = ids.filter((id)=>matchedIds.has(id) === false);
+        if (unresolvedIds.length > 0) {
+            throw new errors.ValidationError(MCP_DELETE_FOLDER_UNRESOLVED_IDS(unresolvedIds));
+        }
+        const folders = matched.map((folder)=>sanitizeMediaFolder(folder));
+        if (dryRun) {
+            const counts = await countCascade(strapi, matched.map((folder)=>folder.path));
+            return ok({
+                dryRun: true,
+                folders,
+                ...counts
+            });
+        }
+        const { totalFolderNumber, totalFileNumber } = await getFolderService(strapi).deleteByIds(matched.map((folder)=>folder.id));
+        return ok({
+            dryRun: false,
+            folders,
+            totalFolderNumber,
+            totalFileNumber
+        });
+    };
+};
+
+export { createMediaCreateFolderHandler, createMediaDeleteFolderHandler, createMediaMoveFolderHandler, createMediaRenameFolderHandler };
+//# sourceMappingURL=folder-handlers.mjs.map

package/dist/server/mcp/handlers/folder-handlers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-handlers.mjs","sources":["../../../../server/src/mcp/handlers/folder-handlers.ts"],"sourcesContent":["import { errors } from '@strapi/utils';\nimport type { Core, Modules } from '@strapi/types';\n\nimport { assertAmbientInstance, getFolderService } from '../ambient-instance';\nimport { ACTIONS, FOLDER_MODEL_UID, FILE_MODEL_UID } from '../../constants';\nimport { isFolderOrChild } from '../../controllers/utils/folders';\nimport { assertMediaPermission } from '../permissions';\nimport { sanitizeMediaFolder } from '../sanitizers/sanitize-media';\nimport {\n  MCP_NOT_FOUND_FOLDER,\n  MCP_FOLDER_NAME_TAKEN,\n  MCP_PARENT_FOLDER_NOT_FOUND,\n  MCP_FOLDER_MOVE_INTO_SELF,\n  MCP_DELETE_FOLDER_UNRESOLVED_IDS,\n} from './constants';\nimport { ok } from '../utils';\n\nimport type { Folder } from '../../types';\n\n// Arg types are type-level only: the MCP SDK validates `args` against the tool's strict Zod\n// input schema before the handler runs, so unknown keys never reach here.\ntype CreateFolderArgs = {\n  name: string;\n  parent?: number | null;\n};\n\ntype RenameFolderArgs = {\n  id: number;\n  name: string;\n};\n\ntype MoveFolderArgs = {\n  id: number;\n  parent: number | null;\n};\n\ntype DeleteFolderArgs = {\n  ids: number[];\n  dryRun?: boolean;\n};\n\n/** The folder fields the handlers need; `path` drives the cascade and subtree checks. */\ntype FolderRow = Pick<Folder, 'id' | 'name' | 'path'>;\n\n/**\n * `withParent` populates the parent relation in the same round trip. Rename needs the parent id\n * to scope its sibling-uniqueness check, so it would otherwise read the same row twice; the\n * subtree and cascade callers do not, and skip the join.\n */\nconst findFolderById = async (\n  strapi: Core.Strapi,\n  id: number,\n  { withParent = false }: { withParent?: boolean } = {}\n): Promise<(FolderRow & { parent?: { id: number } | null }) | null> =>\n  strapi.db.query(FOLDER_MODEL_UID).findOne({\n    select: ['id', 'name', 'path'],\n    where: { id },\n    ...(withParent ? { populate: { parent: { select: ['id'] } } } : {}),\n  });\n\n/**\n * Re-reads a folder with its parent populated, so the write tools can echo back the same shape\n * regardless of what the service returned.\n *\n * `folder.update()` resolves the row it wrote without the `parent` relation, and on a pure rename\n * it never touches the join table at all — so the parent has to be read back to be reported.\n */\nconst readFolderForOutput = async (\n  strapi: Core.Strapi,\n  id: number,\n  fallback: Record<string, unknown>\n) => {\n  const row = await strapi.db.query(FOLDER_MODEL_UID).findOne({\n    where: { id },\n    populate: { parent: { select: ['id', 'name'] } },\n  });\n\n  // The write succeeded, so report it even if the read-back comes back empty rather than\n  // failing a completed operation on a follow-up query.\n  return sanitizeMediaFolder(row ?? fallback);\n};\n\n/**\n * Replicates the admin folder controller's `parent` check: a named parent must exist.\n *\n * null is the media library root and always valid, so only a numeric id is looked up.\n */\nconst assertParentExists = async (strapi: Core.Strapi, parent: number | null | undefined) => {\n  if (parent === null || parent === undefined) {\n    return;\n  }\n\n  const exists = await getFolderService(strapi).exists({ id: parent });\n\n  if (!exists) {\n    throw new errors.ValidationError(MCP_PARENT_FOLDER_NOT_FOUND);\n  }\n};\n\n/**\n * Replicates `is-folder-unique` from the admin folder validation: a folder name must be unique\n * among its siblings.\n *\n * `excludeId` is the folder being renamed — without it a rename to the folder's current name\n * would collide with itself.\n */\nconst assertNameAvailable = async (\n  strapi: Core.Strapi,\n  name: string,\n  parent: number | null,\n  excludeId?: number\n) => {\n  const filters: Record<string, unknown> = { name, parent: parent ?? null };\n\n  if (excludeId !== undefined) {\n    filters.id = { $ne: excludeId };\n  }\n\n  if (await getFolderService(strapi).exists(filters)) {\n    throw new errors.ValidationError(MCP_FOLDER_NAME_TAKEN);\n  }\n};\n\n/**\n * Replicates `dont-move-inside-self`: a folder cannot become its own descendant.\n *\n * Without this the folder service would rewrite the subtree's materialized paths into a cycle,\n * orphaning every descendant — the tree has no root to walk back to afterwards.\n */\nconst assertNotMovedIntoOwnSubtree = async (\n  strapi: Core.Strapi,\n  folder: FolderRow,\n  parent: number | null\n) => {\n  if (parent === null) {\n    return;\n  }\n\n  const destination = await findFolderById(strapi, parent);\n\n  // A missing destination is already reported by `assertParentExists`.\n  if (destination === null) {\n    return;\n  }\n\n  if (isFolderOrChild(destination, folder)) {\n    throw new errors.ValidationError(MCP_FOLDER_MOVE_INTO_SELF);\n  }\n};\n\n/**\n * Counts the folders and files a `deleteByIds` of these paths would remove.\n *\n * Mirrors the two `$or` predicates in `folder.deleteByIds` exactly — self path plus the\n * `${path}/` prefix — so the dry-run number is the same set the destructive branch acts on\n * rather than an independent estimate that could drift from it.\n */\nconst countCascade = async (strapi: Core.Strapi, paths: string[]) => {\n  const pathPredicate = (field: string) => ({\n    $or: paths.flatMap((path) => [\n      { [field]: { $eq: path } },\n      { [field]: { $startsWith: `${path}/` } },\n    ]),\n  });\n\n  const [totalFolderNumber, totalFileNumber] = await Promise.all([\n    strapi.db.query(FOLDER_MODEL_UID).count({ where: pathPredicate('path') }),\n    strapi.db.query(FILE_MODEL_UID).count({ where: pathPredicate('folderPath') }),\n  ]);\n\n  return { totalFolderNumber, totalFileNumber };\n};\n\n/**\n * `media_create_folder` — a new folder, optionally nested.\n *\n * Gated on `plugin::upload.assets.create` and mirrors `POST /upload/folders`: the same\n * permission, the same uniqueness and parent-existence validation, the same `folder.create()`\n * call, and the same `createdBy` attribution from the session user.\n *\n * `create` rather than the `update` the other folder tools use: creating a folder is the one\n * folder operation whose admin route gates on `assets.create`.\n */\nexport const createMediaCreateFolderHandler = (\n  strapi: Core.Strapi,\n  context: Modules.MCP.McpHandlerContext\n) => {\n  assertAmbientInstance(strapi);\n\n  return async ({\n    args,\n  }: {\n    args: Record<string, unknown>;\n  }): Promise<Modules.MCP.McpToolHandlerReturn> => {\n    const { name, parent = null } = args as CreateFolderArgs;\n\n    assertMediaPermission(strapi, context, ACTIONS.create, FOLDER_MODEL_UID);\n\n    await assertParentExists(strapi, parent);\n    await assertNameAvailable(strapi, name, parent);\n\n    const created = await getFolderService(strapi).create({ name, parent }, { user: context.user });\n\n    return ok({ data: await readFolderForOutput(strapi, created.id, created) });\n  };\n};\n\n/**\n * `media_rename_folder` — changes a folder's name and nothing else.\n *\n * Deliberately does not forward `parent` to `folder.update()`: the service branches on\n * `isUndefined(parent)`, and the name-only branch skips the transaction that rewrites descendant\n * paths. Passing the folder's existing parent would take the move branch and rewrite the whole\n * subtree to compute the identical paths.\n */\nexport const createMediaRenameFolderHandler = (\n  strapi: Core.Strapi,\n  context: Modules.MCP.McpHandlerContext\n) => {\n  assertAmbientInstance(strapi);\n\n  return async ({\n    args,\n  }: {\n    args: Record<string, unknown>;\n  }): Promise<Modules.MCP.McpToolHandlerReturn> => {\n    const { id, name } = args as RenameFolderArgs;\n\n    assertMediaPermission(strapi, context, ACTIONS.update, FOLDER_MODEL_UID);\n\n    const folder = await findFolderById(strapi, id, { withParent: true });\n\n    if (folder === null) {\n      throw new errors.NotFoundError(MCP_NOT_FOUND_FOLDER);\n    }\n\n    // Siblings are the folders sharing this folder's parent, so uniqueness is checked against\n    // the current location — a rename never changes it.\n    const parentId = folder.parent?.id ?? null;\n\n    await assertNameAvailable(strapi, name, parentId, id);\n\n    // `parent` is omitted on purpose — see the note above.\n    const renamed = await getFolderService(strapi).update(id, { name }, { user: context.user });\n\n    return ok({ data: await readFolderForOutput(strapi, id, renamed ?? { ...folder, name }) });\n  };\n};\n\n/**\n * `media_move_folder` — re-parents a folder, carrying its whole subtree with it.\n *\n * `folder.update()` recalculates the materialized `path` of every descendant folder and the\n * `folderPath` of every contained file inside a transaction, so the move is atomic and no\n * separate bookkeeping is needed here.\n */\nexport const createMediaMoveFolderHandler = (\n  strapi: Core.Strapi,\n  context: Modules.MCP.McpHandlerContext\n) => {\n  assertAmbientInstance(strapi);\n\n  return async ({\n    args,\n  }: {\n    args: Record<string, unknown>;\n  }): Promise<Modules.MCP.McpToolHandlerReturn> => {\n    const { id, parent } = args as MoveFolderArgs;\n\n    assertMediaPermission(strapi, context, ACTIONS.update, FOLDER_MODEL_UID);\n\n    const folder = await findFolderById(strapi, id);\n\n    if (folder === null) {\n      throw new errors.NotFoundError(MCP_NOT_FOUND_FOLDER);\n    }\n\n    await assertParentExists(strapi, parent);\n    await assertNotMovedIntoOwnSubtree(strapi, folder, parent);\n\n    // A folder keeps its name across a move, so uniqueness must hold in the destination.\n    await assertNameAvailable(strapi, folder.name, parent, id);\n\n    const moved = await getFolderService(strapi).update(\n      id,\n      { name: folder.name, parent },\n      { user: context.user }\n    );\n\n    return ok({ data: await readFolderForOutput(strapi, id, moved ?? folder) });\n  };\n};\n\n/**\n * `media_delete_folder` — previews or performs a cascading folder deletion.\n *\n * Two branches behind one tool, because the preview and the deletion must agree on what the\n * cascade covers; splitting them across tools would let the two drift apart, and an agent could\n * reach the destructive one without ever seeing a count.\n *\n * `dryRun` defaults to true (see the input schema): omitting the flag previews, and deleting\n * takes an explicit `dryRun: false`.\n */\nexport const createMediaDeleteFolderHandler = (\n  strapi: Core.Strapi,\n  context: Modules.MCP.McpHandlerContext\n) => {\n  assertAmbientInstance(strapi);\n\n  return async ({\n    args,\n  }: {\n    args: Record<string, unknown>;\n  }): Promise<Modules.MCP.McpToolHandlerReturn> => {\n    const { ids, dryRun = true } = args as DeleteFolderArgs;\n\n    assertMediaPermission(strapi, context, ACTIONS.update, FOLDER_MODEL_UID);\n\n    const matched: FolderRow[] = await strapi.db.query(FOLDER_MODEL_UID).findMany({\n      select: ['id', 'name', 'path'],\n      where: { id: { $in: ids } },\n    });\n\n    /**\n     * All-or-nothing: any id that does not resolve to a folder rejects the whole call, before\n     * anything is deleted.\n     *\n     * Folder ids and asset ids are indistinguishable integers, so a list mixing the two is the\n     * mistake this tool exists to catch — and deleting the folders that did match while\n     * reporting the rest back would be exactly the silent confusion that requirement forbids,\n     * with the cascade already gone by the time the agent reads the response.\n     *\n     * An unresolvable id cannot be diagnosed further from here (an asset id and a deleted\n     * folder id look identical), and it does not need to be: either way it is unusable.\n     *\n     * The dry run rejects on the same rule. A preview that reported a cascade for a request the\n     * executing call would refuse is worse than no preview — it is a confirmation an agent\n     * cannot act on.\n     */\n    const matchedIds = new Set(matched.map((folder) => folder.id));\n    const unresolvedIds = ids.filter((id) => matchedIds.has(id) === false);\n\n    if (unresolvedIds.length > 0) {\n      throw new errors.ValidationError(MCP_DELETE_FOLDER_UNRESOLVED_IDS(unresolvedIds));\n    }\n\n    const folders = matched.map((folder) => sanitizeMediaFolder(folder));\n\n    if (dryRun) {\n      const counts = await countCascade(\n        strapi,\n        matched.map((folder) => folder.path)\n      );\n\n      return ok({ dryRun: true, folders, ...counts });\n    }\n\n    const { totalFolderNumber, totalFileNumber } = await getFolderService(strapi).deleteByIds(\n      matched.map((folder) => folder.id)\n    );\n\n    return ok({\n      dryRun: false,\n      folders,\n      totalFolderNumber,\n      totalFileNumber,\n    });\n  };\n};\n"],"names":["findFolderById","strapi","id","withParent","db","query","FOLDER_MODEL_UID","findOne","select","where","populate","parent","readFolderForOutput","fallback","row","sanitizeMediaFolder","assertParentExists","undefined","exists","getFolderService","errors","ValidationError","MCP_PARENT_FOLDER_NOT_FOUND","assertNameAvailable","name","excludeId","filters","$ne","MCP_FOLDER_NAME_TAKEN","assertNotMovedIntoOwnSubtree","folder","destination","isFolderOrChild","MCP_FOLDER_MOVE_INTO_SELF","countCascade","paths","pathPredicate","field","$or","flatMap","path","$eq","$startsWith","totalFolderNumber","totalFileNumber","Promise","all","count","FILE_MODEL_UID","createMediaCreateFolderHandler","context","assertAmbientInstance","args","assertMediaPermission","ACTIONS","create","created","user","ok","data","createMediaRenameFolderHandler","update","NotFoundError","MCP_NOT_FOUND_FOLDER","parentId","renamed","createMediaMoveFolderHandler","moved","createMediaDeleteFolderHandler","ids","dryRun","matched","findMany","$in","matchedIds","Set","map","unresolvedIds","filter","has","length","MCP_DELETE_FOLDER_UNRESOLVED_IDS","folders","counts","deleteByIds"],"mappings":"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"}

package/dist/server/mcp/handlers/read-handlers.js

@@ -0,0 +1,134 @@
+'use strict';
+
+var utils$1 = require('@strapi/utils');
+var index = require('../../utils/index.js');
+var ambientInstance = require('../ambient-instance.js');
+var constants = require('../../constants.js');
+var permissions = require('../permissions.js');
+var findEntityAndCheckPermissions = require('../../controllers/utils/find-entity-and-check-permissions.js');
+var sanitizeMedia = require('../sanitizers/sanitize-media.js');
+var constants$1 = require('./constants.js');
+var utils = require('../utils.js');
+
+const DEFAULT_SORT = 'createdAt:DESC';
+/**
+ * Builds the `filters` clause for `media_list_assets`.
+ *
+ * `folderId: null` is meaningfully different from an omitted `folderId`: null means "assets at
+ * the media library root" (no folder relation), while omitting it means "any folder".
+ *
+ * `mime` accepts both a full type and a bare prefix. An exact match on "image" would never hit,
+ * so a value without a slash is matched as a prefix ("image" → every "image/*").
+ */ const buildAssetFilters = (args)=>{
+    const filters = {};
+    if (args.folderId === null) {
+        filters.folder = null;
+    } else if (args.folderId !== undefined) {
+        filters.folder = {
+            id: args.folderId
+        };
+    }
+    if (args.mime !== undefined) {
+        filters.mime = args.mime.includes('/') ? {
+            $eqi: args.mime
+        } : {
+            $startsWithi: `${args.mime}/`
+        };
+    }
+    if (args.name !== undefined) {
+        filters.name = {
+            $containsi: args.name
+        };
+    }
+    return filters;
+};
+/**
+ * `media_list_assets` — paginated, filtered listing of media files.
+ *
+ * Permission conditions are applied through the permissions manager
+ * (`addPermissionsQueryTo`) so a token restricted by a condition — e.g. own-assets-only —
+ * sees the same subset it would through the admin API.
+ */ const createMediaListAssetsHandler = (strapi, context)=>{
+    ambientInstance.assertAmbientInstance(strapi);
+    return async ({ args })=>{
+        const { folderId, mime, name, page, pageSize, sort } = args;
+        const pm = permissions.assertMediaPermission(strapi, context, constants.ACTIONS.read, constants.FILE_MODEL_UID);
+        const query = await pm.addPermissionsQueryTo({
+            filters: buildAssetFilters({
+                folderId,
+                mime,
+                name
+            }),
+            sort: sort ?? DEFAULT_SORT,
+            page: page ?? 1,
+            pageSize: pageSize ?? 25,
+            populate: {
+                folder: {
+                    fields: [
+                        'id',
+                        'name'
+                    ]
+                }
+            }
+        });
+        const { results, pagination } = await index.getService('upload', strapi).findPage(query);
+        return utils.ok({
+            results: results.map(sanitizeMedia.sanitizeMediaAsset),
+            pagination
+        });
+    };
+};
+/**
+ * `media_get_asset` — a single asset by numeric id.
+ *
+ * Row-level permission *conditions* are enforced by `findEntityAndCheckPermissions`, the same
+ * helper the admin `findOne` controller uses: it populates `createdBy` and the creator's roles
+ * before building the CASL subject, which is what the admin conditions read. Checking a subject
+ * without those fields would deny a conditioned grant its own assets, and would disagree with
+ * `media_list_assets`, where the condition is pushed into the query instead.
+ */ const createMediaGetAssetHandler = (strapi, context)=>{
+    ambientInstance.assertAmbientInstance(strapi);
+    return async ({ args })=>{
+        const { id } = args;
+        // Model-level gate first, so a token without upload read at all is refused before a lookup.
+        permissions.assertMediaPermission(strapi, context, constants.ACTIONS.read, constants.FILE_MODEL_UID);
+        let asset;
+        try {
+            ({ file: asset } = await findEntityAndCheckPermissions.findEntityAndCheckPermissions(context.userAbility, constants.ACTIONS.read, constants.FILE_MODEL_UID, id, strapi));
+        } catch (error) {
+            // The helper is written for HTTP, where a bare NotFoundError is enough. MCP answers an
+            // agent, so restate it with the message the other media tools use.
+            if (error instanceof utils$1.errors.NotFoundError) {
+                throw new utils$1.errors.NotFoundError(constants$1.MCP_NOT_FOUND_ASSET);
+            }
+            throw error;
+        }
+        return utils.ok({
+            data: sanitizeMedia.sanitizeMediaAsset(asset)
+        });
+    };
+};
+/**
+ * `media_list_folders` — the nested folder structure, reusing `folder.getStructure()`.
+ *
+ * `getStructure()` returns the whole tree in one query and has no permission-condition
+ * filtering, so this is gated on the model-level read permission only — matching
+ * `GET /upload/folder-structure` in the admin API.
+ *
+ * The factory asserts the handler's instance is the ambient `global.strapi` the folder service
+ * actually queries — see `assertAmbientInstance` for why.
+ */ const createMediaListFoldersHandler = (strapi, context)=>{
+    ambientInstance.assertAmbientInstance(strapi);
+    return async ()=>{
+        permissions.assertMediaPermission(strapi, context, constants.ACTIONS.read, constants.FOLDER_MODEL_UID);
+        const structure = await ambientInstance.getFolderService(strapi).getStructure();
+        return utils.ok({
+            data: sanitizeMedia.sanitizeMediaFolderTree(structure)
+        });
+    };
+};
+
+exports.createMediaGetAssetHandler = createMediaGetAssetHandler;
+exports.createMediaListAssetsHandler = createMediaListAssetsHandler;
+exports.createMediaListFoldersHandler = createMediaListFoldersHandler;
+//# sourceMappingURL=read-handlers.js.map

package/dist/server/mcp/handlers/read-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-handlers.js","sources":["../../../../server/src/mcp/handlers/read-handlers.ts"],"sourcesContent":["import { errors } from '@strapi/utils';\nimport type { Core, Modules } from '@strapi/types';\n\nimport { getService } from '../../utils';\nimport { assertAmbientInstance, getFolderService } from '../ambient-instance';\nimport { ACTIONS, FILE_MODEL_UID, FOLDER_MODEL_UID } from '../../constants';\nimport { assertMediaPermission } from '../permissions';\nimport { findEntityAndCheckPermissions } from '../../controllers/utils/find-entity-and-check-permissions';\nimport { sanitizeMediaAsset, sanitizeMediaFolderTree } from '../sanitizers/sanitize-media';\nimport { MCP_NOT_FOUND_ASSET } from './constants';\nimport { ok } from '../utils';\n\nconst DEFAULT_SORT = 'createdAt:DESC';\n\n// Arg types are type-level only: the MCP SDK validates `args` against the tool's Zod input\n// schema before the handler runs, so handlers accept the erased `Record<string, unknown>` the\n// registry hands them and narrow it here.\ntype ListMediaArgs = {\n  folderId?: number | null;\n  mime?: string;\n  name?: string;\n  page?: number;\n  pageSize?: number;\n  sort?: string;\n};\n\ntype GetMediaArgs = {\n  id: number;\n};\n\n/**\n * Builds the `filters` clause for `media_list_assets`.\n *\n * `folderId: null` is meaningfully different from an omitted `folderId`: null means \"assets at\n * the media library root\" (no folder relation), while omitting it means \"any folder\".\n *\n * `mime` accepts both a full type and a bare prefix. An exact match on \"image\" would never hit,\n * so a value without a slash is matched as a prefix (\"image\" → every \"image/*\").\n */\nconst buildAssetFilters = (args: ListMediaArgs): Record<string, unknown> => {\n  const filters: Record<string, unknown> = {};\n\n  if (args.folderId === null) {\n    filters.folder = null;\n  } else if (args.folderId !== undefined) {\n    filters.folder = { id: args.folderId };\n  }\n\n  if (args.mime !== undefined) {\n    filters.mime = args.mime.includes('/')\n      ? { $eqi: args.mime }\n      : { $startsWithi: `${args.mime}/` };\n  }\n\n  if (args.name !== undefined) {\n    filters.name = { $containsi: args.name };\n  }\n\n  return filters;\n};\n\n/**\n * `media_list_assets` — paginated, filtered listing of media files.\n *\n * Permission conditions are applied through the permissions manager\n * (`addPermissionsQueryTo`) so a token restricted by a condition — e.g. own-assets-only —\n * sees the same subset it would through the admin API.\n */\nexport const createMediaListAssetsHandler = (\n  strapi: Core.Strapi,\n  context: Modules.MCP.McpHandlerContext\n) => {\n  assertAmbientInstance(strapi);\n\n  return async ({\n    args,\n  }: {\n    args: Record<string, unknown>;\n  }): Promise<Modules.MCP.McpToolHandlerReturn> => {\n    const { folderId, mime, name, page, pageSize, sort } = args as ListMediaArgs;\n    const pm = assertMediaPermission(strapi, context, ACTIONS.read, FILE_MODEL_UID);\n\n    const query = await pm.addPermissionsQueryTo({\n      filters: buildAssetFilters({ folderId, mime, name }),\n      sort: sort ?? DEFAULT_SORT,\n      page: page ?? 1,\n      pageSize: pageSize ?? 25,\n      populate: { folder: { fields: ['id', 'name'] } },\n    });\n\n    const { results, pagination } = await getService('upload', strapi).findPage(query);\n\n    return ok({\n      results: results.map(sanitizeMediaAsset),\n      pagination,\n    });\n  };\n};\n\n/**\n * `media_get_asset` — a single asset by numeric id.\n *\n * Row-level permission *conditions* are enforced by `findEntityAndCheckPermissions`, the same\n * helper the admin `findOne` controller uses: it populates `createdBy` and the creator's roles\n * before building the CASL subject, which is what the admin conditions read. Checking a subject\n * without those fields would deny a conditioned grant its own assets, and would disagree with\n * `media_list_assets`, where the condition is pushed into the query instead.\n */\nexport const createMediaGetAssetHandler = (\n  strapi: Core.Strapi,\n  context: Modules.MCP.McpHandlerContext\n) => {\n  assertAmbientInstance(strapi);\n\n  return async ({\n    args,\n  }: {\n    args: Record<string, unknown>;\n  }): Promise<Modules.MCP.McpToolHandlerReturn> => {\n    const { id } = args as GetMediaArgs;\n\n    // Model-level gate first, so a token without upload read at all is refused before a lookup.\n    assertMediaPermission(strapi, context, ACTIONS.read, FILE_MODEL_UID);\n\n    let asset;\n    try {\n      ({ file: asset } = await findEntityAndCheckPermissions(\n        context.userAbility,\n        ACTIONS.read,\n        FILE_MODEL_UID,\n        id,\n        strapi\n      ));\n    } catch (error) {\n      // The helper is written for HTTP, where a bare NotFoundError is enough. MCP answers an\n      // agent, so restate it with the message the other media tools use.\n      if (error instanceof errors.NotFoundError) {\n        throw new errors.NotFoundError(MCP_NOT_FOUND_ASSET);\n      }\n      throw error;\n    }\n\n    return ok({ data: sanitizeMediaAsset(asset) });\n  };\n};\n\n/**\n * `media_list_folders` — the nested folder structure, reusing `folder.getStructure()`.\n *\n * `getStructure()` returns the whole tree in one query and has no permission-condition\n * filtering, so this is gated on the model-level read permission only — matching\n * `GET /upload/folder-structure` in the admin API.\n *\n * The factory asserts the handler's instance is the ambient `global.strapi` the folder service\n * actually queries — see `assertAmbientInstance` for why.\n */\nexport const createMediaListFoldersHandler = (\n  strapi: Core.Strapi,\n  context: Modules.MCP.McpHandlerContext\n) => {\n  assertAmbientInstance(strapi);\n\n  return async (): Promise<Modules.MCP.McpToolHandlerReturn> => {\n    assertMediaPermission(strapi, context, ACTIONS.read, FOLDER_MODEL_UID);\n\n    const structure = await getFolderService(strapi).getStructure();\n\n    return ok({ data: sanitizeMediaFolderTree(structure) });\n  };\n};\n"],"names":["DEFAULT_SORT","buildAssetFilters","args","filters","folderId","folder","undefined","id","mime","includes","$eqi","$startsWithi","name","$containsi","createMediaListAssetsHandler","strapi","context","assertAmbientInstance","page","pageSize","sort","pm","assertMediaPermission","ACTIONS","read","FILE_MODEL_UID","query","addPermissionsQueryTo","populate","fields","results","pagination","getService","findPage","ok","map","sanitizeMediaAsset","createMediaGetAssetHandler","asset","file","findEntityAndCheckPermissions","userAbility","error","errors","NotFoundError","MCP_NOT_FOUND_ASSET","data","createMediaListFoldersHandler","FOLDER_MODEL_UID","structure","getFolderService","getStructure","sanitizeMediaFolderTree"],"mappings":"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"}

package/dist/server/mcp/handlers/read-handlers.mjs

@@ -0,0 +1,130 @@
+import { errors } from '@strapi/utils';
+import { getService } from '../../utils/index.mjs';
+import { assertAmbientInstance, getFolderService } from '../ambient-instance.mjs';
+import { ACTIONS, FILE_MODEL_UID, FOLDER_MODEL_UID } from '../../constants.mjs';
+import { assertMediaPermission } from '../permissions.mjs';
+import { findEntityAndCheckPermissions } from '../../controllers/utils/find-entity-and-check-permissions.mjs';
+import { sanitizeMediaAsset, sanitizeMediaFolderTree } from '../sanitizers/sanitize-media.mjs';
+import { MCP_NOT_FOUND_ASSET } from './constants.mjs';
+import { ok } from '../utils.mjs';
+
+const DEFAULT_SORT = 'createdAt:DESC';
+/**
+ * Builds the `filters` clause for `media_list_assets`.
+ *
+ * `folderId: null` is meaningfully different from an omitted `folderId`: null means "assets at
+ * the media library root" (no folder relation), while omitting it means "any folder".
+ *
+ * `mime` accepts both a full type and a bare prefix. An exact match on "image" would never hit,
+ * so a value without a slash is matched as a prefix ("image" → every "image/*").
+ */ const buildAssetFilters = (args)=>{
+    const filters = {};
+    if (args.folderId === null) {
+        filters.folder = null;
+    } else if (args.folderId !== undefined) {
+        filters.folder = {
+            id: args.folderId
+        };
+    }
+    if (args.mime !== undefined) {
+        filters.mime = args.mime.includes('/') ? {
+            $eqi: args.mime
+        } : {
+            $startsWithi: `${args.mime}/`
+        };
+    }
+    if (args.name !== undefined) {
+        filters.name = {
+            $containsi: args.name
+        };
+    }
+    return filters;
+};
+/**
+ * `media_list_assets` — paginated, filtered listing of media files.
+ *
+ * Permission conditions are applied through the permissions manager
+ * (`addPermissionsQueryTo`) so a token restricted by a condition — e.g. own-assets-only —
+ * sees the same subset it would through the admin API.
+ */ const createMediaListAssetsHandler = (strapi, context)=>{
+    assertAmbientInstance(strapi);
+    return async ({ args })=>{
+        const { folderId, mime, name, page, pageSize, sort } = args;
+        const pm = assertMediaPermission(strapi, context, ACTIONS.read, FILE_MODEL_UID);
+        const query = await pm.addPermissionsQueryTo({
+            filters: buildAssetFilters({
+                folderId,
+                mime,
+                name
+            }),
+            sort: sort ?? DEFAULT_SORT,
+            page: page ?? 1,
+            pageSize: pageSize ?? 25,
+            populate: {
+                folder: {
+                    fields: [
+                        'id',
+                        'name'
+                    ]
+                }
+            }
+        });
+        const { results, pagination } = await getService('upload', strapi).findPage(query);
+        return ok({
+            results: results.map(sanitizeMediaAsset),
+            pagination
+        });
+    };
+};
+/**
+ * `media_get_asset` — a single asset by numeric id.
+ *
+ * Row-level permission *conditions* are enforced by `findEntityAndCheckPermissions`, the same
+ * helper the admin `findOne` controller uses: it populates `createdBy` and the creator's roles
+ * before building the CASL subject, which is what the admin conditions read. Checking a subject
+ * without those fields would deny a conditioned grant its own assets, and would disagree with
+ * `media_list_assets`, where the condition is pushed into the query instead.
+ */ const createMediaGetAssetHandler = (strapi, context)=>{
+    assertAmbientInstance(strapi);
+    return async ({ args })=>{
+        const { id } = args;
+        // Model-level gate first, so a token without upload read at all is refused before a lookup.
+        assertMediaPermission(strapi, context, ACTIONS.read, FILE_MODEL_UID);
+        let asset;
+        try {
+            ({ file: asset } = await findEntityAndCheckPermissions(context.userAbility, ACTIONS.read, FILE_MODEL_UID, id, strapi));
+        } catch (error) {
+            // The helper is written for HTTP, where a bare NotFoundError is enough. MCP answers an
+            // agent, so restate it with the message the other media tools use.
+            if (error instanceof errors.NotFoundError) {
+                throw new errors.NotFoundError(MCP_NOT_FOUND_ASSET);
+            }
+            throw error;
+        }
+        return ok({
+            data: sanitizeMediaAsset(asset)
+        });
+    };
+};
+/**
+ * `media_list_folders` — the nested folder structure, reusing `folder.getStructure()`.
+ *
+ * `getStructure()` returns the whole tree in one query and has no permission-condition
+ * filtering, so this is gated on the model-level read permission only — matching
+ * `GET /upload/folder-structure` in the admin API.
+ *
+ * The factory asserts the handler's instance is the ambient `global.strapi` the folder service
+ * actually queries — see `assertAmbientInstance` for why.
+ */ const createMediaListFoldersHandler = (strapi, context)=>{
+    assertAmbientInstance(strapi);
+    return async ()=>{
+        assertMediaPermission(strapi, context, ACTIONS.read, FOLDER_MODEL_UID);
+        const structure = await getFolderService(strapi).getStructure();
+        return ok({
+            data: sanitizeMediaFolderTree(structure)
+        });
+    };
+};
+
+export { createMediaGetAssetHandler, createMediaListAssetsHandler, createMediaListFoldersHandler };
+//# sourceMappingURL=read-handlers.mjs.map