@wonderwhy-er/desktop-commander 0.2.35 → 0.2.37

package/dist/server.js

@@ -1,5 +1,5 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListPromptsRequestSchema, InitializeRequestSchema, LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, ListPromptsRequestSchema, InitializeRequestSchema, LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, } from "@modelcontextprotocol/sdk/types.js";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { getSystemInfo, getOSSpecificGuidance, getPathGuidance, getDevelopmentToolGuidance } from './utils/system-info.js';
 // Get system information once at startup
@@ -21,6 +21,8 @@ import { handleWelcomePageOnboarding } from './utils/welcome-onboarding.js';
 import { VERSION } from './version.js';
 import { capture, capture_call_tool } from "./utils/capture.js";
 import { logToStderr, logger } from './utils/logger.js';
+import { buildUiToolMeta, FILE_PREVIEW_RESOURCE_URI } from './ui/contracts.js';
+import { listUiResources, readUiResource } from './ui/resources.js';
 // Store startup messages to send after initialization
 const deferredMessages = [];
 function deferLog(level, message) {
@@ -47,11 +49,18 @@ export const server = new Server({
 });
 // Add handler for resources/list method
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
-    // Return an empty list of resources
     return {
-        resources: [],
+        resources: listUiResources(),
     };
 });
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    const response = await readUiResource(uri);
+    if (response) {
+        return response;
+    }
+    throw new Error(`Unknown resource URI: ${uri}`);
+});
 // Add handler for prompts/list method
 server.setRequestHandler(ListPromptsRequestSchema, async () => {
     // Return an empty list of prompts
@@ -233,10 +242,24 @@ 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}`,
                 inputSchema: zodToJsonSchema(ReadFileArgsSchema),
+                _meta: buildUiToolMeta(FILE_PREVIEW_RESOURCE_URI, true),
                 annotations: {
                     title: "Read File or URL",
                     readOnlyHint: true,
@@ -269,6 +292,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.
@@ -647,6 +672,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.
@@ -1179,6 +1215,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     };
                 }
                 break;
+            case "track_ui_event":
+                try {
+                    result = await handlers.handleTrackUiEvent(args);
+                }
+                catch (error) {
+                    capture('server_request_error', { message: `Error in track_ui_event handler: ${error}` });
+                    result = {
+                        content: [{ type: "text", text: `Error: Failed to track UI event` }],
+                        isError: true,
+                    };
+                }
+                break;
             case "give_feedback_to_desktop_commander":
                 try {
                     result = await giveFeedbackToDesktopCommander(args);
@@ -1265,12 +1313,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         // Add tool call to history (exclude only get_recent_tool_calls to prevent recursion)
         const duration = Date.now() - startTime;
         const EXCLUDED_TOOLS = [
-            'get_recent_tool_calls'
+            'get_recent_tool_calls',
+            'track_ui_event'
         ];
         if (!EXCLUDED_TOOLS.includes(name)) {
             toolHistory.addCall(name, args, result, duration);
         }
         // Track success or failure based on result
+        if (name === 'track_ui_event') {
+            return result;
+        }
         if (result.isError) {
             await usageTracker.trackFailure(name);
             console.log(`[FEEDBACK DEBUG] Tool ${name} failed, not checking feedback`);

package/dist/test-docx.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/docx/builders/image.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Image builder — creates w:drawing elements and manages image relationships.
+ */
+import PizZip from 'pizzip';
+import type { DocxContentImage, InsertImageOp } from '../types.js';
+/**
+ * Build an image element and add it to the ZIP archive.
+ *
+ * @param doc The XML document
+ * @param zip The DOCX ZIP archive
+ * @param spec The image specification (from content or operation)
+ * @returns A w:p element containing the image drawing
+ */
+export declare function buildImageElement(doc: Document, zip: PizZip, spec: DocxContentImage | InsertImageOp): Promise<Element>;

package/dist/tools/docx/builders/image.js

@@ -0,0 +1,84 @@
+/**
+ * Image builder — creates w:drawing elements and manages image relationships.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { DOMParser } from '@xmldom/xmldom';
+import { addImageRelationship, ensureContentType } from '../relationships.js';
+import { escapeXmlAttr } from './utils.js';
+import { pixelsToEmu, DEFAULT_IMAGE_WIDTH, DEFAULT_IMAGE_HEIGHT, NAMESPACES } from '../constants.js';
+/**
+ * Build an image element and add it to the ZIP archive.
+ *
+ * @param doc The XML document
+ * @param zip The DOCX ZIP archive
+ * @param spec The image specification (from content or operation)
+ * @returns A w:p element containing the image drawing
+ */
+export async function buildImageElement(doc, zip, spec) {
+    // Validate image exists
+    try {
+        await fs.access(spec.imagePath);
+    }
+    catch {
+        throw new Error(`Image file not found: ${spec.imagePath}`);
+    }
+    // Read image
+    const imgBuffer = await fs.readFile(spec.imagePath);
+    const ext = path.extname(spec.imagePath).toLowerCase();
+    const baseName = path.basename(spec.imagePath);
+    // Find next available media filename
+    let mediaIndex = 1;
+    while (zip.file(`word/media/image${mediaIndex}${ext}`)) {
+        mediaIndex++;
+    }
+    const mediaFileName = `image${mediaIndex}${ext}`;
+    // Add image to ZIP
+    zip.file(`word/media/${mediaFileName}`, imgBuffer);
+    // Add relationship
+    const rId = addImageRelationship(zip, mediaFileName);
+    // Ensure Content_Types entry
+    ensureContentType(zip, ext);
+    // Compute dimensions (EMU)
+    const widthPx = spec.width ?? DEFAULT_IMAGE_WIDTH;
+    const heightPx = spec.height ?? DEFAULT_IMAGE_HEIGHT;
+    const widthEmu = pixelsToEmu(widthPx);
+    const heightEmu = pixelsToEmu(heightPx);
+    // Build drawing XML
+    const altText = spec.altText ?? baseName;
+    const drawingXmlStr = buildDrawingXml(rId, widthEmu, heightEmu, altText, mediaFileName);
+    // Parse drawing XML into a paragraph
+    const drawingFragment = new DOMParser().parseFromString(`<w:p xmlns:w="${NAMESPACES.W}">` +
+        `<w:r>${drawingXmlStr}</w:r></w:p>`, 'application/xml');
+    return doc.importNode(drawingFragment.documentElement, true);
+}
+/**
+ * Build the inline w:drawing XML for an image reference.
+ */
+function buildDrawingXml(rId, widthEmu, heightEmu, altText, fileName) {
+    return (`<w:drawing xmlns:w="${NAMESPACES.W}">` +
+        `<wp:inline distT="0" distB="0" distL="0" distR="0" ` +
+        `xmlns:wp="${NAMESPACES.WP}">` +
+        `<wp:extent cx="${widthEmu}" cy="${heightEmu}"/>` +
+        `<wp:docPr id="1" name="${fileName}" descr="${escapeXmlAttr(altText)}"/>` +
+        `<a:graphic xmlns:a="${NAMESPACES.A}">` +
+        `<a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">` +
+        `<pic:pic xmlns:pic="${NAMESPACES.PIC}">` +
+        `<pic:nvPicPr>` +
+        `<pic:cNvPr id="0" name="${fileName}" descr="${escapeXmlAttr(altText)}"/>` +
+        `<pic:cNvPicPr/>` +
+        `</pic:nvPicPr>` +
+        `<pic:blipFill>` +
+        `<a:blip r:embed="${rId}" xmlns:r="${NAMESPACES.R}"/>` +
+        `<a:stretch><a:fillRect/></a:stretch>` +
+        `</pic:blipFill>` +
+        `<pic:spPr>` +
+        `<a:xfrm><a:off x="0" y="0"/><a:ext cx="${widthEmu}" cy="${heightEmu}"/></a:xfrm>` +
+        `<a:prstGeom prst="rect"><a:avLst/></a:prstGeom>` +
+        `</pic:spPr>` +
+        `</pic:pic>` +
+        `</a:graphicData>` +
+        `</a:graphic>` +
+        `</wp:inline>` +
+        `</w:drawing>`);
+}

package/dist/tools/docx/builders/index.d.ts

@@ -1,5 +1,11 @@
 /**
- * DOCX Builders
- * Centralized exports for all building utilities
+ * DOCX element builders — Single Responsibility: build XML elements
+ * for paragraphs, tables, and images.
+ *
+ * These builders are shared between create.ts and ops/ modules to
+ * eliminate code duplication and ensure consistency.
  */
-export * from './markdown-builder.js';
+export { buildParagraph } from './paragraph.js';
+export { buildTable } from './table.js';
+export { buildImageElement } from './image.js';
+export { escapeXml, escapeXmlAttr } from './utils.js';

package/dist/tools/docx/builders/index.js

@@ -1,5 +1,11 @@
 /**
- * DOCX Builders
- * Centralized exports for all building utilities
+ * DOCX element builders — Single Responsibility: build XML elements
+ * for paragraphs, tables, and images.
+ *
+ * These builders are shared between create.ts and ops/ modules to
+ * eliminate code duplication and ensure consistency.
  */
-export * from './markdown-builder.js';
+export { buildParagraph } from './paragraph.js';
+export { buildTable } from './table.js';
+export { buildImageElement } from './image.js';
+export { escapeXml, escapeXmlAttr } from './utils.js';

package/dist/tools/docx/builders/paragraph.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Paragraph builder — creates w:p elements with optional styles.
+ */
+import type { DocxContentParagraph } from '../types.js';
+/**
+ * Build a paragraph element from content structure.
+ *
+ * @param doc The XML document
+ * @param item The paragraph content item
+ * @returns A w:p element
+ */
+export declare function buildParagraph(doc: Document, item: DocxContentParagraph): Element;

package/dist/tools/docx/builders/paragraph.js

@@ -0,0 +1,29 @@
+/**
+ * Paragraph builder — creates w:p elements with optional styles.
+ */
+/**
+ * Build a paragraph element from content structure.
+ *
+ * @param doc The XML document
+ * @param item The paragraph content item
+ * @returns A w:p element
+ */
+export function buildParagraph(doc, item) {
+    const p = doc.createElement('w:p');
+    // Set style if provided
+    if (item.style) {
+        const pPr = doc.createElement('w:pPr');
+        const pStyle = doc.createElement('w:pStyle');
+        pStyle.setAttribute('w:val', item.style);
+        pPr.appendChild(pStyle);
+        p.appendChild(pPr);
+    }
+    // Add text run
+    const r = doc.createElement('w:r');
+    const t = doc.createElement('w:t');
+    t.setAttribute('xml:space', 'preserve');
+    t.textContent = item.text;
+    r.appendChild(t);
+    p.appendChild(r);
+    return p;
+}

package/dist/tools/docx/builders/table.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Table builder — creates w:tbl elements with headers, rows, and styling.
+ * Supports multiple paragraphs per cell with different styles.
+ */
+import type { DocxContentTable, InsertTableOp } from '../types.js';
+/**
+ * Build a table element from content structure or operation.
+ * Supports cells with multiple paragraphs, each with its own style.
+ */
+export declare function buildTable(doc: Document, spec: DocxContentTable | InsertTableOp): Element;

package/dist/tools/docx/builders/table.js

@@ -0,0 +1,138 @@
+/**
+ * Table builder — creates w:tbl elements with headers, rows, and styling.
+ * Supports multiple paragraphs per cell with different styles.
+ */
+import { buildParagraph } from './paragraph.js';
+/**
+ * Build a table element from content structure or operation.
+ * Supports cells with multiple paragraphs, each with its own style.
+ */
+export function buildTable(doc, spec) {
+    const tbl = doc.createElement('w:tbl');
+    // Table properties
+    const tblPr = doc.createElement('w:tblPr');
+    if (spec.style) {
+        const tblStyle = doc.createElement('w:tblStyle');
+        tblStyle.setAttribute('w:val', spec.style);
+        tblPr.appendChild(tblStyle);
+    }
+    const tblW = doc.createElement('w:tblW');
+    tblW.setAttribute('w:w', '0');
+    tblW.setAttribute('w:type', 'auto');
+    tblPr.appendChild(tblW);
+    // Table borders
+    const tblBorders = doc.createElement('w:tblBorders');
+    for (const side of ['top', 'left', 'bottom', 'right', 'insideH', 'insideV']) {
+        const border = doc.createElement(`w:${side}`);
+        border.setAttribute('w:val', 'single');
+        border.setAttribute('w:sz', '4');
+        border.setAttribute('w:space', '0');
+        border.setAttribute('w:color', '000000');
+        tblBorders.appendChild(border);
+    }
+    tblPr.appendChild(tblBorders);
+    tbl.appendChild(tblPr);
+    // Determine column count
+    const colCount = spec.headers
+        ? spec.headers.length
+        : spec.rows.length > 0
+            ? spec.rows[0].length
+            : 0;
+    // Table grid
+    if (colCount > 0) {
+        const tblGrid = doc.createElement('w:tblGrid');
+        for (let c = 0; c < colCount; c++) {
+            const gridCol = doc.createElement('w:gridCol');
+            const w = spec.colWidths?.[c] ?? Math.floor(9000 / colCount);
+            gridCol.setAttribute('w:w', String(w));
+            tblGrid.appendChild(gridCol);
+        }
+        tbl.appendChild(tblGrid);
+    }
+    /**
+     * Build a cell from content.
+     * Content can be:
+     * - A string: creates one paragraph with that text
+     * - An array of DocxContentParagraph: creates multiple paragraphs, each with its own style
+     */
+    const buildCell = (content, isHeader, widthTwips) => {
+        const tc = doc.createElement('w:tc');
+        // Cell properties (width)
+        if (widthTwips) {
+            const tcPr = doc.createElement('w:tcPr');
+            const tcW = doc.createElement('w:tcW');
+            tcW.setAttribute('w:w', String(widthTwips));
+            tcW.setAttribute('w:type', 'dxa');
+            tcPr.appendChild(tcW);
+            tc.appendChild(tcPr);
+        }
+        // Handle content: string or array of paragraphs
+        if (typeof content === 'string') {
+            // Simple case: single paragraph
+            const p = doc.createElement('w:p');
+            const r = doc.createElement('w:r');
+            // Header cells get bold
+            if (isHeader) {
+                const rPr = doc.createElement('w:rPr');
+                const b = doc.createElement('w:b');
+                rPr.appendChild(b);
+                r.appendChild(rPr);
+            }
+            const t = doc.createElement('w:t');
+            t.setAttribute('xml:space', 'preserve');
+            t.textContent = content;
+            r.appendChild(t);
+            p.appendChild(r);
+            tc.appendChild(p);
+        }
+        else {
+            // Complex case: multiple paragraphs with different styles
+            for (const paraSpec of content) {
+                const p = buildParagraph(doc, paraSpec);
+                // If header and first paragraph, ensure bold on runs
+                if (isHeader) {
+                    const runs = p.getElementsByTagName('w:r');
+                    for (let i = 0; i < runs.length; i++) {
+                        const run = runs.item(i);
+                        let rPr = run.getElementsByTagName('w:rPr').item(0);
+                        if (!rPr) {
+                            rPr = doc.createElement('w:rPr');
+                            if (run.firstChild) {
+                                run.insertBefore(rPr, run.firstChild);
+                            }
+                            else {
+                                run.appendChild(rPr);
+                            }
+                        }
+                        // Add bold if not already present
+                        if (!rPr.getElementsByTagName('w:b').length) {
+                            const b = doc.createElement('w:b');
+                            rPr.appendChild(b);
+                        }
+                    }
+                }
+                tc.appendChild(p);
+            }
+        }
+        return tc;
+    };
+    // Header row
+    if (spec.headers && spec.headers.length > 0) {
+        const tr = doc.createElement('w:tr');
+        for (let i = 0; i < spec.headers.length; i++) {
+            const width = spec.colWidths?.[i];
+            tr.appendChild(buildCell(spec.headers[i], true, width));
+        }
+        tbl.appendChild(tr);
+    }
+    // Data rows
+    for (const row of spec.rows) {
+        const tr = doc.createElement('w:tr');
+        for (let i = 0; i < row.length; i++) {
+            const width = spec.colWidths?.[i];
+            tr.appendChild(buildCell(row[i], false, width));
+        }
+        tbl.appendChild(tr);
+    }
+    return tbl;
+}

package/dist/tools/docx/builders/utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * XML escaping utilities.
+ */
+export declare function escapeXml(s: string): string;
+export declare function escapeXmlAttr(s: string): string;

package/dist/tools/docx/builders/utils.js

@@ -0,0 +1,18 @@
+/**
+ * XML escaping utilities.
+ */
+export function escapeXml(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+export function escapeXmlAttr(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}

package/dist/tools/docx/constants.d.ts

@@ -1,36 +1,32 @@
 /**
- * DOCX Constants
- *
- * Centralised constants shared across the DOCX module.
- *
- * @module docx/constants
+ * DOCX constants — shared values used across the module.
  */
-export declare const DEFAULT_CONVERSION_OPTIONS: {
-    readonly includeImages: true;
-    readonly preserveFormatting: true;
-    readonly styleMap: readonly string[];
-};
-export declare const DEFAULT_BUILD_OPTIONS: {
-    readonly font: "Calibri";
-    readonly fontSize: 11;
-    readonly orientation: "portrait";
-    readonly margins: {
-        readonly top: 1440;
-        readonly right: 1440;
-        readonly bottom: 1440;
-        readonly left: 1440;
-        readonly header: 720;
-        readonly footer: 720;
-        readonly gutter: 0;
-    };
-    readonly footer: true;
-    readonly pageNumber: false;
+export declare const IMAGE_MIME_TYPES: Record<string, string>;
+export declare function getMimeType(ext: string): string;
+/**
+ * Convert pixels to EMU (English Metric Units).
+ * 1 inch = 914400 EMU, 1 px ≈ 9525 EMU (at 96 DPI)
+ */
+export declare const PX_TO_EMU = 9525;
+export declare function pixelsToEmu(px: number): number;
+export declare const NAMESPACES: {
+    readonly W: "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+    readonly WP: "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
+    readonly A: "http://schemas.openxmlformats.org/drawingml/2006/main";
+    readonly PIC: "http://schemas.openxmlformats.org/drawingml/2006/picture";
+    readonly R: "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+    readonly RELS: "http://schemas.openxmlformats.org/package/2006/relationships";
 };
-export declare const DOCX_NAMESPACES: {
-    readonly DUBLIN_CORE: "dc";
-    readonly CUSTOM_PROPERTIES: "cp";
-    readonly DCTERMS: "dcterms";
+export declare const DEFAULT_IMAGE_WIDTH = 300;
+export declare const DEFAULT_IMAGE_HEIGHT = 200;
+export declare const DOCX_PATHS: {
+    readonly CONTENT_TYPES: "[Content_Types].xml";
+    readonly DOCUMENT_XML: "word/document.xml";
+    readonly DOCUMENT_RELS: "word/_rels/document.xml.rels";
+    readonly ROOT_RELS: "_rels/.rels";
+    readonly STYLES_XML: "word/styles.xml";
+    readonly SETTINGS_XML: "word/settings.xml";
+    readonly WEB_SETTINGS_XML: "word/webSettings.xml";
+    readonly FONT_TABLE_XML: "word/fontTable.xml";
+    readonly MEDIA_FOLDER: "word/media";
 };
-export declare const CORE_PROPERTIES_PATH = "docProps/core.xml";
-export declare const IMAGE_MIME_TYPES: Readonly<Record<string, string>>;
-export declare const HTML_WRAPPER_TEMPLATE = "<!DOCTYPE html>\n<html>\n<head>\n  <meta charset=\"UTF-8\">\n</head>\n<body>\n{content}\n</body>\n</html>";