# PDF Generator MCP Server

A powerful MCP (Model Context Protocol) server for generating professional PDFs from markdown content with custom styling, image support, and various formatting options.

## Features

- 🎨 **Multiple Built-in Themes**: Default, Professional, Minimal, and Dark themes
- 📸 **Smart Image Handling**: Automatic optimization, caching, and embedding
- 📄 **Advanced PDF Options**: Headers, footers, page numbers, TOC generation
- 🎯 **Template System**: Create and reuse custom templates
- ✅ **Markdown Validation**: Check content before generation
- 🚀 **Performance Optimized**: Browser instance reuse, image caching
- 💼 **Custom Styles**: Save and reuse custom PDF styles with prompts and formatting

## Installation

### Quick Start with npx from GitHub (Recommended)

No installation required! Add directly to your Claude desktop configuration:

```json
{
  "mcpServers": {
    "pdf-generator": {
      "command": "npx",
      "args": ["github:FabianGenell/pdf-mcp-server"]
    }
  }
}
```

That's it! The server will be downloaded and run automatically.

### Alternative: Local Development

```bash
# Clone the repository
git clone https://github.com/FabianGenell/pdf-mcp-server
cd pdf-mcp-server
npm install

# Add to Claude desktop configuration
{
  "mcpServers": {
    "pdf-generator": {
      "command": "node",
      "args": ["/path/to/pdf-mcp-server/src/index.js"]
    }
  }
}
```

## Available Tools

### 1. generate_pdf

Generate a PDF from markdown content. **PDFs are saved to your Downloads folder by default**.

```javascript
await generate_pdf({
  content: "# My Document\n\nThis is **markdown** content.",
  output_path: "output.pdf",  // Saves to ~/Downloads/output.pdf
  options: {
    theme: "professional",
    include_toc: true,
    page_numbers: true
  }
});
```

**Note**: If you provide just a filename or relative path, the PDF will be saved to your Downloads folder. Use an absolute path to save elsewhere.

### 2. embed_images

Process and embed images in markdown with optimization. **Supports local paths, URLs, and base64 data URLs**.

#### Image Source Types

**Local Files (from your computer):**
```javascript
await embed_images({
  markdown_content: "# Report\n\n[IMAGE_1]\n\nSome text here.",
  image_sources: [{
    placeholder: "[IMAGE_1]",
    source: "/Users/username/Pictures/screenshot.png",  // Absolute path
    caption: "Application Screenshot",
    alignment: "center"
  }]
});
```

**Remote URLs:**
```javascript
await embed_images({
  markdown_content: "# Report\n\n[LOGO]\n\nCompany overview.",
  image_sources: [{
    placeholder: "[LOGO]",
    source: "https://example.com/images/logo.png",  // Remote URL
    caption: "Company Logo",
    alignment: "center"
  }]
});
```

**Base64 Data URLs:**
```javascript
await embed_images({
  markdown_content: "# Report\n\n[CHART]\n\nData analysis.",
  image_sources: [{
    placeholder: "[CHART]",
    source: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",  // Base64 data URL
    caption: "Generated Chart",
    alignment: "center"
  }]
});
```

#### AI Agent Guidelines

For AI agents, you can provide images in three ways:

1. **Local Computer Paths**: Use absolute paths like `/Users/username/Documents/image.png` or `C:\Users\username\Documents\image.png`
2. **Online Images**: Use direct URLs like `https://example.com/image.png`
3. **Generated/Uploaded Images**: Use base64 data URLs starting with `data:image/[type];base64,[data]`

All image types are automatically optimized, cached, and sized appropriately for PDF performance. Images are automatically limited to 70% of page height to ensure proper layout.

### 3. create_styled_template

Create reusable templates for consistent styling.

```javascript
await create_styled_template({
  template_name: "company-report",
  css_content: "/* Custom CSS */",
  html_template: "<!-- Optional HTML structure -->"
});
```

### 4. validate_markdown

Validate markdown before PDF generation.

```javascript
await validate_markdown({
  content: "# Document\n\n...",
  check_images: true,
  check_links: true
});
```

### 5. create_custom_style

Create a custom PDF style with formatting preferences and writing prompts.

```javascript
await create_custom_style({
  style_name: "annual_report",
  description: "Professional annual report style",
  prompt: "Format as an annual report with executive summary, metrics, and professional tone",
  theme: "professional",
  custom_css: "/* Additional styling */",
  format: "A4",
  include_toc: true,
  page_numbers: true
});
```

### 6. generate_pdf_with_style

Generate a PDF using a saved custom style. **PDFs are saved to your Downloads folder by default**.

```javascript
await generate_pdf_with_style({
  style_name: "annual_report",
  content: "# Annual Report 2024\n\n...",
  output_path: "annual_report_2024.pdf"  // Saves to ~/Downloads/annual_report_2024.pdf
});
```

### 7. list_custom_styles

List all available custom styles.

```javascript
const { styles } = await list_custom_styles();
// Returns array of style summaries with names, descriptions, and themes
```

## Themes

### Default
Clean and readable typography perfect for general documentation.

### Professional
Corporate styling with letterhead design, ideal for business reports.

### Minimal
Distraction-free design with generous whitespace for technical docs.

### Dark
High-contrast theme optimized for presentations and screen viewing.

## Custom Styles

The PDF server now supports saving custom styles that combine formatting preferences, CSS styling, and writing prompts. This allows you to create consistent document types like annual reports, technical documentation, or newsletters.

### Pre-built Custom Styles

The server includes several example styles:

- **annual_report**: Professional annual report with executive formatting
- **technical_documentation**: Clean technical docs with code highlighting
- **presentation_slides**: Slide-style formatting for presentations
- **research_paper**: Academic paper formatting
- **newsletter**: Modern newsletter with columns

### Creating Custom Styles

Custom styles can include:
- **Writing prompts**: Instructions for how content should be formatted
- **Theme selection**: Base theme to build upon
- **Custom CSS**: Additional styling rules
- **Page settings**: Format, orientation, margins
- **Features**: TOC, page numbers, headers/footers

Example:
```javascript
await create_custom_style({
  style_name: "project_proposal",
  description: "Professional project proposal format",
  prompt: "Format as a project proposal with objectives, timeline, budget sections",
  theme: "professional",
  custom_css: ".budget-table { ... }",
  format: "Letter",
  include_toc: true,
  page_numbers: true,
  header: "<div>Project Proposal</div>"
});
```

## Custom Styling

Use CSS classes in your markdown with markdown-it-attrs:

```markdown
# Title {.center}

This is an info box {.info-box}

![Image](path.jpg){.img-shadow .img-rounded}
```

Available CSS classes:
- `.page-break` - Force page break
- `.no-break` - Prevent page break
- `.center`, `.right` - Text alignment
- `.info-box`, `.warning-box`, `.error-box`, `.success-box` - Callout boxes
- `.img-shadow`, `.img-rounded`, `.img-border` - Image styling

## PDF Options

```javascript
{
  // Page settings
  format: 'A4',              // A4, Letter, Legal, etc.
  orientation: 'portrait',   // portrait or landscape
  margin: {
    top: '1in',
    right: '1in',
    bottom: '1in',
    left: '1in'
  },
  
  // Styling
  theme: 'professional',     // Theme name
  custom_css: '...',        // Additional CSS
  
  // Content
  include_toc: true,        // Table of contents
  toc_depth: 3,            // TOC heading depth
  page_numbers: true,       // Show page numbers
  
  // Images
  image_quality: 85,        // JPEG quality
  max_image_width: 800,     // Max width in pixels
  
  // Advanced
  wait_for_network: true,   // Wait for images
  print_background: true    // Include backgrounds
}
```

## Example Usage

### Professional Report

```javascript
// First, embed images (supports local files, URLs, and base64)
const { processed_markdown } = await embed_images({
  markdown_content: reportContent,
  image_sources: [
    {
      placeholder: '[HERO_IMAGE]',
      source: '/Users/username/Downloads/hero.png',  // Local file
      alignment: 'full-width'
    },
    {
      placeholder: '[LOGO]',
      source: 'https://company.com/logo.png',  // Remote URL
      alignment: 'center'
    },
    {
      placeholder: '[CHART]',
      source: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...',  // Base64
      caption: 'Sales Data',
      alignment: 'center'
    }
  ],
  options: {
    auto_optimize: true,
    quality: 90
  }
});

// Then generate PDF
await generate_pdf({
  content: processed_markdown,
  output_path: 'report.pdf',  // Saves to Downloads
  options: {
    theme: 'professional',
    include_toc: true,
    page_numbers: true,
    header: '<div style="text-align: right">Q4 2024 Report</div>',
    footer: '<div style="text-align: center">Confidential</div>'
  }
});
```

### Technical Documentation

```javascript
await generate_pdf({
  content: technicalDocs,
  output_path: 'docs.pdf',  // Saves to Downloads
  options: {
    theme: 'minimal',
    include_toc: true,
    toc_depth: 4,
    enable_javascript: false
  }
});
```

## File Structure

```
pdf-mcp-server/
├── src/
│   ├── index.js              # MCP server entry point
│   ├── pdf-generator.js      # Core PDF generation
│   ├── markdown-processor.js # Markdown processing
│   ├── image-processor.js    # Image optimization
│   ├── template-manager.js   # Template system
│   └── themes/              # Built-in themes
├── templates/               # User templates
├── temp/                   # Temporary files
└── docs/                   # Documentation
```

## Requirements

- Node.js 18+
- Playwright browsers (auto-installed)

## License

ISC

## Contributing

Pull requests are welcome! Please read the contributing guidelines first.

## Support

For issues and feature requests, please use the GitHub issue tracker.