mcp-word-bridge 3.2.3 → 3.3.0

package/README.md

@@ -66,7 +66,7 @@ mcp-word-bridge/
 └── README.md
 ```
 
-## Tools (82)
+## Tools (84)
 
 ### 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 |
@@ -227,21 +229,23 @@ 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
 
-## Regenerating TLS Certificates
+## TLS Certificate
 
-A self-signed localhost certificate is **auto-generated on first run** if `certs/cert.pem` and `certs/key.pem` don't exist. No manual step needed.
+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:
 
-To trust the cert (required for Word to connect without warnings):
-
-**macOS:**
-```bash
-sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain node_modules/mcp-word-bridge/certs/cert.pem
 ```
+[mcp-word-bridge] ✓ Certificate generated.
+[mcp-word-bridge]
+[mcp-word-bridge] To trust the certificate (required once for Word to connect):
+[mcp-word-bridge]   security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain-db "/path/to/certs/cert.pem"
+```
+
+Run the printed command once. No `sudo` required — it adds to your user login keychain.
 
-**To regenerate manually:**
+**To regenerate:**
 ```bash
 rm certs/cert.pem certs/key.pem
-node index.js  # will regenerate on startup
+# restart the MCP server — it will regenerate and print the trust command again
 ```
 
 ## Known Limitations & Word API Behavior

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.3.0 — 84 tools
  */
 const https = require('https');
 const fs = require('fs');
@@ -12,7 +12,7 @@ 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 PORT = parseInt(process.env.MCP_WORD_BRIDGE_PORT || '3000', 10);
 const CERTS_DIR = path.join(__dirname, 'certs');
@@ -40,8 +40,17 @@ function ensureCerts() {
     ].join('\n'));
   }
   execSync('openssl req -x509 -newkey rsa:2048 -keyout "' + keyPath + '" -out "' + certPath + '" -days 3650 -nodes -config "' + confPath + '"', { stdio: 'pipe' });
-  process.stderr.write('[mcp-word-bridge] Certificate generated at ' + CERTS_DIR + '\n');
-  process.stderr.write('[mcp-word-bridge] NOTE: You may need to trust this cert in your OS keychain for Word to connect.\n');
+  process.stderr.write('[mcp-word-bridge] ✓ Certificate generated.\n');
+  process.stderr.write('[mcp-word-bridge]\n');
+  process.stderr.write('[mcp-word-bridge] To trust the certificate (required once for Word to connect):\n');
+  if (process.platform === 'darwin') {
+    process.stderr.write('[mcp-word-bridge]   security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain-db "' + certPath + '"\n');
+  } else if (process.platform === 'win32') {
+    process.stderr.write('[mcp-word-bridge]   certutil -user -addstore Root "' + certPath + '"\n');
+  } else {
+    process.stderr.write('[mcp-word-bridge]   sudo cp "' + certPath + '" /usr/local/share/ca-certificates/ && sudo update-ca-certificates\n');
+  }
+  process.stderr.write('[mcp-word-bridge]\n');
 }
 
 ensureCerts();
@@ -176,6 +185,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'] } },
@@ -254,6 +265,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',
@@ -279,8 +291,8 @@ const toolActionMap = {
 };
 
 const mcpServer = new Server(
-  { name: 'mcp-word-bridge', version: '3.2.0' },
-  { capabilities: { tools: {} } }
+  { name: 'mcp-word-bridge', version: '3.3.0' },
+  { capabilities: { tools: {}, resources: {} } }
 );
 
 mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
@@ -297,18 +309,138 @@ 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: [
+    {
+      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.3",
+  "version": "3.3.0",
   "description": "MCP server for live Word document editing via Office Add-in",
   "main": "index.js",
   "bin": {

package/taskpane-app.js

@@ -1113,6 +1113,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;