autoform-mcp-server 1.2.0

package/README.md

@@ -0,0 +1,135 @@
+# AutoForm MCP Server
+
+MCP server for bulk PDF form filling. Detect fields, fill templates, and generate hundreds of PDFs from data — directly from Claude.
+
+## Quick Setup
+
+### Claude Code
+
+Create `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "autoform": {
+      "command": "npx",
+      "args": ["-y", "autoform-mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "autoform": {
+      "command": "npx",
+      "args": ["-y", "autoform-mcp-server"]
+    }
+  }
+}
+```
+
+Config file location:
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+## Tools (9)
+
+### PDF Analysis
+| Tool | Description |
+|------|-------------|
+| `autoform_get_pdf_info` | Get page count and dimensions of a PDF |
+| `autoform_detect_fields` | Detect AcroForm fields in interactive PDFs |
+
+### Fill Single PDF
+| Tool | Description |
+|------|-------------|
+| `autoform_fill_pdf` | Fill a PDF using AcroForm or a saved template |
+| `autoform_fill_at_coordinates` | Write text at exact coordinates (for static PDFs Claude analyzes visually) |
+
+### Batch Generation
+| Tool | Description |
+|------|-------------|
+| `autoform_fill_batch_at_coordinates` | Generate multiple PDFs from one template + data, using coordinates |
+| `autoform_generate_batch` | Generate multiple PDFs using a saved template + data array |
+
+### Template Management
+| Tool | Description |
+|------|-------------|
+| `autoform_save_coordinates_as_template` | Save PDF + field coordinates as a reusable template |
+| `autoform_import_template` | Import a template JSON exported from the AutoForm web app |
+| `autoform_list_templates` | List all saved templates |
+
+## Usage Examples
+
+### Fill a certificate (Claude analyzes the PDF visually)
+
+```
+You: "Fill this certificate with the name Juan Pérez"
+
+Claude:
+1. Gets PDF dimensions with autoform_get_pdf_info
+2. Analyzes the PDF visually to find where the name goes
+3. Calls autoform_fill_at_coordinates with the exact position
+→ Generates filled certificate
+```
+
+### Batch generate from data
+
+```
+You: "Generate certificates for: Ana García, Pedro López, María Torres"
+
+Claude:
+1. Calls autoform_fill_batch_at_coordinates with positions + data
+→ Generates 3 PDFs + optional merged PDF
+```
+
+### Save and reuse a template
+
+```
+You: "Save this certificate layout for future use"
+
+Claude:
+1. Calls autoform_save_coordinates_as_template
+→ Template saved
+
+You: "Generate 50 certificates using the saved template with this data..."
+
+Claude:
+1. Calls autoform_generate_batch with template name + data
+→ Generates 50 PDFs
+```
+
+### Fill interactive PDF forms (AcroForm)
+
+```
+You: "Detect and fill the fields in this form"
+
+Claude:
+1. Calls autoform_detect_fields → finds form fields
+2. Calls autoform_fill_pdf with field values
+→ Generates filled form
+```
+
+## Distribution Modes
+
+When a template has repeated fields (e.g., 3 fields named "nombre"):
+
+- **`sequential`** (default): Each field consumes a different data row. 9 rows + 3 fields = 3 documents.
+- **`repeat`**: One row fills ALL fields with the same name. 9 rows = 9 documents.
+
+## How It Works
+
+- Templates and generated PDFs are stored locally in the MCP server directory
+- Uses `pdf-lib` for PDF manipulation (no external services)
+- All processing happens locally — no data leaves your machine
+- Zero vulnerabilities — only 3 dependencies
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,69 @@
+#!/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 { handleDetectFields, detectFieldsSchema } from './tools/detectFields.js';
+import { handleFillPdf, fillPdfSchema } from './tools/fillPdf.js';
+import { handleFillAtCoordinates, fillAtCoordinatesSchema, handleGetPdfInfo, getPdfInfoSchema } from './tools/fillAtCoordinates.js';
+import { handleFillBatchAtCoordinates, fillBatchAtCoordinatesSchema } from './tools/fillBatchAtCoordinates.js';
+import { handleSaveCoordinatesAsTemplate, saveCoordinatesAsTemplateSchema } from './tools/saveCoordinatesAsTemplate.js';
+import { handleGenerateBatch, generateBatchSchema } from './tools/generateBatch.js';
+import { handleListTemplates, listTemplatesSchema } from './tools/manageTemplates.js';
+import { handleImportTemplate, importTemplateSchema } from './tools/importTemplate.js';
+const server = new Server({ name: 'autoform', version: '1.2.0' }, { capabilities: { tools: {} } });
+// Register all tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        // Info & detection
+        getPdfInfoSchema,
+        detectFieldsSchema,
+        // Single fill
+        fillPdfSchema,
+        fillAtCoordinatesSchema,
+        // Batch fill
+        fillBatchAtCoordinatesSchema,
+        generateBatchSchema,
+        // Template management
+        saveCoordinatesAsTemplateSchema,
+        listTemplatesSchema,
+        importTemplateSchema
+    ]
+}));
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case 'autoform_get_pdf_info':
+                return await handleGetPdfInfo(args);
+            case 'autoform_detect_fields':
+                return await handleDetectFields(args);
+            case 'autoform_fill_pdf':
+                return await handleFillPdf(args);
+            case 'autoform_fill_at_coordinates':
+                return await handleFillAtCoordinates(args);
+            case 'autoform_fill_batch_at_coordinates':
+                return await handleFillBatchAtCoordinates(args);
+            case 'autoform_save_coordinates_as_template':
+                return await handleSaveCoordinatesAsTemplate(args);
+            case 'autoform_generate_batch':
+                return await handleGenerateBatch(args);
+            case 'autoform_list_templates':
+                return await handleListTemplates();
+            case 'autoform_import_template':
+                return await handleImportTemplate(args);
+            default:
+                return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+        }
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+            isError: true
+        };
+    }
+});
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('[AutoForm MCP] Server v1.2.0 started — 9 tools registered');

package/dist/services/batchGenerator.d.ts

@@ -0,0 +1,10 @@
+import { SavedTemplate, ParsedData, DistributionMode, GenerationResult } from '../types.js';
+/**
+ * Batch PDF generation with distribution logic.
+ * Adapts web app's distributionEngine + pdfGenerator for Node.js.
+ */
+export declare class BatchGenerator {
+    static generate(template: SavedTemplate, data: ParsedData[], mode?: DistributionMode, mergeIntoSingle?: boolean): Promise<GenerationResult>;
+    private static calculateDocumentsNeeded;
+    private static createMappings;
+}

package/dist/services/batchGenerator.js

@@ -0,0 +1,105 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { PdfService } from './pdfService.js';
+const OUTPUT_DIR = path.resolve(import.meta.dirname, '../../output');
+/**
+ * Batch PDF generation with distribution logic.
+ * Adapts web app's distributionEngine + pdfGenerator for Node.js.
+ */
+export class BatchGenerator {
+    static async generate(template, data, mode = 'sequential', mergeIntoSingle = false) {
+        fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+        const timestamp = new Date().toISOString().slice(0, 10);
+        const safeName = template.name.replace(/[^a-zA-Z0-9_\-]/g, '_');
+        // Read base PDF
+        const pdfBytes = fs.readFileSync(template.pdfPath);
+        const basePdf = new Uint8Array(pdfBytes);
+        // Calculate distribution
+        const documentsNeeded = this.calculateDocumentsNeeded(data, template, mode);
+        if (documentsNeeded === 0) {
+            return { documentsGenerated: 0, outputPaths: [], errors: ['No hay datos para generar documentos'] };
+        }
+        const outputPaths = [];
+        const errors = [];
+        for (let docNum = 0; docNum < documentsNeeded; docNum++) {
+            try {
+                const mappings = this.createMappings(data, template, docNum, mode);
+                const docNumStr = String(docNum + 1).padStart(3, '0');
+                const outputPath = path.join(OUTPUT_DIR, `${safeName}_${docNumStr}_${timestamp}.pdf`);
+                await PdfService.generateSingleDocument(basePdf, mappings, outputPath);
+                outputPaths.push(outputPath);
+            }
+            catch (err) {
+                errors.push(`Doc ${docNum + 1}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Merge if requested
+        let mergedPath;
+        if (mergeIntoSingle && outputPaths.length > 0) {
+            mergedPath = path.join(OUTPUT_DIR, `${safeName}_merged_${timestamp}.pdf`);
+            await PdfService.mergePdfs(outputPaths, mergedPath);
+        }
+        return {
+            documentsGenerated: outputPaths.length,
+            outputPaths,
+            mergedPath,
+            errors
+        };
+    }
+    static calculateDocumentsNeeded(data, template, mode) {
+        if (data.length === 0 || template.analysis.fieldGroups.length === 0)
+            return 0;
+        if (mode === 'repeat')
+            return data.length;
+        // Sequential: each field with the same name consumes a different row
+        return Math.max(...template.analysis.fieldGroups.map(group => {
+            const values = data.map(row => row[group.fieldName]).filter(v => v !== null && v !== undefined);
+            return Math.ceil(values.length / group.count);
+        }));
+    }
+    static createMappings(data, template, docNum, mode) {
+        const mappings = [];
+        // Group fields by name, sorted by page then Y
+        const fieldsByName = {};
+        for (const f of template.fields) {
+            const name = f.fieldName || f.name;
+            if (!fieldsByName[name])
+                fieldsByName[name] = [];
+            fieldsByName[name].push(f);
+        }
+        for (const group of Object.values(fieldsByName)) {
+            group.sort((a, b) => a.pageNumber !== b.pageNumber ? a.pageNumber - b.pageNumber : a.y - b.y);
+        }
+        if (mode === 'repeat') {
+            // All fields with the same name get the SAME value from one row
+            const row = data[docNum];
+            if (!row)
+                return mappings;
+            for (const [fieldName, fields] of Object.entries(fieldsByName)) {
+                const value = row[fieldName];
+                for (const field of fields) {
+                    mappings.push({ field, value });
+                }
+            }
+        }
+        else {
+            // Sequential: each field consumes a different row
+            const columnArrays = {};
+            for (const group of template.analysis.fieldGroups) {
+                columnArrays[group.fieldName] = data.map(r => r[group.fieldName]).filter(v => v !== null && v !== undefined);
+            }
+            for (const group of template.analysis.fieldGroups) {
+                const fields = fieldsByName[group.fieldName] || [];
+                const colArr = columnArrays[group.fieldName] || [];
+                for (let fi = 0; fi < fields.length; fi++) {
+                    const arrIdx = docNum * group.count + fi;
+                    mappings.push({
+                        field: fields[fi],
+                        value: arrIdx < colArr.length ? colArr[arrIdx] : null
+                    });
+                }
+            }
+        }
+        return mappings;
+    }
+}

package/dist/services/pdfService.d.ts

@@ -0,0 +1,65 @@
+import { DetectedField, FieldBox } from '../types.js';
+/**
+ * PDF field detection and filling service.
+ * Uses pdf-lib's AcroForm API for detection + drawText for template-based filling.
+ */
+export declare class PdfService {
+    /** Detect AcroForm fields in a PDF */
+    static detectFields(pdfPath: string): Promise<{
+        fields: DetectedField[];
+        hasAcroform: boolean;
+    }>;
+    /** Fill AcroForm fields and save */
+    static fillAcroForm(pdfPath: string, values: Record<string, string>, outputPath: string): Promise<number>;
+    /** Fill PDF using template coordinates (drawText), same logic as web app's pdfGenerator */
+    static fillWithTemplate(pdfPath: string, fields: FieldBox[], values: Record<string, string>, outputPath: string): Promise<number>;
+    /**
+     * Fill PDF at exact coordinates (points, PDF native system — origin bottom-left).
+     * Designed for Claude to pass positions it determined visually.
+     */
+    static fillAtCoordinates(pdfPath: string, fields: Array<{
+        text: string;
+        page: number;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        fontSize?: number;
+        overflowMode?: 'shrink' | 'wrap';
+    }>, outputPath: string): Promise<number>;
+    /**
+     * Batch fill: generates multiple PDFs from the same template with different data sets.
+     * Each entry in `dataRows` produces one PDF using the same field positions.
+     */
+    static batchFillAtCoordinates(pdfPath: string, fieldDefinitions: Array<{
+        label: string;
+        page: number;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        fontSize?: number;
+        overflowMode?: 'shrink' | 'wrap';
+    }>, dataRows: Array<Record<string, string>>, outputDir: string, baseName: string, merge?: boolean): Promise<{
+        outputPaths: string[];
+        mergedPath?: string;
+        errors: string[];
+    }>;
+    /** Get PDF page dimensions (useful for Claude to calculate coordinates) */
+    static getPageDimensions(pdfPath: string): Promise<Array<{
+        page: number;
+        width: number;
+        height: number;
+    }>>;
+    /** Generate a single document with field mappings (for batch generation) */
+    static generateSingleDocument(basePdfBytes: Uint8Array, mappings: {
+        field: FieldBox;
+        value: any;
+    }[], outputPath: string): Promise<void>;
+    /** Merge multiple PDFs into one */
+    static mergePdfs(pdfPaths: string[], outputPath: string): Promise<void>;
+    private static drawFieldText;
+    private static sanitize;
+    private static optimalFontSize;
+    private static wrapText;
+}