PDF Operations in DesktopCommanderMCP: Parsing, Creation, and Editing Explained

DesktopCommanderMCP supports three core PDF operations: converting PDFs to Markdown, generating PDFs from Markdown strings, and batch editing existing PDFs through page deletion and insertion.

The PDF toolkit in DesktopCommanderMCP is located under src/tools/pdf and provides a TypeScript-based interface for document manipulation. These capabilities are exposed through the PDF tool and rely on pdf-lib for low-level PDF handling and @opendocsg/pdf2md for parsing.

Parsing PDFs to Markdown

The PDF to Markdown conversion extracts textual content and page metadata from existing documents. This operation is implemented in src/tools/pdf/lib/pdf2md.ts, which wraps the @opendocsg/pdf2md library to produce a markdown representation suitable for previewing and downstream editing.

import { parsePdfToMarkdown } from '@/tools/pdf/index.js';

const markdown = await parsePdfToMarkdown('/tmp/report.pdf');
// markdown contains the textual content plus page markers

Creating PDFs from Markdown

DesktopCommanderMCP can generate new PDF documents from markdown strings using the markdownToPdf function. Located in src/tools/pdf/markdown.ts, this utility calculates page sizes and margins based on layout parameters before rendering the final document.

import { markdownToPdf } from '@/tools/pdf/index.js';
import fs from 'fs/promises';

const md = '# Title\n\nSome content on page 1\n\n---\n\nMore content on page 2';

const pdfBytes = await markdownToPdf(md, { pageSize: 'A4' });

await fs.writeFile('output.pdf', pdfBytes);

Editing Existing PDFs

The editing functionality performs batch page manipulation on existing PDFs through the editPdf function exported from src/tools/pdf/index.ts. This feature supports two primary operation types defined by Zod schemas: PdfDeleteOperationSchema and PdfInsertOperationSchema.

Deleting Pages

The deletePages function in src/tools/pdf/manipulations.ts removes specified pages using positive or negative indexes. Negative indexes count from the end of the document, allowing you to target the last page without knowing the total page count.

import { editPdf } from '@/tools/pdf/index.js';

// Delete pages 2 and the last page
await editPdf('input.pdf', [
  { op: 'delete', pageIndexes: [1, -1] }
]);

Inserting Pages

The insertPages function merges pages from a source PDF into the target document at a specified position. This operation uses the same manipulations.ts module and supports inserting entire documents or specific page ranges.

import { editPdf } from '@/tools/pdf/index.js';

// Insert pages from another PDF after page 3
await editPdf('input.pdf', [
  {
    op: 'insert',
    pageIndex: 3,
    sourcePath: 'extra.pdf'
  }
]);

Core Implementation Files

The PDF operations depend on the following source files:

• src/tools/pdf/index.ts – Public entry point that re-exports parsePdfToMarkdown, markdownToPdf, and editPdf.
• src/tools/pdf/lib/pdf2md.ts – Wraps the conversion from PDF to markdown.
• src/tools/pdf/markdown.ts – Handles markdown-to-PDF generation with layout calculations.
• src/tools/pdf/manipulations.ts – Contains deletePages and insertPages for editing operations.
• src/tools/pdf/utils.ts – Provides helper utilities such as normalizePageIndexes for handling negative indexing.

Summary

• DesktopCommanderMCP provides three PDF operations: parsing to Markdown, creating from Markdown, and editing existing documents.
• The editing capabilities support batch operations including page deletion and insertion via editPdf with Zod-validated schemas.
• All operations are implemented in TypeScript under src/tools/pdf using pdf-lib and @opendocsg/pdf2md.
• Page indexing supports negative values to reference pages from the end of the document.

Frequently Asked Questions

What dependencies power the PDF operations in DesktopCommanderMCP?

The toolkit relies on pdf-lib for low-level PDF document manipulation and @opendocsg/pdf2md for extracting text and structure from existing PDFs. These dependencies are wrapped in TypeScript utilities located in src/tools/pdf to provide type-safe operations.

How does DesktopCommanderMCP handle page indexing when editing PDFs?

The system uses normalizePageIndexes from src/tools/pdf/utils.ts to convert negative indexes (e.g., -1 for the last page) into absolute positions. This allows you to specify pages relative to the document end without calculating total page counts manually.

Can DesktopCommanderMCP convert PDFs to formats other than Markdown?

According to the source code in wonderwhy-er/DesktopCommanderMCP, the current implementation only supports conversion to Markdown. The parsePdfToMarkdown function in src/tools/pdf/lib/pdf2md.ts is the primary extraction method, with no native support for HTML or plain text export.

Is batch editing supported for PDF operations?

Yes. The editPdf function accepts an array of operation objects, allowing you to chain multiple deletions and insertions in a single call. Each operation is validated against PdfDeleteOperationSchema or PdfInsertOperationSchema before execution in src/tools/pdf/manipulations.ts.

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