mcp-word-bridge 3.4.1 → 3.5.0

package/README.md

@@ -58,7 +58,7 @@ That's it. The MCP server starts automatically when your MCP client loads the co
 mcp-word-bridge/
 ├── index.js              # Entry point: HTTPS server + MCP handlers + WebSocket relay
 ├── lib/
-│   ├── tools.js          # Tool definitions (87) and action mapping
+│   ├── tools.js          # Tool definitions and action mapping
 │   ├── equations.js      # LaTeX→OMML pipeline (fixDelimiters, fixNaryOperands, latexToOmml)
 │   └── usage-guide.js    # MCP resource content (usage patterns for LLMs)
 ├── taskpane-app.js       # Client-side Word JS API logic (runs in add-in)
@@ -80,7 +80,7 @@ mcp-word-bridge/
 └── README.md
 ```
 
-## Tools (87)
+## Tools (90)
 
 ### Document
 | Tool | Description |
@@ -95,14 +95,18 @@ mcp-word-bridge/
 | `word_get_styles` | List available styles |
 | `word_get_coauthors` | Get co-authoring status and active authors |
 | `word_set_change_tracking` | Enable/disable track changes |
+| `word_get_document_outline` | Get heading hierarchy as a structured outline tree |
 
 ### Paragraphs
 | Tool | Description |
 |------|-------------|
 | `word_get_paragraphs` | Get paragraphs with style, alignment, TOC flag (paginated) |
 | `word_get_paragraph_by_index` | Get full details of one paragraph (font, spacing, indent) |
-| `word_insert_paragraph` | Insert a styled paragraph at Start or End |
+| `word_insert_paragraph` | Append/prepend a styled paragraph at document Start or End |
+| `word_insert_paragraph_at_index` | Insert a paragraph before or after a specific paragraph index |
 | `word_delete_paragraph` | Delete a paragraph by index |
+| `word_replace_paragraph_text` | Replace paragraph text by index (preserves style) |
+| `word_move_paragraph` | Move one or more consecutive paragraphs to another position |
 | `word_set_paragraph_style` | Change style or alignment of a paragraph |
 | `word_set_paragraph_spacing` | Set line spacing, before/after, and indentation |
 
@@ -111,7 +115,7 @@ mcp-word-bridge/
 |------|-------------|
 | `word_search` | Find text matches (case-insensitive by default) |
 | `word_search_and_replace` | Find and replace all occurrences |
-| `word_insert_text` | Insert text before or after a search match |
+| `word_insert_text_at_match` | Insert text before or after a search match |
 | `word_get_selection_info` | Get current selection with font details |
 | `word_insert_text_at_selection` | Insert or replace text at cursor |
 | `word_insert_line_break` | Insert a soft line break (Shift+Enter) |
@@ -127,7 +131,7 @@ mcp-word-bridge/
 | Tool | Description |
 |------|-------------|
 | `word_insert_table` | Insert a table with data and optional style |
-| `word_get_tables` | Get all tables with values and styles |
+| `word_list_tables` | List table metadata (count, dimensions, style) — no cell values |
 | `word_get_table_data` | Get cell values from a specific table |
 | `word_set_table_cell` | Set text in a cell |
 | `word_add_table_row` | Add a row with optional values |
@@ -148,13 +152,11 @@ mcp-word-bridge/
 | Tool | Description |
 |------|-------------|
 | `word_add_comment` | Add a comment anchored to text |
-| `word_get_comments` | Get all comments with author, date, status |
+| `word_get_comments` | Get all comments with author, date, status, and anchor text |
 | `word_get_comment_replies` | Get replies for a comment |
 | `word_reply_to_comment` | Reply to a comment |
 | `word_resolve_comment` | Mark a comment as resolved |
 | `word_delete_comment` | Delete a comment and its replies |
-| `word_get_comment_anchor` | Get the document text a comment is anchored to |
-| `word_get_comments_with_anchor` | Get all comments with their anchor text included |
 
 ### Footnotes & Endnotes
 | Tool | Description |
@@ -239,7 +241,12 @@ mcp-word-bridge/
 ### Equations
 | Tool | Description |
 |------|-------------|
-| `word_insert_equation` | Insert a LaTeX equation as a native editable Word equation. Supports display (centered block) and inline modes. |
+| `word_insert_equation` | Insert a LaTeX equation as a native editable Word equation. Display (block) or inline mode with optional anchor text positioning. |
+
+### Batch
+| Tool | Description |
+|------|-------------|
+| `word_batch` | Execute up to 50 operations in a single call. Native ops are bundled into one message to Word for maximum speed. |
 
 ## How it works
 
@@ -264,6 +271,8 @@ LaTeX → temml → MathML → mathml2omml → OMML → OOXML → Word
 
 - **Display mode** (`displayMode: true`, default): centered block equation on its own line
 - **Inline mode** (`displayMode: false`): inserted at the current cursor position within a paragraph
+  - With `anchorText`: searches for the text and inserts the equation after the match (recommended — no manual cursor positioning needed)
+  - Without `anchorText`: inserts at wherever the cursor currently is
 - Supports: fractions, roots, integrals, sums, products, matrices, Greek letters, piecewise functions, aligned systems, and all standard LaTeX math
 - Equations are fully editable in Word's built-in equation editor
 - Invalid LaTeX returns a descriptive error message

package/index.js

@@ -119,7 +119,7 @@ function sendToTaskpane(action, params) {
       return;
     }
     const id = String(++mcpRequestId);
-    const heavyOps = ['insertHtml', 'insertOoxml', 'getStyles', 'insertTableOfContents'];
+    const heavyOps = ['insertHtml', 'insertOoxml', 'getStyles', 'insertTableOfContents', 'batchExecute'];
     const timeoutMs = heavyOps.includes(action) ? 60000 : 30000;
     const timeout = setTimeout(() => {
       bridgePending.delete(id);
@@ -134,47 +134,211 @@ function sendToTaskpane(action, params) {
 }
 
 const mcpServer = new Server(
-  { name: 'mcp-word-bridge', version: '3.4.1' },
+  { name: 'mcp-word-bridge', version: '3.5.0' },
   { capabilities: { tools: {}, resources: {} } }
 );
 
 mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
 
-mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-
-  // Special handling for word_insert_equation (server-side LaTeX→OMML conversion)
+// Helper: execute a single tool call (used by both direct calls and batch)
+async function executeTool(name, args) {
+  // word_insert_equation: server-side LaTeX→OMML conversion
   if (name === 'word_insert_equation') {
+    const latex = args.latex;
+    const displayMode = args.displayMode !== false;
+
+    let result;
     try {
-      const latex = args.latex;
-      const displayMode = args.displayMode !== false;
+      const { mml2omml } = require('mathml2omml');
+      result = latexToOmml(latex, displayMode, mml2omml);
+    } catch (e) {
+      const msg = e.message.startsWith('LaTeX parse error') || e.message.startsWith('"latex"') ? e.message : 'Error: ' + e.message;
+      return { content: [{ type: 'text', text: msg }], isError: true };
+    }
 
-      // Convert LaTeX → OMML via lib/equations.js
-      let result;
-      try {
-        const { mml2omml } = require('mathml2omml');
-        result = latexToOmml(latex, displayMode, mml2omml);
-      } catch (e) {
-        return { content: [{ type: 'text', text: e.message.startsWith('LaTeX parse error') || e.message.startsWith('"latex"') ? e.message : 'Error: ' + e.message }], isError: true };
+    const cleanOmml = result.omml;
+    const ooxml = buildEquationOoxml(cleanOmml, displayMode);
+
+    if (displayMode) {
+      await sendToTaskpane('insertOoxml', { ooxml, location: args.location || 'End' });
+    } else if (args.anchorText) {
+      // Inline mode with anchor: search for anchor text, insert space+marker after it, insert equation at cursor, clean up marker
+      const marker = '\u200B\uFEFF'; // unique two-char sequence unlikely to exist in normal text
+      const searchResult = await sendToTaskpane('search', { query: args.anchorText, matchCase: args.matchCase || false });
+      if (!searchResult || searchResult.count === 0) throw new Error('Anchor not found: ' + args.anchorText);
+      const occurrence = args.occurrence || 0;
+      if (occurrence >= searchResult.count) throw new Error('Occurrence ' + occurrence + ' not found (only ' + searchResult.count + ' match' + (searchResult.count === 1 ? '' : 'es') + ')');
+      // Insert space + marker to position cursor (space ensures equation doesn't glue to preceding text)
+      await sendToTaskpane('insertText', { text: ' ' + marker, after: args.anchorText, occurrence: occurrence, matchCase: args.matchCase || false });
+      await sendToTaskpane('insertOoxmlAtSelection', { ooxml });
+      // Clean up the marker (space remains, giving proper separation)
+      await sendToTaskpane('searchAndReplace', { find: marker, replace: '' });
+    } else {
+      await sendToTaskpane('insertOoxmlAtSelection', { ooxml });
+    }
+    return { content: [{ type: 'text', text: JSON.stringify({ success: true, displayMode, latex }) }] };
+  }
+
+  // word_get_document_outline: server-side filtering of paragraphs by heading style
+  if (name === 'word_get_document_outline') {
+    const maxLevel = args.maxLevel !== undefined ? args.maxLevel : 3;
+    const result = await sendToTaskpane('getParagraphs', {});
+    const headings = [];
+    for (const para of result.paragraphs) {
+      const match = para.style && para.style.match(/^Heading (\d)$/i);
+      if (match) {
+        const level = parseInt(match[1], 10);
+        if (level <= maxLevel) {
+          headings.push({ level, text: para.text, index: para.index });
+        }
+      }
+    }
+    return { content: [{ type: 'text', text: JSON.stringify({ count: headings.length, outline: headings }, null, 2) }] };
+  }
+
+  // word_move_paragraph: atomic move (read text+style, delete, insert at new position)
+  // Supports moving multiple consecutive paragraphs via optional 'count' parameter
+  if (name === 'word_move_paragraph') {
+    const fromIndex = args.fromIndex;
+    const toIndex = args.toIndex;
+    const count = args.count || 1;
+    const location = args.location || 'After';
+    if (fromIndex < 0) throw new Error('fromIndex must be non-negative');
+    if (toIndex < 0) throw new Error('toIndex must be non-negative');
+    if (count < 1) throw new Error('count must be at least 1');
+    if (fromIndex === toIndex && count === 1) throw new Error('fromIndex and toIndex must be different');
+    // Validate all indices are in bounds before mutating
+    const paraCount = await sendToTaskpane('getParagraphs', {});
+    const total = paraCount.count;
+    if (fromIndex >= total) throw new Error('fromIndex ' + fromIndex + ' out of range. Document has ' + total + ' paragraphs (0-indexed).');
+    if (fromIndex + count - 1 >= total) throw new Error('fromIndex + count (' + (fromIndex + count) + ') exceeds paragraph count (' + total + ').');
+    if (toIndex >= total) throw new Error('toIndex ' + toIndex + ' out of range. Document has ' + total + ' paragraphs (0-indexed).');
+    // Collect all paragraphs to move (text + style)
+    const collected = [];
+    for (let i = 0; i < count; i++) {
+      const details = await sendToTaskpane('getParagraphByIndex', { index: fromIndex + i });
+      collected.push({ text: details.text, style: details.style });
+    }
+    // Delete from last to first to preserve indices during deletion
+    for (let i = count - 1; i >= 0; i--) {
+      await sendToTaskpane('deleteParagraph', { index: fromIndex + i });
+    }
+    // Adjust destination index after deletions
+    let adjustedTo;
+    if (fromIndex < toIndex) {
+      adjustedTo = toIndex - count;
+    } else {
+      adjustedTo = toIndex;
+    }
+    // Insert in order at destination
+    for (let i = 0; i < collected.length; i++) {
+      if (i === 0) {
+        await sendToTaskpane('insertParagraphAtIndex', { index: adjustedTo, text: collected[i].text, style: collected[i].style, location: location });
+      } else {
+        // After the first insert, the paragraph we just inserted is at a known position.
+        // For 'Before': first para went to adjustedTo, so second goes After adjustedTo.
+        // For 'After': first para went to adjustedTo+1, so second goes After adjustedTo+1.
+        const prevInsertedAt = location === 'Before' ? adjustedTo + (i - 1) : adjustedTo + i;
+        await sendToTaskpane('insertParagraphAtIndex', { index: prevInsertedAt, text: collected[i].text, style: collected[i].style, location: 'After' });
       }
+    }
+    return { content: [{ type: 'text', text: JSON.stringify({ success: true, moved: { from: fromIndex, count, to: adjustedTo, location } }) }] };
+  }
 
-      const cleanOmml = result.omml;
-      const ooxml = buildEquationOoxml(cleanOmml, displayMode);
+  // word_batch: execute multiple operations in a single call
+  if (name === 'word_batch') {
+    const operations = args.operations;
+    if (!operations || !Array.isArray(operations) || operations.length === 0) {
+      return { content: [{ type: 'text', text: 'Error: operations must be a non-empty array' }], isError: true };
+    }
+    if (operations.length > 50) {
+      return { content: [{ type: 'text', text: 'Error: maximum 50 operations per batch' }], isError: true };
+    }
 
-      const action = displayMode ? 'insertOoxml' : 'insertOoxmlAtSelection';
-      const params = displayMode ? { ooxml, location: args.location || 'End' } : { ooxml };
-      await sendToTaskpane(action, params);
-      return { content: [{ type: 'text', text: JSON.stringify({ success: true, displayMode, latex }) }] };
-    } catch (e) {
-      return { content: [{ type: 'text', text: 'Error: ' + e.message }], isError: true };
+    // Partition into taskpane-native ops (have action mapping) vs server-composed ops
+    const SERVER_HANDLED = new Set(['word_insert_equation', 'word_batch', 'word_get_document_outline', 'word_move_paragraph']);
+    const results = [];
+
+    // Collect consecutive taskpane-native ops into batches, flush when hitting a server op
+    let nativeBuf = [];
+
+    const flushNative = async () => {
+      if (nativeBuf.length === 0) return;
+      const batchOps = nativeBuf.map(item => ({
+        action: toolActionMap[item.tool],
+        params: item.args || {}
+      }));
+      const batchResult = await sendToTaskpane('batchExecute', { operations: batchOps });
+      for (const r of batchResult.results) {
+        const item = nativeBuf[r.index];
+        if (r.success) {
+          results.push({ index: item.originalIndex, tool: item.tool, success: true, result: r.result });
+        } else {
+          results.push({ index: item.originalIndex, tool: item.tool, success: false, error: r.error });
+          // Mark that we should stop
+          nativeBuf = [];
+          return false;
+        }
+      }
+      nativeBuf = [];
+      return true;
+    };
+
+    let stopped = false;
+    for (let i = 0; i < operations.length && !stopped; i++) {
+      const op = operations[i];
+      if (!op.tool) {
+        results.push({ index: i, tool: op.tool, success: false, error: 'Missing tool name' });
+        stopped = true;
+        break;
+      }
+
+      if (SERVER_HANDLED.has(op.tool)) {
+        // Flush any pending native ops first
+        const ok = await flushNative();
+        if (ok === false) { stopped = true; break; }
+        // Execute server-side
+        try {
+          const opResult = await executeTool(op.tool, op.args || {});
+          if (opResult.isError) {
+            results.push({ index: i, tool: op.tool, success: false, result: opResult.content[0].text });
+            stopped = true;
+          } else {
+            results.push({ index: i, tool: op.tool, success: true, result: JSON.parse(opResult.content[0].text) });
+          }
+        } catch (e) {
+          results.push({ index: i, tool: op.tool, success: false, error: e.message });
+          stopped = true;
+        }
+      } else if (toolActionMap[op.tool]) {
+        // Buffer taskpane-native op
+        nativeBuf.push({ tool: op.tool, args: op.args || {}, originalIndex: i });
+      } else {
+        // Flush pending, then report unknown tool
+        const ok = await flushNative();
+        if (ok === false) { stopped = true; break; }
+        results.push({ index: i, tool: op.tool, success: false, error: 'Unknown tool: ' + op.tool });
+        stopped = true;
+      }
     }
+    // Flush any remaining native ops
+    if (!stopped) await flushNative();
+
+    const succeeded = results.filter(r => r.success).length;
+    return { content: [{ type: 'text', text: JSON.stringify({ completed: succeeded, failed: results.length - succeeded, total: operations.length, results }, null, 2) }] };
   }
 
+  // Default: forward to taskpane via action map
   const action = toolActionMap[name];
   if (!action) return { content: [{ type: 'text', text: 'Unknown tool: ' + name }], isError: true };
+  const result = await sendToTaskpane(action, args || {});
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}
+
+mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
   try {
-    const result = await sendToTaskpane(action, args || {});
-    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    return await executeTool(name, args || {});
   } catch (e) {
     return { content: [{ type: 'text', text: 'Error: ' + e.message }], isError: true };
   }