mcp-word-bridge 3.2.4 → 3.4.0

package/README.md

@@ -66,7 +66,7 @@ mcp-word-bridge/
 └── README.md
 ```
 
-## Tools (82)
+## Tools (85)
 
 ### Document
 | Tool | Description |
@@ -137,6 +137,8 @@ mcp-word-bridge/
 | `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 |
@@ -218,6 +220,11 @@ mcp-word-bridge/
 | `word_insert_table_of_contents` | Insert a TOC based on headings |
 | `word_get_fields` | Get all fields (hyperlinks, TOC, page numbers) |
 
+### Equations
+| Tool | Description |
+|------|-------------|
+| `word_insert_equation` | Insert a LaTeX equation as a native editable Word equation. Supports display (centered block) and inline modes. |
+
 ## How it works
 
 1. The MCP client spawns `index.js` via stdio
@@ -227,6 +234,24 @@ mcp-word-bridge/
 5. Changes go through Word's editing pipeline — cursor follows edits like a human typing
 6. When the MCP client terminates the process, the bridge server stops automatically
 
+## Resources
+
+The server exposes an MCP resource at `word-bridge://usage-guide` containing patterns, workflows, and pitfalls for LLMs operating on Word documents. MCP clients that support resources can read this for context on how to use the tools effectively.
+
+## Equations
+
+`word_insert_equation` converts LaTeX math to native Word equations via:
+
+```
+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
+- 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
+
 ## TLS Certificate
 
 A self-signed localhost certificate is **auto-generated on first run** if `certs/cert.pem` and `certs/key.pem` don't exist. The server prints the exact trust command with the resolved path:

package/index.js

@@ -4,7 +4,7 @@
  * Single entry point: starts HTTPS bridge + MCP server in one process.
  * The MCP client spawns this; everything starts and stops together.
  *
- * v3.2.0 — 82 tools
+ * v3.4.0 — 85 tools
  */
 const https = require('https');
 const fs = require('fs');
@@ -12,7 +12,102 @@ const path = require('path');
 const { WebSocketServer, WebSocket } = require('ws');
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
-const { CallToolRequestSchema, ListToolsRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
+const { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
+
+const temml = require('temml/dist/temml.cjs');
+let mml2ommlFn = null;
+const getMml2omml = async () => {
+  if (!mml2ommlFn) {
+    const mod = await import('mathml2omml');
+    mml2ommlFn = mod.mml2omml;
+  }
+  return mml2ommlFn;
+};
+
+// Post-process OMML: convert literal delimiter characters into proper <m:d> elements
+// so Word renders them as stretchy (auto-sizing) delimiters.
+const DELIM_PAIRS = { '(': ')', '[': ']', '{': '}', '|': '|', '\u2016': '\u2016', '\u2308': '\u2309', '\u230A': '\u230B', '\u27E8': '\u27E9' };
+const OPEN_CHARS = new Set(Object.keys(DELIM_PAIRS));
+
+function fixDelimiters(omml) {
+  // First, split text runs that contain delimiters mixed with other chars
+  // so each delimiter ends up in its own <m:r><m:t>X</m:t></m:r>
+  const DELIM_CHARS_STR = '()[]{}|\u2016\u2308\u2309\u230A\u230B\u27E8\u27E9';
+  omml = omml.replace(/<m:r>(<m:rPr>[^]*?<\/m:rPr>)?<m:t([^>]*)>([^<]+)<\/m:t><\/m:r>/g, (match, rPr, attrs, text) => {
+    if (text.length <= 1) return match;
+    const hasDelim = [...text].some(c => DELIM_CHARS_STR.includes(c));
+    if (!hasDelim) return match;
+    const rPrStr = rPr || '';
+    const segments = [];
+    let current = '';
+    for (const ch of text) {
+      if (DELIM_CHARS_STR.includes(ch)) {
+        if (current) segments.push(current);
+        segments.push(ch);
+        current = '';
+      } else {
+        current += ch;
+      }
+    }
+    if (current) segments.push(current);
+    return segments.map(s => '<m:r>' + rPrStr + '<m:t' + attrs + '>' + s + '</m:t></m:r>').join('');
+  });
+
+  const delimRun = /<m:r><m:t xml:space="preserve">([\(\)\[\]\{\}\|\u2016\u2308\u2309\u230A\u230B\u27E8\u27E9]|)<\/m:t><\/m:r>/g;
+  const delims = [];
+  let m;
+  while ((m = delimRun.exec(omml)) !== null) {
+    delims.push({ index: m.index, length: m[0].length, char: m[1] });
+  }
+  if (delims.length < 2) return omml;
+
+  const pairs = [];
+  const stack = [];
+  for (const d of delims) {
+    if (d.char === '|' || d.char === '\u2016') {
+      const stackIdx = stack.findIndex(s => s.char === d.char);
+      if (stackIdx >= 0) {
+        pairs.push({ open: stack[stackIdx], close: d });
+        stack.splice(stackIdx, 1);
+        continue;
+      }
+    }
+    if (OPEN_CHARS.has(d.char)) {
+      stack.push(d);
+    } else {
+      const expectedOpen = d.char === ')' ? '(' : d.char === ']' ? '[' : d.char === '}' ? '{' : d.char === '' ? '{' : d.char === '\u2309' ? '\u2308' : d.char === '\u230B' ? '\u230A' : d.char === '\u27E9' ? '\u27E8' : null;
+      for (let i = stack.length - 1; i >= 0; i--) {
+        if (stack[i].char === expectedOpen) {
+          pairs.push({ open: stack[i], close: d });
+          stack.splice(i, 1);
+          break;
+        }
+      }
+    }
+  }
+
+  pairs.sort((a, b) => b.open.index - a.open.index);
+  for (const pair of pairs) {
+    const { open, close } = pair;
+    // Re-find the delimiter runs at current positions (indices may have shifted)
+    const openMatch = omml.indexOf('<m:r><m:t xml:space="preserve">' + open.char + '</m:t></m:r>', open.index > 10 ? open.index - 10 : 0);
+    const closeSearch = open.char === close.char ? openMatch + 50 : 0; // for | pairs, search after open
+    const closeMatch = omml.indexOf('<m:r><m:t xml:space="preserve">' + close.char + '</m:t></m:r>', closeSearch > openMatch ? closeSearch : openMatch + 1);
+    if (openMatch < 0 || closeMatch < 0 || closeMatch <= openMatch) continue;
+
+    const openLen = ('<m:r><m:t xml:space="preserve">' + open.char + '</m:t></m:r>').length;
+    const closeLen = ('<m:r><m:t xml:space="preserve">' + close.char + '</m:t></m:r>').length;
+    const content = omml.substring(openMatch + openLen, closeMatch);
+
+    let dPrContent = '';
+    if (open.char !== '(') dPrContent += '<m:begChr m:val="' + open.char + '"/>';
+    if (close.char !== ')') dPrContent += '<m:endChr m:val="' + close.char + '"/>';
+    const dPr = dPrContent ? '<m:dPr>' + dPrContent + '</m:dPr>' : '';
+    const replacement = '<m:d>' + dPr + '<m:e>' + content + '</m:e></m:d>';
+    omml = omml.substring(0, openMatch) + replacement + omml.substring(closeMatch + closeLen);
+  }
+  return omml;
+}
 
 const PORT = parseInt(process.env.MCP_WORD_BRIDGE_PORT || '3000', 10);
 const CERTS_DIR = path.join(__dirname, 'certs');
@@ -185,6 +280,8 @@ const tools = [
   { name: 'word_reply_to_comment', description: 'Reply to a comment by its ID (from get_comments).', inputSchema: { type: 'object', properties: { commentId: { type: 'string' }, text: { type: 'string' } }, required: ['commentId', 'text'] } },
   { name: 'word_resolve_comment', description: 'Mark a comment as resolved by its ID.', inputSchema: { type: 'object', properties: { commentId: { type: 'string' } }, required: ['commentId'] } },
   { name: 'word_delete_comment', description: 'Delete a comment and its replies by ID.', inputSchema: { type: 'object', properties: { commentId: { type: 'string' } }, required: ['commentId'] } },
+  { name: 'word_get_comment_anchor', description: 'Get the document text that a comment is anchored to (the highlighted/marked text the comment refers to).', inputSchema: { type: 'object', properties: { commentId: { type: 'string' } }, required: ['commentId'] } },
+  { name: 'word_get_comments_with_anchor', description: 'Get all comments with ID, author, content, date, resolved status, AND the anchor text each comment is attached to.', inputSchema: { type: 'object', properties: {} } },
   // 8. FOOTNOTES & ENDNOTES
   { name: 'word_insert_footnote', description: 'Insert a footnote anchored to a text match.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string' }, text: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['anchorText', 'text'] } },
   { name: 'word_insert_footnote_at_index', description: 'Insert a footnote at the end of a paragraph by index (no search needed).', inputSchema: { type: 'object', properties: { paragraphIndex: { type: 'number' }, text: { type: 'string' } }, required: ['paragraphIndex', 'text'] } },
@@ -235,6 +332,8 @@ const tools = [
   { name: 'word_insert_ooxml', description: 'Insert raw Office Open XML for precise formatting control when HTML is insufficient.', inputSchema: { type: 'object', properties: { ooxml: { type: 'string' }, location: { type: 'string', enum: ['Start', 'End'] } }, required: ['ooxml'] } },
   { name: 'word_insert_table_of_contents', description: 'Insert a table of contents based on heading styles.', inputSchema: { type: 'object', properties: { location: { type: 'string', enum: ['Start', 'End'] }, switches: { type: 'string' } } } },
   { name: 'word_get_fields', description: 'Get all fields in the document (hyperlinks, TOC entries, page numbers, etc).', inputSchema: { type: 'object', properties: {} } },
+  // 18. EQUATIONS
+  { name: 'word_insert_equation', description: 'Insert a LaTeX math equation as a native Word equation (editable in Word equation editor). Supports fractions, roots, integrals, matrices, Greek letters, and all standard LaTeX math. Use displayMode:true for centered block equations, false for inline.', inputSchema: { type: 'object', properties: { latex: { type: 'string', description: 'LaTeX math expression (e.g. "\\\\frac{a}{b}", "\\\\int_0^\\\\infty e^{-x} dx")' }, displayMode: { type: 'boolean', description: 'true = block/centered equation (default), false = inline equation' }, location: { type: 'string', enum: ['Start', 'End'], description: 'Where to insert. Default: End' } }, required: ['latex'] } },
 ];
 
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -263,6 +362,7 @@ const toolActionMap = {
   word_add_comment: 'addComment', word_get_comments: 'getComments',
   word_get_comment_replies: 'getCommentReplies', word_reply_to_comment: 'replyToComment',
   word_resolve_comment: 'resolveComment', word_delete_comment: 'deleteComment',
+  word_get_comment_anchor: 'getCommentAnchor', word_get_comments_with_anchor: 'getCommentsWithAnchor',
   word_insert_footnote: 'insertFootnote', word_insert_footnote_at_index: 'insertFootnoteAtIndex',
   word_insert_endnote: 'insertEndnote', word_get_footnotes: 'getFootnotes',
   word_get_endnotes: 'getEndnotes', word_delete_footnote: 'deleteFootnote', word_delete_endnote: 'deleteEndnote',
@@ -288,14 +388,157 @@ const toolActionMap = {
 };
 
 const mcpServer = new Server(
-  { name: 'mcp-word-bridge', version: '3.2.0' },
-  { capabilities: { tools: {} } }
+  { name: 'mcp-word-bridge', version: '3.4.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)
+  if (name === 'word_insert_equation') {
+    try {
+      const latex = args.latex;
+      if (!latex || typeof latex !== 'string') {
+        return { content: [{ type: 'text', text: 'Error: "latex" parameter is required and must be a string.' }], isError: true };
+      }
+
+      // Step 1: LaTeX → MathML via temml
+      let mathml;
+      try {
+        mathml = temml.renderToString(latex);
+      } catch (e) {
+        return { content: [{ type: 'text', text: 'LaTeX parse error: ' + e.message + '\n\nCheck your LaTeX syntax. Common issues: unmatched braces, unknown commands, missing backslashes.' }], isError: true };
+      }
+      // temml returns a <span class="temml-error"> instead of throwing on parse errors
+      if (mathml.includes('temml-error') || !mathml.startsWith('<math')) {
+        const errMatch = mathml.match(/ParseError:\s*(.+?)(<|$)/);
+        const errMsg = errMatch ? errMatch[1].trim() : 'Invalid LaTeX expression';
+        return { content: [{ type: 'text', text: 'LaTeX parse error: ' + errMsg + '\n\nCheck your LaTeX syntax. Common issues: unmatched braces, unknown commands, missing backslashes.' }], isError: true };
+      }
+
+      // Step 2: MathML → OMML via mathml2omml
+      const mml2omml = await getMml2omml();
+      const displayMode = args.displayMode !== false; // default: true (block)
+      let omml;
+      try {
+        // Preprocess: strip temml-specific attributes and mspace elements that cause conversion artifacts
+        let cleanMml = mathml;
+        cleanMml = cleanMml.replace(/<mspace[^>]*\/>/g, '');
+        cleanMml = cleanMml.replace(/<mspace[^>]*><\/mspace>/g, '');
+        cleanMml = cleanMml.replace(/ class="[^"]*"/g, '');
+        // In display mode, convert limit-like operators from <msub> to <munder>
+        // so they render with the subscript below (not to the side).
+        // Operators: lim, limsup, liminf, min, max, inf, sup
+        if (displayMode) {
+          cleanMml = cleanMml.replace(
+            /<msub><mi>(lim|lim sup|lim inf|min|max|inf|sup)<\/mi>/g,
+            '<munder><mi>$1</mi>'
+          );
+          cleanMml = cleanMml.replace(
+            /(<munder><mi>(?:lim|lim sup|lim inf|min|max|inf|sup)<\/mi><[^]*?)<\/msub>/g,
+            '$1</munder>'
+          );
+        }
+        // Fix nary operator handling: mathml2omml expects the integrand/summand to be wrapped
+        // in <mrow> as the next sibling of the nary <msubsup> or <msub>. Temml doesn't do this.
+        // We wrap all siblings after a nary operator (up to a top-level <mo>=</mo>) in <mrow>.
+        // Handle both <msubsup> (e.g. \int_a^b) and <msub> (e.g. \sum_i)
+        cleanMml = cleanMml.replace(
+          /(<msub(?:sup)?><mo[^>]*>[\s\S]*?<\/msub(?:sup)?>)([\s\S]*?)(<mo>[=<]<\/mo>)/g,
+          '$1<mrow>$2</mrow>$3'
+        );
+        // Also handle case where there's no = sign (nary at end of mrow or math)
+        cleanMml = cleanMml.replace(
+          /(<msub(?:sup)?><mo[^>]*>[\s\S]*?<\/msub(?:sup)?>)((?:<m(?:sup|sub|Sub|i|n|r|o|frac|sqrt|row)[^]*?)?)(<\/mrow>)/g,
+          '$1<mrow>$2</mrow>$3'
+        );
+        omml = mml2omml(cleanMml);
+      } catch (e) {
+        return { content: [{ type: 'text', text: 'MathML→OMML conversion error: ' + e.message }], isError: true };
+      }
+
+      // Strip redundant namespace declarations (will be declared at document level)
+      let cleanOmml = omml.replace(/ xmlns:m="[^"]*"/g, '').replace(/ xmlns:w="[^"]*"/g, '');
+      // Safety net: remove any remaining empty <m:e/> elements (renders as squares in Word)
+      cleanOmml = cleanOmml.replace(/<m:e\/>/g, '');
+      // Fix unescaped < and & in text nodes (mathml2omml doesn't escape special chars in <m:t>)
+      // Use split/rejoin to safely process only text content between <m:t...> and </m:t>
+      // Note: regex must not match <m:type> or other tags starting with "m:t"
+      const parts = cleanOmml.split(/(<m:t>|<m:t\s[^>]*>|<\/m:t>)/);
+      let inText = false;
+      for (let i = 0; i < parts.length; i++) {
+        if (parts[i] === '<m:t>' || (parts[i].startsWith('<m:t ') && parts[i].endsWith('>'))) { inText = true; continue; }
+        if (parts[i] === '</m:t>') { inText = false; continue; }
+        if (inText && (parts[i].includes('<') || parts[i].includes('&'))) {
+          parts[i] = parts[i].replace(/&(?!amp;|lt;|gt;|quot;|apos;)/g, '&amp;').replace(/</g, '&lt;');
+        }
+      }
+      cleanOmml = parts.join('');
+      // Fix lost trailing spaces in \text{} runs (mathml2omml trims trailing spaces from mtext)
+      cleanOmml = cleanOmml.replace(/(<m:r><m:rPr><m:nor\/><\/m:rPr><m:t[^>]*>)([^<]+)(<\/m:t><\/m:r><m:r>)/g, (match, prefix, text, suffix) => {
+        // Add a space after the text if it doesn't already end with one
+        if (!text.endsWith(' ')) return prefix + text + ' ' + suffix;
+        return match;
+      });
+      // Fix delimiters: convert literal paren/bracket/brace chars into <m:d> elements
+      cleanOmml = fixDelimiters(cleanOmml);
+
+      // Step 3: Wrap in OOXML flat OPC package
+
+      // Fix nary limit placement: in display mode, limits go under/over (not to the side)
+      if (displayMode) {
+        cleanOmml = cleanOmml.replace(/<m:limLoc m:val="subSup"\/>/g, '<m:limLoc m:val="undOvr"/>');
+      }
+      const mathContent = displayMode ? '<m:oMathPara>' + cleanOmml + '</m:oMathPara>' : cleanOmml;
+
+      // For display mode: equation in its own paragraph with center justification
+      // A trailing empty paragraph with explicit Normal style resets the formatting context
+      // so that subsequent insertParagraph calls don't inherit math font/alignment.
+      // For inline mode: equation inserted at current selection (cursor) within existing paragraph
+      // A trailing run with explicit normal font resets the context for subsequent text insertion.
+      let bodyContent;
+      if (displayMode) {
+        bodyContent = '<w:p><w:pPr><w:jc w:val="center"/></w:pPr>' + mathContent + '</w:p>' +
+          '<w:p><w:pPr><w:pStyle w:val="Normal"/><w:jc w:val="left"/><w:rPr><w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:cs="Calibri"/><w:sz w:val="24"/></w:rPr></w:pPr></w:p>';
+      } else {
+        // Include a zero-width space run after the equation with explicit normal font to break math context
+        bodyContent = '<w:p>' + mathContent +
+          '<w:r><w:rPr><w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:cs="Calibri"/><w:sz w:val="24"/><w:i w:val="0"/></w:rPr><w:t>\u200B</w:t></w:r>' +
+          '</w:p>';
+      }
+
+      const ooxml = '<pkg:package xmlns:pkg="http://schemas.microsoft.com/office/2006/xmlPackage">' +
+        '<pkg:part pkg:name="/_rels/.rels" pkg:contentType="application/vnd.openxmlformats-package.relationships+xml">' +
+          '<pkg:xmlData>' +
+            '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+              '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>' +
+            '</Relationships>' +
+          '</pkg:xmlData>' +
+        '</pkg:part>' +
+        '<pkg:part pkg:name="/word/document.xml" pkg:contentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml">' +
+          '<pkg:xmlData>' +
+            '<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math">' +
+              '<w:body>' + bodyContent + '</w:body>' +
+            '</w:document>' +
+          '</pkg:xmlData>' +
+        '</pkg:part>' +
+      '</pkg:package>';
+
+      // Step 4: Insert via taskpane
+      // Display mode: insert at body End (new paragraph)
+      // Inline mode: insert at current selection (cursor must be positioned by caller)
+      const action = displayMode ? 'insertOoxml' : 'insertOoxmlAtSelection';
+      const params = displayMode ? { ooxml, location: args.location || 'End' } : { ooxml };
+      const result = 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 };
+    }
+  }
+
   const action = toolActionMap[name];
   if (!action) return { content: [{ type: 'text', text: 'Unknown tool: ' + name }], isError: true };
   try {
@@ -306,18 +549,148 @@ mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// PART 3b: Resources — Usage Guide for LLMs
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const USAGE_GUIDE = `# MCP Word Bridge — Usage Guide
+
+Controls a live Word document through an Office Add-in. All operations execute immediately in Word.
+
+## Reading Content
+- \`word_get_paragraphs\` — structured content (text, style, alignment, isTocEntry). Paginate with start/end.
+- \`word_get_text\` — quick plain-text dump (no structure)
+- \`word_search\` — locate text before operating on it
+
+## Editing Text
+- \`word_search_and_replace\` — bulk find/replace
+- \`word_insert_text\` — insert before/after a search match (use \`occurrence\` for Nth match)
+- \`word_insert_text_at_selection\` — insert at cursor or replace selection
+- Verify edits with \`word_search\` or \`word_get_paragraphs\`
+
+## Search Behavior (applies to ALL search-based tools)
+- Case-insensitive by default. Pass \`matchCase: true\` for exact match.
+- Affected tools: search, search_and_replace, format_text, insert_text, insert_footnote, add_comment, insert_hyperlink, insert_bookmark, insert_content_control, clear_formatting, get_font_info, insert_line_break, remove_hyperlink, insert_endnote.
+
+## Alignment Values
+The bridge normalizes aliases: Left, Center/Centered, Right, Justify/Justified.
+
+## Change Tracking
+- Call \`word_set_change_tracking({mode:"TrackAll"})\` BEFORE edits for tracked changes
+- Adjacent insertions by the same author may coalesce into a single tracked change
+- \`search_and_replace\` with tracking may only expose the "Added" half; use \`accept_all_tracked_changes\` if granular control isn't needed
+
+## Comments — CRITICAL PATTERNS
+
+### Reading
+- \`word_get_comments_with_anchor\` — preferred: returns comments + their anchored document text
+- \`word_get_comment_replies\` — reply thread for a specific comment
+
+### Comment + text editing interaction
+**Problem:** \`word_search_and_replace\` on text anchoring a comment collapses the anchor (shrinks to empty). The comment survives but loses its positional context.
+
+**Safe pattern:**
+1. \`word_get_comments_with_anchor\` — identify commented text
+2. If replacement overlaps a comment anchor:
+   a. \`word_reply_to_comment\` explaining resolution (if appropriate)
+   b. \`word_resolve_comment\`
+   c. THEN replace the text
+3. Resolved thread is preserved as a record
+
+**Avoid:** replacing text first (anchor collapses), or deleting+recreating comments (loses author/date/thread).
+
+### Adding
+- \`word_add_comment\` — anchor to a text match
+- \`word_reply_to_comment\` — reply to existing thread
+- \`word_resolve_comment\` — hides in Word UI, preserves history
+
+## Tables
+- 0-based indexing: tableIndex, row, col
+- \`word_get_tables\` for overview, \`word_get_table_data\` for a specific table's cells
+- Table cell paragraphs can't be structurally deleted (only cleared)
+- Can't insert page/section breaks inside table cells
+
+## Footnotes & Endnotes
+- \`word_insert_footnote\` — anchor to text match
+- \`word_insert_footnote_at_index\` — anchor to paragraph by index (no search needed)
+
+## Page Layout
+- Margins in points (72 pt = 1 inch)
+- \`lineSpacing\` in \`set_paragraph_spacing\` is in points, not a multiplier (12pt font: 12=single, 18=1.5x, 24=double)
+
+## Content Controls
+- RichText/PlainText: wraps the anchor text (non-destructive)
+- CheckBox: REPLACES anchor text with a checkbox glyph (destructive, cannot be modified with set_content_control_text)
+
+## TOC Behavior
+After inserting a Table of Contents, heading text appears twice in the document (once in TOC, once in body). Search matches TOC entries first — use \`occurrence\` parameter to target the body instance.
+
+## Error Messages
+- "Word taskpane not connected" — user must open the MCP Word Bridge add-in in Word
+- "Anchor not found" — search text not found in document
+- "Occurrence N not found" — match index out of range
+- Timeout: 30s default, 60s for HTML/OOXML/styles/TOC insertion
+
+## Equations
+- \`word_insert_equation\` takes a LaTeX string and inserts a native Word equation
+- \`displayMode: true\` (default) = centered block equation; \`false\` = inline
+- Inline mode inserts at the current cursor position. Use \`word_insert_paragraph\` or \`word_insert_text_at_selection\` first to position the cursor, then call \`word_insert_equation\` with \`displayMode: false\`.
+- After an inline equation, use \`word_insert_text_at_selection\` (not \`word_insert_paragraph\`) to continue text in the same paragraph.
+- Supports: fractions, roots, integrals, sums, matrices, Greek letters, AMS math
+- Invalid LaTeX returns a descriptive parse error (not a crash)
+- The equation is fully editable in Word's built-in equation editor
+- Examples: \`\\\\frac{a}{b}\`, \`\\\\int_0^\\\\infty e^{-x} dx\`, \`\\\\sum_{i=1}^n x_i\`
+
+## Best Practices
+1. Read before writing — understand document structure first
+2. \`word_get_comments_with_anchor\` before bulk replacements to avoid anchor damage
+3. Enable change tracking for collaborative documents
+4. \`word_save\` explicitly after significant changes
+5. Resolve comments rather than deleting them (preserves audit trail)
+`;
+
+mcpServer.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [
+    {
+      uri: 'word-bridge://usage-guide',
+      name: 'Word Bridge Usage Guide',
+      description: 'Patterns, workflows, and pitfalls for LLMs operating on Word documents via this MCP server',
+      mimeType: 'text/markdown'
+    }
+  ]
+}));
+
+mcpServer.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+  if (uri === 'word-bridge://usage-guide') {
+    return { contents: [{ uri, mimeType: 'text/markdown', text: USAGE_GUIDE }] };
+  }
+  throw new Error('Resource not found: ' + uri);
+});
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // PART 4: Startup & Shutdown
 // ═══════════════════════════════════════════════════════════════════════════════
 
+let shuttingDown = false;
 function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
   process.stderr.write('[mcp-word-bridge] Shutting down...\n');
+  // Close all WebSocket connections immediately
+  wss.clients.forEach((ws) => ws.terminate());
+  // Close the HTTPS server and force-destroy all open sockets
   httpsServer.close();
-  process.exit(0);
+  httpsServer.closeAllConnections();
+  // Ensure exit even if something holds the event loop
+  setTimeout(() => process.exit(0), 500);
 }
 
 process.on('SIGTERM', shutdown);
 process.on('SIGINT', shutdown);
+// MCP clients terminate by closing stdin — StdioServerTransport doesn't handle this
+process.stdin.on('end', shutdown);
+process.stdin.on('close', shutdown);
 
 async function main() {
   // Start HTTPS bridge server

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-word-bridge",
-  "version": "3.2.4",
+  "version": "3.4.0",
   "description": "MCP server for live Word document editing via Office Add-in",
   "main": "index.js",
   "bin": {
@@ -11,7 +11,14 @@
     "start": "node index.js",
     "install-manifest": "node install-manifest.js"
   },
-  "keywords": ["mcp", "word", "office", "add-in", "document", "editing"],
+  "keywords": [
+    "mcp",
+    "word",
+    "office",
+    "add-in",
+    "document",
+    "editing"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/likelion/mcp-word-bridge.git"
@@ -20,6 +27,8 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "mathml2omml": "^0.5.0",
+    "temml": "^0.13.3",
     "ws": "^8.16.0"
   }
 }

package/taskpane-app.js

@@ -6,7 +6,7 @@ const wsStatus = document.getElementById('ws-status');
 function log(msg, cls) {
   const line = document.createElement('div');
   line.className = cls || '';
-  line.textContent = new Date().toLocaleTimeString() + ' ' + msg;
+  line.textContent = new Date().toLocaleTimeString('en-GB', { hour12: false }) + ' ' + msg;
   logEl.appendChild(line);
   logEl.scrollTop = logEl.scrollHeight;
   if (logEl.children.length > 200) logEl.removeChild(logEl.firstChild);
@@ -998,6 +998,21 @@ commands.insertOoxml = (p) => Word.run(async (ctx) => {
   return { success: true };
 });
 
+commands.insertOoxmlAtSelection = (p) => Word.run(async (ctx) => {
+  const sel = ctx.document.getSelection();
+  const range = sel.insertOoxml(p.ooxml, Word.InsertLocation.replace);
+  range.getRange('End').select();
+  try {
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('GeneralException')) {
+      throw new Error('Invalid OOXML. Ensure the XML follows the Office Open XML package structure (pkg:package with word/document.xml part).');
+    }
+    throw e;
+  }
+  return { success: true };
+});
+
 // == PARAGRAPH DETAILS & SPACING ==
 commands.getParagraphByIndex = (p) => Word.run(async (ctx) => {
   if (p.index < 0) throw new Error('Index must be non-negative');
@@ -1113,6 +1128,36 @@ commands.getCommentReplies = (p) => Word.run(async (ctx) => {
   throw new Error('Comment not found: ' + p.commentId);
 });
 
+// == COMMENT ANCHOR TEXT ==
+commands.getCommentAnchor = (p) => Word.run(async (ctx) => {
+  const comments = ctx.document.body.getComments();
+  comments.load('id');
+  await ctx.sync();
+  let target = null;
+  for (const c of comments.items) {
+    if (String(c.id) === String(p.commentId)) { target = c; break; }
+  }
+  if (!target) throw new Error('Comment not found: ' + p.commentId);
+  const range = target.getRange();
+  range.load('text');
+  await ctx.sync();
+  return { commentId: p.commentId, anchorText: range.text };
+});
+
+commands.getCommentsWithAnchor = () => Word.run(async (ctx) => {
+  const comments = ctx.document.body.getComments();
+  comments.load('id,authorName,content,creationDate,resolved');
+  await ctx.sync();
+  const items = [];
+  for (const c of comments.items) {
+    const range = c.getRange();
+    range.load('text');
+    await ctx.sync();
+    items.push({ id: c.id, author: c.authorName, content: c.content, date: c.creationDate, resolved: c.resolved, anchorText: range.text });
+  }
+  return { count: items.length, comments: items };
+});
+
 // == CHANGE TRACKING MODE ==
 commands.getChangeTrackingMode = () => Word.run(async (ctx) => {
   const doc = ctx.document;