Customizing the Electron BrowserWindow Configuration in chat-mcp: Options and Implementation

TLDR: The ai-ql/chat-mcp repository enables customizing the Electron BrowserWindow configuration by extending the options object in src/main/main.ts, supporting all standard Electron window properties for size, appearance, security, and behavior.

The ai-ql/chat-mcp application renders its user interface through an Electron BrowserWindow instance created in the main process. While the default implementation prioritizes security, customizing the Electron BrowserWindow configuration allows developers to tailor window dimensions, visual styling, and behavioral characteristics to match specific deployment requirements or user preferences.

Current Implementation in main.ts

The primary window is instantiated in [src/main/main.ts](https://github.com/ai-ql/chat-mcp/blob/main/src/main/main.ts) at line 111 using a minimal configuration:

const mainWindow = new BrowserWindow({
  width: 1920,
  height: 1080,
  webPreferences: {
    nodeIntegration: false,
    contextIsolation: true,
    preload: preloadPath
  }
});

This establishes a 1920×1080 pixel window with security-hardened webPreferences. Any standard Electron BrowserWindow constructor property can be added to this object to modify the window's behavior.

Size and Layout Options

Control window dimensions and user resizing constraints by adding these properties to the configuration object:

• minWidth and minHeight: Define minimum dimensions in pixels to prevent the UI from breaking at small sizes. Example: minWidth: 800, minHeight: 600
• maxWidth and maxHeight: Set upper limits for window expansion. Example: maxWidth: 2560, maxHeight: 1440
• resizable: Boolean value allowing or preventing manual resizing. Defaults to true
• center: Automatically positions the window in the center of the primary display on launch
• fullscreen: Launch the application directly into fullscreen mode

Appearance and Visual Styling

Modify the window chrome and loading experience with these Electron BrowserWindow configuration properties:

• title: Set the string displayed in the OS title bar or taskbar. Example: title: 'Chat MCP'
• backgroundColor: Specify a hex color code shown before the renderer content loads. Example: backgroundColor: '#202020'
• frame: Boolean to show or hide the native operating system window frame. Set to false to implement custom title bars
• transparent: Enable full window transparency for overlay-style applications
• titleBarStyle: macOS-specific option accepting default, hidden, or hiddenInset to customize the title bar appearance

Web Preferences and Security Settings

The webPreferences object controls renderer process capabilities and security boundaries:

• nodeIntegration: Currently set to false to prevent exposing Node.js APIs to the renderer process, mitigating security risks
• contextIsolation: Enabled (true) to run preload scripts in an isolated context, protecting against prototype pollution attacks
• preload: References preloadPath pointing to src/preload/preload.ts, establishing a safe IPC bridge between main and renderer processes
• sandbox: Enable Chromium OS-level sandboxing with sandbox: true for additional process isolation
• webSecurity: Enforce same-origin policy and CORS restrictions
• enableRemoteModule: Explicitly disable the deprecated remote module with false

Behavior and Performance Configuration

Control window interaction patterns and resource usage:

• show: Set to false to create the window hidden, allowing you to call mainWindow.show() only after content is ready to prevent visual flicker
• autoHideMenuBar: Hide the menu bar until the Alt key is pressed (Linux/Windows)
• skipTaskbar: Prevent the window from appearing in the system taskbar or dock
• alwaysOnTop: Keep the chat window floating above other applications
• focusable: Control whether the window can receive keyboard focus
• backgroundThrottling: Throttle JavaScript timers and animations when the application loses focus to conserve CPU
• webgl: Enable or disable WebGL support in the renderer process

Practical Customization Example

To implement a frameless, centered window with minimum size constraints and a dark loading background while maintaining security:

const mainWindow = new BrowserWindow({
  width: 1920,
  height: 1080,
  minWidth: 800,
  minHeight: 600,
  title: 'Chat MCP',
  backgroundColor: '#111111',
  frame: false,
  titleBarStyle: 'hidden',
  center: true,
  show: false,
  webPreferences: {
    nodeIntegration: false,
    contextIsolation: true,
    preload: preloadPath,
    sandbox: true,
    webSecurity: true
  }
});

// Show window when ready
mainWindow.once('ready-to-show', () => {
  mainWindow.show();
});

This configuration preserves the security-focused defaults of chat-mcp while adding usability and visual polish.

Key Files for Window Configuration

When customizing the Electron BrowserWindow configuration, reference these source files:

• src/main/main.ts: Contains the BrowserWindow constructor and window lifecycle management. This is the primary location for adding configuration options.
• src/preload/preload.ts: Defines the IPC bridge loaded via the preload path. Changes to contextIsolation or sandbox settings must align with this file's exports.
• src/renderer/index.html: The HTML entry point displayed within the window. Affected by backgroundColor and dimension settings.

Summary

• The chat-mcp application initializes its main window in src/main/main.ts with security-first defaults including nodeIntegration: false and contextIsolation: true
• All standard Electron BrowserWindow options are available for customizing the Electron BrowserWindow configuration, including size constraints, visual styling, and behavioral controls
• The webPreferences object manages critical security boundaries, with the preload script providing controlled access to main process APIs
• Options like frame, titleBarStyle, and backgroundColor enable platform-specific customization without compromising the application's IPC security model

Frequently Asked Questions

How do I prevent the chat-mcp window from being resized below certain dimensions?

Add minWidth and minHeight properties to the BrowserWindow constructor options in src/main/main.ts. For example, setting minWidth: 800, minHeight: 600 ensures the chat interface maintains usable proportions even when users attempt to shrink the window.

What security settings must I preserve when customizing the window configuration?

Always maintain nodeIntegration: false and contextIsolation: true as implemented in the original codebase. These settings prevent renderer process scripts from accessing Node.js APIs or manipulating JavaScript prototypes. If you enable sandbox: true, verify that your src/preload/preload.ts script correctly exposes only necessary IPC methods.

Can I make the chat-mcp window frameless while keeping it draggable?

Yes. Set frame: false and titleBarStyle: 'hidden' in the BrowserWindow options, then add a draggable region in your renderer HTML using CSS -webkit-app-region: drag. This removes the native title bar while allowing users to drag the window by your custom header area, common in modern chat applications.

Where is the preload script configured in the chat-mcp repository?

The preloadPath variable passed to webPreferences.preload in src/main/main.ts points to the compiled output of src/preload/preload.ts. This script establishes the secure communication bridge between the Electron main process and the renderer, enabling controlled access to native APIs while maintaining process isolation.

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