# 📝 Usage Examples This file contains practical examples of using the PDF MCP Server with Claude Desktop and VS Code Copilot. ## Basic Examples ### Example 1: Count Pages **Claude Desktop**: ``` User: How many pages are in ~/Documents/report.pdf? Claude: I'll use the count-pdf-pages tool to check. [Uses count-pdf-pages tool] Result: The PDF contains 24 pages. ``` **VS Code Copilot**: ``` @workspace Count the pages in /Users/yourname/Documents/report.pdf ``` --- ### Example 2: Extract Text **Claude Desktop**: ``` User: Extract all text from ~/Downloads/invoice.pdf Claude: I'll extract the text from the PDF. [Uses extract-pdf-text tool] Result: [Full text content with 1,234 characters from 2 pages] ``` **VS Code Copilot**: ``` @workspace Extract text from /path/to/invoice.pdf ``` --- ### Example 3: Get Metadata **Claude Desktop**: ``` User: What information can you tell me about ~/Documents/paper.pdf? Claude: I'll check the PDF metadata. [Uses extract-pdf-metadata tool] Result: 📄 PDF Metadata Title: Research on AI Systems Author: Dr. Jane Smith Subject: Machine Learning Created: 2024-01-15 Modified: 2024-02-01 Pages: 42 PDF Version: 1.7 ``` **VS Code Copilot**: ``` @workspace Show me the metadata for /path/to/paper.pdf ``` --- ### Example 4: Summarize PDF (requires LLM sampling) **Claude Desktop**: ``` User: Can you summarize the main points of ~/Documents/research.pdf? Claude: I'll read and summarize the document. [Uses summarize-pdf tool with LLM sampling] Result: This research paper discusses three main areas: 1. Novel approaches to neural network optimization 2. Comparative analysis of existing methods 3. Experimental results showing 15% improvement The paper concludes that the proposed method offers significant advantages in computational efficiency. ``` **VS Code Copilot**: ``` @workspace Summarize the main points in /path/to/research.pdf ``` --- ### Example 5: Answer Questions (requires LLM sampling) **Claude Desktop**: ``` User: Based on ~/Documents/user-manual.pdf, how do I reset the device? Claude: I'll search the manual for reset instructions. [Uses answer-pdf-question tool with LLM sampling] Result: According to the manual, to reset the device: 1. Power off the device completely 2. Hold the reset button for 10 seconds 3. Release and wait for the LED to flash 4. Power on and complete the setup wizard ``` **VS Code Copilot**: ``` @workspace In /path/to/manual.pdf, how do I configure the network settings? ``` --- ## Advanced Examples ### Multi-Step Analysis **Claude Desktop**: ``` User: I have a research paper at ~/Documents/ai-paper.pdf. Can you tell me about it? Claude: I'll analyze the document for you. [Step 1: Uses extract-pdf-metadata] This is a 28-page research paper titled "Deep Learning Advances" by Dr. Smith, created in January 2024. [Step 2: Uses summarize-pdf] The paper presents new techniques for training neural networks more efficiently, with experimental results showing 20% improvement over baseline methods. Would you like me to extract specific information or answer questions about the content? ``` --- ### Batch Processing **Claude Desktop**: ``` User: I have 3 PDF files in ~/Documents/reports/. Can you tell me how many pages each has? Claude: I'll check each PDF file. [Uses count-pdf-pages for report1.pdf] report1.pdf: 15 pages [Uses count-pdf-pages for report2.pdf] report2.pdf: 23 pages [Uses count-pdf-pages for report3.pdf] report3.pdf: 8 pages Total: 46 pages across all reports. ``` --- ### Extract Specific Information **Claude Desktop**: ``` User: Extract all email addresses mentioned in ~/Downloads/contacts.pdf Claude: I'll extract the text and find email addresses. [Uses extract-pdf-text] [Analyzes extracted text] Found the following email addresses: - john@example.com - support@company.org - info@business.net - contact@service.io ``` --- ### Compare PDFs **Claude Desktop**: ``` User: Compare ~/Documents/version1.pdf and ~/Documents/version2.pdf Claude: I'll analyze both documents. [Uses extract-pdf-metadata for both files] Version 1: Created 2024-01-01, 15 pages Version 2: Created 2024-02-15, 18 pages [Uses extract-pdf-text for both files] Version 2 appears to have 3 additional pages with new content in the methodology section. ``` --- ## Use Cases ### 📚 Research & Academia ``` User: Analyze this research paper and tell me about the methodology Claude: [Uses extract-pdf-text] [Uses answer-pdf-question with specific query about methodology] The research uses a mixed-methods approach: 1. Quantitative survey of 500 participants 2. Qualitative interviews with 20 experts 3. Statistical analysis using regression models ``` --- ### 💼 Business & Legal ``` User: What are the key terms in this contract? Claude: [Uses extract-pdf-text] [Analyzes content] Key contract terms: - Effective date: January 1, 2024 - Contract duration: 2 years - Payment terms: Net 30 days - Termination clause: 60 days notice - Liability limit: $100,000 ``` --- ### 📄 Document Management ``` User: Organize these PDFs by author and creation date Claude: [Uses extract-pdf-metadata for each file] Organized by author: Dr. Smith: 3 documents (2023-2024) Prof. Jones: 2 documents (2024) Unknown: 1 document (2022) Sorted by date: 1. doc1.pdf (2022-03-15) 2. doc2.pdf (2023-06-20) 3. doc3.pdf (2024-01-10) [... etc] ``` --- ### 🔍 Information Extraction ``` User: Find all dates mentioned in this timeline document Claude: [Uses extract-pdf-text] [Parses for date patterns] Timeline dates found: - January 15, 2023: Project kickoff - March 1, 2023: Phase 1 completion - June 30, 2023: Mid-year review - December 31, 2023: Final delivery ``` --- ## Tool Combination Examples ### Example: Comprehensive Document Analysis ``` User: Give me a complete analysis of ~/Documents/report.pdf Claude: [Step 1: extract-pdf-metadata] Document Info: - Title: "Quarterly Sales Report" - Author: "Sales Team" - Created: March 31, 2024 - Pages: 12 [Step 2: extract-pdf-text] [Analyzes structure] The document has 5 main sections: 1. Executive Summary 2. Q1 Performance 3. Regional Breakdown 4. Forecast 5. Recommendations [Step 3: summarize-pdf] Key findings: - Sales increased 15% year-over-year - North region showed strongest growth (22%) - Digital channels outperformed traditional (3:1 ratio) - Forecast predicts continued growth in Q2 Would you like me to extract specific metrics or answer questions about any section? ``` --- ### Example 6: Add Watermark to PDF **Claude Desktop**: ``` User: Add a watermark "CONFIDENTIAL" to ~/Documents/report.pdf Claude: I'll add a watermark to the PDF. [Uses add-pdf-watermark tool] Result: ✅ Successfully added watermark "CONFIDENTIAL" to 24 pages 📄 Output file: ~/Documents/report_watermarked.pdf Configuration: - Position: center - Font Size: 48pt - Opacity: 0.3 - Rotation: -45° - Margin: 50pt ``` **VS Code Copilot**: ``` @workspace Add watermark "DRAFT" to /path/to/document.pdf with red color and bottom-right position ``` **Advanced Watermark Example**: ``` User: Add a watermark to ~/Documents/presentation.pdf with these specifications: - Text: "SAMPLE" - Position: bottom-right corner - Font size: 36 - Color: light gray (RGB: 0.7, 0.7, 0.7) - Opacity: 0.5 - No rotation - 30pt margin Claude: I'll create a custom watermark with your specifications. [Uses add-pdf-watermark tool with custom parameters] Result: ✅ Successfully added watermark "SAMPLE" to 15 pages 📄 Output file: ~/Documents/presentation_watermarked.pdf Configuration: - Position: bottom-right - Font Size: 36pt - Opacity: 0.5 - Rotation: 0° - Margin: 30pt ``` --- ### Example 7: Add Header and Footer to PDF **Claude Desktop**: ``` User: Add "My Document" as header and "Page X of Y" as footer to ~/Documents/manual.pdf Claude: I'll add headers and footers to the PDF. [Uses add-pdf-header-footer tool] Result: ✅ Successfully added Header: "My Document" and Footer: "Page {page} of {totalPages}" to 42 pages 📄 Output file: ~/Documents/manual_with_headers_footers.pdf Configuration: - Alignment: center - Font Size: 12pt - Margin: 30pt Supported variables in text: - {page}: Current page number - {totalPages}: Total number of pages - {date}: Current date (YYYY-MM-DD) - {title}: PDF document title ``` **VS Code Copilot**: ``` @workspace Add header "Company Report" and footer "Page {page} of {totalPages}" to /path/to/report.pdf ``` **Advanced Header/Footer Example**: ``` User: Add headers and footers to ~/Documents/contract.pdf with these specifications: - Header: "{title} - {date}" aligned left - Footer: "Page {page} of {totalPages}" aligned right - Font size: 10pt - Color: dark gray (RGB: 0.3, 0.3, 0.3) - Apply only to pages 2-20 - 25pt margins Claude: I'll add custom headers and footers to the specified pages. [Uses add-pdf-header-footer tool with custom parameters] Result: ✅ Successfully added Header: "{title} - {date}" and Footer: "Page {page} of {totalPages}" to 19 pages (pages 2-20) 📄 Output file: ~/Documents/contract_with_headers_footers.pdf Configuration: - Alignment: left (header) / right (footer) - Font Size: 10pt - Margin: 25pt The header will show the document title and current date, while the footer shows page numbers in the format "Page 2 of 20". ``` --- ## Tips for Best Results ### ✅ Do's - **Use absolute paths**: `/Users/name/Documents/file.pdf` - **Be specific**: "Extract text from pages 1-5" (if supported) - **Ask follow-up questions**: Chain queries for deeper analysis - **Verify file exists**: Check path before asking Claude ### ❌ Don'ts - **Don't use relative paths without context**: `./file.pdf` may not work - **Don't process password-protected PDFs**: Remove password first - **Don't expect OCR**: Scanned images won't extract text - **Don't exceed file size limits**: Default is 50MB --- ## Error Handling Examples ### File Not Found ``` User: Count pages in /path/to/nonexistent.pdf Claude: I encountered an error: Error: File not found or not accessible: /path/to/nonexistent.pdf Please check: - The file path is correct - The file exists - You have read permissions ``` --- ### Invalid PDF ``` User: Extract text from ~/Documents/image.jpg Claude: I encountered an error: Error: File must be a PDF. Got: .jpg This tool only works with PDF files. If you have an image, you may need to convert it to PDF first. ``` --- ### Password Protected ``` User: Read ~/Documents/secure.pdf Claude: I encountered an error: Error: PDF is password protected and cannot be parsed Please remove the password protection before processing, or provide the unprotected version. ``` --- ## 🆕 Advanced Analysis Examples (v2.1) ### Example 11: Analyze Page Layout **Claude Desktop**: ``` User: Analyze the layout of page 1 in ~/Documents/report.pdf Claude: I'll analyze the page dimensions and margins. [Uses analyze-pdf-page tool] Result: 📐 Page Analysis - report.pdf (Page 1) Dimensions: • Size: 595.28 x 841.89 points • Inches: 8.27" x 11.69" • Millimeters: 210.00mm x 297.00mm • Rotation: 0° Margins (detected): • Top: 71.0 points (~1 inch) • Bottom: 71.0 points (~1 inch) • Left: 71.0 points (~1 inch) • Right: 71.0 points (~1 inch) Page Type: A4 Standard ``` **Use Case**: Understanding page layout before adding watermarks or headers --- ### Example 12: Detect Text Positions **Claude Desktop**: ``` User: Find all text positions on page 1 of ~/Documents/contract.pdf Claude: I'll extract text positions with precise coordinates. [Uses detect-text-position tool] Result: 📍 Text Position Analysis - contract.pdf (Page 1) Found 15 text elements: 1. "SERVICE AGREEMENT" • Position: (50.0, 750.0) • Size: 195.2 x 24.0 points • Font: Helvetica-Bold @ 24pt 2. "This agreement is made between..." • Position: (50.0, 700.0) • Size: 450.0 x 12.0 points • Font: Times-Roman @ 12pt [... more text items ...] Page Dimensions: 612 x 792 points (Letter size) ``` **Use Case**: Understanding where text is located for intelligent content placement --- ### Example 13: Search for Specific Text **Claude Desktop**: ``` User: Find all instances of "CONFIDENTIAL" in ~/Documents/report.pdf page 1 Claude: I'll search for that text with position data. [Uses detect-text-position tool with searchQuery] Result: 🔍 Search Results for "CONFIDENTIAL" Found 2 matches: 1. "CONFIDENTIAL" • Position: (250.0, 750.0) • Size: 120.5 x 18.0 points • Font: Helvetica-Bold @ 18pt • Location: Near top of page 2. "CONFIDENTIAL - DO NOT DISTRIBUTE" • Position: (200.0, 50.0) • Size: 250.0 x 12.0 points • Font: Helvetica @ 12pt • Location: Bottom footer Total matches: 2 of 45 text items ``` **Use Case**: Finding specific text for verification or analysis --- ### Example 14: Smart Watermark Placement **Claude Desktop**: ``` User: Add a watermark to ~/Documents/report.pdf but avoid covering any text Claude: I'll first analyze the text positions, then place the watermark strategically. Step 1: Analyzing page layout... [Uses analyze-pdf-page tool] • Page size: 8.5" x 11" (Letter) • Margins: 1" on all sides Step 2: Detecting text positions... [Uses detect-text-position tool] • Found 25 text elements • Text concentrated in upper 60% of page • Lower-right corner is clear Step 3: Adding watermark to clear area... [Uses add-pdf-watermark tool with custom position] • Position: Bottom-right corner (x:400, y:100) • Text: "DRAFT" • Opacity: 30% • No text overlap! ✅ Watermark added successfully at optimal position! ``` **Use Case**: Intelligent watermark placement using analysis tools --- ### Example 15: Layout-Aware Header/Footer **Claude Desktop**: ``` User: Add headers to ~/Documents/manual.pdf without overlapping existing content Claude: I'll analyze the page to find safe header placement. Step 1: Analyzing page 1 layout... [Uses analyze-pdf-page tool] • Top margin: 72 points (1 inch) Step 2: Checking for existing header text... [Uses detect-text-position tool] • Highest text element at y=720 • Safe header zone: y>750 Step 3: Adding header with safe positioning... [Uses add-pdf-header-footer tool] • Header margin: 36 points (well above text) • Text: "User Manual - Version 2.0" ✅ Header added without overlapping content! ``` **Use Case**: Content-aware document modification --- ### Example 16: Complete Page Analysis **Claude Desktop**: ``` User: Give me a complete analysis of ~/Documents/thesis.pdf page 5 Claude: I'll provide comprehensive page analysis. [Uses analyze-pdf-page + detect-text-position] 📊 Complete Page Analysis - thesis.pdf (Page 5) LAYOUT: • Page Size: A4 (210mm x 297mm) • Orientation: Portrait (0° rotation) • Margins: 25mm all sides CONTENT DISTRIBUTION: • Total text elements: 47 • Header text: 2 items (title, page number) • Body text: 42 items (main content) • Footer text: 3 items (references) TEXT CHARACTERISTICS: • Primary font: Times-Roman @ 12pt • Headers: Times-Bold @ 14pt • Footnotes: Times-Roman @ 10pt LAYOUT ZONES: • Header zone: 750-792 points (occupied) • Content zone: 100-750 points (dense) • Footer zone: 0-100 points (occupied) AVAILABLE SPACE: • No large clear areas • Watermark recommendation: Diagonal center with low opacity ``` **Use Case**: Understanding document structure for processing decisions --- ## Integration Examples ### VS Code Workflow 1. **Open a PDF file path in editor** 2. **Highlight the path** 3. **Open Copilot Chat**: `Cmd+I` 4. **Ask**: "Analyze this PDF" 5. **Copilot uses MCP tools** to process the file ### Claude Desktop Workflow 1. **Drag PDF to chat** (if supported) 2. **Or type path**: `~/Documents/file.pdf` 3. **Ask natural language questions** 4. **Claude uses appropriate MCP tools** 5. **Get results and ask follow-ups** --- ## Advanced Workflows ### Workflow 1: Intelligent Document Processing ``` 1. analyze-pdf-page → Get page dimensions and margins 2. detect-text-position → Find all text locations 3. [Your logic] → Calculate optimal positions 4. add-pdf-watermark → Add watermark at calculated position 5. add-pdf-header-footer → Add headers/footers in safe zones ``` ### Workflow 2: Content-Aware Watermarking ``` 1. detect-text-position with searchQuery → Find sensitive terms 2. [Your logic] → Calculate areas to avoid 3. add-pdf-watermark → Place watermark in clear area ``` ### Workflow 3: Document Structure Analysis ``` 1. analyze-pdf-page → Get page layout 2. detect-text-position → Extract all text with fonts 3. [Your logic] → Identify headers, body, footers by font size 4. Generate document outline ``` --- **Need more examples?** Check out: - [README.md](README.md) - Full documentation - [ADVANCED_TOOLS.md](ADVANCED_TOOLS.md) - Advanced tools documentation - [QUICKSTART.md](QUICKSTART.md) - Setup guide - MCP Documentation: https://modelcontextprotocol.io