# How the Deferred Message System Works in Desktop Commander MCP

> Discover how Desktop Commander MCP's deferred message system buffers logs during startup and flushes them to prevent lost diagnostic messages once STDIO transport initializes.

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

---

**Desktop Commander MCP implements a buffer-based deferred message system that captures log entries during startup and flushes them once the STDIO transport is fully initialized, preventing early diagnostic messages from being lost.**

Desktop Commander MCP, an open-source Model Context Protocol server, faces a critical initialization challenge: logging must occur before the custom STDIO transport is ready to receive output. To solve this, the codebase employs a deferred message system that temporarily stores log entries in memory and releases them only after the transport layer is fully operational. This pattern ensures that configuration loading, feature flag initialization, and other early diagnostics are never lost during the bootstrap sequence.

## Why Deferred Messages Are Necessary

During the bootstrap phase of [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts), the application loads configuration files and initializes feature flags before instantiating the `FilteredStdioServerTransport`. If the code attempted to emit logs directly during these early steps, the messages would disappear because the transport destination does not yet exist. The deferred message system bridges this gap by queueing log entries in a temporary buffer until the logging infrastructure is fully wired.

## Core Architecture and Implementation

The deferred message system relies on a shared buffer and two key functions defined across the main entry point and server modules.

### The Message Buffer and deferLog Helper

At the top of both [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) (line 19) and [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) (line 83), the code declares a typed array to hold pending messages:

```typescript
const deferredMessages: Array<{ level: string; message: string }> = [];

```

The `deferLog` helper function, defined at lines 20-21 in [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) and lines 84-85 in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts), pushes entries onto this buffer:

```typescript
function deferLog(level: string, message: string) {
  deferredMessages.push({ level, message });
}

```

Instead of calling the real logger during startup, the codebase uses `deferLog('info', 'message')` to capture diagnostic output. For example, at lines 61-63 in [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts), the system logs configuration loading status via `deferLog` to ensure the message is retained.

### Flushing Deferred Messages After Initialization

Once the server signals readiness through the `oninitialized` event, the `flushDeferredMessages` function drains the buffer. In [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) (lines 124-125), the initialization callback invokes this flush:

```typescript
server.oninitialized = () => {
  // ... other setup ...
  flushDeferredMessages();
};

```

The actual implementation in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) (lines 88-93) iterates through the array and emits each message through the operational logger:

```typescript
export function flushDeferredMessages() {
  while (deferredMessages.length > 0) {
    const msg = deferredMessages.shift()!;
    logger.info(msg.message);
  }
}

```

This guarantees that early startup logs are emitted in chronological order after the transport is attached.

## Implementation Walkthrough

Understanding the temporal sequence of transport creation versus message buffering is critical to implementing this pattern correctly.

### Transport-First Initialization

The code explicitly instantiates the `FilteredStdioServerTransport` at lines 55-58 in [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) before any deferred logs are flushed:

```typescript
const transport = new FilteredStdioServerTransport();
global.mcpTransport = transport;

```

This ordering ensures that when `flushDeferredMessages` eventually runs, the global transport is available to carry the output.

### Complete Startup Flow

A typical startup sequence in [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) demonstrates the full lifecycle:

```typescript
async function runServer() {
  // 1. Create transport first
  const transport = new FilteredStdioServerTransport();
  global.mcpTransport = transport;

  // 2. Buffer early logs during async initialization
  deferLog('info', 'Loading configuration...');
  await configManager.loadConfig();
  deferLog('info', 'Configuration loaded');

  // 3. Register flush callback for when server is ready
  server.oninitialized = () => {
    flushDeferredMessages();
  };

  // 4. Connect to activate the transport
  await server.connect(transport);
}

```

## Key Source Files

The deferred message system spans three primary locations in the repository:

- **[`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts)**: The CLI entry point that initializes the transport, populates the buffer using `deferLog` during early setup, and triggers the flush via `server.oninitialized` (lines 124-125).
- **[`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)**: Defines the shared `deferredMessages` buffer, exports the `deferLog` helper, and implements `flushDeferredMessages` to drain the queue into the active logger (lines 88-93).
- **[`src/custom-stdio.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/custom-stdio.ts)**: Implements `FilteredStdioServerTransport`, the destination that ultimately receives flushed messages through the logger subsystem.

## Summary

- Desktop Commander MCP uses a **deferred message buffer** to capture logs emitted before the STDIO transport is ready.
- The **`deferLog`** function stores messages in a temporary array during the bootstrap phase.
- **`flushDeferredMessages`** drains the buffer once the server signals initialization completion via `oninitialized`.
- This pattern ensures **no lost startup diagnostics** and preserves chronological message ordering.

## Frequently Asked Questions

### What happens if flushDeferredMessages is called multiple times?

Calling `flushDeferredMessages` multiple times is safe. The function uses `shift()` to drain the array completely, so subsequent calls find an empty buffer and exit immediately without error.

### Why not just delay logging until after transport initialization?

Early startup steps like configuration loading and feature-flag initialization can fail or produce critical diagnostic information needed for debugging. Deferring rather than delaying ensures these messages are captured and visible even if the startup sequence encounters errors before full initialization.

### Does the deferred message system affect performance?

No. The buffer is a simple in-memory array, and `flushDeferredMessages` executes a synchronous loop that drains the queue immediately upon initialization. The overhead is negligible compared to the I/O operations of the transport itself.

### Where is the deferredMessages buffer defined?

The `deferredMessages` array is declared in both [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) at line 19 and [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) at line 83, ensuring both the entry point and server module can access the shared buffer during the startup sequence.