mcp-pdf-tools

Instructions

Implementation Reference

• src/pdf_tools/server.py:221-262 (handler)

  Handler implementation for the 'search-pdfs' tool. Searches for PDF files in the specified base directory (recursively by default) matching the given filename pattern using substring matching (case-insensitive). Returns list of matching full paths.

  elif name == "search-pdfs":
      base_path = arguments.get("base_path")
      pattern = arguments.get("pattern", "*.pdf")
      recursive = arguments.get("recursive", True)
      
      if not base_path:
          raise ValueError("Missing base_path argument")
  
      # Normalize the base path to handle Windows paths
      base_path = os.path.normpath(base_path)
      found_files = []
      
      try:
          if recursive:
              for root, _, files in os.walk(base_path):
                  for filename in files:
                      # Convert both pattern and filename to lowercase for case-insensitive matching
                      if filename.lower().endswith('.pdf'):
                          # Remove the .pdf from pattern if it exists for more flexible matching
                          search_pattern = pattern.lower().replace('.pdf', '')
                          if search_pattern in filename.lower():
                              full_path = os.path.join(root, filename)
                              found_files.append(full_path)
          else:
              for file in os.listdir(base_path):
                  if file.lower().endswith('.pdf'):
                      search_pattern = pattern.lower().replace('.pdf', '')
                      if search_pattern in file.lower():
                          full_path = os.path.join(base_path, file)
                          found_files.append(full_path)
  
          return [types.TextContent(
              type="text",
              text=f"Found {len(found_files)} PDF files:\n" + 
                  "\n".join(f"- {f}" for f in found_files)
          )]
          
      except Exception as e:
          return [types.TextContent(
              type="text",
              text=f"Error searching for PDFs: {str(e)}\nBase path: {base_path}"
          )]

• src/pdf_tools/server.py:63-85 (registration)

  Registration of the 'search-pdfs' tool in the @server.list_tools() handler, including name, description, and input schema definition.

  types.Tool(
      name="search-pdfs",
      description="Search for PDF files in a directory with optional pattern matching",
      inputSchema={
          "type": "object",
          "properties": {
              "base_path": {
                  "type": "string",
                  "description": "Base directory to search in"
              },
              "pattern": {
                  "type": "string",
                  "description": "Pattern to match against filenames (e.g., 'report*.pdf')"
              },
              "recursive": {
                  "type": "boolean",
                  "description": "Whether to search in subdirectories",
                  "default": True
              }
          },
          "required": ["base_path"]
      }
  ),

• src/pdf_tools/server.py:66-84 (schema)

  Input schema for the 'search-pdfs' tool defining the parameters: base_path (required), pattern (optional, defaults to '*.pdf'), recursive (optional boolean, defaults to true).

  inputSchema={
      "type": "object",
      "properties": {
          "base_path": {
              "type": "string",
              "description": "Base directory to search in"
          },
          "pattern": {
              "type": "string",
              "description": "Pattern to match against filenames (e.g., 'report*.pdf')"
          },
          "recursive": {
              "type": "boolean",
              "description": "Whether to search in subdirectories",
              "default": True
          }
      },
      "required": ["base_path"]
  }