How the DesktopCommander PDF Generation Tool Ensures Chrome Availability and Handles Headless Rendering

The PDF generation tool uses a three-tier fallback strategy—checking Puppeteer cache, system-wide installations, and automatically downloading Chrome via @puppeteer/browsers—to guarantee browser availability, then renders documents headlessly using md-to-pdf and Puppeteer.

DesktopCommanderMCP provides robust PDF generation capabilities through a sophisticated Chrome management system implemented in src/tools/pdf/markdown.ts. The tool ensures seamless headless rendering by automatically resolving browser dependencies before conversion requests occur. This article examines how the repository orchestrates Chrome discovery, installation, and headless PDF creation.

Chrome Discovery and Installation Strategy

The system implements a cascading resolution mechanism in getChromePath() within src/tools/pdf/markdown.ts (lines 206-236). This function maintains a module-level cachedChromePath variable to eliminate redundant lookups across multiple PDF operations.

Puppeteer Cache Inspection

First, findPuppeteerChrome() scans the Puppeteer cache directory for existing Chrome for Testing builds. When located, pruneOldPuppeteerChromeBuilds() removes outdated versions while retaining the current executable.

System-Wide Chrome Detection

If no cached build exists, findSystemChrome() examines common installation paths across Windows, macOS, and Linux distributions.

Automatic Download Fallback

When neither cache nor system Chrome is available, installChrome() leverages the @puppeteer/browsers package to download the appropriate platform-specific binary. This ensures zero-configuration deployment for end users.

// src/tools/pdf/markdown.ts – getChromePath()
async function getChromePath(): Promise<string | undefined> {
    if (cachedChromePath !== null) return cachedChromePath;

    const cachedChrome = findPuppeteerChrome();
    if (cachedChrome) {
        await pruneOldPuppeteerChromeBuilds(cachedChrome.executablePath);
        cachedChromePath = cachedChrome.executablePath;
        return cachedChrome.executablePath;
    }

    const systemChrome = findSystemChrome();
    if (systemChrome) {
        cachedChromePath = systemChrome;
        return systemChrome;
    }

    const installedChrome = await installChrome();
    await pruneOldPuppeteerChromeBuilds(installedChrome.executablePath);
    cachedChromePath = installedChrome.executablePath;
    return installedChrome.executablePath;
}

Pre-emptive Availability Checks

To prevent latency during the first PDF request, ensureChromeAvailable() runs during application startup via src/index.ts. This background initialization calls getChromePath() and caches the result, logging failures without aborting the program (lines 255-259).

// src/tools/pdf/markdown.ts – ensureChromeAvailable()
export function ensureChromeAvailable(): void {
    getChromePath().catch((error) => {
        console.error('Background Chrome check failed:', error);
    });
}

Headless Rendering Pipeline

Once Chrome is guaranteed, the conversion process utilizes the md-to-pdf library. This wrapper launches Puppeteer in headless mode, passing Markdown content and user-supplied pdfOptions directly to the rendering engine. The tool internally routes to this pipeline, ensuring Chrome is already available when mdToPdf executes (lines 302-304).

// src/tools/pdf/markdown.ts – render Markdown → PDF
import { mdToPdf } from 'md-to-pdf';
// ...
const pdf = await mdToPdf({ content: markdown }, options);
return pdf.content;

Error Handling and User Guidance

If all resolution strategies fail, the tool provides explicit guidance. When Chrome cannot be located or installed, the error handler returns a clear message directing users to install Google Chrome manually (lines 308-311).

if (errorMessage.includes('Could not find Chrome')) {
    throw new Error(
        'PDF generation requires Chrome or Chromium browser. ' +
        'Please install Google Chrome from https://www.google.com/chrome/ '
    );
}

Summary

• Three-tier discovery: The tool checks Puppeteer cache, system-wide installations, and automatically downloads Chrome as a last resort via getChromePath().
• Startup optimization: ensureChromeAvailable() runs during initialization to preload Chrome before the first PDF request.
• Headless execution: The md-to-pdf library handles actual rendering, launching Chrome in headless mode with user-provided options.
• Graceful degradation: Clear error messages guide users to manual Chrome installation if automatic resolution fails.

Frequently Asked Questions

What happens if Chrome is not installed when I first generate a PDF?

The tool automatically downloads and installs Chrome for Testing using the @puppeteer/browsers package. If automatic installation fails due to network restrictions or permissions, it displays explicit instructions to manually install Google Chrome from the official website.

Does the tool re-download Chrome for every PDF generation?

No. The system caches the Chrome executable path in the module-level cachedChromePath variable after the first successful lookup. Subsequent calls to getChromePath() return the cached value immediately, avoiding repeated disk scans or downloads.

Which file handles the actual headless browser control?

While src/tools/pdf/markdown.ts manages Chrome discovery and availability, the actual headless rendering is delegated to the md-to-pdf library (lines 302-304). This library internally uses Puppeteer to launch and control Chrome in headless mode for document conversion.

Can I use a specific Chrome version already installed on my system?

Yes. The tool checks system-wide Chrome installations via findSystemChrome() before attempting automatic downloads. If you have Chrome or Chromium installed in standard locations, the tool will use your existing browser rather than downloading a new copy.

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