How Feature Flags Dynamically Control Server Behavior in DesktopCommanderMCP

Feature flags in DesktopCommanderMCP enable runtime toggling of functionality via a singleton manager that caches remote configuration locally and evaluates flags on every request without requiring server restarts.

DesktopCommanderMCP implements a lightweight feature flag system to dynamically control server behavior without code changes or redeployments. The architecture uses a centralized singleton defined in src/utils/feature-flags.ts that loads JSON configuration from a remote service while maintaining a local cache for resilience. This implementation allows the server to adjust functionality instantly based on flag states evaluated at runtime.

The Feature Flag Architecture

Singleton Pattern and Initialization

The feature flag system initializes in src/index.ts as a non-blocking startup task. The FeatureFlags singleton loads configuration asynchronously, ensuring the server accepts requests immediately while flags populate in the background. This design prevents network latency from delaying server availability.

Remote Configuration and Local Caching

The system fetches a JSON document from a remote configuration service containing key-value pairs like { "enableUsageTracking": true, "remoteKillSwitch": false }. These values are written to .feature-flags.json on disk. On subsequent starts, the server loads cached flags instantly if the network is unavailable, guaranteeing continuous operation with known configuration states.

Runtime Evaluation and Dynamic Control

The isEnabled API

Core modules query flag states through FeatureFlags.isEnabled(flagName), a synchronous check performed at execution time. Because flags are evaluated during every guarded code path execution, remote changes take effect immediately without restarting the server.

Practical Implementation Examples

Developers guard optional functionality using the singleton API:

import { FeatureFlags } from '@/utils/feature-flags';

// Conditional telemetry emission
if (FeatureFlags.isEnabled('enableUsageTracking')) {
  sendTelemetry(data);
}

// Emergency kill switch for critical operations
if (!FeatureFlags.isEnabled('remoteKillSwitch')) {
  performCriticalUpdate();
}

Use Cases in DesktopCommanderMCP

Usage Tracking Controls

In src/utils/usageTracker.ts, the system checks the enableUsageTracking flag before emitting telemetry data. It also respects remoteKillSwitch to disable all reporting dynamically, protecting against runaway processes or compliance issues.

Onboarding Flow Management

The src/utils/welcome-onboarding.ts module waits for the flag cache to load and conditionally renders the welcome UI. If a flag disables onboarding for specific user cohorts, the server skips the presentation logic entirely.

A/B Testing Integration

The src/utils/ab-test.ts utility reads experiment definitions from the same flag payload, enabling weighted rollouts of new UI variants. The getExperimentVariant method returns assignment values based on remote configuration:

const variant = FeatureFlags.getExperimentVariant('newSidebar');
if (variant === 'control') {
  renderOldSidebar();
} else {
  renderNewSidebar();
}

Summary

• The FeatureFlags singleton in src/utils/feature-flags.ts manages remote configuration and local caching to .feature-flags.json
• Runtime checks via isEnabled() and getExperimentVariant() allow immediate behavior changes without server restarts
• Usage tracking in src/utils/usageTracker.ts respects kill switches for safe telemetry control
• Onboarding flows in src/utils/welcome-onboarding.ts conditionally execute based on flag states
• A/B testing infrastructure in src/utils/ab-test.ts leverages the same flag system for dynamic experiment allocation

Frequently Asked Questions

How do feature flags load without blocking server startup?

The initialization in src/index.ts creates the FeatureFlags singleton asynchronously, allowing the server to boot and accept requests while configuration loads in the background from the remote service.

Where are feature flags cached locally?

Flags are persisted to .feature-flags.json on disk, enabling the server to load the last known configuration instantly during startup if the remote configuration service is unreachable.

Can feature flags change behavior without restarting the server?

Yes, because FeatureFlags.isEnabled() evaluates the current flag state on every invocation, updates to the remote configuration apply immediately to subsequent requests and operations without requiring a restart.

What happens if the remote configuration service is unavailable?

The server falls back to the locally cached .feature-flags.json file, ensuring continuous operation with previously loaded flag values while attempting to refresh the configuration in the background.

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