Feat/implement docx support task

package.json

@@ -86,11 +86,16 @@
     "@supabase/supabase-js": "^2.89.0",
     "@vscode/ripgrep": "^1.15.9",
     "cross-fetch": "^4.1.0",
+    "@xmldom/xmldom": "^0.8.10",
+    "docx": "^8.5.0",
+    "docxtemplater": "^3.44.0",
     "exceljs": "^4.4.0",
     "fastest-levenshtein": "^1.0.16",
     "file-type": "^21.1.1",
     "glob": "^10.3.10",
     "isbinaryfile": "^5.0.4",
+    "jszip": "^3.10.1",
+    "pizzip": "^3.1.6",
     "md-to-pdf": "^5.2.5",
     "open": "^10.2.0",
     "pdf-lib": "^1.17.1",

src/handlers/filesystem-handlers.ts

@@ -7,6 +7,7 @@ import {
     moveFile,
     getFileInfo,
     writePdf,
+    writeDocx,
     type FileResult,
     type MultiFileResult
 } from '../tools/filesystem.js';
@@ -25,7 +26,8 @@ import {
     ListDirectoryArgsSchema,
     MoveFileArgsSchema,
     GetFileInfoArgsSchema,
-    WritePdfArgsSchema
+    WritePdfArgsSchema,
+    WriteDocxArgsSchema
 } from '../tools/schemas.js';
 
 /**
@@ -106,6 +108,50 @@ export async function handleReadFile(args: unknown): Promise<ServerResult> {
             };
         }
 
+        // Handle DOCX files
+        if (fileResult.metadata?.isDocx) {
+            const meta = fileResult.metadata;
+            const contentItems: Array<{ type: string, text?: string, data?: string, mimeType?: string }> = [];
+
+            // Add document info
+            const infoParts = [`DOCX file: ${parsed.path}`];
+            if (meta?.title) infoParts.push(`Title: "${meta.title}"`);
+            if (meta?.author) infoParts.push(`Author: ${meta.author}`);
+            if (meta?.images && meta.images.length > 0) {
+                infoParts.push(`${meta.images.length} embedded images`);
+            }
+
+            contentItems.push({
+                type: "text",
+                text: infoParts.join(', ') + '\n\n'
+            });
+
+            // Add embedded images first
+            if (meta?.images && meta.images.length > 0) {
+                for (const image of meta.images) {
+                    contentItems.push({
+                        type: "image",
+                        data: image.data,
+                        mimeType: image.mimeType
+                    });
+                }
+            }
+
+            // Add the main document content as markdown
+            const textContent = typeof fileResult.content === 'string'
+                ? fileResult.content
+                : fileResult.content.toString('utf8');
+
+            contentItems.push({
+                type: "text",
+                text: textContent
+            });
+
+            return {
+                content: contentItems
+            };
+        }
+
         // Handle image files
         if (fileResult.metadata?.isImage) {
             // For image files, return as an image content type
@@ -164,6 +210,8 @@ export async function handleReadMultipleFiles(args: unknown): Promise<ServerResu
             return `${result.path}: Error - ${result.error}`;
         } else if (result.isPdf) {
             return `${result.path}: PDF file with ${result.payload?.pages?.length} pages`;
+        } else if (result.isDocx) {
+            return `${result.path}: DOCX file (Word document)`;
         } else if (result.mimeType) {
             return `${result.path}: ${result.mimeType} ${result.isImage ? '(image)' : '(text)'}`;
         } else {
@@ -376,3 +424,54 @@ export async function handleWritePdf(args: unknown): Promise<ServerResult> {
         return createErrorResponse(errorMessage);
     }
 }
+
+/**
+ * Handle write_docx command
+ */
+export async function handleWriteDocx(args: unknown): Promise<ServerResult> {
+    try {
+        const parsed = WriteDocxArgsSchema.parse(args);
+        await writeDocx(parsed.path, parsed.content, parsed.outputPath, parsed.options);
+        const targetPath = parsed.outputPath || parsed.path;
+
+        // Build success message with operation details
+        let message: string;
+        if (parsed.outputPath) {
+            message = `Successfully created new DOCX file: ${targetPath}\nOriginal file preserved: ${parsed.path}`;
+        } else {
+            message = `Successfully updated DOCX file: ${targetPath}`;
+        }
+
+        // Add operation summary if using operations mode
+        if (Array.isArray(parsed.content)) {
+            const opCounts = {
+                replaceText: 0,
+                appendMarkdown: 0,
+                insertTable: 0,
+                insertImage: 0,
+            };
+
+            for (const op of parsed.content) {
+                if (op.type in opCounts) {
+                    opCounts[op.type as keyof typeof opCounts]++;
+                }
+            }
+
+            const details = Object.entries(opCounts)
+                .filter(([_, count]) => count > 0)
+                .map(([type, count]) => `${count} ${type}`)
+                .join(', ');
+
+            if (details) {
+                message += `\nOperations applied: ${details}`;
+            }
+        }
+
+        return {
+            content: [{ type: "text", text: message }],
+        };
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return createErrorResponse(errorMessage);
+    }
+}

src/server.ts

@@ -49,6 +49,7 @@ import {
     GetPromptsArgsSchema,
     GetRecentToolCallsArgsSchema,
     WritePdfArgsSchema,
+    WriteDocxArgsSchema,
 } from './tools/schemas.js';
 import { getConfig, setConfigValue } from './tools/config.js';
 import { getUsageStats } from './tools/usage.js';
@@ -264,7 +265,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 name: "read_file",
                 description: `
                         Read contents from files and URLs.
-                        Read PDF files and extract content as markdown and images.
+                        Read PDF and DOCX files and extract content as markdown and images.
 
                         Prefer this over 'execute_command' with cat/type for viewing files.
 
@@ -301,6 +302,10 @@ 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): Extracts text content as markdown with formatting
+                          * Preserves headings, lists, tables, bold, italic
+                          * Includes embedded images as base64
+                          * Extracts document metadata (title, author, dates)
 
                         ${PATH_GUIDANCE}
                         ${CMD_PREFIX_DESCRIPTION}`,
@@ -439,6 +444,74 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     openWorldHint: false,
                 },
             },
+            {
+                name: "write_docx",
+                description: `
+                        Create a new DOCX (Word) file or modify an existing one.
+
+                        THIS IS THE TOOL FOR CREATING AND MODIFYING WORD DOCUMENTS (.docx).
+
+                        MODES:
+                        1. CREATE NEW DOCX:
+                           - Pass a markdown string as 'content'.
+                           - Markdown will be converted to a formatted Word document.
+                           write_docx(path="new_doc.docx", content="# Title\\n\\nBody text...")
+
+                        2. UPDATE/MODIFY EXISTING DOCX (DEFAULT: OVERWRITES ORIGINAL):
+                           - Pass array of operations as 'content'.
+                           - WITHOUT 'outputPath': UPDATES the original file (OVERWRITES IT)
+                           - WITH 'outputPath': Creates a NEW file, preserving the original
+
+                           // Update the original file (RECOMMENDED for edits):
+                           write_docx(path="document.docx", content=[
+                               { type: "replaceText", search: "old", replace: "new" }
+                           ])
+
+                           // Create a modified copy (use when you need to preserve original):
+                           write_docx(path="document.docx", content=[
+                               { type: "appendMarkdown", markdown: "# New Section" }
+                           ], outputPath="document_updated.docx")
+
+                        OPERATIONS:
+                        - replaceText: Search and replace text in the document.
+                          { type: "replaceText", search: "old text", replace: "new text", matchCase: true, global: true }
+
+                        - appendMarkdown: Add content at the end of the document.
+                          { type: "appendMarkdown", markdown: "# New Section\\n\\nContent here..." }
+
+                        - insertTable: Add a table to the document.
+                          { type: "insertTable", rows: [["Header1", "Header2"], ["Row1Col1", "Row1Col2"]] }
+                          or
+                          { type: "insertTable", markdownTable: "| Header1 | Header2 |\\n| --- | --- |\\n| Data1 | Data2 |" }
+
+                        - insertImage: Add an image to the document.
+                          { type: "insertImage", imagePath: "/path/to/image.png", altText: "Description", width: 400, height: 300 }
+                          Supports: local file paths, data URLs (data:image/png;base64,...)
+
+                        SUPPORTED MARKDOWN FEATURES:
+                        - Headings (# through ######)
+                        - Paragraphs
+                        - Tables (markdown table syntax)
+                        - Images (![alt](path))
+                        - Basic text formatting (bold, italic)
+
+                        OPTIONS:
+                        - baseDir: Base directory for resolving relative image paths
+                        - includeImages: Extract/include images (default: true)
+                        - preserveFormatting: Preserve text formatting (default: true)
+
+                        Only works within allowed directories.
+
+                        ${PATH_GUIDANCE}
+                        ${CMD_PREFIX_DESCRIPTION}`,
+                inputSchema: zodToJsonSchema(WriteDocxArgsSchema),
+                annotations: {
+                    title: "Write/Modify DOCX",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    openWorldHint: false,
+                },
+            },
             {
                 name: "create_directory",
                 description: `
@@ -1322,6 +1395,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request: CallToolRequest)
                 result = await handlers.handleWritePdf(args);
                 break;
 
+            case "write_docx":
+                result = await handlers.handleWriteDocx(args);
+                break;
+
             case "create_directory":
                 result = await handlers.handleCreateDirectory(args);
                 break;

src/tools/docx/builders/index.ts

@@ -0,0 +1,7 @@
+/**
+ * DOCX Builders
+ * Centralized exports for all building utilities
+ */
+
+export * from './markdown-builder.js';
+