ocr-provenance-mcp 1.0.0

package/dist/tools/form-fill.js

@@ -0,0 +1,250 @@
+/**
+ * Form Fill MCP Tools
+ *
+ * Tools for filling forms using Datalab API.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ * Use console.error() for all logging.
+ *
+ * @module tools/form-fill
+ */
+import { z } from 'zod';
+import { v4 as uuidv4 } from 'uuid';
+import { formatResponse, handleError, fetchProvenanceChain, } from './shared.js';
+import { validateInput, sanitizePath } from '../utils/validation.js';
+import { requireDatabase } from '../server/state.js';
+import { successResult } from '../server/types.js';
+import { FormFillClient } from '../services/ocr/form-fill.js';
+import { ProvenanceType } from '../models/provenance.js';
+import { computeHash } from '../utils/hash.js';
+/**
+ * Safely parse JSON from stored form fill data. Returns fallback on corrupt data
+ * instead of crashing the entire tool handler.
+ */
+function safeJsonParse(json, fallback) {
+    if (!json)
+        return fallback;
+    try {
+        return JSON.parse(json);
+    }
+    catch (err) {
+        console.error(`[form-fill] Failed to parse stored JSON: ${err instanceof Error ? err.message : String(err)}`);
+        return fallback;
+    }
+}
+const FormFillInput = z.object({
+    file_path: z.string().min(1).describe('Path to form file (PDF or image)'),
+    field_data: z
+        .record(z.object({
+        value: z.string(),
+        description: z.string().optional(),
+    }))
+        .describe('Field names mapped to values and descriptions'),
+    context: z.string().optional().describe('Additional context for field matching'),
+    confidence_threshold: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0.5)
+        .describe('Confidence threshold (0-1)'),
+    page_range: z.string().optional().describe('Page range, 0-indexed'),
+    output_path: z.string().optional().describe('Path to save filled form PDF'),
+});
+const FormFillStatusInput = z.object({
+    form_fill_id: z.string().optional().describe('Specific form fill ID to retrieve'),
+    status_filter: z.enum(['pending', 'processing', 'complete', 'failed', 'all']).default('all'),
+    search_query: z
+        .string()
+        .optional()
+        .describe('Search form fills by field values, file path (LIKE match)'),
+    limit: z.number().int().min(1).max(100).default(50),
+    offset: z.number().int().min(0).default(0).describe('Offset for pagination'),
+    include_provenance: z
+        .boolean()
+        .default(false)
+        .describe('Include provenance chain when retrieving a specific form fill'),
+});
+async function handleFormFill(params) {
+    try {
+        const input = validateInput(FormFillInput, params);
+        const { db } = requireDatabase();
+        const client = new FormFillClient();
+        const safeFilePath = sanitizePath(input.file_path);
+        const result = await client.fillForm(safeFilePath, {
+            fieldData: input.field_data,
+            context: input.context,
+            confidenceThreshold: input.confidence_threshold,
+            pageRange: input.page_range,
+        });
+        // Save PDF to disk if output_path provided and we have output
+        if (input.output_path && result.outputBase64) {
+            const { writeFileSync, mkdirSync } = await import('fs');
+            const { dirname: dirPath } = await import('path');
+            const safeOutputPath = sanitizePath(input.output_path);
+            mkdirSync(dirPath(safeOutputPath), { recursive: true });
+            writeFileSync(safeOutputPath, Buffer.from(result.outputBase64, 'base64'));
+            console.error(`[INFO] Saved filled form to ${safeOutputPath}`);
+        }
+        // Create provenance record
+        const provId = uuidv4();
+        const now = new Date().toISOString();
+        const contentHash = computeHash(JSON.stringify({
+            fields_filled: result.fieldsFilled,
+            fields_not_found: result.fieldsNotFound,
+        }));
+        db.insertProvenance({
+            id: provId,
+            type: ProvenanceType.FORM_FILL,
+            created_at: now,
+            processed_at: now,
+            source_file_created_at: null,
+            source_file_modified_at: null,
+            source_type: 'FORM_FILL',
+            source_path: input.file_path,
+            source_id: null,
+            root_document_id: provId, // Self-referencing for standalone form fills
+            location: null,
+            content_hash: contentHash,
+            input_hash: result.sourceFileHash,
+            file_hash: result.sourceFileHash,
+            processor: 'datalab-form-fill',
+            processor_version: '1.0.0',
+            processing_params: {
+                field_count: Object.keys(input.field_data).length,
+                confidence_threshold: input.confidence_threshold,
+                has_context: !!input.context,
+            },
+            processing_duration_ms: result.processingDurationMs,
+            processing_quality_score: null,
+            parent_id: null,
+            parent_ids: JSON.stringify([]),
+            chain_depth: 0,
+            chain_path: JSON.stringify(['FORM_FILL']),
+        });
+        // Store in database
+        db.insertFormFill({
+            id: result.id,
+            source_file_path: result.sourceFilePath,
+            source_file_hash: result.sourceFileHash,
+            field_data_json: JSON.stringify(input.field_data),
+            context: input.context ?? null,
+            confidence_threshold: input.confidence_threshold ?? 0.5,
+            output_file_path: input.output_path ?? null,
+            output_base64: result.outputBase64,
+            fields_filled: JSON.stringify(result.fieldsFilled),
+            fields_not_found: JSON.stringify(result.fieldsNotFound),
+            page_count: result.pageCount,
+            cost_cents: result.costCents,
+            status: result.status,
+            error_message: result.error,
+            provenance_id: provId,
+            created_at: now,
+        });
+        const response = {
+            id: result.id,
+            status: result.status,
+            fields_filled: result.fieldsFilled,
+            fields_not_found: result.fieldsNotFound,
+            page_count: result.pageCount,
+            cost_cents: result.costCents,
+            output_saved: !!input.output_path,
+            provenance_id: provId,
+            processing_duration_ms: result.processingDurationMs,
+        };
+        return formatResponse(successResult({
+            ...response,
+            next_steps: [{ tool: 'ocr_form_fill_status', description: 'Check the form fill result' }],
+        }));
+    }
+    catch (error) {
+        return handleError(error);
+    }
+}
+async function handleFormFillStatus(params) {
+    try {
+        const input = validateInput(FormFillStatusInput, params);
+        const { db } = requireDatabase();
+        if (input.form_fill_id) {
+            const formFill = db.getFormFill(input.form_fill_id);
+            if (!formFill) {
+                throw new Error(`Form fill not found: ${input.form_fill_id}`);
+            }
+            const formFillResponse = {
+                form_fill: {
+                    ...formFill,
+                    // Parse JSON strings for display (safe parse handles corrupt stored data)
+                    fields_filled: safeJsonParse(formFill.fields_filled, []),
+                    fields_not_found: safeJsonParse(formFill.fields_not_found, []),
+                    field_data: safeJsonParse(formFill.field_data_json, {}),
+                    // Don't include base64 in status response
+                    output_base64: formFill.output_base64 ? '[base64 data available]' : null,
+                },
+            };
+            if (input.include_provenance) {
+                formFillResponse.provenance_chain = fetchProvenanceChain(db, formFill.provenance_id, 'form-fill');
+            }
+            return formatResponse(successResult({
+                ...formFillResponse,
+                next_steps: [{ tool: 'ocr_form_fill', description: 'Submit another form fill operation' }, { tool: 'ocr_document_get', description: 'View the source document' }],
+            }));
+        }
+        // If search_query is provided, use search instead of list
+        if (input.search_query) {
+            const searchResults = db.searchFormFills(input.search_query, {
+                limit: input.limit,
+                offset: input.offset,
+            });
+            return formatResponse(successResult({
+                total: searchResults.length,
+                search_query: input.search_query,
+                form_fills: searchResults.map((ff) => ({
+                    id: ff.id,
+                    source_file_path: ff.source_file_path,
+                    status: ff.status,
+                    fields_filled: safeJsonParse(ff.fields_filled, []).length,
+                    fields_not_found: safeJsonParse(ff.fields_not_found, []).length,
+                    cost_cents: ff.cost_cents,
+                    created_at: ff.created_at,
+                    error_message: ff.error_message,
+                })),
+                next_steps: [{ tool: 'ocr_form_fill', description: 'Submit another form fill operation' }, { tool: 'ocr_document_get', description: 'View the source document' }],
+            }));
+        }
+        const statusFilter = input.status_filter === 'all' ? undefined : input.status_filter;
+        const formFills = db.listFormFills({
+            status: statusFilter,
+            limit: input.limit,
+            offset: input.offset,
+        });
+        return formatResponse(successResult({
+            total: formFills.length,
+            form_fills: formFills.map((ff) => ({
+                id: ff.id,
+                source_file_path: ff.source_file_path,
+                status: ff.status,
+                fields_filled: safeJsonParse(ff.fields_filled, []).length,
+                fields_not_found: safeJsonParse(ff.fields_not_found, []).length,
+                cost_cents: ff.cost_cents,
+                created_at: ff.created_at,
+                error_message: ff.error_message,
+            })),
+            next_steps: [{ tool: 'ocr_form_fill', description: 'Submit another form fill operation' }, { tool: 'ocr_document_get', description: 'View the source document' }],
+        }));
+    }
+    catch (error) {
+        return handleError(error);
+    }
+}
+export const formFillTools = {
+    ocr_form_fill: {
+        description: '[PROCESSING] Extract/fill key-value form fields via Datalab API. For forms, invoices, applications. Use ocr_extract_structured for page-schema extraction instead.',
+        inputSchema: FormFillInput.shape,
+        handler: handleFormFill,
+    },
+    ocr_form_fill_status: {
+        description: '[STATUS] Use to check status or retrieve details of past form fill operations. Returns form fill records with field data and status. Use after ocr_form_fill.',
+        inputSchema: FormFillStatusInput.shape,
+        handler: handleFormFillStatus,
+    },
+};
+//# sourceMappingURL=form-fill.js.map

package/dist/tools/form-fill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-fill.js","sourceRoot":"","sources":["../../src/tools/form-fill.ts"],"names":[],"mappings":"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"}

package/dist/tools/health.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Health Check MCP Tools
+ *
+ * Tools: ocr_health_check
+ *
+ * Detects data integrity gaps and optionally triggers fixes.
+ * Internal-only - no external API calls needed.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ * Use console.error() for all logging.
+ *
+ * @module tools/health
+ */
+import { type ToolDefinition } from './shared.js';
+/**
+ * Health check tools collection for MCP server registration
+ */
+export declare const healthTools: Record<string, ToolDefinition>;
+//# sourceMappingURL=health.d.ts.map

package/dist/tools/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/tools/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,EAAkD,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AA4PlG;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAOtD,CAAC"}

package/dist/tools/health.js

@@ -0,0 +1,229 @@
+/**
+ * Health Check MCP Tools
+ *
+ * Tools: ocr_health_check
+ *
+ * Detects data integrity gaps and optionally triggers fixes.
+ * Internal-only - no external API calls needed.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ * Use console.error() for all logging.
+ *
+ * @module tools/health
+ */
+import { z } from 'zod';
+import { requireDatabase } from '../server/state.js';
+import { successResult } from '../server/types.js';
+import { validateInput } from '../utils/validation.js';
+import { formatResponse, handleError } from './shared.js';
+// ═══════════════════════════════════════════════════════════════════════════════
+// INPUT SCHEMAS
+// ═══════════════════════════════════════════════════════════════════════════════
+const HealthCheckInput = z.object({
+    fix: z.boolean().default(false)
+        .describe('If true, trigger processing for fixable gaps (chunks without embeddings). Other gaps are reported but need manual intervention via specific tools.'),
+});
+// ═══════════════════════════════════════════════════════════════════════════════
+// HANDLER: ocr_health_check
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Handle ocr_health_check - Detect and optionally fix data integrity gaps
+ *
+ * Checks for:
+ * 1. Chunks without embeddings (fixable via embedding generation)
+ * 2. Documents without OCR results (non-pending status)
+ * 3. Images without VLM descriptions
+ * 4. Embeddings without vectors in vec_embeddings
+ * 5. Orphaned provenance records
+ */
+async function handleHealthCheck(params) {
+    try {
+        const input = validateInput(HealthCheckInput, params);
+        const { db, vector } = requireDatabase();
+        const conn = db.getConnection();
+        const gaps = {};
+        const fixes = [];
+        const SAMPLE_LIMIT = 10;
+        // ──────────────────────────────────────────────────────────────
+        // Gap 1: Chunks without embeddings
+        // ──────────────────────────────────────────────────────────────
+        const chunksWithoutEmbeddings = conn.prepare(`SELECT c.id FROM chunks c
+       LEFT JOIN embeddings e ON e.chunk_id = c.id
+       WHERE e.id IS NULL AND c.embedding_status != 'complete'`).all();
+        gaps.chunks_without_embeddings = {
+            count: chunksWithoutEmbeddings.length,
+            sample_ids: chunksWithoutEmbeddings.slice(0, SAMPLE_LIMIT).map(r => r.id),
+            fixable: true,
+            fix_tool: 'ocr_process_pending',
+            fix_hint: 'Set fix=true to trigger embedding generation',
+        };
+        // Fix: Generate embeddings for chunks missing them
+        if (input.fix && chunksWithoutEmbeddings.length > 0) {
+            try {
+                const { getEmbeddingService } = await import('../services/embedding/embedder.js');
+                const embeddingService = getEmbeddingService();
+                // Get pending chunks (those with embedding_status != 'complete')
+                const pendingChunks = db.getPendingEmbeddingChunks(100);
+                if (pendingChunks.length > 0) {
+                    // Group chunks by document for proper provenance
+                    const chunksByDoc = new Map();
+                    for (const chunk of pendingChunks) {
+                        const existing = chunksByDoc.get(chunk.document_id);
+                        if (existing) {
+                            existing.push(chunk);
+                        }
+                        else {
+                            chunksByDoc.set(chunk.document_id, [chunk]);
+                        }
+                    }
+                    let totalEmbedded = 0;
+                    for (const [docId, docChunks] of chunksByDoc.entries()) {
+                        const doc = db.getDocument(docId);
+                        if (!doc) {
+                            console.error(`[HealthCheck] Document ${docId} not found, skipping ${docChunks.length} chunks`);
+                            continue;
+                        }
+                        try {
+                            const result = await embeddingService.embedDocumentChunks(db, vector, docChunks, {
+                                documentId: doc.id,
+                                filePath: doc.file_path,
+                                fileName: doc.file_name,
+                                fileHash: doc.file_hash,
+                                documentProvenanceId: doc.provenance_id,
+                            });
+                            totalEmbedded += result.totalChunks;
+                        }
+                        catch (embedError) {
+                            console.error(`[HealthCheck] Failed to embed chunks for ${docId}: ${String(embedError)}`);
+                            fixes.push(`FAILED: Embedding generation for document ${docId}: ${String(embedError)}`);
+                        }
+                    }
+                    if (totalEmbedded > 0) {
+                        fixes.push(`Generated embeddings for ${totalEmbedded} chunks across ${chunksByDoc.size} documents`);
+                    }
+                }
+            }
+            catch (serviceError) {
+                console.error(`[HealthCheck] Embedding service initialization failed: ${String(serviceError)}`);
+                fixes.push(`FAILED: Could not initialize embedding service: ${String(serviceError)}`);
+            }
+        }
+        // ──────────────────────────────────────────────────────────────
+        // Gap 2: Documents without OCR results (non-pending)
+        // ──────────────────────────────────────────────────────────────
+        const docsWithoutOCR = conn.prepare(`SELECT d.id FROM documents d
+       LEFT JOIN ocr_results o ON o.document_id = d.id
+       WHERE o.id IS NULL AND d.status NOT IN ('pending', 'processing')`).all();
+        gaps.documents_without_ocr = {
+            count: docsWithoutOCR.length,
+            sample_ids: docsWithoutOCR.slice(0, SAMPLE_LIMIT).map(r => r.id),
+            fixable: false,
+            fix_tool: 'ocr_retry_failed',
+            fix_hint: 'Use ocr_process_pending to process pending docs, or ocr_retry_failed for failed ones',
+        };
+        // ──────────────────────────────────────────────────────────────
+        // Gap 3: Images without VLM descriptions
+        // ──────────────────────────────────────────────────────────────
+        const imagesWithoutVLM = conn.prepare(`SELECT id FROM images
+       WHERE vlm_status IN ('pending', 'failed') OR vlm_status IS NULL`).all();
+        gaps.images_without_vlm = {
+            count: imagesWithoutVLM.length,
+            sample_ids: imagesWithoutVLM.slice(0, SAMPLE_LIMIT).map(r => r.id),
+            fixable: false,
+            fix_tool: 'ocr_vlm_process',
+            fix_hint: null,
+        };
+        // ──────────────────────────────────────────────────────────────
+        // Gap 4: Embeddings without vectors in vec_embeddings
+        // ──────────────────────────────────────────────────────────────
+        const embeddingsWithoutVectors = conn.prepare(`SELECT e.id FROM embeddings e
+       LEFT JOIN vec_embeddings v ON v.embedding_id = e.id
+       WHERE v.embedding_id IS NULL`).all();
+        gaps.embeddings_without_vectors = {
+            count: embeddingsWithoutVectors.length,
+            sample_ids: embeddingsWithoutVectors.slice(0, SAMPLE_LIMIT).map(r => r.id),
+            fixable: false,
+            fix_tool: 'ocr_embedding_rebuild',
+            fix_hint: 'Use include_vlm=true for VLM embeddings',
+        };
+        // ──────────────────────────────────────────────────────────────
+        // Gap 5: Orphaned provenance records
+        // Provenance records not referenced by any entity's provenance_id
+        // ──────────────────────────────────────────────────────────────
+        const orphanedProvenance = conn.prepare(`SELECT p.id FROM provenance p
+       WHERE p.type = 'DOCUMENT' AND p.id NOT IN (SELECT provenance_id FROM documents WHERE provenance_id IS NOT NULL)
+       UNION ALL
+       SELECT p.id FROM provenance p
+       WHERE p.type = 'OCR_RESULT' AND p.id NOT IN (SELECT provenance_id FROM ocr_results WHERE provenance_id IS NOT NULL)
+       UNION ALL
+       SELECT p.id FROM provenance p
+       WHERE p.type = 'CHUNK' AND p.id NOT IN (SELECT provenance_id FROM chunks WHERE provenance_id IS NOT NULL)
+       UNION ALL
+       SELECT p.id FROM provenance p
+       WHERE p.type = 'EMBEDDING' AND p.id NOT IN (SELECT provenance_id FROM embeddings WHERE provenance_id IS NOT NULL)
+       UNION ALL
+       SELECT p.id FROM provenance p
+       WHERE p.type = 'IMAGE' AND p.id NOT IN (SELECT provenance_id FROM images WHERE provenance_id IS NOT NULL)
+       LIMIT 100`).all();
+        gaps.orphaned_provenance = {
+            count: orphanedProvenance.length,
+            sample_ids: orphanedProvenance.slice(0, SAMPLE_LIMIT).map(r => r.id),
+            fixable: false,
+            fix_tool: null,
+            fix_hint: null,
+        };
+        // ──────────────────────────────────────────────────────────────
+        // Summary statistics
+        // ──────────────────────────────────────────────────────────────
+        const totalDocuments = conn.prepare('SELECT COUNT(*) as count FROM documents').get().count;
+        const totalChunks = conn.prepare('SELECT COUNT(*) as count FROM chunks').get().count;
+        const totalEmbeddings = conn.prepare('SELECT COUNT(*) as count FROM embeddings').get().count;
+        const totalImages = conn.prepare('SELECT COUNT(*) as count FROM images').get().count;
+        const totalGaps = Object.values(gaps).reduce((sum, g) => sum + g.count, 0);
+        const healthy = totalGaps === 0;
+        // Build dynamic next_steps based on gaps found
+        const nextSteps = [];
+        if (gaps.chunks_without_embeddings?.count > 0 || gaps.documents_without_ocr?.count > 0) {
+            nextSteps.push({ tool: 'ocr_process_pending', description: 'Process pending documents through the OCR pipeline' });
+        }
+        if (gaps.documents_without_ocr?.count > 0) {
+            nextSteps.push({ tool: 'ocr_retry_failed', description: 'Retry failed documents' });
+        }
+        if (gaps.images_without_vlm?.count > 0) {
+            nextSteps.push({ tool: 'ocr_vlm_process', description: 'Generate VLM descriptions for images without them' });
+        }
+        if (nextSteps.length === 0 && healthy) {
+            nextSteps.push({ tool: 'ocr_search', description: 'Search across all documents' });
+        }
+        return formatResponse(successResult({
+            healthy,
+            total_gaps: totalGaps,
+            gaps,
+            fixes_applied: fixes.length > 0 ? fixes : undefined,
+            summary: {
+                total_documents: totalDocuments,
+                total_chunks: totalChunks,
+                total_embeddings: totalEmbeddings,
+                total_images: totalImages,
+            },
+            next_steps: nextSteps,
+        }));
+    }
+    catch (error) {
+        return handleError(error);
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// TOOL DEFINITIONS EXPORT
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Health check tools collection for MCP server registration
+ */
+export const healthTools = {
+    ocr_health_check: {
+        description: '[ESSENTIAL] Diagnose data integrity issues: missing embeddings, orphaned provenance, VLM gaps. Set fix=true to auto-repair.',
+        inputSchema: HealthCheckInput.shape,
+        handler: handleHealthCheck,
+    },
+};
+//# sourceMappingURL=health.js.map

package/dist/tools/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/tools/health.ts"],"names":[],"mappings":"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"}

package/dist/tools/images.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Image Extraction and Management MCP Tools
+ *
+ * Tools for extracting images from PDFs and managing image records in the database.
+ * Uses PyMuPDF for extraction and integrates with VLM pipeline.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ * Use console.error() for all logging.
+ *
+ * @module tools/images
+ */
+import { type ToolResponse, type ToolDefinition } from './shared.js';
+/**
+ * Handle ocr_image_list - List all images in a document
+ */
+export declare function handleImageList(params: Record<string, unknown>): Promise<ToolResponse>;
+/**
+ * Handle ocr_image_get - Get details of a specific image
+ */
+export declare function handleImageGet(params: Record<string, unknown>): Promise<ToolResponse>;
+/**
+ * Handle ocr_image_stats - Get image processing statistics
+ */
+export declare function handleImageStats(params: Record<string, unknown>): Promise<ToolResponse>;
+/**
+ * Handle ocr_image_delete - Delete images by image_id (single) or document_id (all for document)
+ *
+ * Must provide exactly one of image_id or document_id. Requires confirm=true.
+ */
+export declare function handleImageDelete(params: Record<string, unknown>): Promise<ToolResponse>;
+/**
+ * Handle ocr_image_reset_failed - Reset failed and stuck processing images to pending status
+ */
+export declare function handleImageResetFailed(params: Record<string, unknown>): Promise<ToolResponse>;
+/**
+ * Handle ocr_image_search - Search images by keyword filters or semantic similarity
+ *
+ * mode=keyword: SQL LIKE search on VLM descriptions and metadata filters
+ * mode=semantic: Vector similarity search on VLM embeddings
+ */
+export declare function handleImageSearch(params: Record<string, unknown>): Promise<ToolResponse>;
+/**
+ * Handle ocr_image_pending - Get images pending VLM processing
+ */
+export declare function handleImagePending(params: Record<string, unknown>): Promise<ToolResponse>;
+/**
+ * Handle ocr_image_reanalyze - Re-run VLM analysis on a specific image with optional custom prompt
+ */
+export declare function handleImageReanalyze(params: Record<string, unknown>): Promise<ToolResponse>;
+/**
+ * Image tools collection for MCP server registration
+ */
+export declare const imageTools: Record<string, ToolDefinition>;
+//# sourceMappingURL=images.d.ts.map

package/dist/tools/images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"images.d.ts","sourceRoot":"","sources":["../../src/tools/images.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,EAAqD,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AA8ExH;;GAEG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAuD5F;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAmD3F;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CA8B7F;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAwE9F;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,YAAY,CAAC,CAyBvB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAuL9F;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CA+B/F;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAuMjG;AAMD;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAqGrD,CAAC"}