# Changelog

All notable changes to the PDF MCP Server project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## [2.1.0] - 2025-10-30

### 🎯 Added - Advanced PDF Analysis Tools

#### New Tools

1. **analyze-pdf-page**
   - Extract comprehensive page layout information
   - Get dimensions in points, inches, and millimeters
   - Automatic margin detection for standard page sizes (Letter, A4, Legal)
   - MediaBox and CropBox information extraction
   - Rotation detection (0°, 90°, 180°, 270°)
   - Essential for layout-aware PDF operations

2. **detect-text-position**
   - OCR-level text position detection using PDF.js
   - Precise bounding boxes for every text element
   - Font name and size information for each text item
   - Text search and filtering capabilities
   - Transformation matrix extraction for advanced positioning
   - Text direction detection (horizontal/vertical)
   - Perfect for intelligent watermark placement

#### New Utilities

- `src/utils/page-analysis-utils.ts` (320 lines)
  - Page dimension extraction with multi-unit support
  - Heuristic-based margin estimation
  - Safe content area calculations
  - Standard page size detection (Letter, A4, Legal)

- `src/utils/text-position-utils.ts` (350+ lines)
  - PDF.js integration for text extraction
  - Bounding box calculations from transformation matrices
  - Font metadata extraction
  - Text layout analysis
  - Optimal watermark position suggestions

#### New Types

Extended `src/types.ts` with 6 new interfaces:
- `PageDimensions`: Width, height, rotation, multi-unit dimensions
- `PageMargins`: Top, bottom, left, right margins with detection flag
- `BoundingBox`: Rectangle coordinates (x, y, width, height)
- `TextItem`: Text content with font, bounds, transform, direction
- `PageAnalysisResult`: Complete page analysis output
- `TextPositionResult`: Text detection output with metadata

#### Dependencies Added

- `pdfjs-dist` (legacy build): Mozilla's PDF.js for text extraction
- `canvas`: HTML5 Canvas API for Node.js (PDF.js requirement)
- `canvas-5-polyfill`: DOM polyfills for PDF.js in Node.js
- `tsx`: TypeScript execution for test scripts

### 📚 Documentation

- **NEW**: `ADVANCED_TOOLS.md` - Comprehensive documentation for new analysis tools
  - Detailed tool descriptions and schemas
  - Technical details on algorithms used
  - Unit conversion reference
  - PDF coordinate system explanation
  - Performance considerations
  - Troubleshooting guide
  - Use case examples

- **UPDATED**: `README.md`
  - Added v2.1 feature highlights
  - Updated tool count (7 → 9 tools)
  - Added documentation for both new tools
  - Updated project structure
  - Added links to advanced tools documentation

- **UPDATED**: `EXAMPLES.md`
  - Added 6 new advanced analysis examples
  - Smart watermark placement workflow
  - Layout-aware header/footer examples
  - Complete page analysis example
  - Advanced workflow patterns

- **NEW**: `CHANGELOG.md` - This file

### 🧪 Testing

- `scripts/test-new-tools.ts`: Comprehensive test suite
  - Test 1: Page dimension analysis accuracy
  - Test 2: Text position detection with bounding boxes
  - Test 3: Text search and filtering
  - Automated test PDF generation
  - All tests passing ✅

### 🔧 Technical Improvements

- Configured PDF.js legacy build for Node.js compatibility
- Implemented transformation matrix parsing for precise positioning
- Added support for rotated pages in analysis
- Optimized memory usage for large PDFs
- Enhanced error handling for edge cases

### 🎯 Use Cases Enabled

- ✅ Intelligent watermark placement avoiding text overlap
- ✅ Content-aware PDF modifications
- ✅ Automated document structure analysis
- ✅ Layout-aware element positioning
- ✅ Text distribution analysis
- ✅ Document processing workflows

### 📦 Version Updates

- Package version: `2.0.0` → `2.1.0`
- Server version display: Updated to v2.1.0
- Updated package description to include new capabilities

---

## [2.0.0] - 2024-10-29

### 🚀 Major Improvements

#### Added

1. **🔍 Intelligent File Path Resolution**
   - Automatic file path resolution from common directories
   - Supports Downloads, Documents, Desktop on macOS/Windows/Linux
   - Handles relative paths (./file.pdf, ../folder/file.pdf)
   - Supports absolute paths and file:// URIs
   - Just use filename: `"document.pdf"` instead of full paths
   - Implemented in `src/utils/path-resolver.ts`

2. **🎯 Perfect Watermark Centering**
   - Fixed watermark positioning to account for page rotation
   - Accurate center positioning on all page orientations
   - All position presets work correctly (corners, center)
   - Rotation-aware coordinate transformations
   - Updated `src/utils/watermark-utils.ts`

3. **📥 Automatic File Downloads**
   - All modification tools return downloadable PDF files
   - Base64-encoded file content in responses
   - Works seamlessly in Claude Desktop and VS Code
   - Implemented for watermark and header/footer tools

4. **🔒 Strict PDF Validation**
   - Only accepts .pdf files (rejects .docx, .txt, etc.)
   - Clear error messages for invalid file types
   - Path traversal attack prevention
   - File existence validation
   - File size limits (50MB default)

5. **🏷️ Enhanced Watermark Tool**
   - 8 position presets (corners, centers, custom)
   - Full customization: font size, color (RGB), opacity, rotation
   - Margin control for preset positions
   - Memory-efficient batch processing for large PDFs
   - Smart defaults for quick usage

6. **📑 New Header/Footer Tool**
   - Dynamic variables: `{page}`, `{totalPages}`, `{date}`, `{title}`
   - Flexible alignment: left, center, right
   - Page range support
   - Font size and color customization
   - Memory-efficient batch processing

### 📚 Documentation

- **NEW**: `ENHANCEMENTS.md` - Detailed v2.0 improvements documentation
- **NEW**: `QUICKSTART.md` - Step-by-step setup guide
- **NEW**: `USAGE_GUIDE.md` - Comprehensive usage guide with examples
- **NEW**: `EXAMPLES.md` - Practical usage examples
- **NEW**: `CLAUDE_DESKTOP_CONFIG.md` - Claude Desktop setup guide
- **NEW**: `VSCODE_CONFIG.md` - VS Code Copilot setup guide
- **UPDATED**: `README.md` - Complete rewrite with v2.0 features

### 🔧 Technical Improvements

- Implemented batch processing for memory efficiency
- Added comprehensive error handling
- Created modular utility structure
- Added Zod schema validation for all inputs
- TypeScript strict mode enabled
- Enhanced logging and debugging

### 🐛 Bug Fixes

- Fixed watermark not centering correctly
- Fixed rotation-aware positioning issues
- Fixed file path resolution on different platforms
- Fixed memory issues with large PDFs

---

## [1.0.0] - 2024-10-15

### Initial Release

#### Added

1. **count-pdf-pages** - Count total pages in a PDF file
2. **extract-pdf-text** - Extract all text content from a PDF
3. **extract-pdf-metadata** - Get PDF metadata (title, author, dates)
4. **summarize-pdf** - AI-powered PDF summarization (requires LLM sampling)
5. **answer-pdf-question** - Answer questions about PDF content (requires LLM sampling)

#### Features

- MCP protocol v1.0 support
- stdio transport for local communication
- Basic PDF operations using pdf-lib and PDF.js
- Error handling and validation
- TypeScript implementation

#### Documentation

- Initial README.md
- Basic usage examples
- Installation instructions

---

## Version Comparison

| Feature | v1.0 | v2.0 | v2.1 |
|---------|------|------|------|
| Tool Count | 5 | 7 | 9 |
| File Path Resolution | ❌ | ✅ | ✅ |
| Watermark Tool | ❌ | ✅ | ✅ |
| Header/Footer Tool | ❌ | ✅ | ✅ |
| Page Analysis | ❌ | ❌ | ✅ |
| Text Position Detection | ❌ | ❌ | ✅ |
| Downloadable Files | ❌ | ✅ | ✅ |
| Batch Processing | ❌ | ✅ | ✅ |
| Strict Validation | ❌ | ✅ | ✅ |

---

## Upgrade Guide

### From v2.0 to v2.1

1. **Update dependencies**:
   ```bash
   npm install
   ```

2. **Rebuild**:
   ```bash
   npm run build
   ```

3. **Restart MCP client** (Claude Desktop or VS Code)

4. **New tools available**:
   - `analyze-pdf-page` - Get page layout information
   - `detect-text-position` - Find text positions

5. **Read new documentation**: [ADVANCED_TOOLS.md](ADVANCED_TOOLS.md)

### From v1.0 to v2.0

1. **Update dependencies**:
   ```bash
   npm install
   ```

2. **Rebuild**:
   ```bash
   npm run build
   ```

3. **Update MCP configuration** (if needed):
   - No configuration changes required
   - Just restart your MCP client

4. **New features**:
   - Use simple filenames instead of full paths
   - Try the new watermark tool
   - Try the new header/footer tool

---

## Future Roadmap

### Planned for v2.2

- [ ] PDF merging and splitting tools
- [ ] Image extraction from PDFs
- [ ] PDF form field detection and filling
- [ ] Digital signature support
- [ ] Advanced text extraction with formatting

### Planned for v3.0

- [ ] HTTP transport support for remote access
- [ ] Batch operation tools
- [ ] PDF comparison and diff tools
- [ ] OCR for scanned PDFs
- [ ] Advanced annotation tools

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for information on how to contribute to this project.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.