@formepdf/mcp 0.5.0

package/README.md

@@ -0,0 +1,85 @@
+# @formepdf/mcp
+
+MCP server that lets AI tools generate PDFs. Add one line to your config, then ask Claude, Cursor, or Windsurf to generate invoices, receipts, reports, and more.
+
+## Setup
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "forme": {
+      "command": "npx",
+      "args": ["@formepdf/mcp"]
+    }
+  }
+}
+```
+
+Restart your AI tool. Done.
+
+## What you can say
+
+- "Generate an invoice for Acme Corp, 10 hours of consulting at $150/hour"
+- "Create a shipping label from Seattle to NYC, 3 lbs, fragile"
+- "Make a receipt for 2 lattes and a muffin"
+- "Write a business letter to Jane Smith about our partnership proposal"
+- "Create a custom PDF with a big centered title that says Hello World"
+
+The agent figures out the data shape from the tool schema. You don't need to know the template fields.
+
+## Tools
+
+### `list_templates`
+
+Returns all available templates with descriptions and field summaries.
+
+### `get_template_schema`
+
+Returns the full JSON Schema and example data for a specific template. This is how the agent knows what data to construct from your request.
+
+### `render_pdf`
+
+Renders a built-in template with data and writes the PDF to disk.
+
+```
+Input: { template: "invoice", data: { ... }, output: "invoice.pdf" }
+Output: PDF file at the specified path
+```
+
+### `render_custom_pdf`
+
+Renders arbitrary JSX to PDF. The agent writes Forme JSX on the fly, the server transpiles it with esbuild and renders it.
+
+```
+Input: { jsx: "<Document><Page>...</Page></Document>", output: "custom.pdf" }
+Output: PDF file at the specified path
+```
+
+## Built-in Templates
+
+| Template | Description |
+|----------|-------------|
+| `invoice` | Line items, tax, totals, company/customer info |
+| `receipt` | Payment confirmation, items, total, payment method |
+| `report` | Multi-section document with title, headings, body text |
+| `letter` | Business letter with letterhead, date, recipient, body |
+| `shipping-label` | From/to addresses, weight, 4x6 format |
+
+## How it works
+
+The MCP server runs locally. PDF rendering happens in-process via Forme's Rust/WASM engine. No network calls, no API keys, no browser. The agent calls the tool, gets a file path back.
+
+## Works with
+
+- Claude Code
+- Cursor
+- Windsurf
+- Any tool supporting the Model Context Protocol
+
+## Links
+
+- [Forme](https://github.com/formepdf/forme) -- PDF generation with JSX
+- [Docs](https://docs.formepdf.com)
+- [MCP Specification](https://modelcontextprotocol.io)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { listTemplates } from './tools/list-templates.js';
+import { getSchema } from './tools/get-schema.js';
+import { renderPdf } from './tools/render-pdf.js';
+import { renderCustom } from './tools/render-custom.js';
+const server = new McpServer({
+    name: 'forme',
+    version: '0.4.4',
+});
+// ── list_templates ──────────────────────────────────────────────────
+server.tool('list_templates', 'List available built-in PDF templates with descriptions and field summaries', {}, async () => {
+    const result = listTemplates();
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(result, null, 2),
+            }],
+    };
+});
+// ── get_template_schema ─────────────────────────────────────────────
+server.tool('get_template_schema', 'Get full JSON Schema and example data for a specific template', { template: z.string().describe('Template name (e.g. "invoice", "receipt", "report", "shipping-label", "letter")') }, async ({ template }) => {
+    try {
+        const result = getSchema(template);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [{
+                    type: 'text',
+                    text: err.message,
+                }],
+        };
+    }
+});
+// ── render_pdf ──────────────────────────────────────────────────────
+server.tool('render_pdf', 'Render a built-in template with data and write PDF to disk', {
+    template: z.string().describe('Template name (e.g. "invoice", "receipt", "report", "shipping-label", "letter")'),
+    data: z.record(z.unknown()).describe('Template data matching the template schema'),
+    output: z.string().optional().describe('Output file path (defaults to ./{template}.pdf)'),
+}, async ({ template, data, output }) => {
+    try {
+        const result = await renderPdf(template, data, output);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `PDF rendered successfully.\nPath: ${result.path}\nSize: ${(result.size / 1024).toFixed(1)} KB`,
+                }],
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [{
+                    type: 'text',
+                    text: `Failed to render PDF: ${err.message}`,
+                }],
+        };
+    }
+});
+// ── render_custom_pdf ───────────────────────────────────────────────
+server.tool('render_custom_pdf', 'Render arbitrary JSX to PDF. Use Forme components: Document, Page, View, Text, Image, Table, Row, Cell, Fixed, Svg, PageBreak, StyleSheet, Font', {
+    jsx: z.string().describe('JSX/TSX source code using Forme components (Document, Page, View, Text, etc.)'),
+    output: z.string().optional().describe('Output file path (defaults to ./custom.pdf)'),
+}, async ({ jsx, output }) => {
+    try {
+        const result = await renderCustom(jsx, output);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `PDF rendered successfully.\nPath: ${result.path}\nSize: ${(result.size / 1024).toFixed(1)} KB`,
+                }],
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [{
+                    type: 'text',
+                    text: `Failed to render custom PDF: ${err.message}`,
+                }],
+        };
+    }
+});
+// ── Start server ────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Forme MCP server running on stdio');
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/dist/schemas/invoice.d.ts

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+export declare const invoiceSchema: z.ZodObject<{
+    invoiceNumber: z.ZodString;
+    date: z.ZodString;
+    dueDate: z.ZodString;
+    taxRate: z.ZodNumber;
+    company: z.ZodObject<{
+        name: z.ZodString;
+        initials: z.ZodString;
+        address: z.ZodString;
+        cityStateZip: z.ZodString;
+        email: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        initials: string;
+        address: string;
+        cityStateZip: string;
+        email: string;
+    }, {
+        name: string;
+        initials: string;
+        address: string;
+        cityStateZip: string;
+        email: string;
+    }>;
+    billTo: z.ZodObject<{
+        name: z.ZodString;
+        company: z.ZodString;
+        address: z.ZodString;
+        cityStateZip: z.ZodString;
+        email: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        email: string;
+        company: string;
+    }, {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        email: string;
+        company: string;
+    }>;
+    shipTo: z.ZodObject<{
+        name: z.ZodString;
+        address: z.ZodString;
+        cityStateZip: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        address: string;
+        cityStateZip: string;
+    }, {
+        name: string;
+        address: string;
+        cityStateZip: string;
+    }>;
+    items: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        quantity: z.ZodNumber;
+        unitPrice: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        quantity: number;
+        unitPrice: number;
+    }, {
+        description: string;
+        quantity: number;
+        unitPrice: number;
+    }>, "many">;
+    paymentTerms: z.ZodString;
+    notes: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    invoiceNumber: string;
+    date: string;
+    dueDate: string;
+    taxRate: number;
+    company: {
+        name: string;
+        initials: string;
+        address: string;
+        cityStateZip: string;
+        email: string;
+    };
+    billTo: {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        email: string;
+        company: string;
+    };
+    shipTo: {
+        name: string;
+        address: string;
+        cityStateZip: string;
+    };
+    items: {
+        description: string;
+        quantity: number;
+        unitPrice: number;
+    }[];
+    paymentTerms: string;
+    notes?: string | undefined;
+}, {
+    invoiceNumber: string;
+    date: string;
+    dueDate: string;
+    taxRate: number;
+    company: {
+        name: string;
+        initials: string;
+        address: string;
+        cityStateZip: string;
+        email: string;
+    };
+    billTo: {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        email: string;
+        company: string;
+    };
+    shipTo: {
+        name: string;
+        address: string;
+        cityStateZip: string;
+    };
+    items: {
+        description: string;
+        quantity: number;
+        unitPrice: number;
+    }[];
+    paymentTerms: string;
+    notes?: string | undefined;
+}>;
+export type InvoiceData = z.infer<typeof invoiceSchema>;
+export declare const invoiceDescription = "Professional invoice with company header, billing/shipping addresses, itemized line items table, tax calculation, and payment terms.";
+export declare const invoiceFields: Record<string, string>;
+export declare const invoiceExample: InvoiceData;

package/dist/schemas/invoice.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+export const invoiceSchema = z.object({
+    invoiceNumber: z.string().describe('Invoice identifier, e.g. "INV-2026-0142"'),
+    date: z.string().describe('Invoice date, e.g. "February 10, 2026"'),
+    dueDate: z.string().describe('Payment due date'),
+    taxRate: z.number().describe('Tax rate as decimal, e.g. 0.08 for 8%'),
+    company: z.object({
+        name: z.string(),
+        initials: z.string().describe('1-3 letter initials for logo badge'),
+        address: z.string(),
+        cityStateZip: z.string(),
+        email: z.string(),
+    }).describe('Your company details'),
+    billTo: z.object({
+        name: z.string(),
+        company: z.string(),
+        address: z.string(),
+        cityStateZip: z.string(),
+        email: z.string(),
+    }).describe('Customer billing address'),
+    shipTo: z.object({
+        name: z.string(),
+        address: z.string(),
+        cityStateZip: z.string(),
+    }).describe('Shipping address'),
+    items: z.array(z.object({
+        description: z.string(),
+        quantity: z.number(),
+        unitPrice: z.number(),
+    })).describe('Line items'),
+    paymentTerms: z.string().describe('Payment terms paragraph'),
+    notes: z.string().optional().describe('Optional notes'),
+});
+export const invoiceDescription = 'Professional invoice with company header, billing/shipping addresses, itemized line items table, tax calculation, and payment terms.';
+export const invoiceFields = {
+    invoiceNumber: 'string - invoice identifier',
+    date: 'string - invoice date',
+    dueDate: 'string - payment due date',
+    taxRate: 'number - tax rate as decimal (e.g. 0.08)',
+    company: 'object - your company name, initials, address, email',
+    billTo: 'object - customer name, company, address, email',
+    shipTo: 'object - shipping name, address',
+    items: 'array - line items with description, quantity, unitPrice',
+    paymentTerms: 'string - payment terms text',
+    notes: 'string? - optional notes',
+};
+export const invoiceExample = {
+    invoiceNumber: 'INV-2026-0142',
+    date: 'February 10, 2026',
+    dueDate: 'March 12, 2026',
+    taxRate: 0.08,
+    company: {
+        name: 'Northwind Design Co.',
+        initials: 'ND',
+        address: '1847 Lakewood Boulevard, Suite 300',
+        cityStateZip: 'Portland, OR 97205',
+        email: 'billing@northwinddesign.co',
+    },
+    billTo: {
+        name: 'Sarah Chen',
+        company: 'Meridian Architecture Group',
+        address: '520 Market Street, Floor 14',
+        cityStateZip: 'San Francisco, CA 94105',
+        email: 'sarah.chen@meridianarch.com',
+    },
+    shipTo: {
+        name: 'Meridian Architecture Group',
+        address: '520 Market Street, Floor 14',
+        cityStateZip: 'San Francisco, CA 94105',
+    },
+    items: [
+        { description: 'Brand Identity Package - logo design, color palette, typography system', quantity: 1, unitPrice: 4500.00 },
+        { description: 'Website Design - homepage, about, services, contact (desktop + mobile)', quantity: 1, unitPrice: 6200.00 },
+        { description: 'Business Card Design - front and back, print-ready files', quantity: 1, unitPrice: 350.00 },
+        { description: 'Social Media Templates - Instagram, LinkedIn, Twitter (12 templates)', quantity: 12, unitPrice: 125.00 },
+        { description: 'Brand Guidelines Document - 24-page PDF with usage rules', quantity: 1, unitPrice: 1800.00 },
+    ],
+    paymentTerms: 'Net 30. Payment due within 30 days of invoice date. A late fee of 1.5% per month will be applied to overdue balances.',
+    notes: 'Thank you for choosing Northwind Design.',
+};

package/dist/schemas/letter.d.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+export declare const letterSchema: z.ZodObject<{
+    sender: z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        company: z.ZodString;
+        address: z.ZodString;
+        cityStateZip: z.ZodString;
+        phone: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        company: string;
+        email?: string | undefined;
+        title?: string | undefined;
+        phone?: string | undefined;
+    }, {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        company: string;
+        email?: string | undefined;
+        title?: string | undefined;
+        phone?: string | undefined;
+    }>;
+    date: z.ZodString;
+    recipient: z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        company: z.ZodOptional<z.ZodString>;
+        address: z.ZodString;
+        cityStateZip: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        company?: string | undefined;
+        title?: string | undefined;
+    }, {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        company?: string | undefined;
+        title?: string | undefined;
+    }>;
+    salutation: z.ZodString;
+    body: z.ZodArray<z.ZodString, "many">;
+    closing: z.ZodString;
+    signatureName: z.ZodString;
+    signatureTitle: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    date: string;
+    sender: {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        company: string;
+        email?: string | undefined;
+        title?: string | undefined;
+        phone?: string | undefined;
+    };
+    recipient: {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        company?: string | undefined;
+        title?: string | undefined;
+    };
+    salutation: string;
+    body: string[];
+    closing: string;
+    signatureName: string;
+    signatureTitle?: string | undefined;
+}, {
+    date: string;
+    sender: {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        company: string;
+        email?: string | undefined;
+        title?: string | undefined;
+        phone?: string | undefined;
+    };
+    recipient: {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        company?: string | undefined;
+        title?: string | undefined;
+    };
+    salutation: string;
+    body: string[];
+    closing: string;
+    signatureName: string;
+    signatureTitle?: string | undefined;
+}>;
+export type LetterData = z.infer<typeof letterSchema>;
+export declare const letterDescription = "Formal business letter with letterhead, recipient address, body paragraphs, and closing signature.";
+export declare const letterFields: Record<string, string>;
+export declare const letterExample: LetterData;

package/dist/schemas/letter.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+export const letterSchema = z.object({
+    sender: z.object({
+        name: z.string(),
+        title: z.string().optional(),
+        company: z.string(),
+        address: z.string(),
+        cityStateZip: z.string(),
+        phone: z.string().optional(),
+        email: z.string().optional(),
+    }).describe('Sender/letterhead details'),
+    date: z.string().describe('Letter date'),
+    recipient: z.object({
+        name: z.string(),
+        title: z.string().optional(),
+        company: z.string().optional(),
+        address: z.string(),
+        cityStateZip: z.string(),
+    }).describe('Recipient address'),
+    salutation: z.string().describe('Greeting, e.g. "Dear Ms. Chen,"'),
+    body: z.array(z.string()).describe('Body paragraphs'),
+    closing: z.string().describe('Closing phrase, e.g. "Sincerely,"'),
+    signatureName: z.string().describe('Printed name under signature'),
+    signatureTitle: z.string().optional().describe('Title under signature'),
+});
+export const letterDescription = 'Formal business letter with letterhead, recipient address, body paragraphs, and closing signature.';
+export const letterFields = {
+    sender: 'object - name, title?, company, address, cityStateZip, phone?, email?',
+    date: 'string - letter date',
+    recipient: 'object - name, title?, company?, address, cityStateZip',
+    salutation: 'string - greeting line',
+    body: 'array - body paragraphs as strings',
+    closing: 'string - closing phrase',
+    signatureName: 'string - printed name',
+    signatureTitle: 'string? - title under name',
+};
+export const letterExample = {
+    sender: {
+        name: 'James Mitchell',
+        title: 'Director of Partnerships',
+        company: 'Northwind Design Co.',
+        address: '1847 Lakewood Boulevard, Suite 300',
+        cityStateZip: 'Portland, OR 97205',
+        phone: '(503) 555-0147',
+        email: 'james.mitchell@northwinddesign.co',
+    },
+    date: 'February 24, 2026',
+    recipient: {
+        name: 'Sarah Chen',
+        title: 'VP of Operations',
+        company: 'Meridian Architecture Group',
+        address: '520 Market Street, Floor 14',
+        cityStateZip: 'San Francisco, CA 94105',
+    },
+    salutation: 'Dear Ms. Chen,',
+    body: [
+        'Thank you for our productive meeting last Thursday to discuss the upcoming Meridian rebrand initiative. We are excited about the opportunity to partner with your team on this project.',
+        'As discussed, our proposal includes a comprehensive brand identity package, website redesign, and full suite of marketing collateral. The enclosed statement of work outlines the project timeline, deliverables, and investment summary for your review.',
+        'We believe our experience with architectural and design firms positions us uniquely to capture the essence of Meridian\'s vision. Our team is prepared to begin discovery sessions as early as next month.',
+        'Please don\'t hesitate to reach out if you have any questions. We look forward to hearing from you.',
+    ],
+    closing: 'Sincerely,',
+    signatureName: 'James Mitchell',
+    signatureTitle: 'Director of Partnerships',
+};

package/dist/schemas/receipt.d.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+export declare const receiptSchema: z.ZodObject<{
+    receiptNumber: z.ZodString;
+    date: z.ZodString;
+    taxRate: z.ZodNumber;
+    store: z.ZodObject<{
+        name: z.ZodString;
+        address: z.ZodString;
+        cityStateZip: z.ZodString;
+        phone: z.ZodString;
+        website: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        phone: string;
+        website: string;
+    }, {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        phone: string;
+        website: string;
+    }>;
+    items: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        price: z.ZodNumber;
+        quantity: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        price: number;
+        quantity?: number | undefined;
+    }, {
+        name: string;
+        price: number;
+        quantity?: number | undefined;
+    }>, "many">;
+    paymentMethod: z.ZodString;
+    cardLastFour: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    date: string;
+    taxRate: number;
+    items: {
+        name: string;
+        price: number;
+        quantity?: number | undefined;
+    }[];
+    receiptNumber: string;
+    store: {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        phone: string;
+        website: string;
+    };
+    paymentMethod: string;
+    cardLastFour?: string | undefined;
+}, {
+    date: string;
+    taxRate: number;
+    items: {
+        name: string;
+        price: number;
+        quantity?: number | undefined;
+    }[];
+    receiptNumber: string;
+    store: {
+        name: string;
+        address: string;
+        cityStateZip: string;
+        phone: string;
+        website: string;
+    };
+    paymentMethod: string;
+    cardLastFour?: string | undefined;
+}>;
+export type ReceiptData = z.infer<typeof receiptSchema>;
+export declare const receiptDescription = "Simple retail receipt with store header, itemized purchases, tax calculation, and payment method.";
+export declare const receiptFields: Record<string, string>;
+export declare const receiptExample: ReceiptData;