Audit Logging and Log Rotation in Desktop Commander MCP: Security Monitoring Implementation

Desktop Commander MCP implements audit logging through three complementary subsystems—the Tool Call Tracker for recording every tool invocation with automatic size-based rotation, the Fuzzy Search Logger for query auditing, and a Central Logger for runtime events—ensuring comprehensive security monitoring without unbounded disk growth.

Desktop Commander MCP (wonderwhy-er/DesktopCommanderMCP) provides robust audit logging capabilities to track tool executions and system interactions for security forensics. The implementation spans three distinct logging layers that capture who called which tool, what queries were performed, and general runtime events. This architecture ensures complete traceability while implementing intelligent log rotation policies to prevent storage exhaustion.

Tool Call Audit Logging with Automatic Rotation

The primary audit mechanism resides in src/utils/trackTools.ts, which persists every invocation of built-in tools (e.g., fs, git, custom commands) to disk for later forensic analysis.

Size-Based Rotation Mechanism

The exported trackToolCall function appends timestamped entries to the file defined by TOOL_CALL_FILE. When the log exceeds TOOL_CALL_FILE_MAX_SIZE (approximately 10 MiB as defined in src/config.ts), the current file is automatically renamed with a timestamp suffix following the pattern <base>_YYYY-MM-DD_HH-MM-SS.<ext>, and a fresh log file is created.

Recording Tool Invocations

Each tool execution is captured via the trackToolCall function:

import { trackToolCall } from './utils/trackTools.js';

// Example: invoking a custom "run-script" tool
await trackToolCall('run-script', { script: 'build.sh', cwd: '/project' });

This creates an immutable record linking specific tool calls to their arguments and execution context, essential for security auditing and debugging.

Fuzzy Search Activity Auditing

The src/utils/fuzzySearchLogger.ts subsystem audits fuzzy-search interactions for performance tuning and behavioral analysis.

Unlike the tool-call tracker, this logger writes to ~/.claude-server-commander-logs/fuzzy-search.log as compact single-line JSON entries. The FuzzySearchLogger.log(entry) method ensures the directory exists and creates the file on first use.

import { FuzzySearchLogger } from './utils/fuzzySearchLogger.js';

await FuzzySearchLogger.log({
  query: 'open file',
  resultsCount: 12,
  durationMs: 34,
  timestamp: new Date().toISOString(),
});

This subsystem intentionally omits automatic rotation—the compact JSON format keeps files small, and administrators can manually clear logs via FuzzySearchLogger.clear().

Centralized Runtime Logging

The src/utils/logger.ts provides a unified interface for console output and optional remote telemetry. Rather than file-based storage, this layer routes messages through the MCP logger and mirrors them to stderr via logToStderr(level, msg) for immediate visibility.

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

logger.info('Desktop Commander started');
logger.error('Failed to load user configuration', { path: configPath });

Rotation for this stream is delegated to the host environment or external log aggregation systems, as logs are emitted to stdout/stderr rather than persisted to disk.

Security Monitoring Architecture

Together, these mechanisms provide a comprehensive audit trail:

• Tool invocations: Captured by trackToolCall with automatic rotation preventing unbounded growth
• Search patterns: Recorded by FuzzySearchLogger for behavioral analysis
• System events: Emitted via the central logger for real-time monitoring

The configuration constants in src/config.ts drive the rotation logic, specifically TOOL_CALL_FILE and TOOL_CALL_FILE_MAX_SIZE, ensuring audit data remains available for forensic analysis while respecting disk constraints.

Summary

• Tool Call Tracker (src/utils/trackTools.ts): Records every tool invocation with automatic size-based rotation at approximately 10 MiB thresholds
• Fuzzy Search Logger (src/utils/fuzzySearchLogger.ts): Audits search queries to a per-user JSON log file at ~/.claude-server-commander-logs/fuzzy-search.log without automatic rotation
• Central Logger (src/utils/logger.ts): Handles runtime events through stdout/stderr, delegating rotation to external systems
• Rotation Strategy: Size-based for tool calls (timestamped archives), manual clearing for fuzzy search, host-managed for central logs
• Configuration: Constants defined in src/config.ts control file paths and size limits

Frequently Asked Questions

How does Desktop Commander handle log rotation for audit trails?

Desktop Commander implements size-based rotation specifically for the tool-call audit log in src/utils/trackTools.ts. When the log file reaches approximately 10 MiB (TOOL_CALL_FILE_MAX_SIZE), the system automatically renames the current file with a timestamp suffix and creates a fresh log. The fuzzy-search and central loggers do not rotate automatically—the former remains small by design, while the latter relies on the host environment's log management.

What events are captured in the tool call audit log?

The tool call audit log captures every invocation of built-in tools including filesystem operations (fs), version control commands (git), and custom user-defined commands. Each entry recorded via trackToolCall includes the tool name, arguments, working directory, and timestamp, creating a complete forensic trail of system modifications.

Where are the audit logs stored on disk?

Tool call audit logs are stored at the path defined by TOOL_CALL_FILE (configured in src/config.ts), while fuzzy-search audit logs reside in the user's home directory at ~/.claude-server-commander-logs/fuzzy-search.log. The central logger outputs to stdout/stderr rather than persistent files, making it suitable for containerized or systemd-managed environments.

Can I manually clear or rotate the audit logs?

Yes. Administrators can force rotation of tool-call logs by invoking the tracking mechanism under specific conditions, though this happens automatically by default. For fuzzy-search logs, the FuzzySearchLogger.clear() method provides explicit deletion capabilities. The central logger requires host-level management for log clearing since it streams to standard output.

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