mcp-pdf-tools

Instructions

Implementation Reference

• src/pdf_tools/server.py:264-328 (handler)

  Handler for the 'merge-pdfs-ordered' tool: matches PDF files to provided patterns (exact or fuzzy), collects them in order, and merges using PyPDF2.PdfMerger.

  elif name == "merge-pdfs-ordered":
      base_path = arguments.get("base_path")
      patterns = arguments.get("patterns", [])
      output_path = arguments.get("output_path")
      fuzzy_matching = arguments.get("fuzzy_matching", True)
      
      if not all([base_path, patterns, output_path]):
          raise ValueError("Missing required arguments")
  
      try:
          # Get all PDF files in the directory
          all_pdfs = []
          for root, _, files in os.walk(base_path):
              for file in files:
                  if file.lower().endswith('.pdf'):
                      all_pdfs.append(os.path.join(root, file))
  
          # Match files to patterns
          selected_files = []
          for pattern in patterns:
              pattern_matched = False
              
              # Try exact matches first
              exact_matches = [f for f in all_pdfs if pattern in os.path.basename(f)]
              if exact_matches:
                  selected_files.extend(exact_matches)
                  pattern_matched = True
              
              # Try fuzzy matching if enabled and no exact matches
              elif fuzzy_matching:
                  filenames = [os.path.basename(f) for f in all_pdfs]
                  matches = get_close_matches(pattern, filenames, n=3, cutoff=0.6)
                  if matches:
                      for match in matches:
                          matching_files = [f for f in all_pdfs if os.path.basename(f) == match]
                          selected_files.extend(matching_files)
                          pattern_matched = True
              
              if not pattern_matched:
                  return [types.TextContent(
                      type="text",
                      text=f"Warning: No matches found for pattern '{pattern}'"
                  )]
  
          # Merge the matched files
          merger = PyPDF2.PdfMerger()
          for pdf_path in selected_files:
              with open(pdf_path, 'rb') as pdf_file:
                  merger.append(pdf_file)
          
          with open(output_path, 'wb') as output_file:
              merger.write(output_file)
  
          return [types.TextContent(
              type="text",
              text=f"Successfully merged {len(selected_files)} PDFs into {output_path}\n" +
                   "Files merged in this order:\n" +
                   "\n".join(f"- {os.path.basename(f)}" for f in selected_files)
          )]
          
      except Exception as e:
          return [types.TextContent(
              type="text",
              text=f"Error merging PDFs: {str(e)}"
          )]

• src/pdf_tools/server.py:86-113 (registration)

  Tool registration in @server.list_tools(), including name, description, and input schema definition.

  types.Tool(
      name="merge-pdfs-ordered",
      description="Merge PDFs in a specific order based on patterns or exact names",
      inputSchema={
          "type": "object",
          "properties": {
              "base_path": {
                  "type": "string",
                  "description": "Base directory containing PDFs"
              },
              "patterns": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "List of patterns or names in desired order"
              },
              "output_path": {
                  "type": "string",
                  "description": "Output path for merged PDF"
              },
              "fuzzy_matching": {
                  "type": "boolean",
                  "description": "Use fuzzy matching for filenames",
                  "default": True
              }
          },
          "required": ["base_path", "patterns", "output_path"]
      }
  ),

• src/pdf_tools/server.py:89-111 (schema)

  Input schema for the merge-pdfs-ordered tool, defining parameters like base_path, patterns, output_path, and fuzzy_matching.

  inputSchema={
      "type": "object",
      "properties": {
          "base_path": {
              "type": "string",
              "description": "Base directory containing PDFs"
          },
          "patterns": {
              "type": "array",
              "items": {"type": "string"},
              "description": "List of patterns or names in desired order"
          },
          "output_path": {
              "type": "string",
              "description": "Output path for merged PDF"
          },
          "fuzzy_matching": {
              "type": "boolean",
              "description": "Use fuzzy matching for filenames",
              "default": True
          }
      },
      "required": ["base_path", "patterns", "output_path"]