# Quick Usage Guide - PDF MCP Server v2.0

## 🎯 Common Use Cases

### 1. Adding a Watermark (Simple)

**With Claude Desktop:**
```
"Add a CONFIDENTIAL watermark to report.pdf"
```

**What happens:**
1. Server finds `report.pdf` in your Downloads folder automatically
2. Adds a centered, semi-transparent "CONFIDENTIAL" watermark
3. Returns a downloadable watermarked PDF

**Behind the scenes:**
```typescript
{
  filePath: "report.pdf",  // Just the filename!
  text: "CONFIDENTIAL",
  position: "center",
  fontSize: 48,
  opacity: 0.3,
  rotation: -45
}
```

---

### 2. Adding a Watermark (Custom)

**With Claude Desktop:**
```
"Add a red DRAFT watermark to contract.pdf, 
positioned in the bottom right corner, 
with 60pt font size and 50% opacity"
```

**Result:**
```typescript
{
  filePath: "contract.pdf",
  text: "DRAFT",
  position: "bottom-right",
  fontSize: 60,
  opacity: 0.5,
  rotation: 0,
  color: { r: 1, g: 0, b: 0 }  // Red
}
```

---

### 3. Adding Headers and Footers

**With Claude Desktop:**
```
"Add header 'Confidential Report' and 
footer 'Page X of Y' to analysis.pdf"
```

**Result:**
- Header: "Confidential Report" (centered)
- Footer: "Page 1 of 5", "Page 2 of 5", etc. (centered)
- Applied to all pages

---

### 4. Complex Header/Footer

**With Claude Desktop:**
```
"Add left-aligned header with the title 
and right-aligned footer with page numbers 
to the first 10 pages of document.pdf"
```

**Result:**
```typescript
{
  filePath: "document.pdf",
  headerText: "{title}",
  footerText: "Page {page}",
  alignment: "left",   // Header left, Footer right handled separately
  fontSize: 12,
  pageRange: [1, 10]   // Only pages 1-10
}
```

---

## 📝 File Path Examples

All of these work equally well:

### ✅ Filename Only (Recommended)
```
"watermark.pdf"
```
Searches: CWD → Downloads → Documents → Desktop

### ✅ Relative Path
```
"./files/watermark.pdf"
"../documents/watermark.pdf"
```

### ✅ Absolute Path
```
"/Users/username/Downloads/watermark.pdf"
"C:\\Users\\username\\Downloads\\watermark.pdf"  # Windows
```

### ✅ File URI
```
"file:///Users/username/Downloads/watermark.pdf"
```

---

## 🎨 Watermark Position Options

| Position | Description | Use Case |
|----------|-------------|----------|
| `center` | Perfect center (default) | Most common watermarks |
| `top-left` | Top left corner | Document stamps |
| `top-center` | Top center | Headers |
| `top-right` | Top right corner | Classification marks |
| `bottom-left` | Bottom left corner | Source attribution |
| `bottom-center` | Bottom center | Page numbers |
| `bottom-right` | Bottom right corner | Company logos |
| `custom` | Specify X,Y coordinates | Precise placement |

---

## 🌈 Color Examples

Colors use RGB values from 0 to 1:

```typescript
// Black (default for headers/footers)
{ r: 0, g: 0, b: 0 }

// Gray (default for watermarks)
{ r: 0.5, g: 0.5, b: 0.5 }

// Red
{ r: 1, g: 0, b: 0 }

// Blue
{ r: 0, g: 0, b: 1 }

// Green
{ r: 0, g: 1, b: 0 }

// Orange
{ r: 1, g: 0.5, b: 0 }

// Purple
{ r: 0.5, g: 0, b: 0.5 }
```

---

## 📊 Dynamic Variables (Headers/Footers)

Use these in your header/footer text:

| Variable | Replaced With | Example |
|----------|---------------|---------|
| `{page}` | Current page number | `1`, `2`, `3` |
| `{totalPages}` | Total page count | `25` |
| `{date}` | Current date | `2025-10-29` |
| `{title}` | PDF title from metadata | `Annual Report 2024` |

**Examples:**

```
"Page {page} of {totalPages}"           → "Page 1 of 25"
"Generated on {date}"                   → "Generated on 2025-10-29"
"{title} - Page {page}"                 → "Annual Report 2024 - Page 1"
"© 2024 Company - Page {page}/{totalPages}" → "© 2024 Company - Page 1/25"
```

---

## ⚡ Performance Tips

### For Large PDFs (100+ pages)

Enable batch processing:

```
"Add watermark to large-document.pdf with batch processing enabled"
```

This:
- Processes pages in chunks of 100
- Reduces memory usage
- Provides progress updates
- Handles PDFs with unlimited pages

### File Size Limits

- Maximum: 50MB per PDF
- Recommended: Under 10MB for best performance
- For larger files, consider splitting first

---

## 🐛 Troubleshooting

### "File not found"

**Problem**: Server can't locate your PDF

**Solutions**:
1. Check the filename spelling
2. Make sure it's in Downloads, Documents, or Desktop
3. Try using the full path
4. Ensure file exists and is accessible

---

### "File must be a PDF"

**Problem**: You're trying to process a non-PDF file

**Solution**: 
- Only `.pdf` files are supported
- Convert Word docs, images, etc. to PDF first

---

### "File size exceeds maximum"

**Problem**: PDF is larger than 50MB

**Solutions**:
1. Compress the PDF first
2. Split into smaller chunks
3. Use a PDF optimizer tool

---

### Watermark appears in wrong position

**Problem**: Watermark not where you expected

**Solutions**:
1. Check the `position` parameter
2. For `custom` position, verify X and Y coordinates
3. Try using preset positions first

---

## 💡 Pro Tips

### 1. Start Simple
Begin with defaults, then customize:
```
"Add watermark DRAFT to document.pdf"
```

### 2. Use Presets
Leverage position presets instead of custom coordinates:
```
position: "center"  // Not { x: 300, y: 400 }
```

### 3. Test First
Test watermarks on a single page before processing 100-page documents

### 4. Download Immediately
The returned PDF is only available for the session - download it right away

### 5. Keep Originals
Original files are never modified - output is always a new file

---

## 📞 Need Help?

1. Check the error message - they're detailed and helpful
2. Review the examples above
3. Try the test script: `npx tsx scripts/test-enhanced-features.ts`
4. Read the full documentation: [ENHANCEMENTS.md](ENHANCEMENTS.md)

---

**Happy PDF Processing! 🎉**