Add file listing and exploration for home folder

[vlad-ds]

Feature Request: Home Folder File Listing and Exploration

Summary

Add functionality to list and explore files in the PDF Agent home directory (~/pdf-agent/) to help users understand what files are available for processing.

Proposed Features

1. List Files Tool (list_pdf_files):

   • List all PDF files in the home directory and subdirectories
   • Support filtering by file patterns (e.g., *.pdf)
   • Show file metadata (size, creation date, modification date)
   • Return hierarchical directory structure

2. Explore Directory Tool (explore_directory):

   • Navigate and explore subdirectories within ~/pdf-agent/
   • Show directory contents with file types and sizes
   • Support depth-limited exploration to prevent excessive output

Use Cases

• Users want to see what PDFs they have available without leaving the MCP interface
• AI assistants need to discover available files for processing
• Users want to organize their PDF collection within the home directory
• Debugging and troubleshooting file location issues

Technical Implementation

• Follow existing path resolution patterns (relative to ~/pdf-agent/)
• Use consistent error handling and validation
• Implement file system traversal with safety limits
• Return structured JSON responses similar to other tools

Related Tools

This would complement the existing tools:

• get_pdf_metadata - after discovering files with the new listing tool
• search_pdf - users can search across discovered files
• get_pdf_text - extract text from files found in the directory

Priority

Medium - This would significantly improve user experience and discoverability of available files.