mcp-word-bridge 3.3.0 → 3.4.0

package/README.md

@@ -66,7 +66,7 @@ mcp-word-bridge/
 └── README.md
 ```
 
-## Tools (84)
+## Tools (85)
 
 ### Document
 | Tool | Description |
@@ -220,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
@@ -229,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.3.0 — 84 tools
+ * v3.4.0 — 85 tools
  */
 const https = require('https');
 const fs = require('fs');
@@ -14,6 +14,101 @@ const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.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');
 
@@ -237,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'] } },
 ];
 
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -291,7 +388,7 @@ const toolActionMap = {
 };
 
 const mcpServer = new Server(
-  { name: 'mcp-word-bridge', version: '3.3.0' },
+  { name: 'mcp-word-bridge', version: '3.4.0' },
   { capabilities: { tools: {}, resources: {} } }
 );
 
@@ -299,6 +396,149 @@ 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 {
@@ -391,6 +631,16 @@ After inserting a Table of Contents, heading text appears twice in the 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-word-bridge",
-  "version": "3.3.0",
+  "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');