feat: DOCX support via existing read_file, write_file, edit_block, and start_search tools

package.json

@@ -96,6 +96,7 @@
     "md-to-pdf": "^5.2.5",
     "open": "^10.2.0",
     "pdf-lib": "^1.17.1",
+    "pizzip": "^3.2.0",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",

src/search-manager.ts

@@ -5,6 +5,7 @@ import { validatePath } from './tools/filesystem.js';
 import { capture } from './utils/capture.js';
 import { getRipgrepPath } from './utils/ripgrep-resolver.js';
 import { isExcelFile } from './utils/files/index.js';
+import PizZip from 'pizzip';
 
 export interface SearchResult {
   file: string;
@@ -171,6 +172,27 @@ export interface SearchSessionOptions {
       });
     }
 
+    // For content searches, also search DOCX files
+    const shouldSearchDocx = options.searchType === 'content' &&
+      this.shouldIncludeDocxSearch(options.filePattern, validPath);
+
+    if (shouldSearchDocx) {
+      this.searchDocxFiles(
+        validPath,
+        options.pattern,
+        options.ignoreCase !== false,
+        options.maxResults,
+        options.filePattern
+      ).then(docxResults => {
+        for (const result of docxResults) {
+          session.results.push(result);
+          session.totalMatches++;
+        }
+      }).catch((err) => {
+        capture('docx_search_error', { error: err instanceof Error ? err.message : String(err) });
+      });
+    }
+
     // Wait for first chunk of data or early completion instead of fixed delay
     // Excel search runs in background and results are merged via readSearchResults
     const firstChunk = new Promise<void>(resolve => {
@@ -469,6 +491,157 @@ export interface SearchSessionOptions {
     return excelFiles;
   }
 
+  /**
+   * Determine if DOCX search should be included based on context
+   */
+  private shouldIncludeDocxSearch(filePattern?: string, rootPath?: string): boolean {
+    const docxExtensions = ['.docx'];
+
+    if (rootPath) {
+      const lowerPath = rootPath.toLowerCase();
+      if (docxExtensions.some(ext => lowerPath.endsWith(ext))) {
+        return true;
+      }
+    }
+
+    if (filePattern) {
+      const lowerPattern = filePattern.toLowerCase();
+      if (docxExtensions.some(ext =>
+        lowerPattern.includes(`*${ext}`) || lowerPattern.endsWith(ext)
+      )) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Search DOCX files for content matches
+   * Extracts <w:t> text from document.xml and searches it
+   */
+  private async searchDocxFiles(
+    rootPath: string,
+    pattern: string,
+    ignoreCase: boolean,
+    maxResults?: number,
+    filePattern?: string
+  ): Promise<SearchResult[]> {
+    const results: SearchResult[] = [];
+
+    const flags = ignoreCase ? 'i' : '';
+    let regex: RegExp;
+    try {
+      regex = new RegExp(pattern, flags);
+    } catch {
+      const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      regex = new RegExp(escaped, flags);
+    }
+
+    let docxFiles = await this.findDocxFiles(rootPath);
+
+    if (filePattern) {
+      const patterns = filePattern.split('|').map(p => p.trim()).filter(Boolean);
+      docxFiles = docxFiles.filter(filePath => {
+        const fileName = path.basename(filePath);
+        return patterns.some(pat => {
+          if (pat.includes('*')) {
+            const regexPat = pat.replace(/\./g, '\\.').replace(/\*/g, '.*');
+            return new RegExp(`^${regexPat}$`, 'i').test(fileName);
+          }
+          return fileName.toLowerCase() === pat.toLowerCase();
+        });
+      });
+    }
+
+    for (const filePath of docxFiles) {
+      if (maxResults && results.length >= maxResults) break;
+
+      try {
+        const buf = await fs.readFile(filePath);
+        const zip = new PizZip(buf);
+
+        // Search all XML parts that can contain text
+        const xmlParts = ['word/document.xml', 'word/header1.xml', 'word/header2.xml',
+          'word/header3.xml', 'word/footer1.xml', 'word/footer2.xml', 'word/footer3.xml'];
+
+        for (const xmlPath of xmlParts) {
+          if (maxResults && results.length >= maxResults) break;
+
+          const file = zip.file(xmlPath);
+          if (!file) continue;
+
+          const xml = file.asText();
+          // Extract all <w:t> text with position tracking
+          const wtRe = /<w:t(?:\s[^>]*)?>([^<]*)<\/w:t>/g;
+          let m;
+          let lineNum = 0;
+
+          while ((m = wtRe.exec(xml)) !== null) {
+            if (maxResults && results.length >= maxResults) break;
+            const text = m[1];
+            if (!text || !text.trim()) continue;
+            lineNum++;
+
+            if (regex.test(text)) {
+              const match = text.match(regex);
+              const matchContext = match
+                ? this.getMatchContext(text, match.index || 0, match[0].length)
+                : text.substring(0, 150);
+
+              const partName = xmlPath === 'word/document.xml' ? '' : `:${xmlPath.replace('word/', '')}`;
+              results.push({
+                file: `${filePath}${partName}`,
+                line: lineNum,
+                match: matchContext,
+                type: 'content'
+              });
+            }
+          }
+        }
+      } catch {
+        continue;
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Find all DOCX files in a directory recursively
+   */
+  private async findDocxFiles(rootPath: string): Promise<string[]> {
+    const docxFiles: string[] = [];
+    const isDocx = (name: string) => name.toLowerCase().endsWith('.docx');
+
+    async function walk(dir: string): Promise<void> {
+      try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+              await walk(fullPath);
+            }
+          } else if (entry.isFile() && isDocx(entry.name)) {
+            docxFiles.push(fullPath);
+          }
+        }
+      } catch { /* skip */ }
+    }
+
+    try {
+      const stats = await fs.stat(rootPath);
+      if (stats.isFile() && isDocx(rootPath)) {
+        return [rootPath];
+      } else if (stats.isDirectory()) {
+        await walk(rootPath);
+      }
+    } catch { /* skip */ }
+
+    return docxFiles;
+  }
+
   /**
    * Extract context around a match for display (show surrounding text)
    */

src/server.ts

@@ -316,6 +316,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         - PDF: Extracts text content as markdown with page structure
                           * offset/length work as page pagination (0-based)
                           * Includes embedded images when available
+                        - DOCX (.docx): Two modes depending on parameters:
+                          * DEFAULT (no offset/length): Returns a text-bearing outline — shows paragraphs with text,
+                            tables with cell content, styles, image refs. Skips shapes/drawings/SVG noise.
+                            Each element shows its body index [0], [1], etc.
+                          * WITH offset/length: Returns raw pretty-printed XML with line pagination.
+                            Use this to drill into specific sections or see the actual XML for editing.
+                          * EDITING WORKFLOW: 1) read_file to get outline, 2) read_file with offset/length
+                            to see raw XML around what you want to edit, 3) edit_block with old_string/new_string
+                            using XML fragments copied from the read output.
+                          * IMPORTANT: offset MUST be non-zero to get raw XML (use offset=1 to start from line 1).
+                            offset=0 always returns the outline regardless of length.
+                          * For BULK changes (translation, mass replacements): use start_process with Python
+                            zipfile module to find/replace all <w:t> elements at once.
 
                         ${PATH_GUIDANCE}
                         ${CMD_PREFIX_DESCRIPTION}`,
@@ -353,6 +366,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         Write or append to file contents.
 
                         IMPORTANT: DO NOT use this tool to create PDF files. Use 'write_pdf' for all PDF creation tasks.
+                        DO NOT use this tool to edit DOCX files. Use 'edit_block' with old_string/new_string instead.
+                        To CREATE a new DOCX, use write_file with .docx extension — text content with markdown headings (#, ##, ###) is converted to styled DOCX paragraphs.
 
                         CHUNKING IS STANDARD PRACTICE: Always write files in chunks of 25-30 lines maximum.
                         This is the normal, recommended way to write files - not an emergency measure.
@@ -732,6 +747,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         - new_string: Replacement text
                         - expected_replacements: Optional number of replacements (default: 1)
 
+                        DOCX FILES (.docx) - XML Find/Replace mode:
+                        Takes same parameters as text files (old_string, new_string, expected_replacements).
+                        Operates on the pretty-printed XML inside the DOCX — the same XML you see from
+                        read_file with offset/length. Copy XML fragments from read output as old_string.
+                        After editing, the XML is repacked into a valid DOCX.
+                        Also searches headers/footers if not found in document body.
+                        Examples:
+                        - Replace text: old_string="<w:t>Old Text</w:t>" new_string="<w:t>New Text</w:t>"
+                        - Change style: old_string='<w:pStyle w:val="Normal"/>' new_string='<w:pStyle w:val="Heading1"/>'
+                        - Add content: include surrounding XML context in old_string, add new elements in new_string
+
                         By default, replaces only ONE occurrence of the search text.
                         To replace multiple occurrences, provide expected_replacements with
                         the exact number of matches expected.

src/tools/edit.ts

@@ -371,57 +371,90 @@ function highlightDifferences(expected: string, actual: string): string {
 export async function handleEditBlock(args: unknown): Promise<ServerResult> {
     const parsed = EditBlockArgsSchema.parse(args);
 
-    // Structured files: Range rewrite
     // Note: Check for truthy range to handle empty strings from AI clients that send all optional params
     const hasRange = parsed.range !== undefined && parsed.range !== '';
     const hasContent = parsed.content !== undefined && parsed.content !== '';
-    if (hasRange && hasContent) {
-        try {
-            // Validate path before any filesystem operations
-            const validatedPath = await validatePath(parsed.file_path);
 
-            const { getFileHandler } = await import('../utils/files/factory.js');
-            const handler = await getFileHandler(validatedPath);
+    // Validate path and resolve handler once — used by both dispatch paths below
+    let validatedPath: string;
+    let handler: Awaited<ReturnType<typeof import('../utils/files/factory.js').getFileHandler>>;
+    try {
+        validatedPath = await validatePath(parsed.file_path);
+        const { getFileHandler } = await import('../utils/files/factory.js');
+        handler = await getFileHandler(validatedPath);
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return createErrorResponse(errorMessage);
+    }
+
+    const hasEditRange = 'editRange' in handler && typeof handler.editRange === 'function';
 
-            // Parse content if it's a JSON string (AI often sends arrays as JSON strings)
-            let content = parsed.content;
-            if (typeof content === 'string') {
-                try {
-                    content = JSON.parse(content);
-                } catch {
-                    // Leave as-is if not valid JSON - let handler decide
-                }
+    // Path 1: Range rewrite (Excel, etc.) — range + content
+    if (hasRange && hasContent) {
+        // Parse content if it's a JSON string (AI often sends arrays as JSON strings)
+        let content = parsed.content;
+        if (typeof content === 'string') {
+            try {
+                content = JSON.parse(content);
+            } catch {
+                // Leave as-is if not valid JSON - let handler decide
             }
+        }
 
-            // Check if handler supports range editing
-            if ('editRange' in handler && typeof handler.editRange === 'function') {
+        if (hasEditRange) {
+            try {
                 // parsed.range is guaranteed non-empty string by hasRange check above
-                await handler.editRange(validatedPath, parsed.range!, content, parsed.options);
+                await handler.editRange!(validatedPath!, parsed.range!, content, parsed.options);
                 return {
                     content: [{
                         type: "text",
                         text: `Successfully updated range ${parsed.range} in ${parsed.file_path}`
                     }],
                 };
-            } else {
-                return createErrorResponse(`Range-based editing not supported for ${parsed.file_path}. For text files, use old_string and new_string parameters instead. If your client requires range/content parameters, set them to empty strings ("").`);
+            } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return createErrorResponse(errorMessage);
             }
-        } catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            return createErrorResponse(errorMessage);
         }
+
+        return createErrorResponse(`Range-based editing not supported for ${parsed.file_path}. For text files, use old_string and new_string parameters instead. If your client requires range/content parameters, set them to empty strings ("").`);
     }
 
-    // Text files: String replacement
-    // Validate required parameters for text replacement
+    // Path 2: Text replacement — old_string + new_string
     if (parsed.old_string === undefined || parsed.new_string === undefined) {
         return createErrorResponse(`Text replacement requires both old_string and new_string parameters`);
     }
 
-    const searchReplace = {
+    // If the handler implements editRange it owns text-replacement for its file type
+    // (e.g. DocxFileHandler does find/replace on pretty-printed XML rather than raw bytes).
+    // Plain text files fall through to performSearchReplace.
+    if (hasEditRange) {
+        try {
+            const result = await handler.editRange!(validatedPath!, '', {
+                old_string: parsed.old_string,
+                new_string: parsed.new_string,
+                expected_replacements: parsed.expected_replacements,
+            });
+
+            if (result.success) {
+                return {
+                    content: [{
+                        type: "text",
+                        text: `Successfully applied ${result.editsApplied} edit(s) to ${parsed.file_path}`
+                    }],
+                };
+            }
+
+            const errorMsg = result.errors?.map(e => e.error).join('; ') || 'Unknown error';
+            return createErrorResponse(errorMsg);
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return createErrorResponse(errorMessage);
+        }
+    }
+
+    return performSearchReplace(parsed.file_path, {
         search: parsed.old_string,
         replace: parsed.new_string
-    };
-
-    return performSearchReplace(parsed.file_path, searchReplace, parsed.expected_replacements);
+    }, parsed.expected_replacements);
 }

src/tools/schemas.ts

@@ -140,7 +140,7 @@ export const EditBlockArgsSchema = z.object({
   data => {
     // Helper to check if value is actually provided (not undefined, not empty string)
     const hasValue = (v: unknown) => v !== undefined && v !== '';
-    return (hasValue(data.old_string) && hasValue(data.new_string)) ||
+    return (hasValue(data.old_string) && data.new_string !== undefined) ||
            (hasValue(data.range) && hasValue(data.content));
   },
   { message: "Must provide either (old_string + new_string) or (range + content)" }

src/utils/files/base.ts

@@ -130,6 +130,9 @@ export interface FileMetadata {
     totalPages?: number;
     pages?: PdfPageItem[];
 
+    /** For DOCX files */
+    isDocx?: boolean;
+
     /** Error information if operation failed */
     error?: boolean;
     errorMessage?: string;
@@ -212,7 +215,7 @@ export interface FileInfo {
     permissions: string;
 
     /** File type classification */
-    fileType: 'text' | 'excel' | 'image' | 'binary';
+    fileType: 'text' | 'excel' | 'image' | 'binary' | 'docx';
 
     /** Type-specific metadata */
     metadata?: FileMetadata;