MCP PDF

Instructions

Implementation Reference

• src/mcp/tools/pdf-image.ts:74-152 (handler)

  The core handler function that validates input PDF, converts specified pages to PNG images at given scale using pdf-to-png-converter, stores images in storage directory, generates access URIs, and returns structured content with image metadata including paths, dimensions, and sizes.

  async function handler(args: Input, extra: StorageExtra): Promise<CallToolResult> {
    const { storageContext } = extra;
    const { storageDir, baseUrl, transport } = storageContext;
    const { pdfPath, pages = 1, viewportScale = 0.5 } = args;
  
    try {
      // Validate PDF exists
      if (!existsSync(pdfPath)) {
        throw new McpError(ErrorCode.InvalidParams, `PDF file not found: ${pdfPath}`);
      }
  
      // Determine pages to process
      let pagesToProcess: number[] | undefined;
      if (pages === 'all') {
        pagesToProcess = undefined; // undefined means all pages in pdf-to-png-converter
      } else if (typeof pages === 'number') {
        pagesToProcess = [pages];
      } else {
        pagesToProcess = pages;
      }
  
      // Convert to PNG
      const pngPages = await pdfToPng(pdfPath, {
        viewportScale,
        pagesToProcess,
        verbosityLevel: 0,
      });
  
      if (pngPages.length === 0) {
        throw new McpError(ErrorCode.InternalError, 'Failed to render any pages. The PDF may be empty or invalid.');
      }
  
      const pdfBasename = basename(pdfPath, '.pdf');
      const images: z.infer<typeof imageResultSchema>[] = [];
  
      for (const pngPage of pngPages) {
        const pngBuffer = pngPage.content;
        const pageNum = pngPage.pageNumber;
  
        // Generate output filename
        const outputFilename = `${pdfBasename}-p${pageNum}.png`;
  
        // Write to storage
        const { storedName } = await writeFile(pngBuffer, outputFilename, { storageDir });
  
        // Generate URI
        const uri = getFileUri(storedName, transport, {
          storageDir,
          ...(baseUrl && { baseUrl }),
          endpoint: '/files',
        });
  
        images.push({
          imagePath: storedName,
          uri,
          width: pngPage.width,
          height: pngPage.height,
          pageNumber: pageNum,
          fileSizeBytes: pngBuffer.length,
        });
      }
  
      const result: Output = {
        images,
        totalPages: images.length,
      };
  
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
        structuredContent: result,
      };
    } catch (error) {
      if (error instanceof McpError) throw error;
      const message = error instanceof Error ? error.message : String(error);
      throw new McpError(ErrorCode.InternalError, `Error generating PDF image: ${message}`, {
        stack: error instanceof Error ? error.stack : undefined,
      });
    }
  }

• src/mcp/tools/pdf-image.ts:19-68 (schema)

  Zod schemas for input parameters (pdfPath, pages, viewportScale), output structure (images array with metadata), and tool configuration including detailed description and usage recommendations.

  // ============================================================================
  // Schemas
  // ============================================================================
  
  const pagesSchema = z
    .union([z.number().int().min(1), z.array(z.number().int().min(1)), z.literal('all')])
    .optional()
    .describe('Pages to render: single number (e.g., 1), array (e.g., [1, 3, 5]), or "all". Default: 1');
  
  const inputSchema = z.object({
    pdfPath: z.string().describe('Absolute path to the PDF file'),
    pages: pagesSchema,
    viewportScale: z.number().min(0.1).max(3.0).optional().describe('Scale factor for the image. Recommended: 0.25 (thumbnail, ~150px wide, smallest), 0.5 (preview, ~300px wide, good balance), 1.0 (full size, ~612px wide). Default: 0.5'),
  });
  
  const imageResultSchema = z.object({
    imagePath: z.string().describe('Path to the generated PNG image'),
    uri: z.string().describe('URI to access the image'),
    width: z.number().describe('Image width in pixels'),
    height: z.number().describe('Image height in pixels'),
    pageNumber: z.number().describe('Page number that was rendered'),
    fileSizeBytes: z.number().describe('File size in bytes'),
  });
  
  const outputSchema = z.object({
    images: z.array(imageResultSchema).describe('Array of generated images'),
    totalPages: z.number().describe('Total pages rendered'),
  });
  
  const config = {
    title: 'Convert PDF to Image',
    description: `Generate PNG image(s) from PDF pages.
  
  Use this to visually verify PDF output without opening external applications.
  
  **Pages Options:**
  - Single page: \`pages: 1\` or \`pages: 3\`
  - Multiple pages: \`pages: [1, 3, 5]\`
  - All pages: \`pages: "all"\`
  - Default: page 1 only
  
  **Viewport Scale Recommendations:**
  - **0.25 (thumbnail)**: ~150px wide, smallest file (~15-30KB). Use for quick verification.
  - **0.5 (preview)**: ~300px wide, good balance (~40-80KB). **Recommended default.**
  - **1.0 (full)**: ~612px wide, detailed view (~150-300KB). Use when details matter.
  
  Lower scales produce smaller files, reducing context usage when sharing images.`,
    inputSchema,
    outputSchema,
  } as const;

• src/mcp/tools/pdf-image.ts:73-159 (registration)

  The tool factory function createTool() that defines and returns the ToolModule for 'pdf-image', including the name, config (with schemas and description), and the handler function.

  export default function createTool() {
    async function handler(args: Input, extra: StorageExtra): Promise<CallToolResult> {
      const { storageContext } = extra;
      const { storageDir, baseUrl, transport } = storageContext;
      const { pdfPath, pages = 1, viewportScale = 0.5 } = args;
  
      try {
        // Validate PDF exists
        if (!existsSync(pdfPath)) {
          throw new McpError(ErrorCode.InvalidParams, `PDF file not found: ${pdfPath}`);
        }
  
        // Determine pages to process
        let pagesToProcess: number[] | undefined;
        if (pages === 'all') {
          pagesToProcess = undefined; // undefined means all pages in pdf-to-png-converter
        } else if (typeof pages === 'number') {
          pagesToProcess = [pages];
        } else {
          pagesToProcess = pages;
        }
  
        // Convert to PNG
        const pngPages = await pdfToPng(pdfPath, {
          viewportScale,
          pagesToProcess,
          verbosityLevel: 0,
        });
  
        if (pngPages.length === 0) {
          throw new McpError(ErrorCode.InternalError, 'Failed to render any pages. The PDF may be empty or invalid.');
        }
  
        const pdfBasename = basename(pdfPath, '.pdf');
        const images: z.infer<typeof imageResultSchema>[] = [];
  
        for (const pngPage of pngPages) {
          const pngBuffer = pngPage.content;
          const pageNum = pngPage.pageNumber;
  
          // Generate output filename
          const outputFilename = `${pdfBasename}-p${pageNum}.png`;
  
          // Write to storage
          const { storedName } = await writeFile(pngBuffer, outputFilename, { storageDir });
  
          // Generate URI
          const uri = getFileUri(storedName, transport, {
            storageDir,
            ...(baseUrl && { baseUrl }),
            endpoint: '/files',
          });
  
          images.push({
            imagePath: storedName,
            uri,
            width: pngPage.width,
            height: pngPage.height,
            pageNumber: pageNum,
            fileSizeBytes: pngBuffer.length,
          });
        }
  
        const result: Output = {
          images,
          totalPages: images.length,
        };
  
        return {
          content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
          structuredContent: result,
        };
      } catch (error) {
        if (error instanceof McpError) throw error;
        const message = error instanceof Error ? error.message : String(error);
        throw new McpError(ErrorCode.InternalError, `Error generating PDF image: ${message}`, {
          stack: error instanceof Error ? error.stack : undefined,
        });
      }
    }
  
    return {
      name: 'pdf-image',
      config,
      handler,
    } satisfies ToolModule;
  }