mcp-pdf-tools

Instructions

Implementation Reference

• src/pdf_tools/server.py:184-219 (handler)

  The main handler logic for the 'extract-pages' tool. It reads the input PDF using PyPDF2.PdfReader, extracts the specified pages (converting from 1-based to 0-based indexing), writes them to a new PDF using PdfWriter, and returns a success or error message.

  elif name == "extract-pages":
      input_path = arguments.get("input_path")
      output_path = arguments.get("output_path")
      pages = arguments.get("pages", [])
      
      if not input_path or not output_path or not pages:
          raise ValueError("Missing required arguments")
  
      try:
          reader = PyPDF2.PdfReader(input_path)
          writer = PyPDF2.PdfWriter()
  
          # Convert 1-based page numbers to 0-based indices
          for page_num in pages:
              if 1 <= page_num <= len(reader.pages):
                  writer.add_page(reader.pages[page_num - 1])
              else:
                  return [types.TextContent(
                      type="text",
                      text=f"Error: Page number {page_num} is out of range"
                  )]
  
          # Write the extracted pages to the output file
          with open(output_path, 'wb') as output_file:
              writer.write(output_file)
  
          return [types.TextContent(
              type="text",
              text=f"Successfully extracted {len(pages)} pages to {output_path}"
          )]
          
      except Exception as e:
          return [types.TextContent(
              type="text",
              text=f"Error extracting pages: {str(e)}"
          )]

• src/pdf_tools/server.py:40-62 (schema)

  The input schema definition for the 'extract-pages' tool, specifying the required parameters: input_path (string), output_path (string), and pages (array of integers). This is returned by the list_tools handler.

  types.Tool(
      name="extract-pages",
      description="Extract specific pages from a PDF file",
      inputSchema={
          "type": "object",
          "properties": {
              "input_path": {
                  "type": "string",
                  "description": "Input PDF file path"
              },
              "output_path": {
                  "type": "string",
                  "description": "Output path for new PDF"
              },
              "pages": {
                  "type": "array",
                  "items": {"type": "integer"},
                  "description": "List of page numbers to extract (1-based indexing)"
              }
          },
          "required": ["input_path", "output_path", "pages"]
      }
  ),

• src/pdf_tools/server.py:17-143 (registration)

  The tool is registered by being included in the list returned by the handle_list_tools function, decorated with @server.list_tools(). This makes it discoverable by MCP clients.

  @server.list_tools()
  async def handle_list_tools() -> list[types.Tool]:
      """List available PDF manipulation tools."""
      return [
          types.Tool(
              name="merge-pdfs",
              description="Merge multiple PDF files into a single PDF",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "input_paths": {
                          "type": "array",
                          "items": {"type": "string"},
                          "description": "List of input PDF file paths"
                      },
                      "output_path": {
                          "type": "string",
                          "description": "Output path for merged PDF"
                      }
                  },
                  "required": ["input_paths", "output_path"]
              }
          ),
          types.Tool(
              name="extract-pages",
              description="Extract specific pages from a PDF file",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "input_path": {
                          "type": "string",
                          "description": "Input PDF file path"
                      },
                      "output_path": {
                          "type": "string",
                          "description": "Output path for new PDF"
                      },
                      "pages": {
                          "type": "array",
                          "items": {"type": "integer"},
                          "description": "List of page numbers to extract (1-based indexing)"
                      }
                  },
                  "required": ["input_path", "output_path", "pages"]
              }
          ),
          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"]
              }
          ),
          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"]
              }
          ),
          types.Tool(
              name="find-related-pdfs",
              description="Find a PDF and then search for related PDFs based on its content, including common substring patterns",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "base_path": {
                          "type": "string",
                          "description": "Base directory to search in"
                      },
                      "target_filename": {
                          "type": "string",
                          "description": "Name of the initial PDF to analyze"
                      },
                      "pattern_matching_only": {
                          "type": "boolean", 
                          "description": "Only search for repeating substring patterns",
                          "default": False
                      },
                      "min_pattern_occurrences": {
                          "type": "integer",
                          "description": "Minimum times a pattern must appear to be considered significant",
                          "default": 2
                      }
                  },
                  "required": ["base_path", "target_filename"]
              }
          )
      ]