MCP PDF

Instructions

Implementation Reference

• src/mcp/tools/pdf-layout.ts:87-400 (handler)

  Main execution logic: processes layout input, groups content by page, computes Yoga flexbox positions, renders text/images/shapes per page, generates PDF, stores file, returns URI.
  async function handler(args: Input, extra: StorageExtra): Promise<CallToolResult> { const { storageContext } = extra; const { storageDir, baseUrl, transport } = storageContext; const { filename = 'document.pdf', title, author, font, layout, pageSetup, content } = args; const overflowBehavior = layout?.overflow ?? 'auto'; try { // Create PDF document with shared utilities const contentText = JSON.stringify(content); const setup = await createPDFDocument( { title, author, subject: filename, pageSize: pageSetup?.size as PageSizePreset | [number, number] | undefined, margins: pageSetup?.margins ?? { top: 0, bottom: 0, left: 0, right: 0 }, backgroundColor: pageSetup?.backgroundColor, }, font, contentText ); const { doc, pdfPromise, fonts, emojiAvailable, warnings } = setup; const { regular: regularFont, bold: boldFont } = fonts; // Validate text content against font validateContentText(content as ContentItem[], regularFont, boldFont, warnings); // Get page dimensions and margins const pageWidth = doc.page.width; const pageHeight = doc.page.height; const margins = { top: doc.page.margins.top, right: doc.page.margins.right, bottom: doc.page.margins.bottom, left: doc.page.margins.left, }; // Height measurer for Yoga layout const measureHeight = (item: LayoutContent, availableWidth: number): number => { if (item.type === 'text' || item.type === 'heading') { if (!item.text) return 0; const fontSize = item.type === 'heading' ? ((item.fontSize as number) ?? DEFAULT_HEADING_FONT_SIZE) : ((item.fontSize as number) ?? DEFAULT_TEXT_FONT_SIZE); const fontName = item.type === 'heading' ? (item.bold !== false ? boldFont : regularFont) : item.bold ? boldFont : regularFont; let height = measureTextHeight(doc, item.text as string, fontSize, fontName, emojiAvailable, { width: availableWidth, indent: item.indent as number | undefined, lineGap: item.lineGap as number | undefined, }); const moveDown = item.moveDown as number | undefined; if (moveDown !== undefined && moveDown > 0) { doc.fontSize(fontSize).font(fontName); height += moveDown * doc.currentLineHeight(); } return height; } if (item.type === 'image') { const dimensions = resolveImageDimensions(item.imagePath as string, item.width as number | undefined, item.height as number | undefined); return dimensions.height; } if (item.type === 'rect') { return item.height as number; } if (item.type === 'circle') { return (item.radius as number) * 2; } if (item.type === 'line') { return Math.abs((item.y2 as number) - (item.y1 as number)); } return 0; }; // Render a base content item at computed position function renderBaseItem(item: BaseContentItem, computedX?: number, computedY?: number, computedWidth?: number) { switch (item.type) { case 'text': { const fontSize = item.fontSize ?? DEFAULT_TEXT_FONT_SIZE; const fnt = item.bold ? boldFont : regularFont; if (item.color) doc.fillColor(item.color); const options = extractTextOptions(item); if (computedX !== undefined) options.x = computedX; if (computedY !== undefined) options.y = computedY; if (computedWidth !== undefined) options.width = computedWidth; renderTextWithEmoji(doc, item.text ?? '', fontSize, fnt, emojiAvailable, options); if (item.color) doc.fillColor('black'); break; } case 'heading': { const fontSize = item.fontSize ?? DEFAULT_HEADING_FONT_SIZE; const fnt = item.bold !== false ? boldFont : regularFont; if (item.color) doc.fillColor(item.color); const options = extractTextOptions(item); if (computedX !== undefined) options.x = computedX; if (computedY !== undefined) options.y = computedY; if (computedWidth !== undefined) options.width = computedWidth; renderTextWithEmoji(doc, item.text ?? '', fontSize, fnt, emojiAvailable, options); if (item.color) doc.fillColor('black'); break; } case 'image': { const dimensions = resolveImageDimensions(item.imagePath, item.width as number | undefined, item.height as number | undefined); const opts = { width: dimensions.width, height: dimensions.height }; const imgX = computedX ?? item.left; const imgY = computedY ?? item.top; if (imgX !== undefined && imgY !== undefined) { doc.image(item.imagePath, imgX, imgY, opts); } else { doc.image(item.imagePath, opts); } break; } case 'rect': { const rectX = computedX ?? item.left; const rectY = computedY ?? item.top; const rectWidth = computedWidth ?? item.width; doc.rect(rectX, rectY, rectWidth, item.height); if (item.fillColor && item.strokeColor) { if (item.lineWidth) doc.lineWidth(item.lineWidth); doc.fillAndStroke(item.fillColor, item.strokeColor); } else if (item.fillColor) { doc.fill(item.fillColor); } else if (item.strokeColor) { if (item.lineWidth) doc.lineWidth(item.lineWidth); doc.stroke(item.strokeColor); } doc.fillColor('black'); break; } case 'circle': { const circleX = computedX ?? item.left; const circleY = computedY ?? item.top; doc.circle(circleX, circleY, item.radius); if (item.fillColor && item.strokeColor) { if (item.lineWidth) doc.lineWidth(item.lineWidth); doc.fillAndStroke(item.fillColor, item.strokeColor); } else if (item.fillColor) { doc.fill(item.fillColor); } else if (item.strokeColor) { if (item.lineWidth) doc.lineWidth(item.lineWidth); doc.stroke(item.strokeColor); } doc.fillColor('black'); break; } case 'line': { if (item.lineWidth) doc.lineWidth(item.lineWidth); doc .moveTo(item.x1, item.y1) .lineTo(item.x2, item.y2) .stroke(item.strokeColor || 'black'); break; } } } // Render a group with its visual properties function renderGroupVisuals(group: GroupItem, layoutNode: LayoutNode) { if (group.background) { doc.rect(layoutNode.x, layoutNode.y, layoutNode.width, layoutNode.height).fill(group.background); doc.fillColor('black'); } if (group.border) { doc.lineWidth(group.border.width); doc.rect(layoutNode.x, layoutNode.y, layoutNode.width, layoutNode.height).stroke(group.border.color); } } // Render a layout node tree function renderLayoutNode(node: LayoutNode) { const item = node.content as ContentItem; if (item.type === 'group') { const group = item as GroupItem; renderGroupVisuals(group, node); if (node.children) { for (const childNode of node.children) { renderLayoutNode(childNode); } } } else { renderBaseItem(item as BaseContentItem, node.x, node.y, node.width); } } // Helper to get page number for an item function getItemPage(item: ContentItem): number { if ('page' in item && typeof item.page === 'number') return item.page; return 1; } // Group content by page number function groupContentByPage(items: ContentItem[]): Map<number, ContentItem[]> { const pageGroups = new Map<number, ContentItem[]>(); for (const item of items) { const pageNum = getItemPage(item); const existing = pageGroups.get(pageNum) ?? []; existing.push(item); pageGroups.set(pageNum, existing); } return pageGroups; } // Group content by page const pageGroups = groupContentByPage(content as ContentItem[]); const maxPage = Math.max(...pageGroups.keys(), 1); // Width measurer for row layouts with space-between const measureWidth = createWidthMeasurer(doc, regularFont, boldFont, emojiAvailable); // Calculate layout and render per page for (let pageNum = 1; pageNum <= maxPage; pageNum++) { if (pageNum > 1) { doc.addPage(); } // Get content for this page const pageContent = pageGroups.get(pageNum) ?? []; if (pageContent.length === 0) continue; // Convert to LayoutContent for Yoga const layoutContent: LayoutContent[] = pageContent.map((item) => { const layoutItem = item as unknown as LayoutContent; // Root items in pdf-layout default to absolute IF they have explicit coordinates // Items without coordinates (pure flex layouts) remain relative // Users can override with explicit position property if (layoutItem.position !== undefined) { return layoutItem; // Explicit position, use as-is } // Default: absolute if coordinates exist, relative otherwise const hasCoordinates = layoutItem.left !== undefined && layoutItem.top !== undefined; return { ...layoutItem, position: hasCoordinates ? 'absolute' : 'relative', }; }); // Calculate layout for THIS page only const layoutNodes = await calculateLayout(layoutContent, pageWidth, pageHeight, measureHeight, margins, measureWidth); // Check for content overflow when warn mode is enabled if (overflowBehavior === 'warn') { const getMaxBottom = (node: LayoutNode): number => { let maxBottom = node.y + node.height; if (node.children) { for (const child of node.children) { maxBottom = Math.max(maxBottom, getMaxBottom(child)); } } return maxBottom; }; for (const node of layoutNodes) { const bottom = getMaxBottom(node); if (bottom > pageHeight) { warnings.push(`Page ${pageNum}: Content exceeds page height by ${Math.ceil(bottom - pageHeight)}px. Consider reducing font sizes or removing content.`); break; } } } // Render items for this page for (const node of layoutNodes) { renderLayoutNode(node); } } doc.end(); const pdfBuffer = await pdfPromise; // Write file const { storedName } = await writeFile(pdfBuffer, filename, { storageDir }); // Generate URI const fileUri = getFileUri(storedName, transport, { storageDir, ...(baseUrl && { baseUrl }), endpoint: '/files', }); const result: Output = { operationSummary: `Created PDF layout: ${filename}`, itemsProcessed: 1, itemsChanged: 1, completedAt: new Date().toISOString(), documentId: storedName, filename, uri: fileUri, sizeBytes: pdfBuffer.length, pageCount: setup.actualPageCount, margins: setup.doc.page.margins as Margins, ...(warnings.length > 0 && { warnings }), }; return { content: [{ type: 'text' as const, text: JSON.stringify(result) }], structuredContent: { result }, }; } catch (error) { const message = error instanceof Error ? error.message : String(error); throw new McpError(ErrorCode.InternalError, `Error creating PDF layout: ${message}`, { stack: error instanceof Error ? error.stack : undefined, }); } }
• src/mcp/tools/pdf-layout.ts:59-81 (schema)

  Tool configuration including inputSchema (with layout and pageSetup), outputSchema extending pdfOutputSchema with margins.
  const config = { title: 'Create PDF Layout', description: `Create a PDF with precise positioning using Yoga flexbox layout. Best for: Dashboards, slides, certificates, flyers, and designs requiring exact placement. All items are positioned absolutely on specific pages. Use the "page" property to target different pages (e.g., page: 2 for multi-slide presentations). Pages are created as needed. Use groups for flexbox containers - they support direction, gap, justify, alignItems, and alignment properties for sophisticated layouts. Default margins: 0 (full canvas access for precise positioning).`, inputSchema, outputSchema: z.object({ result: pdfOutputSchema.extend({ margins: z.object({ top: z.number(), bottom: z.number(), left: z.number(), right: z.number(), }), }), }), } as const;
• src/mcp/tools/pdf-layout.ts:402-406 (registration)

  Tool module registration: defines name 'pdf-layout', references config and handler.
  return { name: 'pdf-layout', config, handler, } satisfies ToolModule;
• src/mcp/tools/index.ts:3-3 (registration)

  Exports the pdf-layout tool factory (createTool) as pdfLayout for use in MCP server.
  export { default as pdfLayout } from './pdf-layout.ts';