mcp-word-bridge 3.3.0 → 3.4.1

package/README.md

@@ -1,5 +1,8 @@
 # MCP Word Bridge
 
+[![Tests](https://github.com/likelion/mcp-word-bridge/actions/workflows/tests.yml/badge.svg)](https://github.com/likelion/mcp-word-bridge/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/likelion/mcp-word-bridge/branch/main/graph/badge.svg)](https://codecov.io/gh/likelion/mcp-word-bridge)
+
 MCP server for live Word document editing via Office Add-in. Enables programmatic editing of Word documents through the Word JavaScript API, with changes appearing as user edits in co-authoring sessions.
 
 ## Architecture
@@ -53,20 +56,31 @@ That's it. The MCP server starts automatically when your MCP client loads the co
 
 ```
 mcp-word-bridge/
-├── index.js              # Single entry point (MCP + bridge server)
+├── index.js              # Entry point: HTTPS server + MCP handlers + WebSocket relay
+├── lib/
+│   ├── tools.js          # Tool definitions (87) 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)
 ├── install-manifest.js   # Manifest sideloader (npx mcp-word-bridge-install)
 ├── taskpane.html         # Served to Word add-in
-├── taskpane-app.js       # Client-side Word JS API logic
 ├── certs/
 │   ├── cert.pem          # Self-signed TLS cert
 │   ├── key.pem           # TLS private key
 │   └── cert.conf         # OpenSSL config for cert regeneration
 ├── manifest.xml          # Office add-in manifest
+├── test/
+│   ├── mcp-protocol.test.js   # Tool schema & mapping tests (CI)
+│   ├── equations.test.js      # LaTeX→OMML pipeline tests (CI)
+│   ├── validation.test.js     # Input validation tests (CI)
+│   └── live/                  # Integration tests against real Word (manual)
+│       ├── run-all.test.js
+│       └── bridge-client.js
 ├── package.json
 └── README.md
 ```
 
-## Tools (84)
+## Tools (87)
 
 ### Document
 | Tool | Description |
@@ -75,6 +89,8 @@ mcp-word-bridge/
 | `word_get_document_properties` | Get metadata (title, author, path, timestamps) |
 | `word_set_document_properties` | Set metadata fields |
 | `word_save` | Save document to disk |
+| `word_clear` | Clear all document body content. Leaves one empty Normal paragraph. |
+| `word_create_document` | Create and open a new blank document in a new Word window |
 | `word_get_word_count` | Get word, character, and paragraph counts |
 | `word_get_styles` | List available styles |
 | `word_get_coauthors` | Get co-authoring status and active authors |
@@ -220,6 +236,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 +250,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

@@ -3,8 +3,6 @@
  * MCP Word Bridge — Unified Server
  * 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
  */
 const https = require('https');
 const fs = require('fs');
@@ -14,6 +12,10 @@ 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 { latexToOmml, buildEquationOoxml } = require('./lib/equations.js');
+const { tools, toolActionMap } = require('./lib/tools.js');
+const USAGE_GUIDE = require('./lib/usage-guide.js');
+
 const PORT = parseInt(process.env.MCP_WORD_BRIDGE_PORT || '3000', 10);
 const CERTS_DIR = path.join(__dirname, 'certs');
 
@@ -101,7 +103,7 @@ wss.on('connection', (ws, req) => {
           const pending = bridgePending.get(msg.id);
           if (pending) { pending.resolve(msg); bridgePending.delete(msg.id); }
         }
-      } catch (e) {}
+      } catch (_e) {}
     });
     ws.on('close', () => { process.stderr.write('[bridge] Taskpane disconnected\n'); taskpaneSocket = null; });
   }
@@ -131,167 +133,8 @@ function sendToTaskpane(action, params) {
   });
 }
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// PART 2: MCP Tool Definitions
-// ═══════════════════════════════════════════════════════════════════════════════
-
-const tools = [
-  // 1. DOCUMENT
-  { name: 'word_get_text', description: 'Get full plain text of the active document. Use for overview; for structured content use get_paragraphs.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_get_document_properties', description: 'Get all document metadata including title, author, path, changeTrackingMode, template, security, and timestamps.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_set_document_properties', description: 'Set document metadata (title, subject, author, keywords, comments, category, company, manager, format).', inputSchema: { type: 'object', properties: { title: { type: 'string' }, subject: { type: 'string' }, author: { type: 'string' }, keywords: { type: 'string' }, comments: { type: 'string' }, category: { type: 'string' }, company: { type: 'string' }, manager: { type: 'string' }, format: { type: 'string' } } } },
-  { name: 'word_save', description: 'Save the document to disk.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_get_word_count', description: 'Get word, character, and paragraph counts.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_get_styles', description: 'Get available document styles.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_get_coauthors', description: 'Get current co-authors and coauthoring status.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_set_change_tracking', description: 'Set change tracking mode. Use TrackAll to show edits as tracked changes.', inputSchema: { type: 'object', properties: { mode: { type: 'string', enum: ['TrackAll', 'TrackMineOnly', 'Off'] } }, required: ['mode'] } },
-  // 2. PARAGRAPHS
-  { name: 'word_get_paragraphs', description: 'Get paragraphs with text, style, alignment, isTocEntry. Optional start/end index range for pagination.', inputSchema: { type: 'object', properties: { start: { type: 'number' }, end: { type: 'number' } } } },
-  { name: 'word_get_paragraph_by_index', description: 'Get full details of a single paragraph including font, spacing, indentation, and outline level.', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_insert_paragraph', description: 'Insert a styled paragraph at Start or End. Specify style (e.g. "Heading 1", "Heading 2", "Normal") and optional alignment (Left, Center, Right, Justified).', inputSchema: { type: 'object', properties: { text: { type: 'string' }, location: { type: 'string', enum: ['Start', 'End'] }, style: { type: 'string' }, alignment: { type: 'string', description: 'Paragraph alignment: Left, Center, Right, or Justified' } }, required: ['text'] } },
-  { name: 'word_delete_paragraph', description: 'Delete a paragraph by its index.', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_set_paragraph_style', description: 'Change the style or alignment of a paragraph by index. Alignment accepts: Left, Center, Right, Justified.', inputSchema: { type: 'object', properties: { index: { type: 'number' }, style: { type: 'string' }, alignment: { type: 'string', description: 'Paragraph alignment: Left, Center, Right, or Justified' } }, required: ['index'] } },
-  { name: 'word_set_paragraph_spacing', description: 'Set line spacing (in points, e.g. 12=single for 12pt font, 24=double), before/after spacing (points), and indentation (points) on a paragraph by index.', inputSchema: { type: 'object', properties: { index: { type: 'number' }, lineSpacing: { type: 'number', description: 'Line spacing in points (e.g. 12=single for 12pt, 18=1.5x, 24=double)' }, spaceBefore: { type: 'number', description: 'Space before paragraph in points' }, spaceAfter: { type: 'number', description: 'Space after paragraph in points' }, firstLineIndent: { type: 'number', description: 'First line indent in points' }, leftIndent: { type: 'number', description: 'Left indent in points' }, rightIndent: { type: 'number', description: 'Right indent in points' } }, required: ['index'] } },
-  // 3. SEARCH & TEXT
-  { name: 'word_search', description: 'Search for text in the document (case-insensitive by default). Returns match count and up to 30 matches with their text.', inputSchema: { type: 'object', properties: { query: { type: 'string' }, matchCase: { type: 'boolean', description: 'Case-sensitive search. Default: false' }, matchWholeWord: { type: 'boolean' } }, required: ['query'] } },
-  { name: 'word_search_and_replace', description: 'Find and replace all occurrences of text (case-insensitive by default). Returns replacement count.', inputSchema: { type: 'object', properties: { find: { type: 'string' }, replace: { type: 'string' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' }, matchWholeWord: { type: 'boolean' } }, required: ['find', 'replace'] } },
-  { name: 'word_insert_text', description: 'Insert text before or after a search match. Provide "after" OR "before" (not both) as the anchor string to locate.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, after: { type: 'string' }, before: { 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: ['text'] } },
-  { name: 'word_get_selection_info', description: 'Get the current selection text with full font and style details.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_insert_text_at_selection', description: 'Insert text at the current cursor position, or replace the current selection (set replace=true).', inputSchema: { type: 'object', properties: { text: { type: 'string' }, replace: { type: 'boolean', description: 'Replace current selection instead of appending. Default: false' } }, required: ['text'] } },
-  { name: 'word_insert_line_break', description: 'Insert a soft line break (Shift+Enter) before or after a text match.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string' }, before: { type: 'boolean' }, 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'] } },
-  // 4. FORMATTING
-  { name: 'word_format_text', description: 'Apply formatting (bold, italic, color, size, font) to a text match found by search.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, occurrence: { type: 'number', description: '0-indexed match to target (0=first, 1=second, etc)' }, bold: { type: 'boolean' }, italic: { type: 'boolean' }, underline: { type: 'boolean' }, strikeThrough: { type: 'boolean' }, color: { type: 'string', description: 'Hex color e.g. #FF0000' }, highlightColor: { type: 'string' }, size: { type: 'number' }, name: { type: 'string', description: 'Font name' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false (case-insensitive)' } }, required: ['text'] } },
-  { name: 'word_clear_formatting', description: 'Clear direct formatting from a text match, reverting it to the paragraph style defaults.', inputSchema: { type: 'object', properties: { 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: ['text'] } },
-  { name: 'word_get_font_info', description: 'Inspect font properties (name, size, bold, italic, color) of a text match.', inputSchema: { type: 'object', properties: { 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: ['text'] } },
-  // 5. TABLES
-  { name: 'word_insert_table', description: 'Insert a table with data. Provide rows, cols, and data as array of arrays (e.g. [["A","B"],["C","D"]]).', inputSchema: { type: 'object', properties: { rows: { type: 'number' }, cols: { type: 'number' }, data: { type: 'array', items: { type: 'array', items: { type: 'string' } } }, location: { type: 'string', enum: ['Start', 'End'] }, style: { type: 'string' }, headerRowCount: { type: 'number' } }, required: ['rows', 'cols'] } },
-  { name: 'word_get_tables', description: 'Get all tables with row counts, styles, and cell values.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_get_table_data', description: 'Get all cell values from a specific table by index.', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_set_table_cell', description: 'Set text in a specific table cell by tableIndex, row, and col.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, row: { type: 'number' }, col: { type: 'number' }, text: { type: 'string' } }, required: ['tableIndex', 'row', 'col', 'text'] } },
-  { name: 'word_add_table_row', description: 'Add a row to a table with optional cell values.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, values: { type: 'array', items: { type: 'string' } }, location: { type: 'string', enum: ['Start', 'End'] } }, required: ['tableIndex'] } },
-  { name: 'word_delete_table_row', description: 'Delete a row from a table by tableIndex and rowIndex.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, rowIndex: { type: 'number' } }, required: ['tableIndex', 'rowIndex'] } },
-  { name: 'word_merge_table_cells', description: 'Merge a rectangular range of cells (topRow/firstCell to bottomRow/lastCell).', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, topRow: { type: 'number' }, firstCell: { type: 'number' }, bottomRow: { type: 'number' }, lastCell: { type: 'number' } }, required: ['tableIndex', 'topRow', 'firstCell', 'bottomRow', 'lastCell'] } },
-  { name: 'word_split_table_cell', description: 'Split a table cell into multiple rows/columns.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, row: { type: 'number' }, col: { type: 'number' }, rowCount: { type: 'number' }, colCount: { type: 'number' } }, required: ['tableIndex', 'row', 'col'] } },
-  { name: 'word_set_table_style', description: 'Apply a built-in table style (e.g. "Grid Table 4 - Accent 1").', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, style: { type: 'string' } }, required: ['tableIndex', 'style'] } },
-  { name: 'word_set_table_cell_shading', description: 'Set background color on a table cell.', inputSchema: { type: 'object', properties: { tableIndex: { type: 'number' }, row: { type: 'number' }, col: { type: 'number' }, color: { type: 'string', description: 'Hex color e.g. #FFD700' } }, required: ['tableIndex', 'row', 'col', 'color'] } },
-  // 6. LISTS
-  { name: 'word_insert_list', description: 'Insert a bulleted or numbered list from an array of item strings.', inputSchema: { type: 'object', properties: { items: { type: 'array', items: { type: 'string' } }, numbered: { type: 'boolean' }, location: { type: 'string', enum: ['Start', 'End'] } }, required: ['items'] } },
-  { name: 'word_get_list_info', description: 'Get list formatting details (level, numbering) for a paragraph by index.', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_set_list_level', description: 'Set indent level of a list item (0=top, 1=sub-item, etc).', inputSchema: { type: 'object', properties: { index: { type: 'number' }, level: { type: 'number' } }, required: ['index', 'level'] } },
-  // 7. COMMENTS
-  { name: 'word_add_comment', description: 'Add a review comment anchored to a text match in the document.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string' }, comment: { 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', 'comment'] } },
-  { name: 'word_get_comments', description: 'Get all comments with ID, author, content, date, and resolved status.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_get_comment_replies', description: 'Get all replies for a specific comment by ID.', inputSchema: { type: 'object', properties: { commentId: { type: 'string' } }, required: ['commentId'] } },
-  { 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'] } },
-  { name: 'word_insert_endnote', description: 'Insert an endnote 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_get_footnotes', description: 'Get all footnotes with index and text content.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_get_endnotes', description: 'Get all endnotes with index and text content.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_delete_footnote', description: 'Delete a footnote by its index (0-based).', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_delete_endnote', description: 'Delete an endnote by its index (0-based).', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  // 9. TRACK CHANGES
-  { name: 'word_get_tracked_changes', description: 'Get all tracked changes with index, type, author, date, and text.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_accept_tracked_change', description: 'Accept a tracked change by index.', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_reject_tracked_change', description: 'Reject a tracked change by index.', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  { name: 'word_accept_all_tracked_changes', description: 'Accept all tracked changes.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_reject_all_tracked_changes', description: 'Reject all tracked changes.', inputSchema: { type: 'object', properties: {} } },
-  // 10. CONTENT CONTROLS
-  { name: 'word_get_content_controls', description: 'Get all content controls with id, tag, title, type, and text.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_insert_content_control', description: 'Wrap a text match in a content control (RichText or PlainText preserve the anchor text; CheckBox REPLACES the anchor text with a checkbox widget).', inputSchema: { type: 'object', properties: { anchorText: { type: 'string' }, type: { type: 'string', enum: ['RichText', 'PlainText', 'CheckBox'] }, title: { type: 'string' }, tag: { type: 'string' }, color: { 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)' } } } },
-  { name: 'word_set_content_control_text', description: 'Set text in a content control by ID or tag.', inputSchema: { type: 'object', properties: { id: { type: 'number' }, tag: { type: 'string' }, text: { type: 'string' } }, required: ['text'] } },
-  // 11. BOOKMARKS
-  { name: 'word_get_bookmarks', description: 'Get all bookmark names.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_insert_bookmark', description: 'Insert a bookmark at anchor text.', inputSchema: { type: 'object', properties: { name: { type: 'string' }, anchorText: { 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: ['name', 'anchorText'] } },
-  { name: 'word_delete_bookmark', description: 'Delete a bookmark by name.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] } },
-  { name: 'word_go_to_bookmark', description: 'Navigate to a bookmark and select its text range.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] } },
-  { name: 'word_get_bookmark_text', description: 'Get the text content within a named bookmark.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] } },
-  // 12. HYPERLINKS
-  { name: 'word_insert_hyperlink', description: 'Insert a hyperlink on existing text.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string' }, url: { 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', 'url'] } },
-  { name: 'word_get_hyperlinks', description: 'List all hyperlinks with URL, display text, and whether they are internal (TOC) links.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_remove_hyperlink', description: 'Remove a hyperlink from text (keeps the text, removes the link).', inputSchema: { type: 'object', properties: { anchorText: { 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'] } },
-  // 13. HEADERS & FOOTERS
-  { name: 'word_get_header_footer', description: 'Get header or footer text.', inputSchema: { type: 'object', properties: { type: { type: 'string', enum: ['header', 'footer'] }, sectionIndex: { type: 'number' }, headerType: { type: 'string', enum: ['Primary', 'FirstPage', 'EvenPages'] } }, required: ['type'] } },
-  { name: 'word_set_header_footer', description: 'Set header or footer text.', inputSchema: { type: 'object', properties: { type: { type: 'string', enum: ['header', 'footer'] }, text: { type: 'string' }, sectionIndex: { type: 'number' }, headerType: { type: 'string', enum: ['Primary', 'FirstPage', 'EvenPages'] } }, required: ['type', 'text'] } },
-  // 14. IMAGES
-  { name: 'word_insert_image', description: 'Insert an image from base64 data.', inputSchema: { type: 'object', properties: { base64: { type: 'string', description: 'Base64-encoded image data' }, location: { type: 'string', enum: ['Start', 'End'] }, width: { type: 'number' }, height: { type: 'number' }, altText: { type: 'string' } }, required: ['base64'] } },
-  { name: 'word_get_images', description: 'List all inline images with dimensions, alt text, and hyperlinks.', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_delete_image', description: 'Delete an inline image by its index (0-based).', inputSchema: { type: 'object', properties: { index: { type: 'number' } }, required: ['index'] } },
-  // 15. PAGE LAYOUT & SECTIONS
-  { name: 'word_get_page_layout', description: 'Get page layout (margins, orientation, paper size) for a section.', inputSchema: { type: 'object', properties: { sectionIndex: { type: 'number' } } } },
-  { name: 'word_set_page_layout', description: 'Set page margins (in points), orientation, or paper size for a section.', inputSchema: { type: 'object', properties: { orientation: { type: 'string', enum: ['Portrait', 'Landscape'] }, topMargin: { type: 'number' }, bottomMargin: { type: 'number' }, leftMargin: { type: 'number' }, rightMargin: { type: 'number' }, paperSize: { type: 'string', enum: ['Letter', 'A4', 'A3', 'Legal', 'Custom'] }, sectionIndex: { type: 'number' } } } },
-  { name: 'word_get_sections', description: 'List all sections with their page setup (margins, orientation, paper size).', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_insert_page_break', description: 'Insert a page break after a paragraph. Omit paragraphIndex for end of document.', inputSchema: { type: 'object', properties: { paragraphIndex: { type: 'number', description: 'Paragraph index to insert break after. Omit for end of document.' } } } },
-  { name: 'word_insert_section_break', description: 'Insert a section break after a paragraph.', inputSchema: { type: 'object', properties: { paragraphIndex: { type: 'number' }, breakType: { type: 'string', enum: ['SectionNext', 'SectionContinuous', 'SectionEven', 'SectionOdd'], description: 'Default: SectionNext' } } } },
-  // 16. CUSTOM PROPERTIES
-  { name: 'word_get_custom_properties', description: 'Get all custom document properties (key-value pairs with types).', inputSchema: { type: 'object', properties: {} } },
-  { name: 'word_set_custom_property', description: 'Set a custom document property. Creates or updates the key-value pair.', inputSchema: { type: 'object', properties: { key: { type: 'string' }, value: { type: 'string' } }, required: ['key', 'value'] } },
-  { name: 'word_delete_custom_property', description: 'Delete a custom document property by key.', inputSchema: { type: 'object', properties: { key: { type: 'string' } }, required: ['key'] } },
-  // 17. ADVANCED INSERTION & FIELDS
-  { name: 'word_insert_html', description: 'Insert HTML content that Word converts to native formatting. Supports headings, bold, italic, links, tables.', inputSchema: { type: 'object', properties: { html: { type: 'string' }, location: { type: 'string', enum: ['Start', 'End'] } }, required: ['html'] } },
-  { 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: {} } },
-];
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// PART 3: Tool → Action Mapping & MCP Server
-// ═══════════════════════════════════════════════════════════════════════════════
-
-const toolActionMap = {
-  word_get_text: 'getDocumentText', word_get_document_properties: 'getDocumentProperties',
-  word_set_document_properties: 'setDocumentProperties', word_save: 'saveDocument',
-  word_get_word_count: 'getWordCount', word_get_styles: 'getStyles',
-  word_get_coauthors: 'getCoauthors', word_set_change_tracking: 'setChangeTracking',
-  word_get_paragraphs: 'getParagraphs', word_get_paragraph_by_index: 'getParagraphByIndex',
-  word_insert_paragraph: 'insertParagraph', word_delete_paragraph: 'deleteParagraph',
-  word_set_paragraph_style: 'setParagraphStyle', word_set_paragraph_spacing: 'setParagraphSpacing',
-  word_search: 'search', word_search_and_replace: 'searchAndReplace',
-  word_insert_text: 'insertText', word_get_selection_info: 'getSelectionInfo',
-  word_insert_text_at_selection: 'insertTextAtSelection', word_insert_line_break: 'insertLineBreak',
-  word_format_text: 'formatRange', word_clear_formatting: 'clearFormatting',
-  word_get_font_info: 'getFontInfo',
-  word_insert_table: 'insertTable', word_get_tables: 'getTables',
-  word_get_table_data: 'getTableData', word_set_table_cell: 'setTableCell',
-  word_add_table_row: 'addTableRow', word_delete_table_row: 'deleteTableRow',
-  word_merge_table_cells: 'mergeTableCells', word_split_table_cell: 'splitTableCell',
-  word_set_table_style: 'setTableStyle', word_set_table_cell_shading: 'setTableCellShading',
-  word_insert_list: 'insertList', word_get_list_info: 'getListInfo', word_set_list_level: 'setListLevel',
-  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',
-  word_get_tracked_changes: 'getTrackedChanges', word_accept_tracked_change: 'acceptTrackedChange',
-  word_reject_tracked_change: 'rejectTrackedChange', word_accept_all_tracked_changes: 'acceptAllTrackedChanges',
-  word_reject_all_tracked_changes: 'rejectAllTrackedChanges',
-  word_get_content_controls: 'getContentControls', word_insert_content_control: 'insertContentControl',
-  word_set_content_control_text: 'setContentControlText',
-  word_get_bookmarks: 'getBookmarks', word_insert_bookmark: 'insertBookmark',
-  word_delete_bookmark: 'deleteBookmark', word_go_to_bookmark: 'goToBookmark',
-  word_get_bookmark_text: 'getBookmarkText',
-  word_insert_hyperlink: 'insertHyperlink', word_get_hyperlinks: 'getHyperlinks',
-  word_remove_hyperlink: 'removeHyperlink',
-  word_get_header_footer: 'getHeaderFooter', word_set_header_footer: 'setHeaderFooter',
-  word_insert_image: 'insertImage', word_get_images: 'getImages', word_delete_image: 'deleteImage',
-  word_get_page_layout: 'getPageLayout', word_set_page_layout: 'setPageLayout',
-  word_get_sections: 'getSections', word_insert_page_break: 'insertPageBreak',
-  word_insert_section_break: 'insertSectionBreak',
-  word_get_custom_properties: 'getCustomProperties', word_set_custom_property: 'setCustomProperty',
-  word_delete_custom_property: 'deleteCustomProperty',
-  word_insert_html: 'insertHtml', word_insert_ooxml: 'insertOoxml',
-  word_insert_table_of_contents: 'insertTableOfContents', word_get_fields: 'getFields',
-};
-
 const mcpServer = new Server(
-  { name: 'mcp-word-bridge', version: '3.3.0' },
+  { name: 'mcp-word-bridge', version: '3.4.1' },
   { capabilities: { tools: {}, resources: {} } }
 );
 
@@ -299,6 +142,34 @@ 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;
+      const displayMode = args.displayMode !== false;
+
+      // 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);
+
+      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 };
+    }
+  }
+
   const action = toolActionMap[name];
   if (!action) return { content: [{ type: 'text', text: 'Unknown tool: ' + name }], isError: true };
   try {
@@ -311,93 +182,6 @@ 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
-
-## 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: [

package/install-manifest.js

@@ -30,7 +30,7 @@ if (process.platform === 'darwin') {
     fs.copyFileSync(manifestSrc, dest);
     console.log('✓ Manifest installed to: ' + dest);
     console.log('  Restart Word, then: Insert → My Add-ins → Developer Add-ins');
-  } catch (e) {
+  } catch (_e) {
     console.log('Could not auto-install manifest on Windows.');
     console.log('Manual steps:');
     console.log('  1. Copy this file to a local folder: ' + manifestSrc);