How DesktopCommanderMCP Performs MIME Type Detection Across File Extensions

DesktopCommanderMCP determines a file’s MIME type by examining its extension through a lightweight utility located in src/tools/mime-types.ts, using hard-coded mappings for PDFs and images while defaulting to text/plain for unrecognized formats.

DesktopCommanderMCP is a Model Context Protocol (MCP) server that enables AI agents to interact with the desktop filesystem. Accurate MIME type detection is essential for handling different file formats correctly, and according to the DesktopCommanderMCP source code, the project implements a fast, deterministic extension-based approach rather than inspecting file contents.

Core MIME Type Detection Implementation

The heart of the MIME type detection system resides in src/tools/mime-types.ts. This module exports the primary getMimeType function, which follows a straightforward three-tier logic to classify files based solely on their extension.

Extension Extraction Process

The function normalizes the file path by converting it to lowercase and splitting on the period character, isolating the final segment as the extension. This ensures consistent matching regardless of case variations in the filename.

Hard-Coded Type Mappings

For recognized formats, the system uses explicit constant mappings:

• PDF Detection — If the extension equals pdf, the function immediately returns application/pdf.
• Image Detection — A dedicated imageTypes map associates the extensions png, jpg, jpeg, gif, and webp with their respective MIME types (image/png, image/jpeg, image/gif, image/webp).

Default Fallback Behavior

Any extension not explicitly mapped defaults to text/plain. This fallback ensures the system remains functional for text-based files without failing on unknown formats.

Boolean Validation Helpers

Beyond raw MIME type strings, src/tools/mime-types.ts provides convenience functions for type checking:

• isPdfFile(mimeType: string) — Returns true if the MIME type equals application/pdf.
• isImageFile(mimeType: string) — Returns true for any image MIME type in the supported set.

These helpers allow higher-level logic to branch based on file category without hard-coding MIME type strings throughout the codebase.

Filesystem Integration and Usage

Higher-level tools consume these utilities through wrapper functions. In src/tools/filesystem.ts (lines 42-47), the getMimeTypeInfo function wraps getMimeType and enriches the result with boolean flags (isImage, isPdf) for easier conditional logic in file operations.

Additionally, src/utils/files/image.ts (lines 86-88) maintains its own IMAGE_MIME_TYPES map used specifically for normalizing image types during preview generation, ensuring consistency across the image handling pipeline.

Practical Implementation Examples

The following example demonstrates basic MIME type detection using the core utilities:

// Example: Determine MIME type of a path
import { getMimeType, isPdfFile, isImageFile } from "./src/tools/mime-types.js";

const path = "/home/user/docs/report.pdf";
const mime = getMimeType(path);          // → "application/pdf"
console.log(mime, isPdfFile(mime));     // "application/pdf" true

const imgPath = "/home/user/pic/photo.jpeg";
const imgMime = getMimeType(imgPath);    // → "image/jpeg"
console.log(imgMime, isImageFile(imgMime)); // "image/jpeg" true

const txtPath = "/home/user/notes/todo.txt";
const txtMime = getMimeType(txtPath);    // → "text/plain"
console.log(txtMime);                    // "text/plain"

For higher-level filesystem operations, use the async wrapper that provides metadata flags:

// Example: Using the higher‑level helper from filesystem.ts
import { getMimeTypeInfo } from "./src/tools/filesystem.js";

async function printFileInfo(filePath: string) {
  const { mimeType, isImage, isPdf } = await getMimeTypeInfo(filePath);
  console.log(`${filePath} → ${mimeType} ${isImage ? "(image)" : ""} ${isPdf ? "(PDF)" : ""}`);
}

printFileInfo("image.png");   // image.png → image/png (image)
printFileInfo("doc.pdf");     // doc.pdf → application/pdf (PDF)
printFileInfo("notes.md");    // notes.md → text/plain

Summary

• DesktopCommanderMCP uses extension-based detection in src/tools/mime-types.ts for speed and determinism.
• Hard-coded mappings handle PDFs and common image formats explicitly.
• Unknown file types safely fallback to text/plain.
• Helper functions isPdfFile and isImageFile provide convenient boolean checks.
• The getMimeTypeInfo wrapper in src/tools/filesystem.ts exposes mimeType, isImage, and isPdf flags for broader tool integration.

Frequently Asked Questions

Does DesktopCommanderMCP detect MIME types by file content or extension?

DesktopCommanderMCP detects MIME types solely by examining the file extension. This design prioritizes speed and deterministic behavior over content-based inspection, which is implemented in src/tools/mime-types.ts by parsing the filename rather than reading file headers.

What MIME type is assigned to unknown file extensions?

Unknown file extensions default to text/plain. This fallback occurs in the getMimeType function when the extracted extension does not match any entries in the PDF or image type maps, ensuring the system remains functional for text-based files.

How can I check if a file is a PDF or image programmatically?

Use the boolean helper functions exported from src/tools/mime-types.ts. Call isPdfFile(mimeType) to verify PDFs or isImageFile(mimeType) to check for supported image formats. Alternatively, use getMimeTypeInfo from src/tools/filesystem.ts to receive both the MIME string and pre-computed boolean flags.

Where is the MIME type detection used in the broader application?

The detection logic powers file preview capabilities and filesystem operations. Specifically, src/tools/filesystem.ts uses it to populate metadata for file listings, while src/utils/files/image.ts leverages MIME types to normalize image handling during preview generation.

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