pdf_add_page_numbers

Add page numbers to PDF documents with customizable position, format, starting number, and font size for improved document navigation and organization.

Instructions

Add page numbers to a PDF. Supports configurable position, format, starting number, and font size.

Input Schema

TableJSON Schema

Name	Required	Description
`filePath`	Yes	Absolute path to the source PDF file
`outputPath`	Yes	Absolute path for the output PDF
`position`	No	Position of page numbers. Defaults to bottom-center.
`format`	No	Number format. Defaults to "Page X of Y".
`startFrom`	No	Starting page number. Defaults to 1.
`fontSize`	No	Font size for page numbers (6–24). Defaults to 10.

Implementation Reference

src/tools/manipulate.ts:367-444 (handler)

The handler function for pdf_add_page_numbers that processes PDF pages, injects page numbers based on the specified format and position, and saves the result.

async ({ filePath, outputPath, position, format, startFrom, fontSize }) => {
  try {
    const resolvedPath = await validatePdfPath(filePath);
    await validateFileSize(resolvedPath);
    const resolvedOutput = await validateOutputPath(outputPath, filePath);

    const pdfDoc = await loadExistingPdf(resolvedPath);
    const font = await pdfDoc.embedFont(pdfLib.StandardFonts.Helvetica);
    const totalPages = pdfDoc.getPageCount();

    const pos = position ?? "bottom-center";
    const fmt = format ?? "Page X of Y";
    const start = startFrom ?? 1;
    const fSize = fontSize ?? 10;

    for (let i = 0; i < totalPages; i++) {
      const page = pdfDoc.getPage(i);
      const { width, height } = page.getSize();
      const pageNum = i + start;
      const totalNum = totalPages + start - 1;

      let text: string;
      switch (fmt) {
        case "Page X of Y":
          text = `Page ${pageNum} of ${totalNum}`;
          break;
        case "X of Y":
          text = `${pageNum} of ${totalNum}`;
          break;
        case "X":
          text = String(pageNum);
          break;
        case "- X -":
          text = `- ${pageNum} -`;
          break;
        default:
          text = `Page ${pageNum} of ${totalNum}`;
      }

      const textWidth = font.widthOfTextAtSize(text, fSize);
      const margin = 40;

      let x: number;
      let y: number;

      switch (pos) {
        case "bottom-center":
          x = (width - textWidth) / 2;
          y = margin / 2;
          break;
        case "bottom-right":
          x = width - margin - textWidth;
          y = margin / 2;
          break;
        case "top-center":
          x = (width - textWidth) / 2;
          y = height - margin / 2;
          break;
        case "top-right":
          x = width - margin - textWidth;
          y = height - margin / 2;
          break;
        default:
          x = (width - textWidth) / 2;
          y = margin / 2;
      }

      page.drawText(text, {
        x,
        y,
        size: fSize,
        font,
        color: pdfLib.rgb(0.4, 0.4, 0.4),
      });
    }

    await savePdf(pdfDoc, resolvedOutput);
    const fileSize = await getFileSize(resolvedOutput);

src/tools/manipulate.ts:328-359 (schema)

The Zod input schema definition for pdf_add_page_numbers, defining expected arguments like filePath, outputPath, position, format, startFrom, and fontSize.

inputSchema: z
  .object({
    filePath: z
      .string()
      .max(4096)
      .describe("Absolute path to the source PDF file"),
    outputPath: z
      .string()
      .max(4096)
      .describe("Absolute path for the output PDF"),
    position: z
      .enum(["bottom-center", "bottom-right", "top-center", "top-right"])
      .optional()
      .describe("Position of page numbers. Defaults to bottom-center."),
    format: z
      .enum(["Page X of Y", "X of Y", "X", "- X -"])
      .optional()
      .describe('Number format. Defaults to "Page X of Y".'),
    startFrom: z
      .number()
      .int()
      .min(1)
      .optional()
      .describe("Starting page number. Defaults to 1."),
    fontSize: z
      .number()
      .min(6)
      .max(24)
      .optional()
      .describe("Font size for page numbers (6–24). Defaults to 10."),
  })
  .strict(),

src/tools/manipulate.ts:323-366 (registration)

The MCP tool registration for pdf_add_page_numbers within the server instance.

server.registerTool(
  "pdf_add_page_numbers",
  {
    description:
      "Add page numbers to a PDF. Supports configurable position, format, starting number, and font size.",
    inputSchema: z
      .object({
        filePath: z
          .string()
          .max(4096)
          .describe("Absolute path to the source PDF file"),
        outputPath: z
          .string()
          .max(4096)
          .describe("Absolute path for the output PDF"),
        position: z
          .enum(["bottom-center", "bottom-right", "top-center", "top-right"])
          .optional()
          .describe("Position of page numbers. Defaults to bottom-center."),
        format: z
          .enum(["Page X of Y", "X of Y", "X", "- X -"])
          .optional()
          .describe('Number format. Defaults to "Page X of Y".'),
        startFrom: z
          .number()
          .int()
          .min(1)
          .optional()
          .describe("Starting page number. Defaults to 1."),
        fontSize: z
          .number()
          .min(6)
          .max(24)
          .optional()
          .describe("Font size for page numbers (6–24). Defaults to 10."),
      })
      .strict(),
    annotations: {
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false,
    },
  },

pdf-toolkit-mcp