How to Extract Text Content from a PDF using Desktop Commander MCP

Desktop Commander MCP extracts PDF text through the PdfFileHandler in src/utils/files/pdf.ts, which delegates to parsePdfToMarkdown and converts binary PDF data into structured plain text using the @opendocsg/pdf2md library.

Desktop Commander MCP handles PDFs as a specialized file type with dedicated parsing logic that transforms binary documents into readable formats. The extraction pipeline processes document metadata and per-page text content through a series of interconnected modules. This article breaks down the exact source code paths, function signatures, and implementation patterns required to extract text content programmatically.

Architecture Overview

The PDF text extraction system follows a four-stage pipeline implemented across specific modules in the wonderwhy-er/DesktopCommanderMCP repository. Understanding this flow helps you locate the correct APIs and debug extraction issues effectively.

The complete processing chain flows as follows: PdfFileHandler → parsePdfToMarkdown → @opendocsg/pdf2md → structured PdfParseResult → UI or command output.

Step-by-Step Extraction Process

Step 1: PDF File Handler Entry Point (src/utils/files/pdf.ts)

The extraction process begins in the PDF file handler located at src/utils/files/pdf.ts. When the system receives a request to open or process a PDF document, the PdfFileHandler class intercepts the request and prepares the file for parsing.

At line 53 of this handler, the code invokes parsePdfToMarkdown to initiate the conversion. This call passes the file path (or byte buffer) to the conversion layer and awaits a structured parse result containing raw text, document metadata, and any extracted images.

Step 2: Markdown Conversion (src/tools/pdf/markdown.ts)

The conversion orchestration resides in src/tools/pdf/markdown.ts. This module exports the primary API function parsePdfToMarkdown at line 274, which coordinates the transformation from binary PDF to structured text.

This function forwards the input file to the underlying parsing library while handling error boundaries. It ensures the returned data conforms to the PdfParseResult interface that downstream consumers expect.

Step 3: Core Parsing with @opendocsg/pdf2md (src/tools/pdf/lib/pdf2md.ts)

The actual binary parsing occurs in src/tools/pdf/lib/pdf2md.ts, which wraps the @opendocsg/pdf2md library. This library parses the PDF binary format, walks every page structure, and extracts page-wise text content.

The library constructs a PdfParseResult object containing:

• metadata – Author, title, total page count, and document properties
• pages – An array where each element contains the extracted text for that specific page index

Step 4: Result Handling and Response Mapping

After parsing completes, control returns to the handler at lines 57-63 of src/utils/files/pdf.ts. Here, the handler maps the PdfParseResult to the response format expected by the application layer. Callers can access result.pages to retrieve plain-text content or result.metadata for document properties without processing the full text array.

Practical Implementation Guide

To extract text content from a PDF in your own implementation, import the conversion function from the package distribution and consume the structured result:

import { parsePdfToMarkdown } from 'desktop-commander-mcp/dist/tools/pdf/markdown.js';

// Extract all pages as text
async function extractPdfText(filePath: string) {
  // `parsePdfToMarkdown` returns { metadata, pages, ... }
  const result = await parsePdfToMarkdown(filePath);
  console.log('Title:', result.metadata.title);
  console.log('Total pages:', result.metadata.totalPages);
  // Concatenate all page texts into a single string
  const fullText = result.pages.map(p => p.text).join('\n');
  return fullText;
}

// Example usage
extractPdfText('sample.pdf')
  .then(text => console.log('PDF text content:', text))
  .catch(err => console.error('Failed to extract PDF:', err));

This implementation retrieves the complete text across all pages by mapping the pages array and joining the text content with newline separators.

Working with PDF Metadata Only

If your application requires only document metadata—such as author, title, and page count—without the overhead of full text extraction, you can optimize the call. As implemented at line 124 of src/utils/files/pdf.ts, invoke parsePdfToMarkdown with an empty range parameter. This configuration returns the PdfParseResult with populated metadata while skipping the text extraction phase for improved performance.

Key Source Files

• src/utils/files/pdf.ts – Contains the PdfFileHandler class that initiates extraction at line 53 and formats responses at lines 57-63
• src/tools/pdf/markdown.ts – Exports parsePdfToMarkdown (line 274) and parseMarkdownToPdf conversion functions
• src/tools/pdf/lib/pdf2md.ts – Implements core conversion logic utilizing the @opendocsg/pdf2md library
• src/tools/pdf/index.ts – Provides public type re-exports for PDF utility types
• test/test-pdf-parsing.js – Contains test suites demonstrating PDF parsing implementations and expected output formats

Summary

• Desktop Commander MCP extracts PDF text through a dedicated handler pipeline starting at src/utils/files/pdf.ts
• The parsePdfToMarkdown function exported from src/tools/pdf/markdown.ts (line 274) serves as the primary API entry point
• Underlying parsing relies on the @opendocsg/pdf2md library wrapped in src/tools/pdf/lib/pdf2md.ts
• Results return as a structured PdfParseResult containing metadata and a pages array with per-page text content
• Callers can extract full text by mapping the pages array or retrieve metadata-only by passing empty range parameters as shown at line 124 of the handler

Frequently Asked Questions

What library does Desktop Commander MCP use for PDF parsing?

Desktop Commander MCP uses @opendocsg/pdf2md as its core parsing engine. This library is imported and wrapped in src/tools/pdf/lib/pdf2md.ts to handle the binary PDF format and extract structured text and metadata.

How do I extract only metadata without full text content?

Pass an empty range parameter to parsePdfToMarkdown as demonstrated at line 124 of src/utils/files/pdf.ts. This configuration returns the PdfParseResult with document properties like title and author while skipping the text extraction phase for faster processing.

What data structure does parsePdfToMarkdown return?

The function returns a PdfParseResult object containing two primary properties: metadata (with fields like title, author, and totalPages) and pages (an array where each element includes the extracted text string for that specific page index).

Where is the PDF file handler located in the source code?

The PDF file handler is located at src/utils/files/pdf.ts in the Desktop Commander MCP repository. This file contains the PdfFileHandler class that initiates extraction by calling parsePdfToMarkdown at line 53 and formats the final response at lines 57-63.

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