# How DesktopCommanderMCP Prevents Context Overflow in Recursive Directory Listings

> Learn how DesktopCommanderMCP prevents context overflow in recursive directory listings by limiting recursion depth, capping items per folder, and adding truncation warnings. Optimize your large folder management.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: deep-dive
- Published: 2026-08-08

---

**DesktopCommanderMCP prevents context overflow by enforcing a default recursion depth of 2, capping nested directory entries at 100 items per folder, and injecting explicit truncation warnings into the output stream.**

When working with large file systems, unbounded recursive listings can quickly exhaust an AI model's context window. The `wonderwhy-er/DesktopCommanderMCP` repository implements a hardened `listDirectory` routine in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) that balances comprehensive directory exploration with strict token budget protection.

## Depth-Limited Recursion

The primary defense against **context overflow** is a configurable depth parameter. The `listDirectory` function accepts a `depth` argument that defaults to `2`, meaning it traverses the target directory plus one sub-level.

In [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) at line 720, the recursive helper checks the current depth before proceeding:

```typescript
if (currentDepth <= 0) return;

```

This hard stop prevents the function from descending infinitely into deeply nested folder structures. The UI layer 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) (line 241) invokes the tool with this conservative default, while the HTTP API documented in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) (line 581) exposes the `depth` query parameter for power users who explicitly need deeper traversal.

## Hard Cap on Nested Items (MAX_NESTED_ITEMS)

Even with limited depth, individual directories might contain thousands of files. To prevent a single massive folder from flooding the context, the code enforces a **hard limit of 100 entries** for any non-top-level directory.

The constant is defined at line 724 of [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts):

```typescript
const MAX_NESTED_ITEMS = 100;

```

When enumerating children of a nested folder, the implementation never returns more than this maximum, regardless of how many files actually exist in that subdirectory.

## Selective Slicing with Hidden Item Counts

Rather than silently dropping entries, the `listDirectory` implementation slices the entry array and calculates exactly how many items were suppressed. At lines 751–755 of [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts), the code performs:

```typescript
const entriesToShow = entries.slice(0, MAX_NESTED_ITEMS);
const filteredCount = totalEntries - MAX_NESTED_ITEMS;

```

This approach preserves the first 100 items (typically the earliest alphabetically or by creation time, depending on the OS) while maintaining an accurate count of omitted files. The function tracks `filteredCount` separately for each truncated directory, ensuring the AI agent understands the true scale of the file system even when viewing a limited subset.

## User-Visible Truncation Warnings

Transparency is critical when data is elided. After processing a directory that exceeds the item cap, the system appends a warning line to the results array at lines 777–781:

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

```

These inline warnings signal to both the user interface and the consuming AI that the view is incomplete. This prevents hallucinations or incorrect assumptions about directory contents while keeping the total output size predictable.

## Standardized Error Handling

The implementation normalizes error responses to prevent exception stack traces or variable-length error messages from destabilizing context budgets. When encountering permission denials or missing directories, [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) (lines 333–442) returns fixed-format strings:

```typescript
if (err.code === 'ENOENT') return `[NOT_FOUND] ${path}`;
else if (err.code === 'EPERM') return `[DENIED] ${path}`;

```

These compact, consistent tokens replace verbose error objects, ensuring that even directories with hundreds of inaccessible entries contribute only minimal, fixed-size strings to the context.

## Practical Implementation Examples

### Basic Usage with Default Protection

```typescript
import { listDirectory } from "./tools/filesystem.js";

// Default depth = 2, nested items capped at 100
const result = await listDirectory("/Users/me/Documents");
console.log(result.join("\n"));

// Output:
// [DIR] Projects
// [FILE] notes.txt
// [DIR] Projects/MyApp
// [FILE] Projects/MyApp/main.ts
// [WARNING] Projects/MyApp: 452 items hidden (showing first 100 of 552 total)

```

### Increasing Recursion Depth

```typescript
// Request deeper traversal (monitor token usage carefully)
const deepResult = await listDirectory("/var/log", 4);

```

### Programmatic Warning Detection

```typescript
for (const line of deepResult) {
  if (line.startsWith("[WARNING]")) {
    console.warn("Context truncation occurred:", line);
    // Implement pagination or targeted sub-queries here
  }
}

```

## Summary

- **Depth limiting**: Default recursion stops at level 2, configurable via the `depth` parameter in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts).
- **Item capping**: The `MAX_NESTED_ITEMS` constant (100) restricts each nested folder to a manageable subset.
- **Transparent truncation**: The system reports exactly how many files were hidden via `[WARNING]` prefixes.
- **Error normalization**: Permission and existence errors return fixed-format tokens rather than variable-length messages.
- **Token safety**: These mechanisms work together to keep directory listings within AI context limits even when scanning file systems containing thousands of nested files.

## Frequently Asked Questions

### What is the default recursion depth in DesktopCommanderMCP?

The default recursion depth is **2 levels**, implemented 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). This means the tool lists the target directory and its immediate subdirectories, but does not descend into sub-subdirectories unless explicitly requested via the `depth` parameter.

### How does DesktopCommanderMCP handle permission errors during listing?

Permission errors (`EPERM`) and missing directory errors (`ENOENT`) are caught and converted to standardized short strings like `[DENIED] /path` or `[NOT_FOUND] /path` in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts). This prevents large error objects from consuming context budget while clearly signaling access issues to the AI agent.

### Can I view all files in a directory that contains more than 100 items?

No, the **hard cap of 100 nested items** is currently enforced in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) via the `MAX_NESTED_ITEMS` constant. To access files beyond the first 100, you must execute additional targeted `listDirectory` calls on specific subdirectories rather than relying on recursive enumeration of the parent.

### Where is the context overflow protection logic implemented?

All protection mechanisms reside in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts), specifically within the `listDirectory` function starting at line 720. The depth checking, item slicing, and warning generation are co-located in this single file to ensure consistent behavior across the DesktopCommanderMCP server and UI components.