PDF Manipulation Methods in Desktop Commander: Text Extraction, Page Insertion, and Editing

Desktop Commander MCP provides a dedicated PDF toolkit under src/tools/pdf that enables text extraction via @opendocsg/pdf2md, page deletion and insertion via pdf-lib, and Markdown-to-PDF conversion through encapsulated functions like parsePdfToMarkdown, editPdf, and parseMarkdownToPdf.

The PDF manipulation capabilities in Desktop Commander MCP are built on a modular architecture that isolates document processing logic within the src/tools/pdf directory. This design leverages two primary third-party libraries—@opendocsg/pdf2md for content extraction and pdf-lib for structural editing—to provide comprehensive document handling. According to the wonderwhy-er/DesktopCommanderMCP source code, these utilities are exposed through clean TypeScript interfaces that support both programmatic access and integration with the filesystem command layer.

Core PDF Manipulation Architecture

The toolkit organizes functionality into distinct modules based on operation type. This separation ensures that text extraction, image processing, and page-level editing remain decoupled while sharing common PDF loading utilities.

Text Extraction and Markdown Conversion

Located in src/tools/pdf/markdown.ts, the conversion layer handles bidirectional transformation between PDF and Markdown formats. The parsePdfToMarkdown function loads a PDF file, optionally restricts processing to specific page ranges, and invokes pdf2md to return structured text alongside metadata including author, title, and total page count. For reverse conversion, parseMarkdownToPdf accepts Markdown strings and utilizes md-to-pdf to generate PDF buffers suitable for disk storage or further manipulation.

Page-Level Editing Operations

The structural editing implementation resides in src/tools/pdf/manipulations.ts and provides low-level page manipulation through pdf-lib. The internal deletePages function removes specified page indexes from a PDFDocument instance, while insertPages injects pages from a source PDF into a destination document at a designated index. These primitives are orchestrated by the public editPdf function, which accepts an array of edit operations and applies them sequentially before persisting the modified document.

Key PDF Manipulation Functions

Desktop Commander exposes several high-level functions that abstract the underlying library implementations:

• parsePdfToMarkdown (src/tools/pdf/markdown.ts line 274): Converts PDF content to Markdown format with optional page range limiting and metadata extraction.
• editPdf (src/tools/pdf/manipulations.ts line 101): Applies sequential edit operations (deletions or insertions) to modify existing PDFs in place.
• parseMarkdownToPdf (src/tools/pdf/markdown.ts line 302): Generates PDF buffers from Markdown content using styled conversion.
• extractImages (src/tools/pdf/extract-images.ts line 33): Retrieves image data from selected pages using the unpdf helper library.

Supporting these operations are internal utilities such as loadPdfDocumentFromBuffer (src/tools/pdf/manipulations.ts line 22), which wraps PDFDocument.load to instantiate editable PDF objects from Uint8Array buffers.

Practical Implementation Examples

The following code snippets demonstrate the primary PDF manipulation methods available in Desktop Commander:

// Extract text from pages 1-3 of a PDF
import { parsePdfToMarkdown } from '@/tools/pdf/markdown';
const result = await parsePdfToMarkdown('sample.pdf', [1, 2, 3]);
console.log(result.pages.map(p => p.text).join('\n'));

// Delete pages 5-7 from an existing PDF (zero-based indexing)
import { editPdf } from '@/tools/pdf/manipulations';
await editPdf('report.pdf', [
  { type: 'delete', pageIndexes: [4, 5, 6] }
]);

// Insert pages from another PDF at position 2
await editPdf('report.pdf', [
  {
    type: 'insert',
    pageIndex: 1,
    sourcePdfPath: 'appendix.pdf'
  }
]);

// Create a new PDF from Markdown content
import { parseMarkdownToPdf } from '@/tools/pdf/markdown';
const pdfBuffer = await parseMarkdownToPdf('# Title\n\nSome *styled* text');

await Deno.writeFile('output.pdf', pdfBuffer);

Integration with the Filesystem Layer

While the core logic resides in src/tools/pdf, the broader application accesses these capabilities through abstraction layers defined in src/utils/files/pdf.ts. This file-handler bridges the PDF toolkit with the generic filesystem API, enabling commands like write_pdf and edit_pdf exposed in src/tools/filesystem.ts to operate seamlessly. This architecture allows the rest of Desktop Commander to interact with PDFs through unified interfaces without direct dependency on pdf-lib or pdf2md specifics.

Summary

• Text Extraction: The parsePdfToMarkdown function in src/tools/pdf/markdown.ts leverages @opendocsg/pdf2md to convert PDF pages to Markdown with metadata preservation.
• Page Manipulation: The editPdf function in src/tools/pdf/manipulations.ts orchestrates deletions and insertions using pdf-lib, operating on zero-based page indexes.
• Content Creation: parseMarkdownToPdf enables PDF generation from Markdown strings using the md-to-pdf library.
• Image Handling: The extractImages utility utilizes unpdf to extract visual assets from specific page ranges.
• Modular Design: All PDF-specific logic is isolated in src/tools/pdf, with src/utils/files/pdf.ts providing the integration point for filesystem operations.

Frequently Asked Questions

What third-party libraries does Desktop Commander use for PDF manipulation?

Desktop Commander MCP relies on @opendocsg/pdf2md for converting PDF content to Markdown format and extracting text, while pdf-lib handles low-level document editing including page deletion, insertion, and merging operations. Image extraction utilizes the unpdf library, and Markdown-to-PDF conversion employs md-to-pdf.

Why does the page deletion function use zero-based indexing?

The deletePages function in src/tools/pdf/manipulations.ts follows JavaScript array conventions and the pdf-lib library's internal representation, where the first page of a PDF corresponds to index 0 rather than 1. This means that to delete pages 5 through 7 as displayed in a PDF viewer, you must pass indexes [4, 5, 6] to the editPdf operation.

Can Desktop Commander extract images from specific pages only?

Yes, the extractImages function defined in src/tools/pdf/extract-images.ts accepts parameters that allow you to specify which pages to scan for images. The function uses the unpdf helper to pull image data only from the selected page range rather than processing the entire document.

How can I add new PDF manipulation operations like rotation or annotation?

New operations can be added by extending the edit operation types in src/tools/pdf/manipulations.ts and implementing the corresponding logic using pdf-lib primitives. Because the PDF toolkit is isolated in src/tools/pdf, you can add rotation or annotation handlers without modifying the filesystem integration layer in src/utils/files/pdf.ts or the command interface in src/tools/filesystem.ts.

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