autoform-mcp-server 1.3.0 → 1.5.0

package/dist/index.js

@@ -6,21 +6,25 @@ 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 { handleFillBatchAcroForm, fillBatchAcroFormSchema } from './tools/fillBatchAcroForm.js';
+import { handleAnalyzeStaticPdf, analyzeStaticPdfSchema } from './tools/analyzeStaticPdf.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: {} } });
+const server = new Server({ name: 'autoform', version: '1.5.0' }, { capabilities: { tools: {} } });
 // Register all tools
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         // Info & detection
         getPdfInfoSchema,
         detectFieldsSchema,
+        analyzeStaticPdfSchema,
         // Single fill
         fillPdfSchema,
         fillAtCoordinatesSchema,
-        // Batch fill
+        // Batch fill (preferred for multiple documents)
+        fillBatchAcroFormSchema,
         fillBatchAtCoordinatesSchema,
         generateBatchSchema,
         // Template management
@@ -38,12 +42,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return await handleGetPdfInfo(args);
             case 'autoform_detect_fields':
                 return await handleDetectFields(args);
+            case 'autoform_analyze_static_pdf':
+                return await handleAnalyzeStaticPdf(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_fill_batch_acroform':
+                return await handleFillBatchAcroForm(args);
             case 'autoform_save_coordinates_as_template':
                 return await handleSaveCoordinatesAsTemplate(args);
             case 'autoform_generate_batch':
@@ -66,4 +74,4 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 // Start server
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error('[AutoForm MCP] Server v1.2.0 started — 9 tools registered');
+console.error('[AutoForm MCP] Server v1.5.0 started — 11 tools registered');

package/dist/services/pdfService.d.ts

@@ -11,6 +11,16 @@ export declare class PdfService {
     }>;
     /** Fill AcroForm fields and save */
     static fillAcroForm(pdfPath: string, values: Record<string, string>, outputPath: string): Promise<number>;
+    /**
+     * Batch fill AcroForm: generate N PDFs from the same base PDF, one per data row.
+     * If merge=true, all outputs are concatenated into a single PDF and temp files are cleaned.
+     * Optionally accepts a fieldMap to translate logical data keys → technical AcroForm field names.
+     */
+    static batchFillAcroForm(pdfPath: string, dataRows: Array<Record<string, string>>, outputDir: string, baseName: string, merge?: boolean, fieldMap?: Record<string, string>): Promise<{
+        outputPaths: string[];
+        mergedPath?: string;
+        errors: string[];
+    }>;
     /** 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>;
     /**

package/dist/services/pdfService.js

@@ -98,6 +98,86 @@ export class PdfService {
         fs.writeFileSync(outputPath, savedBytes);
         return filled;
     }
+    /**
+     * Batch fill AcroForm: generate N PDFs from the same base PDF, one per data row.
+     * If merge=true, all outputs are concatenated into a single PDF and temp files are cleaned.
+     * Optionally accepts a fieldMap to translate logical data keys → technical AcroForm field names.
+     */
+    static async batchFillAcroForm(pdfPath, dataRows, outputDir, baseName, merge = false, fieldMap) {
+        const outputPaths = [];
+        const errors = [];
+        const timestamp = new Date().toISOString().slice(0, 10);
+        fs.mkdirSync(outputDir, { recursive: true });
+        const workingDir = merge
+            ? fs.mkdtempSync(path.join(outputDir, '.tmp_batch_'))
+            : outputDir;
+        // Load the base PDF once
+        const bytes = fs.readFileSync(pdfPath);
+        for (let i = 0; i < dataRows.length; i++) {
+            try {
+                const row = dataRows[i];
+                // Translate logical keys to technical field names if a map is provided
+                const resolvedValues = {};
+                for (const [key, value] of Object.entries(row)) {
+                    const technicalName = fieldMap?.[key] ?? key;
+                    resolvedValues[technicalName] = String(value ?? '');
+                }
+                const num = String(i + 1).padStart(3, '0');
+                const outPath = path.join(workingDir, `${baseName}_${num}_${timestamp}.pdf`);
+                // Re-load each iteration to get a fresh form instance
+                const pdfDoc = await PDFDocument.load(bytes);
+                const form = pdfDoc.getForm();
+                for (const [name, value] of Object.entries(resolvedValues)) {
+                    try {
+                        const field = form.getField(name);
+                        if (field instanceof PDFTextField) {
+                            field.setText(value);
+                        }
+                        else if (field instanceof PDFCheckBox) {
+                            if (['true', '1', 'yes', 'si', 'sí'].includes(value.toLowerCase()))
+                                field.check();
+                            else
+                                field.uncheck();
+                        }
+                        else if (field instanceof PDFDropdown) {
+                            field.select(value);
+                        }
+                        else if (field instanceof PDFRadioGroup) {
+                            field.select(value);
+                        }
+                    }
+                    catch {
+                        // Field not found — skip silently
+                    }
+                }
+                form.flatten();
+                const savedBytes = await pdfDoc.save();
+                fs.writeFileSync(outPath, savedBytes);
+                outputPaths.push(outPath);
+            }
+            catch (err) {
+                errors.push(`Fila ${i + 1}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        let mergedPath;
+        if (merge && outputPaths.length > 0) {
+            mergedPath = path.join(outputDir, `${baseName}_merged_${timestamp}.pdf`);
+            await this.mergePdfs(outputPaths, mergedPath);
+            // Clean up temp files and dir
+            for (const p of outputPaths) {
+                try {
+                    fs.unlinkSync(p);
+                }
+                catch { /* ignore */ }
+            }
+            try {
+                fs.rmdirSync(workingDir);
+            }
+            catch { /* ignore */ }
+            return { outputPaths: [], mergedPath, errors };
+        }
+        return { outputPaths, mergedPath, errors };
+    }
     /** Fill PDF using template coordinates (drawText), same logic as web app's pdfGenerator */
     static async fillWithTemplate(pdfPath, fields, values, outputPath) {
         const bytes = fs.readFileSync(pdfPath);

package/dist/services/pdfTextExtractor.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Position of a text element in PDF coordinates (origin: bottom-left).
+ */
+export interface TextItem {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fontSize: number;
+    page: number;
+}
+/**
+ * Horizontal line detected as a drawing operator.
+ */
+export interface HorizontalLine {
+    x: number;
+    y: number;
+    width: number;
+    page: number;
+}
+/**
+ * A page's extracted information.
+ */
+export interface PageTextInfo {
+    page: number;
+    width: number;
+    height: number;
+    textItems: TextItem[];
+    totalCharacters: number;
+}
+/**
+ * Classifies a PDF based on its extractable content.
+ */
+export type PdfContentType = 'acroform' | 'text_vectorial' | 'image_only' | 'mixed';
+/**
+ * Extracts text content from a PDF using pdfjs-dist in Node.js-compatible mode.
+ * No native dependencies, works entirely in pure JavaScript.
+ */
+export declare class PdfTextExtractor {
+    /** Extract all text items from all pages of a PDF */
+    static extractAllText(pdfPath: string): Promise<PageTextInfo[]>;
+    /**
+     * Classify a PDF based on extractable text density.
+     * Thresholds are empirical; can be tuned.
+     */
+    static classifyContent(pages: PageTextInfo[]): PdfContentType;
+    /**
+     * For a given point (x, y) on a page, find the text items within a certain distance.
+     * Distance is computed in PDF points (not pixels).
+     * Returns items sorted by distance (closest first).
+     */
+    static findNearbyText(pageInfo: PageTextInfo, targetX: number, targetY: number, maxDistance?: number): Array<TextItem & {
+        distance: number;
+        relativePosition: 'left' | 'right' | 'above' | 'below' | 'inside';
+    }>;
+    /**
+     * Find the most likely label for a field at a given position.
+     * Prefers text that:
+     * - Is to the LEFT of the field (same Y level, typical "Label: ___")
+     * - Is ABOVE the field (stacked layouts)
+     * - Ends with ':' (explicit label)
+     * - Is short (labels are usually 1-3 words)
+     */
+    static inferLabelForField(pageInfo: PageTextInfo, fieldX: number, fieldY: number, fieldWidth: number, fieldHeight: number): {
+        label: string | null;
+        confidence: 'high' | 'medium' | 'low';
+        nearbyText: string[];
+    };
+    /**
+     * Detect probable field locations in a static PDF (no AcroForm).
+     * Heuristics:
+     * 1. Text ending in ':' followed by horizontal space → likely label + input area
+     * 2. Text that looks like a label (short, ends with ':') positioned above a gap
+     */
+    static detectStaticFieldCandidates(pages: PageTextInfo[]): Array<{
+        page: number;
+        inferredLabel: string;
+        hintFromText: string;
+        suggestedX: number;
+        suggestedY: number;
+        suggestedWidth: number;
+        suggestedHeight: number;
+        confidence: 'high' | 'medium' | 'low';
+        reason: string;
+    }>;
+}

package/dist/services/pdfTextExtractor.js

@@ -0,0 +1,224 @@
+import * as fs from 'fs';
+// Use legacy build — works in Node without DOM/canvas
+// @ts-ignore — pdfjs-dist types are incomplete for this path
+import * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf.mjs';
+/**
+ * Extracts text content from a PDF using pdfjs-dist in Node.js-compatible mode.
+ * No native dependencies, works entirely in pure JavaScript.
+ */
+export class PdfTextExtractor {
+    /** Extract all text items from all pages of a PDF */
+    static async extractAllText(pdfPath) {
+        const bytes = fs.readFileSync(pdfPath);
+        const pdf = await pdfjsLib.getDocument({
+            data: new Uint8Array(bytes),
+            useSystemFonts: true,
+            // Silence pdfjs warnings on stderr when running in Node
+            verbosity: 0
+        }).promise;
+        const pages = [];
+        for (let pageNum = 1; pageNum <= pdf.numPages; pageNum++) {
+            const page = await pdf.getPage(pageNum);
+            const viewport = page.getViewport({ scale: 1 });
+            const textContent = await page.getTextContent();
+            const items = [];
+            let totalChars = 0;
+            for (const raw of textContent.items) {
+                const text = String(raw.str ?? '').trim();
+                if (text === '')
+                    continue;
+                // transform = [scaleX, skewX, skewY, scaleY, translateX, translateY]
+                const [, , , scaleY, tx, ty] = raw.transform;
+                const fontSize = Math.abs(scaleY);
+                // pdfjs gives us the baseline; approximate the bounding box
+                // Width is already computed by pdfjs; height ≈ fontSize
+                const width = Math.abs(raw.width ?? 0);
+                const height = Math.abs(raw.height ?? fontSize);
+                items.push({
+                    text,
+                    x: tx,
+                    y: ty, // already in PDF coordinate system (bottom-left origin)
+                    width,
+                    height,
+                    fontSize,
+                    page: pageNum
+                });
+                totalChars += text.length;
+            }
+            pages.push({
+                page: pageNum,
+                width: viewport.width,
+                height: viewport.height,
+                textItems: items,
+                totalCharacters: totalChars
+            });
+        }
+        return pages;
+    }
+    /**
+     * Classify a PDF based on extractable text density.
+     * Thresholds are empirical; can be tuned.
+     */
+    static classifyContent(pages) {
+        if (pages.length === 0)
+            return 'image_only';
+        const totalChars = pages.reduce((sum, p) => sum + p.totalCharacters, 0);
+        const totalItems = pages.reduce((sum, p) => sum + p.textItems.length, 0);
+        const avgCharsPerPage = totalChars / pages.length;
+        // Empty or near-empty: scanned image
+        if (totalChars < 10 || totalItems < 3)
+            return 'image_only';
+        // Low density: possibly mixed (image + some labels)
+        if (avgCharsPerPage < 50)
+            return 'mixed';
+        return 'text_vectorial';
+    }
+    /**
+     * For a given point (x, y) on a page, find the text items within a certain distance.
+     * Distance is computed in PDF points (not pixels).
+     * Returns items sorted by distance (closest first).
+     */
+    static findNearbyText(pageInfo, targetX, targetY, maxDistance = 100) {
+        const results = [];
+        for (const item of pageInfo.textItems) {
+            // Use the center of the text item
+            const itemCenterX = item.x + item.width / 2;
+            const itemCenterY = item.y + item.height / 2;
+            const dx = targetX - itemCenterX;
+            const dy = targetY - itemCenterY;
+            const distance = Math.sqrt(dx * dx + dy * dy);
+            if (distance > maxDistance)
+                continue;
+            // Determine relative position
+            let relativePosition;
+            const absDx = Math.abs(dx);
+            const absDy = Math.abs(dy);
+            if (absDx < item.width / 2 && absDy < item.height / 2) {
+                relativePosition = 'inside';
+            }
+            else if (absDx > absDy) {
+                relativePosition = dx > 0 ? 'left' : 'right';
+            }
+            else {
+                relativePosition = dy > 0 ? 'below' : 'above';
+            }
+            results.push({ ...item, distance, relativePosition });
+        }
+        return results.sort((a, b) => a.distance - b.distance);
+    }
+    /**
+     * Find the most likely label for a field at a given position.
+     * Prefers text that:
+     * - Is to the LEFT of the field (same Y level, typical "Label: ___")
+     * - Is ABOVE the field (stacked layouts)
+     * - Ends with ':' (explicit label)
+     * - Is short (labels are usually 1-3 words)
+     */
+    static inferLabelForField(pageInfo, fieldX, fieldY, fieldWidth, fieldHeight) {
+        // Target point: slightly to the LEFT of the field's center Y
+        const targetX = fieldX; // left edge of field
+        const targetY = fieldY + fieldHeight / 2;
+        const nearby = this.findNearbyText(pageInfo, targetX, targetY, 150);
+        if (nearby.length === 0) {
+            return { label: null, confidence: 'low', nearbyText: [] };
+        }
+        // Score each candidate
+        const scored = nearby.map(item => {
+            let score = 0;
+            // Prefer text to the LEFT
+            if (item.relativePosition === 'left')
+                score += 50;
+            // Secondary: above the field
+            else if (item.relativePosition === 'above')
+                score += 30;
+            // Penalize right/below/inside
+            else
+                score += 10;
+            // Closer is better (inversely proportional)
+            score += Math.max(0, 100 - item.distance);
+            // Ends with ':' → almost certainly a label
+            if (item.text.trim().endsWith(':'))
+                score += 40;
+            // Short text is more label-like (1-4 words)
+            const wordCount = item.text.trim().split(/\s+/).length;
+            if (wordCount >= 1 && wordCount <= 4)
+                score += 20;
+            else if (wordCount > 10)
+                score -= 20;
+            // Penalize very generic text
+            if (/^(página|page|de|the|and|or)$/i.test(item.text.trim()))
+                score -= 30;
+            return { item, score };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        const best = scored[0];
+        const cleanLabel = best.item.text.trim().replace(/:\s*$/, '');
+        // Confidence based on score
+        let confidence;
+        if (best.score >= 100)
+            confidence = 'high';
+        else if (best.score >= 60)
+            confidence = 'medium';
+        else
+            confidence = 'low';
+        // Return top 5 nearby text items for context
+        const nearbyText = scored.slice(0, 5).map(s => s.item.text.trim());
+        return { label: cleanLabel, confidence, nearbyText };
+    }
+    /**
+     * Detect probable field locations in a static PDF (no AcroForm).
+     * Heuristics:
+     * 1. Text ending in ':' followed by horizontal space → likely label + input area
+     * 2. Text that looks like a label (short, ends with ':') positioned above a gap
+     */
+    static detectStaticFieldCandidates(pages) {
+        const candidates = [];
+        for (const pageInfo of pages) {
+            // Find all "label-like" text items (end with ':' or are short and capitalized)
+            const labels = pageInfo.textItems.filter(item => {
+                const t = item.text.trim();
+                if (t.length === 0 || t.length > 40)
+                    return false;
+                return t.endsWith(':') || /^[A-ZÁÉÍÓÚÑ][\wáéíóúñ\s]*$/.test(t);
+            });
+            for (const label of labels) {
+                const labelText = label.text.trim().replace(/:\s*$/, '');
+                if (labelText.length < 2)
+                    continue;
+                // Assume the input goes to the RIGHT of the label
+                // (most common "Label: ___" pattern)
+                const fieldX = label.x + label.width + 5;
+                const fieldY = label.y;
+                const fieldWidth = Math.max(150, (pageInfo.width - fieldX - 20) * 0.4);
+                const fieldHeight = label.fontSize * 1.5;
+                // Only suggest if there's space to the right
+                if (fieldX + fieldWidth > pageInfo.width)
+                    continue;
+                // Check: is there text already occupying that space?
+                const occupied = pageInfo.textItems.some(other => {
+                    if (other === label)
+                        return false;
+                    const otherCenterX = other.x + other.width / 2;
+                    const otherCenterY = other.y + other.height / 2;
+                    return (otherCenterX >= fieldX &&
+                        otherCenterX <= fieldX + fieldWidth &&
+                        Math.abs(otherCenterY - (fieldY + fieldHeight / 2)) < fieldHeight);
+                });
+                if (occupied)
+                    continue;
+                candidates.push({
+                    page: pageInfo.page,
+                    inferredLabel: labelText,
+                    hintFromText: label.text.trim(),
+                    suggestedX: Math.round(fieldX),
+                    suggestedY: Math.round(fieldY),
+                    suggestedWidth: Math.round(fieldWidth),
+                    suggestedHeight: Math.round(fieldHeight),
+                    confidence: labelText.endsWith(':') ? 'high' : 'medium',
+                    reason: `Label text "${label.text.trim()}" detected at (${Math.round(label.x)}, ${Math.round(label.y)}); suggested input area to its right.`
+                });
+            }
+        }
+        return candidates;
+    }
+}

package/dist/tools/analyzeStaticPdf.d.ts

@@ -0,0 +1,27 @@
+export declare const analyzeStaticPdfSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            pdf_path: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleAnalyzeStaticPdf(args: any): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/tools/analyzeStaticPdf.js

@@ -0,0 +1,157 @@
+import { PdfTextExtractor } from '../services/pdfTextExtractor.js';
+export const analyzeStaticPdfSchema = {
+    name: 'autoform_analyze_static_pdf',
+    description: `Analiza un PDF estatico (sin AcroForm) para sugerir donde colocar los campos automaticamente. Extrae texto con posiciones y usa heuristicas para detectar labels y areas de input probables.
+
+CUANDO USAR:
+- El PDF no tiene AcroForm (autoform_detect_fields devolvio has_acroform=false).
+- Es un certificado, diploma, constancia, formulario diseñado en Canva/Word/Figma.
+- Quieres sugerencias automaticas de donde van los campos sin tener que calcular coordenadas visualmente.
+
+QUE DEVUELVE:
+- Clasificacion del PDF: "text_vectorial" (texto extraible), "mixed" (texto + imagenes), "image_only" (escaneado).
+- Para text_vectorial: "suggested_fields" con labels inferidos y coordenadas sugeridas.
+- Para image_only: "suggested_approaches" con opciones claras para el usuario (NO rechaza el PDF).
+- Texto completo con posiciones por pagina ("all_text_items").
+
+⚠️ CASO PDF-IMAGEN (pdf_type: "image_only"):
+Si recibes este tipo, NO intentes procesar el PDF con los otros tools. En su lugar, PRESENTA AL USUARIO las suggested_approaches de forma clara y amigable, y espera su eleccion. Las opciones tipicas son:
+1. Adjuntar el PDF al chat de Claude Desktop (Claude puede verlo visualmente)
+2. Usar la app web de AutoForm para definir campos manualmente
+3. Proporcionar coordenadas manualmente si ya las conoces
+
+⚠️ CASO text_vectorial:
+- suggested_fields son SUGERENCIAS heuristicas (asumen layout "Label: ___" a la derecha).
+- Para layouts atipicos (certificados con campo DEBAJO del label, diplomas con layout centrado, etc.) las sugerencias pueden estar en posiciones incorrectas.
+- USA all_text_items para ver TODOS los textos del PDF con sus posiciones exactas y razona sobre el layout real antes de decidir las coordenadas finales.
+- Los campos "CERTIFICADO", "Firma 1/2" que se detectan como sugerencias probablemente NO son campos editables — son etiquetas del certificado. Descarta sugerencias que claramente son texto decorativo.
+- Cuando no estes seguro, PREGUNTA al usuario donde va cada dato en lugar de adivinar.
+
+⚠️ CASO mixed:
+Hay algo de texto pero poca densidad. Puede haber campos que NO se detectaron automaticamente porque el label es una imagen. Usa suggested_fields como punto de partida pero verifica visualmente si faltan campos.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            pdf_path: {
+                type: 'string',
+                description: 'Ruta absoluta al PDF estatico a analizar'
+            }
+        },
+        required: ['pdf_path']
+    }
+};
+export async function handleAnalyzeStaticPdf(args) {
+    const { pdf_path } = args;
+    let pages;
+    try {
+        pages = await PdfTextExtractor.extractAllText(pdf_path);
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: true,
+                        message: `No se pudo leer el PDF: ${err instanceof Error ? err.message : String(err)}`
+                    }, null, 2)
+                }],
+            isError: true
+        };
+    }
+    if (pages.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: true,
+                        message: 'El PDF no contiene paginas procesables.'
+                    }, null, 2)
+                }],
+            isError: true
+        };
+    }
+    const contentType = PdfTextExtractor.classifyContent(pages);
+    // Case: image-only PDF — return actionable options, never reject
+    if (contentType === 'image_only') {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        pdf_type: 'image_only',
+                        pdf_info: {
+                            pages: pages.length,
+                            dimensions_pt: {
+                                width: Math.round(pages[0].width),
+                                height: Math.round(pages[0].height)
+                            }
+                        },
+                        reason: 'Este PDF no contiene texto vectorial extraible. Probablemente es una imagen escaneada, un PDF aplanado, o un diseño donde todos los textos fueron convertidos a curvas.',
+                        message_for_user: 'Este PDF es tipo imagen — no puedo extraer texto automaticamente para detectar los campos. Sin embargo, tenemos varias opciones para procesarlo. Elige la que prefieras:',
+                        suggested_approaches: [
+                            {
+                                id: 'attach_to_chat',
+                                title: 'Adjuntar el PDF directamente al chat',
+                                description: 'Arrastra el PDF al chat de Claude Desktop. Podre verlo visualmente como imagen y estimar las coordenadas de los campos con buena precision. Luego usaremos autoform_fill_at_coordinates o autoform_fill_batch_at_coordinates para llenar los datos.',
+                                effort: 'bajo',
+                                precision: 'media-alta',
+                                recommended: true
+                            },
+                            {
+                                id: 'web_app',
+                                title: 'Usar la app web de AutoForm',
+                                description: 'Abre la aplicacion web de AutoForm en tu navegador, carga el PDF, dibuja los campos visualmente donde correspondan, exporta como JSON y luego usa autoform_import_template aqui. Es la opcion mas precisa para PDFs complejos.',
+                                effort: 'medio',
+                                precision: 'alta'
+                            },
+                            {
+                                id: 'manual_coordinates',
+                                title: 'Proporcionar coordenadas manualmente',
+                                description: 'Si ya conoces las coordenadas exactas de los campos (por ejemplo porque trabajaste con el PDF antes), puedes pasarlas directamente a autoform_fill_at_coordinates o autoform_fill_batch_at_coordinates.',
+                                effort: 'alto',
+                                precision: 'exacta'
+                            }
+                        ],
+                        next_instruction: 'Presenta estas opciones al usuario de forma clara (no copies el JSON literal, reformulalo conversacionalmente). Espera su eleccion antes de continuar. NO intentes procesar el PDF con otros tools hasta tener instrucciones del usuario.'
+                    }, null, 2)
+                }]
+        };
+    }
+    // Case: text_vectorial or mixed — extract field candidates
+    const suggestedFields = PdfTextExtractor.detectStaticFieldCandidates(pages);
+    const allTextItems = pages.flatMap(p => p.textItems.map(item => ({
+        text: item.text,
+        page: item.page,
+        x: Math.round(item.x),
+        y: Math.round(item.y),
+        fontSize: Math.round(item.fontSize * 10) / 10
+    })));
+    const summary = suggestedFields.length > 0
+        ? `Se detectaron ${suggestedFields.length} campos candidatos automaticamente:\n${suggestedFields.map(f => `- "${f.inferredLabel}" en pag ${f.page}, pos (${f.suggestedX}, ${f.suggestedY}), ${f.suggestedWidth}x${f.suggestedHeight} [${f.confidence}]`).join('\n')}`
+        : 'No se detectaron campos candidatos automaticamente. El PDF tiene texto pero no hay patrones claros de "Label: ___" reconocibles.';
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    pdf_type: contentType,
+                    pdf_info: {
+                        pages: pages.length,
+                        dimensions_pt: pages.map(p => ({
+                            page: p.page,
+                            width: Math.round(p.width),
+                            height: Math.round(p.height)
+                        }))
+                    },
+                    total_text_items: allTextItems.length,
+                    suggested_fields: suggestedFields,
+                    all_text_items: allTextItems.slice(0, 100), // Limit to avoid huge responses
+                    text_items_truncated: allTextItems.length > 100,
+                    summary,
+                    guidance: contentType === 'mixed'
+                        ? 'El PDF tiene densidad baja de texto — puede tener elementos visuales (titulos como imagen, logos) que no se extraen. Usa los suggested_fields como punto de partida pero verifica si faltan campos.'
+                        : suggestedFields.length > 0
+                            ? 'Usa los suggested_fields directamente con autoform_fill_at_coordinates (un documento) o autoform_fill_batch_at_coordinates (multiples documentos).'
+                            : 'No hay campos obvios detectables. Pregunta al usuario donde quiere colocar los datos o pidele que abra el PDF en la app web de AutoForm.'
+                }, null, 2)
+            }]
+    };
+}

package/dist/tools/detectFields.js

@@ -1,11 +1,35 @@
 import { PdfService } from '../services/pdfService.js';
+import { PdfTextExtractor } from '../services/pdfTextExtractor.js';
 export const detectFieldsSchema = {
     name: 'autoform_detect_fields',
-    description: `Detecta campos de formulario AcroForm en un PDF interactivo (creado con Adobe Acrobat, LibreOffice, etc).
+    description: `Detecta campos de formulario AcroForm en un PDF interactivo Y correlaciona cada campo con su label visible extraido del texto del PDF.
 
-CUANDO USAR: El PDF es un formulario donde puedes hacer click y escribir. Si el PDF es una imagen/diseño estatico (certificado, diploma), esta tool dira "sin campos" — en ese caso usa autoform_get_pdf_info + analisis visual.
+CUANDO USAR:
+- El PDF es un formulario donde puedes hacer click y escribir (AcroForm).
+- Quieres saber que campos tiene + como se llaman visualmente.
 
-DESPUES DE DETECTAR: Usa autoform_fill_pdf para llenar los campos encontrados.`,
+QUE DEVUELVE:
+- Lista de campos AcroForm con nombre tecnico, tipo, pagina y coordenadas.
+- Para CADA campo, un "inferred_label" calculado automaticamente correlacionando la posicion del campo con el texto circundante del PDF.
+- "nearby_text": hasta 5 textos cercanos al campo, ordenados por relevancia.
+- "confidence": high/medium/low segun que tan claro es el label correlacionado.
+
+⚠️ COMO USAR EL RESULTADO:
+- Si confidence es "high": confia en inferred_label y usalo directamente.
+- Si confidence es "medium": el label es probable pero verifica con nearby_text si tiene sentido.
+- Si confidence es "low": NO asumas — pregunta al usuario o mira el PDF visualmente si es posible.
+- NUNCA inventes el significado de un campo por su posicion o numero.
+
+SI EL PDF NO TIENE ACROFORM: esta tool devolvera has_acroform=false. En ese caso usa autoform_analyze_static_pdf.
+
+FLUJO RECOMENDADO PARA UN DOCUMENTO:
+1. autoform_detect_fields → obtienes campos + inferred_labels
+2. Usa autoform_fill_pdf con field_values={nombre_tecnico: valor}
+   O usa autoform_fill_pdf con field_map si prefieres claves logicas
+
+FLUJO RECOMENDADO PARA MULTIPLES DOCUMENTOS:
+1. autoform_detect_fields → obtienes campos + inferred_labels
+2. Usa autoform_fill_batch_acroform con data_rows y field_map si las claves son logicas.`,
     inputSchema: {
         type: 'object',
         properties: {
@@ -20,21 +44,85 @@ DESPUES DE DETECTAR: Usa autoform_fill_pdf para llenar los campos encontrados.`,
 export async function handleDetectFields(args) {
     const { pdf_path } = args;
     const { fields, hasAcroform } = await PdfService.detectFields(pdf_path);
-    let summary;
-    if (fields.length === 0) {
-        summary = `El PDF "${pdf_path}" no contiene campos AcroForm.\n\nPara usar este PDF, defina los campos manualmente en la app web de AutoForm y exporte la plantilla como JSON. Luego impórtela con autoform_import_template.`;
+    // If no AcroForm, recommend the static analysis tool
+    if (!hasAcroform || fields.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        has_acroform: false,
+                        total_fields: 0,
+                        fields: [],
+                        message: `El PDF no contiene campos AcroForm interactivos. Use autoform_analyze_static_pdf para analizar PDFs estaticos (certificados, diplomas, formularios diseñados en Canva/Word).`,
+                        next_action: 'autoform_analyze_static_pdf'
+                    }, null, 2)
+                }]
+        };
+    }
+    // Extract text from the PDF to correlate with AcroForm fields
+    let pagesText;
+    try {
+        pagesText = await PdfTextExtractor.extractAllText(pdf_path);
+    }
+    catch (err) {
+        // If extraction fails, return fields without label inference
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        has_acroform: true,
+                        total_fields: fields.length,
+                        fields,
+                        text_extraction_error: err instanceof Error ? err.message : String(err),
+                        warning: 'No se pudo extraer texto del PDF para inferir labels. Los nombres tecnicos se devuelven sin correlacion visual.'
+                    }, null, 2)
+                }]
+        };
+    }
+    // Enrich each field with inferred label and nearby text
+    const enrichedFields = fields.map(field => {
+        const pageInfo = pagesText.find(p => p.page === field.page);
+        if (!pageInfo) {
+            return { ...field, inferred_label: null, confidence: 'low', nearby_text: [] };
+        }
+        const { label, confidence, nearbyText } = PdfTextExtractor.inferLabelForField(pageInfo, field.x, field.y, field.width, field.height);
+        return {
+            ...field,
+            inferred_label: label,
+            confidence,
+            nearby_text: nearbyText
+        };
+    });
+    // Build a summary that emphasizes inferred labels
+    const labelSummary = enrichedFields
+        .map(f => {
+        const labelDisplay = f.inferred_label
+            ? `"${f.inferred_label}" (${f.confidence})`
+            : '[sin label inferido]';
+        return `- ${f.name}: ${labelDisplay} — pag ${f.page}, pos (${Math.round(f.x)}, ${Math.round(f.y)}), ${Math.round(f.width)}x${Math.round(f.height)}`;
+    })
+        .join('\n');
+    const highConfidenceCount = enrichedFields.filter(f => f.confidence === 'high').length;
+    const lowConfidenceCount = enrichedFields.filter(f => f.confidence === 'low').length;
+    let guidance;
+    if (lowConfidenceCount === 0) {
+        guidance = 'Todos los campos tienen labels correlacionados con alta confianza. Puedes proceder a llenar usando los inferred_label directamente.';
+    }
+    else if (lowConfidenceCount < enrichedFields.length) {
+        guidance = `${highConfidenceCount} campos tienen labels claros, pero ${lowConfidenceCount} tienen baja confianza. Verifica los nearby_text antes de llenar.`;
     }
     else {
-        summary = `Encontrados ${fields.length} campos AcroForm:\n\n${fields.map(f => `- ${f.name} (${f.type}) — Pag ${f.page}, pos: ${Math.round(f.x)},${Math.round(f.y)} ${Math.round(f.width)}x${Math.round(f.height)}${f.value ? ` = "${f.value}"` : ''}`).join('\n')}`;
+        guidance = 'Los labels inferidos tienen baja confianza. Revisa el nearby_text de cada campo o pregunta al usuario que represente cada uno antes de llenar.';
     }
     return {
         content: [{
                 type: 'text',
                 text: JSON.stringify({
-                    has_acroform: hasAcroform,
+                    has_acroform: true,
                     total_fields: fields.length,
-                    fields,
-                    summary
+                    fields: enrichedFields,
+                    summary: labelSummary,
+                    guidance
                 }, null, 2)
             }]
     };

package/dist/tools/fillAtCoordinates.js

@@ -4,9 +4,11 @@ import { PdfService } from '../services/pdfService.js';
 const OUTPUT_DIR = path.join(os.homedir(), '.autoform-mcp', 'output');
 export const fillAtCoordinatesSchema = {
     name: 'autoform_fill_at_coordinates',
-    description: `Escribe texto en posiciones exactas de un PDF usando coordenadas en puntos PDF (origen: esquina inferior-izquierda).
+    description: `Escribe texto en posiciones exactas de UN PDF usando coordenadas en puntos PDF (origen: esquina inferior-izquierda).
 Ideal cuando Claude analiza visualmente un PDF y determina dónde colocar el texto.
 
+⚠️ ESTA TOOL ES PARA UN UNICO DOCUMENTO. Si necesitas generar multiples PDFs con los mismos campos pero datos diferentes, USA autoform_fill_batch_at_coordinates (mas eficiente, una sola llamada).
+
 IMPORTANTE — Codificación de texto:
 - El texto se pasa EXACTAMENTE como lo envías. NO simplifiques ni modifiques caracteres.
 - Acentos españoles (á é í ó ú ñ Ñ ü) están soportados completamente.

package/dist/tools/fillBatchAcroForm.d.ts

@@ -0,0 +1,52 @@
+export declare const fillBatchAcroFormSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            pdf_path: {
+                type: string;
+                description: string;
+            };
+            data_rows: {
+                type: string;
+                description: string;
+                items: {
+                    type: string;
+                    additionalProperties: {
+                        type: string;
+                    };
+                };
+            };
+            field_map: {
+                type: string;
+                description: string;
+                additionalProperties: {
+                    type: string;
+                };
+            };
+            merge_into_single: {
+                type: string;
+                description: string;
+            };
+            output_dir: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleFillBatchAcroForm(args: any): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/tools/fillBatchAcroForm.js

@@ -0,0 +1,96 @@
+import * as path from 'path';
+import * as os from 'os';
+import { PdfService } from '../services/pdfService.js';
+const OUTPUT_DIR = path.join(os.homedir(), '.autoform-mcp', 'output');
+export const fillBatchAcroFormSchema = {
+    name: 'autoform_fill_batch_acroform',
+    description: `Genera MULTIPLES PDFs a partir de un PDF con campos AcroForm (formulario interactivo) + array de datos. Una sola llamada genera N documentos.
+
+CUANDO USAR: El PDF base tiene campos AcroForm (detectados con autoform_detect_fields) y el usuario quiere llenarlos con datos de varias personas/filas. Escalable a cientos de documentos en una sola llamada.
+
+NO USAR SI: El PDF es estatico (sin AcroForm) → usa autoform_fill_batch_at_coordinates.
+NO USAR SI: Solo necesitas llenar UN documento → usa autoform_fill_pdf.
+
+IMPORTANTE sobre nombres de campos:
+- Los campos AcroForm tienen nombres TECNICOS (ej: "Text1", "fld_nombre", "field_001") que NO siempre coinciden con los labels visibles del PDF.
+- DESPUES de llamar autoform_detect_fields, DEBES MIRAR EL PDF VISUALMENTE para correlacionar cada campo tecnico con su label visible segun sus coordenadas.
+- Si las claves de tus data_rows NO coinciden con los nombres tecnicos, usa el parametro field_map para traducir: { "nombre_logico": "nombre_tecnico" }
+- Ejemplo: si el campo tecnico es "Text1" pero visualmente corresponde al label "Nombre:", pasa field_map={"nombre": "Text1"} y data_rows=[{"nombre": "Juan"}]
+
+MERGE: Si merge_into_single=true, se genera SOLO el PDF unificado (los individuales son temporales y se borran automaticamente).
+
+CODIFICACION: Los datos se escriben EXACTAMENTE como los envias. Acentos espanoles (a e i o u n N u con tildes) estan completamente soportados. NO simplifiques caracteres.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            pdf_path: {
+                type: 'string',
+                description: 'Ruta absoluta al PDF con AcroForm'
+            },
+            data_rows: {
+                type: 'array',
+                description: 'Array de objetos, cada objeto es un documento. Claves = nombre del campo (tecnico o logico si usas field_map), valores = texto a escribir.',
+                items: {
+                    type: 'object',
+                    additionalProperties: { type: 'string' }
+                }
+            },
+            field_map: {
+                type: 'object',
+                description: '(Opcional) Mapeo de nombres logicos a nombres tecnicos de AcroForm. Formato: {"nombre_logico": "nombre_tecnico"}. Usalo cuando las claves de data_rows son mas legibles que los nombres tecnicos reales del PDF.',
+                additionalProperties: { type: 'string' }
+            },
+            merge_into_single: {
+                type: 'boolean',
+                description: '(Opcional) Si true, une todos los PDFs en uno solo y elimina los individuales. Default: false.'
+            },
+            output_dir: {
+                type: 'string',
+                description: '(Opcional) Directorio de salida. Default: ~/.autoform-mcp/output/'
+            }
+        },
+        required: ['pdf_path', 'data_rows']
+    }
+};
+export async function handleFillBatchAcroForm(args) {
+    const { pdf_path, output_dir, merge_into_single = false } = args;
+    let data_rows = args.data_rows;
+    if (typeof data_rows === 'string') {
+        try {
+            data_rows = JSON.parse(data_rows);
+        }
+        catch { /* keep */ }
+    }
+    let field_map = args.field_map;
+    if (typeof field_map === 'string') {
+        try {
+            field_map = JSON.parse(field_map);
+        }
+        catch { /* keep */ }
+    }
+    if (!data_rows || !Array.isArray(data_rows) || data_rows.length === 0) {
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ error: true, message: 'data_rows es requerido (array de objetos con datos)' }, null, 2) }],
+            isError: true
+        };
+    }
+    const outDir = output_dir || OUTPUT_DIR;
+    const baseName = path.basename(pdf_path, '.pdf').replace(/[^a-zA-Z0-9_\-]/g, '_');
+    const result = await PdfService.batchFillAcroForm(pdf_path, data_rows, outDir, baseName, merge_into_single, field_map);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    documents_generated: merge_into_single ? data_rows.length - result.errors.length : result.outputPaths.length,
+                    output_paths: result.outputPaths,
+                    merged_path: result.mergedPath,
+                    errors: result.errors,
+                    message: result.mergedPath
+                        ? `Generados ${data_rows.length - result.errors.length} documentos unidos en: ${result.mergedPath}`
+                        : result.outputPaths.length > 0
+                            ? `Generados ${result.outputPaths.length} documentos en ${outDir}`
+                            : `Error: ${result.errors.join(', ')}`
+                }, null, 2)
+            }]
+    };
+}

package/dist/tools/fillPdf.js

@@ -5,11 +5,16 @@ import { TemplateStore } from '../services/templateStore.js';
 const OUTPUT_DIR = path.join(os.homedir(), '.autoform-mcp', 'output');
 export const fillPdfSchema = {
     name: 'autoform_fill_pdf',
-    description: `Llena UN PDF con valores. Detecta automaticamente si tiene AcroForm o usa un template guardado.
+    description: `Llena UN SOLO PDF con valores. Detecta automaticamente si tiene AcroForm o usa un template guardado.
 
-CUANDO USAR: Quieres llenar UN SOLO documento y ya tienes AcroForm o un template guardado.
-NO USAR SI: El PDF es estatico sin template → usa autoform_fill_at_coordinates.
-NO USAR SI: Quieres generar MULTIPLES documentos → usa autoform_generate_batch o autoform_fill_batch_at_coordinates.`,
+⚠️ ESTA TOOL ES PARA UN UNICO DOCUMENTO. Si necesitas generar 2 o mas documentos, USA UNA TOOL BATCH (mas eficiente, menos llamadas):
+  - PDF con AcroForm + multiples filas → autoform_fill_batch_acroform
+  - PDF estatico + multiples filas → autoform_fill_batch_at_coordinates
+  - Template guardado + multiples filas → autoform_generate_batch
+
+CUANDO USAR: Solo cuando el usuario pide llenar UN documento especifico.
+NO USAR PARA BATCH: Nunca llames esta tool en loop para generar multiples PDFs — usa las tools batch que existen para eso.
+NO USAR SI: El PDF es estatico sin template → usa autoform_fill_at_coordinates.`,
     inputSchema: {
         type: 'object',
         properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autoform-mcp-server",
-  "version": "1.3.0",
+  "version": "1.5.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",
@@ -41,10 +41,11 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "jszip": "^3.10.1",
-    "pdf-lib": "^1.17.1"
+    "pdf-lib": "^1.17.1",
+    "pdfjs-dist": "^4.10.38"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.2.2"
   }
-}
+}