How the Desktop Commander MCP Audit Logging System Handles Log Rotation and Data Capture

Desktop Commander MCP implements a centralized audit logging system in src/utils/logger.ts that buffers entries through the MCP transport and rotates logs via a client-side fuzzy-log manager when the archive exceeds approximately 10 MiB.

The audit logging system in the wonderwhy-er/DesktopCommanderMCP repository provides comprehensive observability for terminal sessions and command execution. It captures structured events from the moment the process starts, ensuring that critical security and operational data is preserved even during early startup or transport failures. Understanding how this system manages log rotation and what specific data it records is essential for compliance monitoring and forensic analysis.

Centralized Audit Logging Architecture

At the core of the audit logging system lies src/utils/logger.ts, which exports a centralized log function and convenience methods including logger.info(), logger.warning(), and logger.error(). This utility serves as the single entry point for all audit events, forwarding entries to the MCP transport via global.mcpTransport.sendLog when available.

If the transport layer is not yet initialized—such as during early startup—the system falls back to emitting JSON-RPC notifications directly to stdout. This dual-path design ensures that no audit data is lost regardless of the application state. In cases where an unexpected error occurs during the logging attempt itself, the system employs a secondary fallback that writes an error message tagged with [LOG-ERROR] to prevent silent failures.

How Log Rotation Works

Log rotation in Desktop Commander MCP is handled client-side by the fuzzy-log manager, implemented in scripts/clear-fuzzy-logs.js. Unlike traditional server-side log rotation, this approach manages the persistent log archive after the transport buffers have flushed to disk.

The rotation mechanism triggers based on two configurable thresholds:

• Size limit: Default approximately 10 MiB
• Time limit: Configurable number of days

When either threshold is exceeded, the manager trims the stored log archive by deleting the oldest entries. This prevents unbounded growth while preserving recent activity for forensic review. Companion scripts like scripts/view-fuzzy-logs.js provide read access to these rotated files for presentation in the UI and debugging tools.

What Data the Audit Logging System Captures

Each entry logged through the system captures a standardized schema designed for audit trails and compliance checks. The following fields are recorded for every event:

• level: Severity classification from the LogLevel enum (emergency, alert, critical, error, warning, notice, info, debug)
• logger: Hard-coded identifier string "desktop-commander" that tags the source component
• message: Human-readable description of the event passed as the first argument to logging functions
• data: Optional JSON payload containing structured context such as request IDs, command arguments, user identifiers, session tokens, or stack traces
• timestamp: ISO-8601 UTC timestamp added by the transport layer before persistence

The optional data field enables rich contextual logging without polluting the human-readable message, allowing security tools to parse structured information while keeping logs readable.

Fallback Mechanisms and Reliability

The audit logging system implements multiple fallback layers to guarantee capture reliability. When the MCP transport is unavailable, the logger constructs a JSON-RPC notification containing the same field schema and writes it directly to stdout. This ensures that critical security events are captured from process start, even before the transport layer initializes.

If the logging operation itself encounters an error—such as serialization failures or I/O exceptions—the system catches the exception and emits a simplified error record with the [LOG-ERROR] tag. This multi-layered approach provides defense in depth for audit trail preservation.

Implementation Examples

The following examples demonstrate practical usage of the audit logging system:

import { logger } from './utils/logger.js';

// Simple informational audit record
logger.info('User opened a new terminal session', {
  userId: ctx.user.id,
  sessionId: ctx.session.id,
});

// Warning with additional context
logger.warning('Attempted to execute a prohibited command', {
  command: 'rm -rf /',
  origin: 'terminal',
});

// Critical error that will be sent even if the transport is unavailable
logger.error('Fatal crash while processing request', {
  requestId: req.id,
  stack: err.stack,
});

For scenarios occurring before transport initialization, use the stderr fallback:

import { logToStderr } from './utils/logger.js';

logToStderr('error', 'Failed to load configuration file');

Summary

• The audit logging system centralizes all events through src/utils/logger.ts, forwarding to the MCP transport or falling back to JSON-RPC notifications.
• Log rotation is managed client-side by scripts/clear-fuzzy-logs.js, which enforces size limits (default ~10 MiB) and time-based retention to prevent unbounded growth.
• Each log entry captures severity levels, component identifiers, human-readable messages, optional structured JSON data, and ISO-8601 timestamps.
• Fallback mechanisms ensure no audit data is lost during early startup or transport failures, including [LOG-ERROR] tags for logging failures themselves.
• The system guarantees forensic visibility from process start while automatically managing storage through intelligent rotation policies.

Frequently Asked Questions

What triggers log rotation in Desktop Commander MCP?

Log rotation triggers when the audit log archive exceeds the configurable size threshold (default approximately 10 MiB) or when entries age beyond a specified number of days. The scripts/clear-fuzzy-logs.js utility performs this cleanup by deleting the oldest entries first, ensuring recent activity remains available while preventing disk space exhaustion.

What happens if the MCP transport is unavailable during logging?

When the MCP transport is unavailable, the system falls back to emitting JSON-RPC notifications directly to stdout. This fallback preserves the complete event schema—including level, message, data payload, and timestamp—ensuring that critical audit records are captured even during early startup or transport disconnections. If the fallback itself fails, the system logs a [LOG-ERROR] message to signal the failure.

What structured data can be attached to audit log entries?

The optional data field accepts any JSON-serializable object, commonly including request IDs, command arguments, user identifiers, session tokens, stack traces, or custom context objects. This structured approach allows security information and event management (SIEM) systems to parse specific fields while maintaining human-readable log messages.

Where are the audit log files stored and how can I view them?

The persistent log files are managed by the client-side fuzzy-log system and can be accessed using scripts/view-fuzzy-logs.js. This script reads the rotated log archives for presentation in the UI and debugging tools, while scripts/clear-fuzzy-logs.js handles the physical storage location and rotation policies. Both scripts operate on the same underlying archive format produced by the MCP transport buffer.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}