pretext-pdf-mcp 1.0.0

package/README.md

@@ -0,0 +1,187 @@
+# pretext-pdf-mcp
+
+MCP server for [pretext-pdf](https://github.com/Himaan1998Y/pretext-pdf) — generate professional PDFs from structured JSON in Claude, Cursor, or any AI agent.
+
+No headless browser. No puppeteer. Pure Node.js with embedded fonts and precision text layout.
+
+## Install
+
+### Option 1: npx (no global install needed)
+
+```bash
+npx pretext-pdf-mcp
+```
+
+### Option 2: Global install
+
+```bash
+npm install -g pretext-pdf-mcp
+pretext-pdf-mcp
+```
+
+## Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pretext-pdf": {
+      "command": "npx",
+      "args": ["-y", "pretext-pdf-mcp"]
+    }
+  }
+}
+```
+
+Config file location:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+## Tools
+
+| Tool | Input | Output |
+|------|-------|--------|
+| `generate_pdf` | PdfDocument JSON descriptor | Base64 PDF + filename + size |
+| `generate_invoice` | Invoice data (parties, items, GST, currency) | Base64 PDF |
+| `generate_report` | Report sections with optional tables and callouts | Base64 PDF |
+| `list_element_types` | none | Markdown reference of all element types |
+
+### generate_pdf
+
+Full-power access to the pretext-pdf API. Pass any PdfDocument descriptor.
+
+```json
+{
+  "document": {
+    "pageSize": "A4",
+    "footer": { "text": "Page {{pageNumber}} of {{totalPages}}", "fontSize": 9 },
+    "content": [
+      { "type": "heading", "level": 1, "text": "My Document" },
+      { "type": "paragraph", "text": "Hello world." }
+    ]
+  },
+  "filename": "my-document"
+}
+```
+
+Returns:
+```json
+{
+  "success": true,
+  "base64": "<base64-encoded PDF bytes>",
+  "filename": "my-document.pdf",
+  "size_bytes": 42816
+}
+```
+
+### generate_invoice
+
+Business-friendly invoice generator. No PDF knowledge needed.
+
+```json
+{
+  "from": {
+    "company": "Antigravity Systems",
+    "address": "Gurugram, Haryana",
+    "gstin": "06AABCA1234Z1ZK",
+    "email": "hello@antigravity.dev"
+  },
+  "to": {
+    "company": "TCS Ltd",
+    "address": "Mumbai, Maharashtra",
+    "gstin": "27AAACT2727Q1ZW"
+  },
+  "invoice_number": "INV-2026-001",
+  "date": "2026-04-08",
+  "due_date": "2026-05-08",
+  "currency": "INR",
+  "items": [
+    {
+      "description": "LLM Fine-tuning Pipeline",
+      "hsn_code": "998314",
+      "quantity": 1,
+      "rate": 250000,
+      "gst_rate": 18
+    },
+    {
+      "description": "AI Strategy Workshop",
+      "quantity": 2,
+      "rate": 75000,
+      "gst_rate": 18
+    }
+  ],
+  "notes": "Payment due within 30 days. NEFT/IMPS preferred."
+}
+```
+
+Returns:
+```json
+{
+  "success": true,
+  "base64": "<base64-encoded PDF bytes>",
+  "filename": "invoice-INV-2026-001.pdf",
+  "size_bytes": 68420
+}
+```
+
+Features:
+- Supports INR, USD, EUR, GBP
+- Auto-calculates IGST per line item when `gst_rate` is set
+- HSN/SAC code column appears automatically when any item has it
+- Company header with from/to details in a 2-column table
+- Professional footer with invoice number and page numbers
+
+### generate_report
+
+Multi-section report with optional TOC, tables, and callout boxes.
+
+```json
+{
+  "title": "Haryana Real Estate Q1 2026",
+  "subtitle": "Residential & Commercial Analysis",
+  "author": "Antigravity Research",
+  "include_toc": true,
+  "sections": [
+    {
+      "heading": "Executive Summary",
+      "body": "Strong growth across all micro-markets.\n\nGurugram led with 18% YoY volume growth.",
+      "table": {
+        "headers": ["Market", "Avg Rs./sqft", "YoY"],
+        "rows": [
+          ["New Gurugram", "9,800", "+15.6%"],
+          ["Sohna Road", "8,400", "+12.1%"]
+        ]
+      },
+      "callout": {
+        "style": "warning",
+        "text": "Repo rate risk: any hike above 6.75% could suppress volumes 10-15%."
+      }
+    }
+  ]
+}
+```
+
+### list_element_types
+
+No input. Returns a markdown reference of all 16 element types (paragraph, heading, table, list, image, svg, code, blockquote, callout, toc, form-field, comment, hr, spacer, page-break, rich-paragraph) with key properties and examples.
+
+## Decoding the base64 PDF
+
+In Node.js:
+```javascript
+const bytes = Buffer.from(result.base64, 'base64')
+fs.writeFileSync('output.pdf', bytes)
+```
+
+In Python:
+```python
+import base64
+pdf_bytes = base64.b64decode(result['base64'])
+with open('output.pdf', 'wb') as f:
+    f.write(pdf_bytes)
+```
+
+## License
+
+MIT — Himanshu Jain

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { generatePdfTool } from './tools/generate-pdf.js';
+import { generateInvoiceTool } from './tools/generate-invoice.js';
+import { generateReportTool } from './tools/generate-report.js';
+import { listElementsTool } from './tools/list-elements.js';
+const server = new Server({ name: 'pretext-pdf', version: '1.0.0' }, { capabilities: { tools: {} } });
+const tools = [generatePdfTool, generateInvoiceTool, generateReportTool, listElementsTool];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map(t => t.schema),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = tools.find(t => t.schema.name === request.params.name);
+    if (!tool) {
+        return {
+            content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }],
+            isError: true,
+        };
+    }
+    return tool.handler(request.params.arguments ?? {});
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/generate-invoice.js

@@ -0,0 +1,323 @@
+import { render } from 'pretext-pdf';
+import { toBase64 } from '../utils/base64.js';
+const CURRENCY_SYMBOLS = {
+    INR: '₹',
+    USD: '$',
+    EUR: '€',
+    GBP: '£',
+};
+function formatMoney(amount, symbol) {
+    return `${symbol}${amount.toLocaleString('en-IN', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+function partyBlock(p) {
+    const lines = [p.company];
+    if (p.address)
+        lines.push(p.address);
+    if (p.gstin)
+        lines.push(`GSTIN: ${p.gstin}`);
+    if (p.email)
+        lines.push(p.email);
+    if (p.phone)
+        lines.push(p.phone);
+    return lines.join('\n');
+}
+function todayISO() {
+    return new Date().toISOString().slice(0, 10);
+}
+function buildInvoiceDocument(input) {
+    const currency = input.currency ?? 'INR';
+    const sym = CURRENCY_SYMBOLS[currency];
+    const date = input.date ?? todayISO();
+    const invoiceNo = input.invoice_number ?? `INV-${Date.now()}`;
+    const hasHsn = input.items.some(i => i.hsn_code);
+    const hasGst = input.items.some(i => i.gst_rate !== undefined && i.gst_rate > 0);
+    // Build columns for line items table
+    const itemColumns = [{ width: '3*', align: 'left' }];
+    if (hasHsn)
+        itemColumns.push({ width: 70, align: 'center' });
+    itemColumns.push({ width: 60, align: 'right' });
+    itemColumns.push({ width: 80, align: 'right' });
+    itemColumns.push({ width: 90, align: 'right' });
+    // Header row for items table
+    const headerCells = [
+        { text: 'Description', fontWeight: 700, color: '#ffffff' },
+    ];
+    if (hasHsn)
+        headerCells.push({ text: 'HSN', fontWeight: 700, color: '#ffffff' });
+    headerCells.push({ text: 'Qty', fontWeight: 700, color: '#ffffff' });
+    headerCells.push({ text: 'Rate', fontWeight: 700, color: '#ffffff' });
+    headerCells.push({ text: 'Amount', fontWeight: 700, color: '#ffffff' });
+    // Data rows
+    let subtotal = 0;
+    const itemRows = [{ isHeader: true, cells: headerCells }];
+    for (const item of input.items) {
+        const amount = item.quantity * item.rate;
+        subtotal += amount;
+        const cells = [{ text: item.description }];
+        if (hasHsn)
+            cells.push({ text: item.hsn_code ?? '' });
+        cells.push({ text: String(item.quantity) });
+        cells.push({ text: formatMoney(item.rate, sym) });
+        cells.push({ text: formatMoney(amount, sym) });
+        itemRows.push({ cells });
+    }
+    // GST calculation: use IGST if inter-state (default), or CGST+SGST if intra
+    // We'll use IGST for simplicity (single tax line)
+    const totalGst = hasGst
+        ? input.items.reduce((sum, item) => {
+            const amount = item.quantity * item.rate;
+            const rate = item.gst_rate ?? 0;
+            return sum + (amount * rate) / 100;
+        }, 0)
+        : 0;
+    const grandTotal = subtotal + totalGst;
+    // Build totals section
+    const totalsContent = [
+        { type: 'hr', color: '#dddddd', thickness: 0.5, spaceBelow: 6 },
+        {
+            type: 'paragraph',
+            text: `Subtotal:  ${formatMoney(subtotal, sym)}`,
+            align: 'right',
+            spaceAfter: hasGst ? 4 : 8,
+        },
+    ];
+    if (hasGst) {
+        // Build per-rate GST breakdown
+        const rateGroups = {};
+        for (const item of input.items) {
+            if (!item.gst_rate)
+                continue;
+            const amount = item.quantity * item.rate;
+            rateGroups[item.gst_rate] = (rateGroups[item.gst_rate] ?? 0) + (amount * item.gst_rate) / 100;
+        }
+        for (const [rate, gstAmt] of Object.entries(rateGroups)) {
+            totalsContent.push({
+                type: 'paragraph',
+                text: `IGST @ ${rate}%:  ${formatMoney(gstAmt, sym)}`,
+                align: 'right',
+                color: '#555555',
+                spaceAfter: 4,
+            });
+        }
+        totalsContent.push({ type: 'hr', color: '#1a1a2e', thickness: 1, spaceBelow: 6 });
+        totalsContent.push({
+            type: 'paragraph',
+            text: `GRAND TOTAL:  ${formatMoney(grandTotal, sym)}`,
+            fontSize: 13,
+            fontWeight: 700,
+            color: '#1a1a2e',
+            align: 'right',
+            spaceAfter: 16,
+        });
+    }
+    else {
+        totalsContent.push({ type: 'hr', color: '#1a1a2e', thickness: 1, spaceBelow: 6 });
+        totalsContent.push({
+            type: 'paragraph',
+            text: `TOTAL:  ${formatMoney(grandTotal, sym)}`,
+            fontSize: 13,
+            fontWeight: 700,
+            color: '#1a1a2e',
+            align: 'right',
+            spaceAfter: 16,
+        });
+    }
+    const content = [
+        // Header: company name
+        { type: 'heading', level: 1, text: input.from.company, fontSize: 22, color: '#1a1a2e', spaceAfter: 4 },
+        {
+            type: 'paragraph',
+            text: [input.from.address, input.from.gstin ? `GSTIN: ${input.from.gstin}` : null]
+                .filter(Boolean)
+                .join('  ·  '),
+            fontSize: 9,
+            color: '#666666',
+            spaceAfter: 2,
+        },
+        {
+            type: 'paragraph',
+            text: [input.from.email, input.from.phone].filter(Boolean).join('  ·  '),
+            fontSize: 9,
+            color: '#0070f3',
+            spaceAfter: 14,
+        },
+        { type: 'hr', color: '#1a1a2e', thickness: 2, spaceBelow: 12 },
+        // Invoice meta
+        { type: 'heading', level: 3, text: 'INVOICE', fontSize: 16, color: '#1a1a2e', spaceAfter: 8 },
+        {
+            type: 'table',
+            columns: [{ width: '1*' }, { width: '1*' }],
+            rows: [
+                {
+                    cells: [
+                        { text: `Invoice No.\n${invoiceNo}` },
+                        { text: `Bill To\n${partyBlock(input.to)}` },
+                    ],
+                },
+                {
+                    cells: [
+                        { text: `Date\n${date}` },
+                        { text: input.due_date ? `Due Date\n${input.due_date}` : '' },
+                    ],
+                },
+            ],
+            borderColor: '#e8e8e8',
+            borderWidth: 0.5,
+            cellPaddingH: 10,
+            cellPaddingV: 8,
+            spaceAfter: 16,
+        },
+        // Line items
+        { type: 'heading', level: 3, text: 'Services / Items', color: '#1a1a2e', spaceAfter: 6 },
+        {
+            type: 'table',
+            columns: itemColumns,
+            rows: itemRows,
+            headerBgColor: '#1a1a2e',
+            borderColor: '#e0e0e0',
+            borderWidth: 0.5,
+            cellPaddingH: 8,
+            cellPaddingV: 6,
+            spaceAfter: 4,
+        },
+        // Totals
+        ...totalsContent,
+    ];
+    // Notes
+    if (input.notes) {
+        content.push({ type: 'hr', color: '#e8e8e8', thickness: 0.5, spaceBelow: 10 });
+        content.push({ type: 'heading', level: 4, text: 'Notes', spaceAfter: 4 });
+        content.push({ type: 'paragraph', text: input.notes, fontSize: 10, color: '#555555', spaceAfter: 12 });
+    }
+    // Footer note
+    content.push({ type: 'hr', color: '#e8e8e8', thickness: 0.5, spaceBelow: 8 });
+    content.push({
+        type: 'paragraph',
+        text: 'Generated by pretext-pdf',
+        fontSize: 8,
+        color: '#aaaaaa',
+        align: 'center',
+    });
+    return {
+        pageSize: 'A4',
+        margins: { top: 50, bottom: 50, left: 56, right: 56 },
+        defaultFontSize: 10,
+        footer: {
+            text: `Invoice ${invoiceNo}  ·  Page {{pageNumber}} of {{totalPages}}`,
+            fontSize: 8,
+            color: '#aaaaaa',
+            align: 'center',
+        },
+        content,
+    };
+}
+export const generateInvoiceTool = {
+    schema: {
+        name: 'generate_invoice',
+        description: 'Generate a professional invoice PDF. Accepts structured invoice data (from/to parties, line items, GST). Returns base64-encoded PDF. Supports INR/USD/EUR/GBP currencies. GST (IGST) is auto-calculated when gst_rate is set on items.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                from: {
+                    type: 'object',
+                    description: 'Issuing party (your company)',
+                    properties: {
+                        company: { type: 'string' },
+                        address: { type: 'string' },
+                        gstin: { type: 'string' },
+                        email: { type: 'string' },
+                        phone: { type: 'string' },
+                    },
+                    required: ['company'],
+                },
+                to: {
+                    type: 'object',
+                    description: 'Billing party (client)',
+                    properties: {
+                        company: { type: 'string' },
+                        address: { type: 'string' },
+                        gstin: { type: 'string' },
+                    },
+                    required: ['company'],
+                },
+                invoice_number: { type: 'string', description: 'Invoice identifier e.g. INV-2026-001' },
+                date: { type: 'string', description: 'Invoice date ISO format YYYY-MM-DD. Defaults to today.' },
+                due_date: { type: 'string', description: 'Payment due date ISO format.' },
+                currency: {
+                    type: 'string',
+                    enum: ['INR', 'USD', 'EUR', 'GBP'],
+                    description: 'Currency. Default: INR',
+                },
+                items: {
+                    type: 'array',
+                    description: 'Line items',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            description: { type: 'string' },
+                            hsn_code: { type: 'string', description: 'HSN/SAC code for India GST' },
+                            quantity: { type: 'number' },
+                            rate: { type: 'number', description: 'Unit price' },
+                            gst_rate: {
+                                type: 'number',
+                                enum: [0, 5, 12, 18, 28],
+                                description: 'GST rate %. If set, IGST is calculated.',
+                            },
+                        },
+                        required: ['description', 'quantity', 'rate'],
+                    },
+                },
+                notes: { type: 'string', description: 'Additional notes or payment terms.' },
+                filename: { type: 'string', description: 'Suggested filename without .pdf extension.' },
+            },
+            required: ['from', 'to', 'items'],
+        },
+    },
+    handler: async (args) => {
+        try {
+            // Validate required fields
+            if (!args.from || !args.to) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'VALIDATION_ERROR', message: 'from and to are required' }) }],
+                    isError: true,
+                };
+            }
+            const items = args.items;
+            if (!Array.isArray(items) || items.length === 0) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'VALIDATION_ERROR', message: 'items must be a non-empty array' }) }],
+                    isError: true,
+                };
+            }
+            const input = args;
+            const doc = buildInvoiceDocument(input);
+            const bytes = await render(doc);
+            const base64 = toBase64(bytes);
+            const invoiceNo = input.invoice_number ?? 'invoice';
+            const filename = (args.filename ?? `invoice-${invoiceNo}`) + '.pdf';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, base64, filename, size_bytes: bytes.length }),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: err.code ?? 'UNKNOWN_ERROR',
+                            message: err.message,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    },
+};

package/dist/tools/generate-pdf.js

@@ -0,0 +1,59 @@
+import { render } from 'pretext-pdf';
+import { toBase64 } from '../utils/base64.js';
+export const generatePdfTool = {
+    schema: {
+        name: 'generate_pdf',
+        description: 'Generate a PDF from a pretext-pdf document descriptor (PdfDocument JSON). Returns base64-encoded PDF bytes. Use list_element_types to see available elements.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                document: {
+                    type: 'object',
+                    description: 'A PdfDocument config object with content array and optional pageSize, margins, fonts, header, footer, watermark, encryption, etc.',
+                },
+                filename: {
+                    type: 'string',
+                    description: 'Suggested filename (without .pdf extension)',
+                    default: 'document',
+                },
+            },
+            required: ['document'],
+        },
+    },
+    handler: async (args) => {
+        try {
+            if (!args.document || typeof args.document !== 'object') {
+                return {
+                    content: [{ type: 'text', text: 'Error: document is required and must be an object' }],
+                    isError: true,
+                };
+            }
+            const bytes = await render(args.document);
+            const base64 = toBase64(bytes);
+            const filename = (args.filename ?? 'document') + '.pdf';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, base64, filename, size_bytes: bytes.length }),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: err.code ?? 'UNKNOWN_ERROR',
+                            message: err.message,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    },
+};

package/dist/tools/generate-report.js

@@ -0,0 +1,253 @@
+import { render } from 'pretext-pdf';
+import { toBase64 } from '../utils/base64.js';
+const CALLOUT_COLORS = {
+    info: '#0070f3',
+    warning: '#f59e0b',
+    tip: '#10b981',
+    note: '#6366f1',
+};
+function todayISO() {
+    return new Date().toISOString().slice(0, 10);
+}
+function buildReportDocument(input) {
+    const includeToc = input.include_toc !== false;
+    const date = input.date ?? todayISO();
+    const content = [
+        // Cover block
+        { type: 'spacer', height: 40 },
+        {
+            type: 'heading',
+            level: 1,
+            text: input.title,
+            fontSize: 28,
+            color: '#1a1a2e',
+            align: 'center',
+            spaceAfter: 10,
+            bookmark: false,
+        },
+    ];
+    if (input.subtitle) {
+        content.push({
+            type: 'paragraph',
+            text: input.subtitle,
+            fontSize: 14,
+            color: '#555555',
+            align: 'center',
+            spaceAfter: 10,
+        });
+    }
+    const metaParts = [];
+    if (input.author)
+        metaParts.push(input.author);
+    metaParts.push(date);
+    content.push({
+        type: 'paragraph',
+        text: metaParts.join('  ·  '),
+        fontSize: 10,
+        color: '#888888',
+        align: 'center',
+        spaceAfter: 6,
+    });
+    content.push({ type: 'hr', color: '#1a1a2e', thickness: 2, spaceBelow: 40 });
+    // TOC
+    if (includeToc) {
+        content.push({
+            type: 'toc',
+            title: 'Contents',
+            showTitle: true,
+            leader: '.',
+            minLevel: 1,
+            maxLevel: 2,
+            fontSize: 11,
+            spaceAfter: 24,
+        });
+        content.push({ type: 'page-break' });
+    }
+    // Sections
+    for (const section of input.sections) {
+        content.push({
+            type: 'heading',
+            level: 1,
+            text: section.heading,
+            anchor: section.heading.toLowerCase().replace(/\s+/g, '-'),
+            spaceAfter: 8,
+        });
+        // Body: split on double newlines for multiple paragraphs, single newlines become spaces
+        const paragraphs = section.body.split(/\n\n+/);
+        for (const para of paragraphs) {
+            if (para.trim()) {
+                content.push({
+                    type: 'paragraph',
+                    text: para.trim().replace(/\n/g, ' '),
+                    spaceAfter: 8,
+                });
+            }
+        }
+        if (section.table) {
+            const { headers, rows } = section.table;
+            const columns = headers.map(() => ({ width: `${Math.floor(100 / headers.length)}%` }));
+            // Use equal fractional widths
+            const fracColumns = headers.map(() => ({ width: '1*', align: 'left' }));
+            const headerRow = {
+                isHeader: true,
+                cells: headers.map(h => ({ text: h, fontWeight: 700, color: '#ffffff' })),
+            };
+            const dataRows = rows.map(row => ({
+                cells: row.map(cell => ({ text: cell })),
+            }));
+            content.push({
+                type: 'table',
+                columns: fracColumns,
+                rows: [headerRow, ...dataRows],
+                headerBgColor: '#1a1a2e',
+                borderColor: '#dddddd',
+                borderWidth: 0.5,
+                cellPaddingH: 8,
+                cellPaddingV: 6,
+                spaceAfter: 12,
+            });
+            // Suppress unused variable warning
+            void columns;
+        }
+        if (section.callout) {
+            const borderColor = CALLOUT_COLORS[section.callout.style] ?? '#888888';
+            content.push({
+                type: 'callout',
+                style: section.callout.style,
+                content: section.callout.text,
+                borderColor,
+                spaceAfter: 12,
+            });
+        }
+    }
+    return {
+        pageSize: 'A4',
+        margins: { top: 60, bottom: 60, left: 64, right: 64 },
+        defaultFontSize: 11,
+        bookmarks: { minLevel: 1, maxLevel: 3 },
+        header: {
+            text: input.title,
+            fontSize: 8,
+            color: '#999999',
+            align: 'right',
+        },
+        footer: {
+            text: 'Page {{pageNumber}} of {{totalPages}}',
+            fontSize: 8,
+            color: '#999999',
+            align: 'center',
+        },
+        metadata: {
+            title: input.title,
+            author: input.author,
+            subject: input.subtitle,
+        },
+        content,
+    };
+}
+export const generateReportTool = {
+    schema: {
+        name: 'generate_report',
+        description: 'Generate a professional multi-section report PDF with optional TOC, tables, and callout boxes. Returns base64-encoded PDF.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', description: 'Report title' },
+                subtitle: { type: 'string', description: 'Report subtitle or description' },
+                author: { type: 'string', description: 'Author name' },
+                date: { type: 'string', description: 'Date string. Defaults to today.' },
+                include_toc: {
+                    type: 'boolean',
+                    description: 'Include a Table of Contents page. Default: true',
+                    default: true,
+                },
+                sections: {
+                    type: 'array',
+                    description: 'Report sections',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            heading: { type: 'string', description: 'Section heading' },
+                            body: {
+                                type: 'string',
+                                description: 'Section body text. Use double newlines (\\n\\n) to separate paragraphs.',
+                            },
+                            table: {
+                                type: 'object',
+                                description: 'Optional data table',
+                                properties: {
+                                    headers: { type: 'array', items: { type: 'string' } },
+                                    rows: {
+                                        type: 'array',
+                                        items: { type: 'array', items: { type: 'string' } },
+                                    },
+                                },
+                                required: ['headers', 'rows'],
+                            },
+                            callout: {
+                                type: 'object',
+                                description: 'Optional callout / alert box',
+                                properties: {
+                                    style: {
+                                        type: 'string',
+                                        enum: ['info', 'warning', 'tip', 'note'],
+                                    },
+                                    text: { type: 'string' },
+                                },
+                                required: ['style', 'text'],
+                            },
+                        },
+                        required: ['heading', 'body'],
+                    },
+                },
+                filename: { type: 'string', description: 'Suggested filename without .pdf extension.' },
+            },
+            required: ['title', 'sections'],
+        },
+    },
+    handler: async (args) => {
+        try {
+            if (!args.title || typeof args.title !== 'string') {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'VALIDATION_ERROR', message: 'title is required' }) }],
+                    isError: true,
+                };
+            }
+            const sections = args.sections;
+            if (!Array.isArray(sections) || sections.length === 0) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ success: false, error: 'VALIDATION_ERROR', message: 'sections must be a non-empty array' }) }],
+                    isError: true,
+                };
+            }
+            const input = args;
+            const doc = buildReportDocument(input);
+            const bytes = await render(doc);
+            const base64 = toBase64(bytes);
+            const filename = (args.filename ?? `report-${Date.now()}`) + '.pdf';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, base64, filename, size_bytes: bytes.length }),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: err.code ?? 'UNKNOWN_ERROR',
+                            message: err.message,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    },
+};

package/dist/tools/list-elements.js

@@ -0,0 +1,98 @@
+const ELEMENTS_REFERENCE = `# pretext-pdf Element Types Reference
+
+## paragraph
+Renders a text block. Key props: \`text\` (required), \`fontSize\`, \`fontWeight\` (400|700), \`color\` (#hex), \`align\` (left|center|right|justify), \`spaceAfter\`, \`spaceBefore\`, \`bgColor\`, \`underline\`, \`strikethrough\`, \`url\`, \`letterSpacing\`, \`smallCaps\`.
+Example: \`{ type: "paragraph", text: "Hello world", fontSize: 12, color: "#333333" }\`
+
+## heading
+Section heading with automatic bookmarks. Key props: \`level\` (1–4, required), \`text\` (required), \`fontSize\` (defaults: h1=28, h2=22, h3=18, h4=15), \`color\`, \`align\`, \`anchor\` (for internal links), \`bookmark\` (set false to exclude from PDF outline), \`spaceAfter\`.
+Example: \`{ type: "heading", level: 1, text: "Introduction", color: "#1a1a2e" }\`
+
+## rich-paragraph
+Paragraph with per-span formatting. Key props: \`lines\` (array of RichLine, each with \`spans\` array). Each span: \`text\`, \`fontWeight\`, \`color\`, \`fontSize\`, \`italic\`, \`underline\`, \`strikethrough\`, \`url\`, \`href\` (internal anchor link).
+Example: \`{ type: "rich-paragraph", lines: [{ spans: [{ text: "Bold", fontWeight: 700 }, { text: " normal" }] }] }\`
+
+## table
+Data table with optional header rows, borders, and column alignment. Key props: \`columns\` (array of \`{width, align}\`; width can be pt number, \`"2*"\` fraction, or \`"auto"\`), \`rows\` (array of \`{cells, isHeader, bgColor}\`), \`headerBgColor\`, \`borderColor\`, \`borderWidth\`, \`cellPaddingH\`, \`cellPaddingV\`, \`spaceAfter\`.
+Cell props: \`text\`, \`fontWeight\`, \`color\`, \`bgColor\`, \`align\`, \`colSpan\`.
+Example: \`{ type: "table", columns: [{ width: "2*" }, { width: 100, align: "right" }], rows: [{ isHeader: true, cells: [{ text: "Name", fontWeight: 700 }, { text: "Amount", fontWeight: 700 }] }] }\`
+
+## list
+Bulleted or numbered list. Key props: \`style\` (unordered|ordered, required), \`items\` (array of \`{text, children}\`), \`fontSize\`, \`color\`, \`spaceAfter\`, \`indent\` (pt for nested lists).
+Example: \`{ type: "list", style: "unordered", items: [{ text: "Item one" }, { text: "Item two", children: [{ text: "Sub-item" }] }] }\`
+
+## image
+Embed PNG/JPG image. Key props: \`src\` (absolute file path or Uint8Array, required), \`width\` (pt, defaults to content width), \`height\` (optional, auto-scales), \`align\` (left|center|right), \`caption\`, \`spaceAfter\`.
+Example: \`{ type: "image", src: "/abs/path/to/logo.png", width: 120, align: "center" }\`
+
+## svg
+Inline SVG vector graphic. Key props: \`content\` (SVG markup string, required), \`width\` (pt), \`height\` (pt), \`align\`, \`spaceAfter\`.
+Example: \`{ type: "svg", content: "<svg viewBox='0 0 100 100'><circle cx='50' cy='50' r='40'/></svg>", width: 100, height: 100 }\`
+
+## code
+Monospace code block with optional syntax label. Key props: \`code\` (required), \`language\` (label only, no syntax highlighting), \`fontSize\`, \`bgColor\`, \`color\`, \`spaceAfter\`.
+Example: \`{ type: "code", language: "typescript", code: "const x = 42;", bgColor: "#f4f4f4" }\`
+
+## blockquote
+Indented quote with a left border. Key props: \`text\` (required), \`borderColor\` (#hex), \`color\`, \`fontSize\`, \`spaceAfter\`.
+Example: \`{ type: "blockquote", text: "The best code is no code at all.", borderColor: "#6366f1" }\`
+
+## callout
+Alert/info box with preset color schemes and optional title. Key props: \`content\` (body text, required), \`style\` (info|warning|tip|note — sets default colors), \`title\` (bold heading above body), \`borderColor\`, \`backgroundColor\`, \`color\`, \`fontSize\`, \`padding\`, \`spaceAfter\`.
+Example: \`{ type: "callout", style: "warning", content: "This action cannot be undone." }\`
+
+## toc
+Auto-generated Table of Contents. Place after cover, before content. Key props: \`title\` (heading text), \`showTitle\` (boolean), \`leader\` (dot fill char, e.g. "."), \`minLevel\` (1–4), \`maxLevel\` (1–4), \`fontSize\`, \`spaceAfter\`.
+Example: \`{ type: "toc", title: "Contents", showTitle: true, leader: ".", minLevel: 1, maxLevel: 2 }\`
+
+## form-field
+Interactive AcroForm field (text, checkbox, radio, dropdown, button). Key props: \`fieldType\` (required), \`name\` (unique, required), \`label\`, \`placeholder\`, \`defaultValue\`, \`multiline\`, \`options\` (for radio/dropdown), \`width\`, \`height\`, \`borderColor\`, \`spaceAfter\`.
+Example: \`{ type: "form-field", fieldType: "text", name: "full_name", label: "Full Name", placeholder: "Enter your name" }\`
+
+## comment
+Invisible sticky-note annotation (shows as icon in PDF viewer). Key props: \`contents\` (popup text, required), \`author\`, \`color\` (#hex), \`open\` (show popup by default).
+Example: \`{ type: "comment", contents: "Review this section.", author: "Jane" }\`
+
+## hr
+Horizontal rule / divider line. Key props: \`color\` (#hex), \`thickness\` (pt), \`spaceBelow\`.
+Example: \`{ type: "hr", color: "#cccccc", thickness: 1, spaceBelow: 8 }\`
+
+## spacer
+Vertical whitespace. Key props: \`height\` (pt, required).
+Example: \`{ type: "spacer", height: 24 }\`
+
+## page-break
+Force start of a new page. No additional props.
+Example: \`{ type: "page-break" }\`
+
+---
+
+## Document-level options (PdfDocument)
+- \`pageSize\`: 'A4'|'Letter'|'Legal'|'A3'|'A5' or \`[width, height]\` in pt. Default: 'A4'
+- \`margins\`: \`{ top, bottom, left, right }\` in pt. Default: all 72pt
+- \`defaultFont\`: font family name. Default: 'Inter'
+- \`defaultFontSize\`: pt. Default: 12
+- \`header\`: \`{ text, fontSize, align, color, fontFamily }\`. Supports \`{{pageNumber}}\` and \`{{totalPages}}\`
+- \`footer\`: same as header
+- \`watermark\`: \`{ text, opacity, rotation, fontSize, color }\`
+- \`encryption\`: \`{ userPassword, ownerPassword, permissions }\`
+- \`bookmarks\`: \`{ minLevel, maxLevel }\` or \`false\`
+- \`metadata\`: \`{ title, author, subject, keywords, language }\`
+- \`hyphenation\`: \`{ language: 'en-us' }\`
+`;
+export const listElementsTool = {
+    schema: {
+        name: 'list_element_types',
+        description: 'Returns a markdown reference of all pretext-pdf element types and their key properties. Use this before calling generate_pdf to understand what elements and options are available.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    handler: async (_args) => {
+        return {
+            content: [{ type: 'text', text: ELEMENTS_REFERENCE }],
+        };
+    },
+};

package/dist/utils/base64.js

@@ -0,0 +1,6 @@
+export function toBase64(bytes) {
+    return Buffer.from(bytes).toString('base64');
+}
+export function fromBase64(b64) {
+    return new Uint8Array(Buffer.from(b64, 'base64'));
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "pretext-pdf-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for pretext-pdf — generate professional PDFs from JSON in Claude, Cursor, or any AI agent",
+  "keywords": ["mcp", "pdf", "pdf-generation", "invoice", "report", "claude", "ai-agent", "pretext"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": { "pretext-pdf-mcp": "./dist/index.js" },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "tsx --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "pretext-pdf": "^0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "files": ["dist/**/*", "smithery.yaml", "README.md", "LICENSE"],
+  "engines": { "node": ">=18.0.0" },
+  "license": "MIT",
+  "author": "Himanshu Jain",
+  "repository": { "type": "git", "url": "https://github.com/Himaan1998Y/pretext-pdf-mcp" },
+  "homepage": "https://github.com/Himaan1998Y/pretext-pdf-mcp#readme"
+}

package/smithery.yaml

@@ -0,0 +1,7 @@
+name: pretext-pdf
+description: "Generate professional PDFs from structured JSON. Supports invoices (with GST), reports, tables, forms, encryption, and more. No headless browser — pure Node.js."
+version: "1.0.0"
+startCommand:
+  type: stdio
+  command: npx
+  args: ["-y", "pretext-pdf-mcp"]