# Optimize Large Directory Listings Using Depth and Pagination in Desktop Commander MCP

> Learn how to optimize large directory listings in Desktop Commander MCP with depth-limited recursion and on-demand pagination. Prevent context overflow and improve performance efficiently.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: performance
- Published: 2026-07-25

---

**Desktop Commander MCP prevents LLM context overflow by combining depth-limited recursion, a 100-item per-directory cap, and on-demand pagination via the `list_directory` tool.**

Desktop Commander MCP, an open-source Model Context Protocol server by wonderwhy-er, provides sophisticated filesystem tooling designed to handle massive directory trees without exhausting token budgets. When you need to explore large codebases or directories containing thousands of files, the `list_directory` tool employs a three-layer defense mechanism to optimize large directory listings using depth and pagination.

## How Depth-Limited Recursion Works

The foundation of Desktop Commander's optimization strategy lies in controlled recursion depth. Instead of walking entire directory trees indefinitely, the tool respects a configurable depth parameter that defaults to two levels.

### The Core Algorithm in filesystem.ts

In [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts), the `listDirectory` function implements recursive traversal with an explicit depth counter:

```typescript
// src/tools/filesystem.ts (lines 27-34)
if (currentDepth <= 0) return;
// ... process directory ...
await listRecursive(fullPath, currentDepth - 1, ...);

```

Each recursive call decrements the `currentDepth` parameter. When the counter reaches zero, the traversal stops, preventing the tool from descending into deeply nested structures like `node_modules` or `.git` directories. The default value of `depth: 2` strikes a balance between providing useful context and maintaining concise output.

## Context Protection Through Item Caps

Beyond depth control, Desktop Commander implements a hard limit on the number of items displayed per nested directory to prevent individual folders from flooding the context window.

### The MAX_NESTED_ITEMS Guard

The same [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) file defines a constant `MAX_NESTED_ITEMS = 100` that caps visibility for non-top-level directories:

```typescript
// src/tools/filesystem.ts (lines 51-81)
if (!isTopLevel && totalEntries > MAX_NESTED_ITEMS) {
    entriesToShow = entries.slice(0, MAX_NESTED_ITEMS);
    filteredCount = totalEntries - MAX_NESTED_ITEMS;
}

if (filteredCount > 0) {
    results.push(`[WARNING] ${displayPath}: ${filteredCount} items hidden ...`);
}

```

When a directory exceeds 100 items, the tool emits only the first 100 entries followed by a `[WARNING]` marker indicating how many items remain hidden. This approach ensures that a single directory with thousands of files cannot monopolize the LLM's context window.

## On-Demand Pagination for Deep Dives

The third optimization layer involves user-driven pagination, allowing selective expansion of truncated directories only when needed.

### The Load More Pattern in the UI

The frontend component in [`src/ui/file-preview/src/directory-controller.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/ui/file-preview/src/directory-controller.ts) renders interactive "Load More" buttons for any directory that triggered the item cap warning. When activated, it requests the full directory listing with `depth: 1`:

```typescript
// src/ui/file-preview/src/directory-controller.ts (lines 182-194)
const result = await options.callTool?.('list_directory', { 
  path: loadPath, 
  depth: 1, 
  origin: 'ui' 
});

```

This lazy-loading approach keeps initial responses lightweight while preserving the ability to inspect large directories fully. Users drill down only into directories relevant to their current task, maintaining optimal token efficiency.

## LLM Integration and Schema Documentation

The `list_directory` tool schema in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) (lines 774-892) explicitly documents these optimization features for the LLM. The description advises the model on proper depth usage and explains the context overflow protection mechanism, ensuring the LLM understands when to request deeper listings versus accepting the truncated summary.

According to the schema definition, valid depth values include:

- `depth: 1` — Only direct contents
- `depth: 2` — Contents plus one subdirectory level (default)
- `depth: 3+` — Multiple levels deep

## Practical Implementation Examples

### Listing with Default Depth Protection

To list a directory using the default safety settings:

```typescript
await callTool('list_directory', {
  path: '/Users/alice/large-project',
  // depth defaults to 2
});

```

Expected output:

```

[DIR] src
[FILE] src/index.ts
[DIR] src/tools
[FILE] src/tools/filesystem.ts
[WARNING] node_modules: 3522 items hidden (showing first 100 of 3622 total)

```

### Expanding a Large Directory on Demand

When encountering a warning, retrieve the complete listing for that specific directory:

```typescript
await callTool('list_directory', {
  path: '/Users/alice/large-project/node_modules',
  depth: 1  // List all immediate children
});

```

### Custom Depth for Specific Exploration

For targeted deep inspection:

```typescript
await callTool('list_directory', {
  path: '/var/log',
  depth: 3  // Navigate three levels deep
});

```

### Handling Access Errors

The tool also handles filesystem errors gracefully, returning structured markers:

```typescript
// Error handling in src/tools/filesystem.ts
if (err.code === 'ENOENT') {
  results.push(`[NOT_FOUND] ${displayPath} — path does not exist`);
} else if (err.code === 'EPERM' || err.code === 'EACCES') {
  results.push(`[DENIED] ${displayPath} — not accessible`);
}

```

## Summary

- **Depth-limited recursion** in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) prevents runaway traversal by decrementing a `currentDepth` counter until reaching zero, with a sensible default of two levels.
- **Per-directory caps** enforce a maximum of 100 items per nested folder via `MAX_NESTED_ITEMS`, emitting `[WARNING]` markers when truncation occurs.
- **On-demand pagination** allows users to expand truncated directories selectively through the UI controller in [`src/ui/file-preview/src/directory-controller.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/ui/file-preview/src/directory-controller.ts), fetching full listings only when explicitly requested.
- **Schema documentation** in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) ensures the LLM understands these constraints and can make informed decisions about depth parameters.
- **Error resilience** provides clear `[NOT_FOUND]` and `[DENIED]` markers when filesystem access fails, maintaining robust operation across permission boundaries.

## Frequently Asked Questions

### What is the default depth for directory listings in Desktop Commander MCP?

The `list_directory` tool defaults to `depth: 2`, meaning it displays the target directory's immediate contents plus one level of subdirectories. This default prevents accidental enumeration of massive trees like `node_modules` while still providing useful structural context. You can override this by specifying `depth: 1` for flat listings or higher values for deeper exploration.

### How does Desktop Commander handle directories with more than 100 items?

When a nested directory contains more than 100 items, the tool truncates the output to the first 100 entries and appends a `[WARNING]` message indicating the total count of hidden items. For example: `[WARNING] node_modules: 3522 items hidden (showing first 100 of 3622 total)`. The top-level directory remains exempt from this cap to ensure root visibility.

### Can I paginate through large directories programmatically?

Yes. While the UI provides "Load More" buttons that trigger `list_directory` calls with `depth: 1`, you can implement the same pattern programmatically. When you encounter a `[WARNING]` marker in the output, issue a new `list_directory` request targeting that specific subdirectory with an appropriate depth parameter to retrieve the complete listing.

### Where is the depth parameter validated in the codebase?

The depth parameter is defined in [`src/tools/schemas.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts) using Zod schema validation, ensuring type safety before reaching the core logic in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts). The tool description in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) (lines 774-892) further documents the parameter's behavior for the LLM, explaining how different depth values affect the traversal scope.