pdf-toolkit-mcp

Instructions

Implementation Reference

• src/tools/create.ts:547-612 (handler)

  The handler function for pdf_embed_image that processes the input parameters, validates paths, embeds the image (PNG or JPG) into the specified page of the PDF, and saves the resulting document.

  async ({ filePath, imagePath, page, x, y, width, height, outputPath }) => {
    try {
      const resolvedPath = await validatePdfPath(filePath);
      await validateFileSize(resolvedPath);
      const resolvedOutput = await validateOutputPath(outputPath, filePath);
  
      const resolvedImagePath = await validateImagePath(imagePath);
      await validateFileSize(resolvedImagePath);
      const ext = extname(resolvedImagePath).toLowerCase();
      const imageBuffer = await readFile(resolvedImagePath);
      const imageBytes = toUint8Array(imageBuffer);
  
      const pdfDoc = await loadExistingPdf(resolvedPath);
      const totalPages = pdfDoc.getPageCount();
  
      if (page > totalPages) {
        return toolError(
          `Page ${page} exceeds document length (${totalPages} pages).`
        );
      }
  
      const image =
        ext === ".png"
          ? await pdfDoc.embedPng(imageBytes)
          : await pdfDoc.embedJpg(imageBytes);
  
      // Calculate dimensions preserving aspect ratio
      let drawWidth: number;
      let drawHeight: number;
  
      if (width !== undefined && height !== undefined) {
        drawWidth = width;
        drawHeight = height;
      } else if (width !== undefined) {
        drawWidth = width;
        drawHeight = width * (image.height / image.width);
      } else if (height !== undefined) {
        drawHeight = height;
        drawWidth = height * (image.width / image.height);
      } else {
        drawWidth = image.width;
        drawHeight = image.height;
      }
  
      const targetPage = pdfDoc.getPage(page - 1);
      targetPage.drawImage(image, {
        x,
        y,
        width: drawWidth,
        height: drawHeight,
      });
  
      await savePdf(pdfDoc, resolvedOutput);
      const fileSize = await getFileSize(resolvedOutput);
  
      return toolSuccess({
        outputPath: resolvedOutput,
        page,
        position: { x, y },
        dimensions: { width: drawWidth, height: drawHeight },
        fileSize,
      });
    } catch (error) {
      return toolError(
        error instanceof Error ? error.message : String(error)
      );

• src/tools/create.ts:499-539 (schema)

  Input schema definition for the pdf_embed_image tool using Zod.

  inputSchema: z
    .object({
      filePath: z
        .string()
        .max(4096)
        .describe("Absolute path to the source PDF file"),
      imagePath: z
        .string()
        .max(4096)
        .describe("Absolute path to the PNG or JPEG image file"),
      page: z
        .number()
        .int()
        .min(1)
        .describe("Target page number (1-indexed)"),
      x: z
        .number()
        .describe("X position in points from the left edge of the page"),
      y: z
        .number()
        .describe(
          "Y position in points from the bottom edge of the page"
        ),
      width: z
        .number()
        .optional()
        .describe(
          "Image width in points. Omit to use original width (or scale proportionally if height is set)."
        ),
      height: z
        .number()
        .optional()
        .describe(
          "Image height in points. Omit to use original height (or scale proportionally if width is set)."
        ),
      outputPath: z
        .string()
        .max(4096)
        .describe("Absolute path for the output PDF"),
    })
    .strict(),

• src/tools/create.ts:494-546 (registration)

  Tool registration block for pdf_embed_image using server.registerTool.

  server.registerTool(
    "pdf_embed_image",
    {
      description:
        "Embed a PNG or JPEG image into a specific page of a PDF. Supports custom positioning and optional scaling with aspect ratio preservation.",
      inputSchema: z
        .object({
          filePath: z
            .string()
            .max(4096)
            .describe("Absolute path to the source PDF file"),
          imagePath: z
            .string()
            .max(4096)
            .describe("Absolute path to the PNG or JPEG image file"),
          page: z
            .number()
            .int()
            .min(1)
            .describe("Target page number (1-indexed)"),
          x: z
            .number()
            .describe("X position in points from the left edge of the page"),
          y: z
            .number()
            .describe(
              "Y position in points from the bottom edge of the page"
            ),
          width: z
            .number()
            .optional()
            .describe(
              "Image width in points. Omit to use original width (or scale proportionally if height is set)."
            ),
          height: z
            .number()
            .optional()
            .describe(
              "Image height in points. Omit to use original height (or scale proportionally if width is set)."
            ),
          outputPath: z
            .string()
            .max(4096)
            .describe("Absolute path for the output PDF"),
        })
        .strict(),
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },