aps_get_folder_tree

Visualize folder hierarchies and file counts in Autodesk Platform Services projects to understand project organization. Specify project and folder IDs with optional depth control.

Instructions

Build a recursive folder‑tree structure showing subfolder hierarchy and file counts per folder. Useful for understanding a project's organisation at a glance. ⚠️ Each level makes an API call, so keep max_depth low (default 3) to avoid rate limits.

Input Schema

TableJSON Schema

Name	Required	Description
`project_id`	Yes	Project ID – starts with 'b.'.
`folder_id`	Yes	Root folder URN – starts with 'urn:'.
`max_depth`	No	Maximum recursion depth (1‑5). Default 3.

Implementation Reference

src/index.ts:1153-1166 (handler)

The handler for 'aps_get_folder_tree' in src/index.ts. It validates input parameters and calls the helper function 'buildFolderTree'.

// ── aps_get_folder_tree ──────────────────────────────────────
if (name === "aps_get_folder_tree") {
  const projectId = args.project_id as string;
  const folderId = args.folder_id as string;
  const e1 = validateProjectId(projectId);
  if (e1) return fail(e1);
  const e2 = validateFolderId(folderId);
  if (e2) return fail(e2);

  const maxDepth = Math.min(Math.max(Number(args.max_depth) || 3, 1), 5);
  const t = await token();
  const tree = await buildFolderTree(projectId, folderId, t, maxDepth);
  return json(tree);
}

src/aps-dm-helpers.ts:315-382 (helper)

The implementation of the recursive folder tree builder. It fetches contents, handles depth limits, and constructs the tree structure.

export async function buildFolderTree(
  projectId: string,
  folderId: string,
  token: string,
  maxDepth: number = 3,
  _currentDepth: number = 0,
): Promise<FolderTreeNode> {
  const path = `data/v1/projects/${projectId}/folders/${encodeURIComponent(folderId)}/contents`;
  const raw = (await apsDmRequest("GET", path, token, {
    query: { "page[limit]": "200" },
  })) as Record<string, unknown>;
  const data = Array.isArray(raw.data) ? (raw.data as Record<string, unknown>[]) : [];

  const childFolders: FolderTreeNode[] = [];
  let fileCount = 0;

  for (const item of data) {
    const attrs = item.attributes as Record<string, unknown> | undefined;
    if (item.type === "folders") {
      if (_currentDepth < maxDepth - 1) {
        const child = await buildFolderTree(
          projectId,
          item.id as string,
          token,
          maxDepth,
          _currentDepth + 1,
        );
        child.name = (attrs?.displayName as string) ?? "(unknown)";
        childFolders.push(child);
      } else {
        childFolders.push({
          name: (attrs?.displayName as string) ?? "(unknown)",
          id: item.id as string,
          type: "folder",
          // max depth reached – children not fetched
        });
      }
    } else {
      fileCount++;
    }
  }

  // Resolve folder name at the root level of the call
  let folderName = folderId;
  if (_currentDepth === 0) {
    try {
      const folderRaw = (await apsDmRequest(
        "GET",
        `data/v1/projects/${projectId}/folders/${encodeURIComponent(folderId)}`,
        token,
      )) as Record<string, unknown>;
      const fAttrs = (folderRaw.data as Record<string, unknown>)?.attributes as
        | Record<string, unknown>
        | undefined;
      folderName = (fAttrs?.displayName as string) ?? folderId;
    } catch {
      // keep folderId as name
    }
  }

  return {
    name: folderName,
    id: folderId,
    type: "folder",
    children: childFolders.length > 0 ? childFolders : undefined,
    file_count: fileCount,
  };
}

ACC.MCP