How Chat-MCP Handles Electron Mirror and Installation Timeout Issues

Chat-MCP mitigates Electron download failures and installation stalls by configuring the ELECTRON_MIRROR environment variable, clearing local caches when builds fail, and enforcing a 30-second timeout on client initialization in src/main/main.ts.

The open-source Chat-MCP project depends on Electron and electron-builder, which download binaries exceeding 100 MB during installation and packaging. In regions where the default Electron download server is slow or blocked, npm install can stall indefinitely, often after the node_modules folder reaches approximately 300 MB. The repository implements three complementary strategies to ensure reliable builds and startup across network-constrained environments.

Configuring the Electron Mirror Environment Variable

The primary defense against slow or unreachable Electron downloads is redirecting requests to an alternative CDN using the ELECTRON_MIRROR environment variable. Electron’s installer scripts automatically read this variable, requiring no code changes within the project.

As documented in the README under the Installation timeout section, setting this variable to a reachable mirror—such as Tsinghua University’s CDN—allows the install to complete without hitting the default server.

Set the mirror in your shell before running npm install:

# Bash / Zsh

export ELECTRON_MIRROR="https://mirrors.tuna.tsinghua.edu.cn/electron/"
npm install

On Windows (PowerShell), use:

$env:ELECTRON_MIRROR="https://mirrors.tuna.tsinghua.edu.cn/electron/"
npm install

Clearing Stale Electron and Electron-Builder Caches

When electron-builder encounters download interruptions or corrupted partial files, subsequent builds may fail repeatedly. The project recommends manually clearing the local Electron and electron-builder caches to force a fresh download from the configured mirror.

According to the README’s Electron builder timeout section, delete these directories before retrying:

• C:\Users\<USERNAME>\AppData\Local\electron
• C:\Users\<USERNAME>\AppData\Local\electron-builder

Use this PowerShell command to remove both cache folders:

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\electron"
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\electron-builder"

Enforcing a 30-Second Client Initialization Timeout

Beyond installation issues, Chat-MCP prevents runtime hangs by enforcing a strict timeout during client startup. In src/main/main.ts, the application races the initializeClient function against a timeoutPromise that rejects after 30 seconds.

This guard ensures that any client failing to initialize—whether due to network latency or misconfiguration—does not block the UI indefinitely. The implementation appears at lines 64-70 of src/main/main.ts:

const timeoutPromise = new Promise<Client>((resolve, reject) => {
  setTimeout(() => {
    reject(new Error(`Initialization of client for ${name} timed out after 30 seconds`));
  }, 30_000);
});

const client = await Promise.race([
  initializeClient(name, serverConfig),
  timeoutPromise,
]);

If the initialization exceeds 30 seconds, the promise rejects with a diagnostic error, causing the app to exit cleanly rather than hanging.

Summary

• Redirect downloads by setting ELECTRON_MIRROR to a regional CDN before installation to bypass slow or blocked default servers.
• Clear caches at AppData/Local/electron and AppData/Local/electron-builder when electron-builder timeouts persist, ensuring fresh downloads.
• Guard runtime startup with a 30-second timeout in src/main/main.ts to prevent client initialization from blocking the application indefinitely.

Frequently Asked Questions

What causes Electron installation timeouts in Chat-MCP?

Electron binaries are approximately 100 MB and are downloaded during both npm install and electron-builder packaging. In regions with restricted or slow access to the default Electron download server, the transfer can stall, particularly after significant progress when the node_modules folder reaches roughly 300 MB.

How do I configure a mirror for Electron downloads in Chat-MCP?

Set the ELECTRON_MIRROR environment variable to a trusted CDN URL, such as https://mirrors.tuna.tsinghua.edu.cn/electron/, before executing npm install. Electron’s built-in installer scripts detect this variable automatically and fetch binaries from the specified mirror instead of the default host.

Where does Chat-MCP implement the initialization timeout?

The 30-second timeout is implemented in src/main/main.ts (lines 64-70). The code creates a timeoutPromise that rejects after 30,000 milliseconds and races it against the initializeClient function using Promise.race, ensuring the application exits with an error if startup hangs.

Why should I clear the Electron cache when builds fail?

Corrupted or incomplete downloads in the local Electron or electron-builder caches can cause repeated installation failures, even after configuring a working mirror. Deleting the cache folders forces the build tools to download fresh binaries from the currently configured mirror, resolving issues caused by stale or partial files.

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