How the read_file Function in Desktop Commander Handles Local and Remote Files

The read_file function in Desktop Commander MCP automatically detects HTTP(S) URLs and routes them to a web fetch handler while treating all other paths as local filesystem reads, returning a uniform FileResult object for both sources.

Desktop Commander MCP is a Model Context Protocol server that exposes filesystem operations to AI agents. Its read_file tool—implemented as the readFile function in src/tools/filesystem.ts—provides a single, polymorphic API that transparently retrieves content from either the local disk or remote web servers, eliminating the need for callers to distinguish between protocols.

URL Detection and Routing Logic

The entry point at src/tools/filesystem.ts (lines 574-582) inspects the supplied path to determine the data source.

HTTP(S) Pattern Matching

Inside readFile, the code checks if the path matches a URL pattern using isValidUrl(filePath)—a simple RegExp test against /^https?:\/\//i. If the condition is true, execution branches to readFileFromUrl; otherwise it proceeds to readFileFromDisk.

Remote Resource Fetching

When handling web resources, readFileFromUrl (lines 358-376) performs an HTTP GET using the global fetch API. It wraps the request in an AbortController to enforce a configurable timeout, preventing network hangs from blocking the MCP server. The response body is read as text and wrapped in a FileResult object containing content and optional mimeType metadata derived from the response headers.

Local Filesystem Reading

For local paths, readFileFromDisk (lines 432-461) resolves the absolute path and utilizes Node.js fs promises. It supports partial reads via optional offset and length parameters, delegating to readFileWithSmartPositioning from src/utils/files/text.ts for efficient byte-range reading. This allows agents to sample large logs without loading entire files into memory, and also accepts an AbortSignal for cancellation consistency with the remote path.

Unified FileResult Interface

Both execution branches return a standardized FileResult interface defined in the codebase:

interface FileResult {
  content: string;
  mimeType?: string;
  encoding?: string;
  // ... additional metadata
}

This abstraction ensures that downstream handlers in src/handlers/filesystem-handlers.ts consume remote and local content identically, whether displaying a configuration file from disk or fetching a dependency from a CDN.

Practical Usage Examples

The following examples demonstrate how AI agents or client code can invoke the function for both source types:

// Example 1: Read local file with byte-range
import { readFile } from './src/tools/filesystem.js';

const config = await readFile('/etc/nginx/nginx.conf', { offset: 0, length: 500 });
console.log(config.content); // First 500 bytes only

// Example 2: Fetch remote script
const script = await readFile('https://raw.githubusercontent.com/user/repo/main/script.js');
console.log(script.mimeType); // "application/javascript"

Both calls return a FileResult object; callers access .content uniformly regardless of whether the source was local or remote.

Summary

• Polymorphic Routing: The readFile implementation in src/tools/filesystem.ts automatically dispatches HTTP(S) URLs to readFileFromUrl (lines 358-376) and filesystem paths to readFileFromDisk (lines 432-461).
• Safety Mechanisms: Remote fetches use AbortController timeouts to prevent hangs; local reads support offset/length parameters for memory-efficient partial file access via src/utils/files/text.ts.
• Uniform API: Both sources return a FileResult object, allowing handlers in src/handlers/filesystem-handlers.ts to treat web resources and local files interchangeably.
• Zero Caller Complexity: Client code passes any valid path or URL to read_file without needing protocol-specific logic.

Frequently Asked Questions

Does read_file support binary file downloads from remote URLs?

Yes. According to the readFileFromUrl implementation in src/tools/filesystem.ts, the function retrieves the response body as text by default, but the underlying fetch call handles binary streams. The FileResult structure accommodates binary content when the appropriate encoding is specified in the response headers or options.

How does Desktop Commander handle timeouts when fetching remote files?

The readFileFromUrl function instantiates an AbortController and passes its signal to the fetch call. If the request exceeds the configured timeout duration, the controller aborts the operation, throwing an error that prevents the MCP server from hanging on unresponsive web servers.

Can I read a specific section of a large local file without loading it entirely?

Yes. The readFileFromDisk function accepts optional offset and length parameters. When provided, it uses readFileWithSmartPositioning from src/utils/files/text.ts to perform a partial read via Node.js file descriptors, making it efficient to sample logs or large datasets without consuming excessive memory.

What happens if I pass a file path that looks like a URL but isn't HTTP(S)?

The isValidUrl check specifically tests for http:// or https:// schemes using /^https?:\/\//i. Paths with other schemes (such as ftp:// or file://) or malformed URLs fail the regex test and are treated as local filesystem paths, which will subsequently fail with a standard "file not found" error from readFileFromDisk if the path does not exist on disk.

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