autoform-mcp-server 1.2.0

package/dist/tools/generateBatch.js

@@ -0,0 +1,106 @@
+import { TemplateStore } from '../services/templateStore.js';
+import { BatchGenerator } from '../services/batchGenerator.js';
+export const generateBatchSchema = {
+    name: 'autoform_generate_batch',
+    description: `Genera MULTIPLES PDFs usando un TEMPLATE GUARDADO + datos.
+
+CUANDO USAR: Ya tienes un template guardado (via autoform_import_template o autoform_save_coordinates_as_template) y quieres generar muchos documentos.
+NO USAR SI: No tienes template guardado → usa autoform_fill_batch_at_coordinates (no requiere template).
+
+DATOS: Pasa los datos como array de objetos JSON en el parametro "data". Si el usuario tiene un archivo (Excel, CSV, etc.), leelo primero y convierte a JSON.
+
+Modos de distribucion:
+- "sequential": campos repetidos consumen filas diferentes (para tablas/listas)
+- "repeat": una fila se repite en todos los campos con el mismo nombre (para certificados)`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            template_name: {
+                type: 'string',
+                description: 'Nombre del template guardado a usar'
+            },
+            data: {
+                type: 'array',
+                description: 'Datos como array de objetos. Ejemplo: [{"nombre": "Juan", "dni": "123"}, {"nombre": "Maria", "dni": "456"}]',
+                items: {
+                    type: 'object',
+                    additionalProperties: { type: 'string' }
+                }
+            },
+            distribution_mode: {
+                type: 'string',
+                enum: ['sequential', 'repeat'],
+                description: 'Modo de distribucion: "sequential" o "repeat". Default: sequential.'
+            },
+            merge_into_single: {
+                type: 'boolean',
+                description: 'Si es true, une todos los PDFs en uno solo. Default: false.'
+            }
+        },
+        required: ['template_name', 'data']
+    }
+};
+export async function handleGenerateBatch(args) {
+    const { template_name, distribution_mode = 'sequential', merge_into_single = false } = args;
+    // data puede llegar como string JSON o como array
+    let data = args.data;
+    if (typeof data === 'string') {
+        try {
+            data = JSON.parse(data);
+        }
+        catch { /* keep */ }
+    }
+    if (!data || !Array.isArray(data) || data.length === 0) {
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ error: true, message: 'Proporcione "data" como array de objetos. Si tiene un archivo, lealo primero y convierta a JSON.' }, null, 2) }],
+            isError: true
+        };
+    }
+    // Load template
+    const template = TemplateStore.load(template_name);
+    if (!template) {
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ error: true, message: `Template "${template_name}" no encontrado. Use autoform_list_templates para ver los disponibles.` }, null, 2) }],
+            isError: true
+        };
+    }
+    // Convert to ParsedData
+    const parsedData = data.map((row) => {
+        const p = {};
+        for (const [k, v] of Object.entries(row)) {
+            if (v === null || v === undefined || v === '')
+                p[k] = null;
+            else {
+                const num = Number(v);
+                p[k] = !isNaN(num) && isFinite(num) ? num : String(v);
+            }
+        }
+        return p;
+    });
+    // Validate columns match
+    const requiredCols = template.analysis.requiredColumns;
+    const providedCols = Object.keys(parsedData[0] || {});
+    const missing = requiredCols.filter((c) => !providedCols.includes(c));
+    if (missing.length > 0) {
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ error: true, message: `Columnas faltantes: ${missing.join(', ')}. El template requiere: ${requiredCols.join(', ')}. Los datos tienen: ${providedCols.join(', ')}` }, null, 2) }],
+            isError: true
+        };
+    }
+    // Generate
+    const result = await BatchGenerator.generate(template, parsedData, distribution_mode, merge_into_single);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    documents_generated: result.documentsGenerated,
+                    output_paths: result.outputPaths,
+                    merged_path: result.mergedPath,
+                    errors: result.errors,
+                    message: result.documentsGenerated > 0
+                        ? `Generados ${result.documentsGenerated} documentos.${result.mergedPath ? ` PDF unificado: ${result.mergedPath}` : ''}`
+                        : `Error: ${result.errors.join(', ')}`
+                }, null, 2)
+            }]
+    };
+}

package/dist/tools/importTemplate.d.ts

@@ -0,0 +1,20 @@
+export declare const importTemplateSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            json_file_path: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleImportTemplate(args: any): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/importTemplate.js

@@ -0,0 +1,36 @@
+import { TemplateStore } from '../services/templateStore.js';
+export const importTemplateSchema = {
+    name: 'autoform_import_template',
+    description: `Importa una plantilla JSON exportada desde la app web de AutoForm.
+
+CUANDO USAR: El usuario creo la plantilla visualmente en la app web y exporto el JSON. Este JSON contiene el PDF en base64 + coordenadas de campos.
+ALTERNATIVA: Si no usas la app web, usa autoform_save_coordinates_as_template para crear templates directamente desde Claude.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            json_file_path: {
+                type: 'string',
+                description: 'Ruta absoluta al archivo JSON exportado desde la app web de AutoForm'
+            }
+        },
+        required: ['json_file_path']
+    }
+};
+export async function handleImportTemplate(args) {
+    const { json_file_path } = args;
+    const template = TemplateStore.importFromWebApp(json_file_path);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    success: true,
+                    template_name: template.name,
+                    fields_count: template.fields.length,
+                    pages: template.pdfInfo.pageCount,
+                    required_columns: template.analysis.requiredColumns,
+                    pdf_saved_at: template.pdfPath,
+                    message: `Template "${template.name}" importado exitosamente. ${template.fields.length} campos en ${template.pdfInfo.pageCount} pagina(s). Columnas requeridas: ${template.analysis.requiredColumns.join(', ')}`
+                }, null, 2)
+            }]
+    };
+}

package/dist/tools/manageTemplates.d.ts

@@ -0,0 +1,15 @@
+export declare const listTemplatesSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {};
+        required: never[];
+    };
+};
+export declare function handleListTemplates(): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/manageTemplates.js

@@ -0,0 +1,44 @@
+import { TemplateStore } from '../services/templateStore.js';
+export const listTemplatesSchema = {
+    name: 'autoform_list_templates',
+    description: `Lista las plantillas guardadas en AutoForm. Muestra nombre, campos requeridos, paginas y fecha.
+
+CUANDO USAR: Antes de autoform_generate_batch para verificar que el template existe y ver sus columnas requeridas.`,
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: []
+    }
+};
+export async function handleListTemplates() {
+    const templates = TemplateStore.list();
+    if (templates.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        total: 0,
+                        templates: [],
+                        message: 'No hay plantillas guardadas. Importe una con autoform_import_template o cree una desde la app web de AutoForm.'
+                    }, null, 2)
+                }]
+        };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    total: templates.length,
+                    templates: templates.map(t => ({
+                        name: t.name,
+                        description: t.description,
+                        pages: t.pageCount,
+                        fields: t.fieldCount,
+                        required_columns: t.requiredColumns,
+                        created: t.createdAt
+                    })),
+                    message: `${templates.length} plantilla(s) disponibles.`
+                }, null, 2)
+            }]
+    };
+}

package/dist/tools/saveCoordinatesAsTemplate.d.ts

@@ -0,0 +1,78 @@
+export declare const saveCoordinatesAsTemplateSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            pdf_path: {
+                type: string;
+                description: string;
+            };
+            template_name: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            fields: {
+                type: string;
+                description: string;
+                items: {
+                    type: string;
+                    properties: {
+                        label: {
+                            type: string;
+                            description: string;
+                        };
+                        page: {
+                            type: string;
+                            description: string;
+                        };
+                        x: {
+                            type: string;
+                            description: string;
+                        };
+                        y: {
+                            type: string;
+                            description: string;
+                        };
+                        width: {
+                            type: string;
+                            description: string;
+                        };
+                        height: {
+                            type: string;
+                            description: string;
+                        };
+                        fontSize: {
+                            type: string;
+                            description: string;
+                        };
+                        overflowMode: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleSaveCoordinatesAsTemplate(args: any): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/tools/saveCoordinatesAsTemplate.js

@@ -0,0 +1,141 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { PDFDocument } from 'pdf-lib';
+import { TemplateStore } from '../services/templateStore.js';
+export const saveCoordinatesAsTemplateSchema = {
+    name: 'autoform_save_coordinates_as_template',
+    description: `Guarda un PDF + coordenadas de campos como plantilla reutilizable.
+
+CUANDO USAR: Despues de que Claude analizo visualmente un PDF y determino las coordenadas de los campos. Guardar como template permite reutilizar esas posiciones con autoform_generate_batch sin recalcular cada vez.
+
+FLUJO TIPICO:
+1. Claude analiza el PDF visualmente + autoform_get_pdf_info
+2. Determina coordenadas de campos
+3. Llama esta tool para guardar como template
+4. Futuras generaciones usan autoform_generate_batch con el template guardado`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            pdf_path: {
+                type: 'string',
+                description: 'Ruta absoluta al PDF base'
+            },
+            template_name: {
+                type: 'string',
+                description: 'Nombre para la plantilla (ej: "certificado_seminario")'
+            },
+            description: {
+                type: 'string',
+                description: '(Opcional) Descripcion de la plantilla'
+            },
+            fields: {
+                type: 'array',
+                description: 'Campos con sus coordenadas en puntos PDF. El "label" se convierte en el nombre de columna requerido.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        label: { type: 'string', description: 'Nombre del campo (sera el nombre de la columna en el Excel/datos)' },
+                        page: { type: 'number', description: 'Pagina (1-indexed)' },
+                        x: { type: 'number', description: 'X en puntos desde la izquierda' },
+                        y: { type: 'number', description: 'Y en puntos desde abajo (origen PDF)' },
+                        width: { type: 'number', description: 'Ancho en puntos' },
+                        height: { type: 'number', description: 'Alto en puntos' },
+                        fontSize: { type: 'number', description: '(Opcional) Tamaño de fuente deseado' },
+                        overflowMode: { type: 'string', enum: ['shrink', 'wrap'], description: '(Opcional) Default: shrink' }
+                    },
+                    required: ['label', 'page', 'x', 'y', 'width', 'height']
+                }
+            }
+        },
+        required: ['pdf_path', 'template_name', 'fields']
+    }
+};
+export async function handleSaveCoordinatesAsTemplate(args) {
+    const { pdf_path, template_name, description = '' } = args;
+    let fields = args.fields;
+    if (typeof fields === 'string') {
+        try {
+            fields = JSON.parse(fields);
+        }
+        catch { /* keep */ }
+    }
+    if (!fields || !Array.isArray(fields) || fields.length === 0) {
+        return { content: [{ type: 'text', text: JSON.stringify({ error: true, message: 'fields es requerido' }, null, 2) }], isError: true };
+    }
+    // Read PDF to get page info
+    const pdfBytes = fs.readFileSync(pdf_path);
+    const pdfDoc = await PDFDocument.load(pdfBytes, { ignoreEncryption: true });
+    const pageCount = pdfDoc.getPageCount();
+    const pageSize = pdfDoc.getPage(0).getSize();
+    // Copy PDF to templates directory
+    const TEMPLATES_DIR = path.resolve(import.meta.dirname, '../../templates');
+    fs.mkdirSync(TEMPLATES_DIR, { recursive: true });
+    const safeName = template_name.replace(/[^a-zA-Z0-9_\-]/g, '_');
+    const pdfDest = path.join(TEMPLATES_DIR, `${safeName}.pdf`);
+    fs.copyFileSync(pdf_path, pdfDest);
+    // Convert coordinate-based fields to FieldBox format (percentage-based for web app compatibility)
+    const fieldBoxes = fields.map((f, i) => ({
+        id: `field_${Date.now()}_${i}`,
+        // Convert points to percentages relative to page size
+        x: (f.x / pageSize.width) * 100,
+        y: ((pageSize.height - f.y - f.height) / pageSize.height) * 100, // Flip Y (PDF bottom-left → top-left)
+        width: (f.width / pageSize.width) * 100,
+        height: (f.height / pageSize.height) * 100,
+        pageNumber: f.page,
+        name: `Campo_${i + 1}`,
+        fieldName: f.label,
+        fieldType: 'text',
+        fontSize: f.fontSize,
+        overflowMode: f.overflowMode
+    }));
+    // Build analysis
+    const groups = {};
+    for (const f of fieldBoxes) {
+        if (!groups[f.fieldName])
+            groups[f.fieldName] = { fieldName: f.fieldName, count: 0, fields: [], pageDistribution: {} };
+        groups[f.fieldName].count++;
+        groups[f.fieldName].fields.push(f);
+        groups[f.fieldName].pageDistribution[f.pageNumber] = (groups[f.fieldName].pageDistribution[f.pageNumber] || 0) + 1;
+    }
+    const fieldGroups = Object.values(groups);
+    const counts = fieldGroups.map((g) => g.count);
+    const template = {
+        id: `template_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`,
+        name: template_name,
+        description,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        version: '1.0.0',
+        pdfPath: pdfDest,
+        pdfInfo: {
+            name: path.basename(pdf_path),
+            size: pdfBytes.length,
+            pageCount
+        },
+        fields: fieldBoxes,
+        analysis: {
+            totalFields: fieldBoxes.length,
+            fieldGroups,
+            documentCapacity: fieldBoxes.length,
+            maxFieldCount: Math.max(...counts, 0),
+            minFieldCount: Math.min(...counts, 0),
+            requiredColumns: fieldGroups.map((g) => g.fieldName),
+            isBalanced: new Set(counts).size <= 1
+        },
+        metadata: { totalUsages: 0 }
+    };
+    TemplateStore.save(template);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    success: true,
+                    template_name: template.name,
+                    fields_count: fieldBoxes.length,
+                    required_columns: template.analysis.requiredColumns,
+                    pages: pageCount,
+                    message: `Template "${template_name}" guardado con ${fieldBoxes.length} campo(s). Columnas: ${template.analysis.requiredColumns.join(', ')}. Ahora puede usar autoform_generate_batch con template_name="${template_name}" para generacion masiva.`
+                }, null, 2)
+            }]
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+export interface FieldBox {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    pageNumber: number;
+    name: string;
+    fieldName: string;
+    fieldType?: string;
+    fontSize?: number;
+    overflowMode?: 'shrink' | 'wrap';
+}
+export interface FieldGroup {
+    fieldName: string;
+    count: number;
+    fields: FieldBox[];
+    pageDistribution: {
+        [pageNumber: number]: number;
+    };
+}
+export interface TemplateAnalysis {
+    totalFields: number;
+    fieldGroups: FieldGroup[];
+    documentCapacity: number;
+    maxFieldCount: number;
+    minFieldCount: number;
+    requiredColumns: string[];
+    isBalanced: boolean;
+}
+export interface SavedTemplate {
+    id: string;
+    name: string;
+    description: string;
+    createdAt: string;
+    updatedAt: string;
+    version: string;
+    pdfPath: string;
+    pdfInfo: {
+        name: string;
+        size: number;
+        pageCount: number;
+        dataUrl?: string;
+    };
+    fields: FieldBox[];
+    analysis: TemplateAnalysis;
+    metadata: {
+        totalUsages: number;
+        lastUsedAt?: string;
+        tags?: string[];
+    };
+}
+export interface TemplatePreview {
+    name: string;
+    description: string;
+    createdAt: string;
+    fieldCount: number;
+    pageCount: number;
+    requiredColumns: string[];
+}
+export interface DetectedField {
+    name: string;
+    type: string;
+    page: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    value?: string;
+}
+export interface ParsedData {
+    [columnName: string]: string | number | null;
+}
+export type DistributionMode = 'sequential' | 'repeat';
+export interface FieldDataMapping {
+    fieldId: string;
+    fieldName: string;
+    fieldIndex: number;
+    pageNumber: number;
+    dataValue: any;
+    dataRowIndex: number;
+    isEmpty: boolean;
+}
+export interface DataChunk {
+    chunkNumber: number;
+    fieldsMapping: FieldDataMapping[];
+    isComplete: boolean;
+}
+export interface GenerationResult {
+    documentsGenerated: number;
+    outputPaths: string[];
+    mergedPath?: string;
+    errors: string[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Types for the MCP server — mirrors relevant types from the web app
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "autoform-mcp-server",
+  "version": "1.2.0",
+  "description": "MCP server for bulk PDF form filling. Detect fields, fill templates, and generate hundreds of PDFs from data — directly from Claude.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "autoform-mcp-server": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "claude",
+    "pdf",
+    "pdf-fill",
+    "form-filling",
+    "bulk-pdf",
+    "autoform",
+    "template",
+    "certificate-generator"
+  ],
+  "author": "YeferAndersson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YeferAndersson/auto-form"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "templates/.gitkeep",
+    "output/.gitkeep",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "jszip": "^3.10.1",
+    "pdf-lib": "^1.17.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.2.2"
+  }
+}