PDF Tools MCP Server

Instructions

Supports both local file paths and URLs. For URLs, the PDF will be downloaded
to a temporary directory and cached for future use.

Args:
    pdf_file_path: Path to the PDF file or URL to PDF
    pattern: Regular expression pattern to search for
    page_size: Number of results per page (10-50, default: 10)

Returns:
    Search results with UUID for pagination, or error message

Implementation Reference

• pdf_tools_mcp/server.py:616-708 (handler)

  The `search_pdf_content` tool handler, which performs regex searches on PDF content and returns paginated results.

  async def search_pdf_content(pdf_file_path: str, pattern: str, page_size: int = 10) -> str:
      """Search for regex pattern in PDF content and return paginated results.
      
      Supports both local file paths and URLs. For URLs, the PDF will be downloaded
      to a temporary directory and cached for future use.
      
      Args:
          pdf_file_path: Path to the PDF file or URL to PDF
          pattern: Regular expression pattern to search for
          page_size: Number of results per page (10-50, default: 10)
      
      Returns:
          Search results with UUID for pagination, or error message
      """
      try:
          # Resolve path (download if URL, validate if local path)
          actual_path = resolve_path(pdf_file_path)
          
          # Validate local path if not URL
          if not is_url(pdf_file_path):
              is_valid, error_msg = validate_path(pdf_file_path)
              if not is_valid:
                  return error_msg
      
      except Exception as e:
          return f"Error resolving path: {str(e)}"
      
      # Validate page size
      page_size, warning = validate_page_size(page_size)
      
      try:
          # Extract all text from PDF using actual path
          pdf_content = extract_all_text_from_pdf(actual_path)
          if not pdf_content:
              return "Error: Could not extract text from PDF or PDF is empty"
          
          # Find all matches across all pages
          all_results = []
          for page_num, page_text in pdf_content.items():
              page_matches = find_regex_matches(page_text, pattern, page_num)
              all_results.extend(page_matches)
          
          if not all_results:
              return f"No matches found for pattern: {pattern}"
          
          # Create search session
          search_id = str(uuid.uuid4())[:8]  # Short UUID
          session = SearchSession(
              search_id=search_id,
              pdf_path=pdf_file_path,
              pattern=pattern,
              results=all_results,
              current_page=1,
              page_size=page_size,
              total_results=len(all_results),
              last_accessed=datetime.now(),
              cached_content=pdf_content
          )
          
          with cache_lock:
              # Only cleanup if we have too many sessions
              if len(search_sessions) > 20:  # reasonable limit
                  cleanup_cache()
              search_sessions[search_id] = session
          
          # Format first page of results
          start_idx = 0
          end_idx = min(page_size, len(all_results))
          current_results = all_results[start_idx:end_idx]
          
          result = warning if warning else ""
          result += f"Search ID: {search_id}\n"
          result += f"Pattern: {pattern}\n"
          result += f"Total matches: {len(all_results)}\n"
          result += f"Page: 1/{(len(all_results) + page_size - 1) // page_size}\n"
          result += f"Results per page: {page_size}\n\n"
          
          for i, match in enumerate(current_results, 1):
              result += f"Match {start_idx + i}:\n"
              result += f"  Page: {match.page_number}\n"
              result += f"  Text: \"{match.text}\"\n"
              result += f"  Context: ...{match.context_before}[{match.text}]{match.context_after}...\n\n"
          
          if len(all_results) > page_size:
              result += f"Use search_pdf_next_page, search_pdf_prev_page, or search_pdf_go_page with search_id '{search_id}' to navigate."
          
          return result
          
      except FileNotFoundError:
          return f"Error: File not found '{actual_path}'"
      except Exception as e:
          return f"Error searching PDF: {str(e)}"