/** * ┌─────────────────────────────────────────────────────────────────────────┐ * │ REPLACE TEXT AT POSITION V2 - Context-Aware MCP Tool │ * ├─────────────────────────────────────────────────────────────────────────┤ * │ Filename: replace-text-at-position-v2.tool.ts │ * │ Language: TypeScript │ * │ MCP Server: PDF Operations Server │ * │ │ * │ Purpose: │ * │ Implements an advanced MCP tool that replaces text in PDF documents │ * │ with full context awareness. Intelligently detects whether text is │ * │ part of a name, email, identifier, or plain text, and preserves │ * │ document structure during replacement. │ * │ │ * │ Why this file exists: │ * │ - Provides SURGICAL PRECISION for text replacement │ * │ - Prevents data loss from partial replacements │ * │ - Maintains document integrity and formatting │ * │ - Enables preview/validation before applying changes │ * │ │ * │ Key Features (v2 Improvements): │ * │ ✓ CONTEXT DETECTION: Identifies names, emails, identifiers, text │ * │ ✓ WORD BOUNDARIES: Only replaces complete words, not substrings │ * │ ✓ COMPONENT PRESERVATION: Keeps non-target parts intact │ * │ ✓ VALIDATION MODE: Preview changes before applying │ * │ ✓ CASE INSENSITIVE: Optional case-insensitive matching │ * │ ✓ FIRST MATCH ONLY: Option to replace only first occurrence │ * │ │ * │ MCP Tool Information: │ * │ Tool Name: replace-text-at-position-v2 │ * │ Category: pdf-operations │ * │ Input: { filePath, searchTerm, replacementTerm, options } │ * │ Output: { success, message, validationPassed, context, details } │ * │ │ * │ Examples: │ * │ 1. Name: "Ramya Lakhani" → search "Ramya", replace "Raj" │ * │ Result: "Raj Lakhani" ✓ (preserves last name) │ * │ │ * │ 2. Email: "lakhani.ramya.u@gmail.com" → search "ramya", replace "raj" │ * │ Result: "lakhani.raj.u@gmail.com" ✓ (preserves structure) │ * │ │ * │ 3. Text: "The ramayana and ramya" → search "ramya", replace "raj" │ * │ Result: "The ramayana and raj" ✓ (word boundary prevents partial) │ * │ │ * │ Workflow: │ * │ 1. User calls tool with search and replacement terms │ * │ 2. Tool detects all occurrences using detect-text-position │ * │ 3. For each occurrence: │ * │ a. Detect context type (name/email/text/identifier) │ * │ b. Validate word boundaries │ * │ c. Calculate precise replacement bounds │ * │ d. Preview the change │ * │ 4. If validate_only=true, return preview without applying │ * │ 5. Otherwise, apply replacements and save PDF │ * │ │ * │ Dependencies: │ * │ - @modelcontextprotocol/sdk: MCP server SDK │ * │ - zod: Input validation and schema definition │ * │ - pdf-lib: PDF manipulation library │ * │ - ../utils/text-replacement-utils: Context detection functions │ * │ - ../utils/path-resolver: File path resolution │ * │ - ./detect-text-position.tool: Text position detection │ * │ │ * │ Related Tools: │ * │ - detect-text-position: Finds text positions in PDFs │ * │ - replace-text-at-position: Original (v1) text replacement tool │ * │ │ * │ Security Considerations: │ * │ - Validates file paths to prevent traversal attacks │ * │ - Sanitizes search/replacement text │ * │ - Validates word boundaries to prevent unintended replacements │ * │ - Preview mode allows verification before changes │ * │ │ * │ Author: PDF MCP Team │ * │ Created: 2025-11-01 │ * │ Version: 2.0.0 │ * └─────────────────────────────────────────────────────────────────────────┘ */ import { z } from 'zod'; /** * Zod schema for replace-text-at-position-v2 tool input validation */ export declare const ReplaceTextAtPositionV2InputSchema: { filePath: z.ZodString; searchTerm: z.ZodString; replacementTerm: z.ZodString; pageNumber: z.ZodOptional; caseInsensitive: z.ZodDefault>; firstOccurrenceOnly: z.ZodDefault>; matchWholeWords: z.ZodDefault>; validateOnly: z.ZodDefault>; outputPath: z.ZodOptional; createBackup: z.ZodDefault>; }; /** * Zod schema for replace-text-at-position-v2 tool output */ export declare const ReplaceTextAtPositionV2OutputSchema: { success: z.ZodBoolean; message: z.ZodString; validationPassed: z.ZodBoolean; outputPath: z.ZodOptional; occurrencesFound: z.ZodNumber; occurrencesReplaced: z.ZodNumber; contextSummary: z.ZodObject<{ names: z.ZodNumber; emails: z.ZodNumber; plainText: z.ZodNumber; identifiers: z.ZodNumber; unknown: z.ZodNumber; }, "strip", z.ZodTypeAny, { unknown: number; names: number; emails: number; plainText: number; identifiers: number; }, { unknown: number; names: number; emails: number; plainText: number; identifiers: number; }>; previews: z.ZodArray; }, "strip", z.ZodTypeAny, { pageNumber: number; bounds: { x: number; y: number; width: number; height: number; }; originalText: string; replacementText: string; contextType: string; safe: boolean; explanation: string; }, { pageNumber: number; bounds: { x: number; y: number; width: number; height: number; }; originalText: string; replacementText: string; contextType: string; safe: boolean; explanation: string; }>, "many">; warnings: z.ZodOptional>; }; /** * Performs context-aware text replacement in a PDF document * * This is the main function that orchestrates the entire replacement process: * 1. Detect all occurrences of search term * 2. Analyze context for each occurrence * 3. Validate replacements for safety * 4. Apply replacements (unless validate_only is true) * * @param params - Replacement parameters * @returns Complete context-aware replacement result * @throws Error if file cannot be processed */ export declare function replaceTextAtPositionV2(params: { filePath: string; searchTerm: string; replacementTerm: string; pageNumber?: number; caseInsensitive?: boolean; firstOccurrenceOnly?: boolean; matchWholeWords?: boolean; validateOnly?: boolean; outputPath?: string; createBackup?: boolean; }): Promise<{ success: boolean; message: string; validationPassed: boolean; outputPath?: string; occurrencesFound: number; occurrencesReplaced: number; contextSummary: { names: number; emails: number; plainText: number; identifiers: number; unknown: number; }; previews: Array<{ pageNumber: number; originalText: string; replacementText: string; contextType: string; safe: boolean; explanation: string; bounds: { x: number; y: number; width: number; height: number; }; }>; warnings?: string[]; }>; /** * Tool handler for replace-text-at-position-v2 * Formats the result for MCP protocol */ export declare const replaceTextAtPositionV2ToolHandler: (params: any) => Promise<{ content: { type: "text"; text: string; }[]; structuredContent: { success: boolean; message: string; validationPassed: boolean; outputPath?: string; occurrencesFound: number; occurrencesReplaced: number; contextSummary: { names: number; emails: number; plainText: number; identifiers: number; unknown: number; }; previews: Array<{ pageNumber: number; originalText: string; replacementText: string; contextType: string; safe: boolean; explanation: string; bounds: { x: number; y: number; width: number; height: number; }; }>; warnings?: string[]; }; }>; //# sourceMappingURL=replace-text-at-position-v2.tool.d.ts.map