mcp-word-bridge 4.0.2 → 4.0.4

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.
 
 ## Quick Start

package/dist/server.js

@@ -18722,7 +18722,7 @@ var Bridge = class {
 
 // src/server/mcp.ts
 var import_server = require("@modelcontextprotocol/sdk/server/index.js");
-var import_types5 = require("@modelcontextprotocol/sdk/types.js");
+var import_types7 = require("@modelcontextprotocol/sdk/types.js");
 
 // src/server/tools/helpers.ts
 function jsonResult(data) {
@@ -18874,9 +18874,23 @@ var ToolError = class extends Error {
 };
 
 // src/server/validation.ts
+var WORD_SPECIAL_CODES = /\^(p|w|t|l|m|b|n|s|d|a|e|f|g|v|~|\^|\-|13|11|14|12|07|09|30|31|32|34|36|37|38|39|40|41|42|43|44|45|46|47|92|94|127|129|130|131|132|133|134|135|136|137|138|139|140|141|142|143|144|145|146|147|148|149|150|151|152|153|154|155|156|157|158|159|160|161|162|163|164|165|166|167|168|169|170|171|172|173|174|175|176|177|178|179|180|181|182|183|184|185|186|187|188|189|190|191|192|193|194|195|196|197|198|199|200|201|202|203|204|205|206|207|208|209|210|211|212|213|214|215|216|217|218|219|220|221|222|223|224|225|226|227|228|229|230|231|232|233|234|235|236|237|238|239|240|241|242|243|244|245|246|247|248|249|250|251|252|253|254|255)/;
+function checkNoSpecialCodes(text2, paramName) {
+  const match = text2.match(WORD_SPECIAL_CODES);
+  if (match) {
+    throw new ToolError(
+      `${paramName} contains Word special code "${match[0]}" which can corrupt document structure. Use literal text only. Common special codes: ^p (paragraph mark), ^t (tab), ^w (whitespace), ^13 (paragraph mark).`
+    );
+  }
+}
+function checkNonEmpty(value, name) {
+  if (!value || typeof value !== "string" || value.trim() === "") {
+    throw new ToolError(`${name} must be a non-empty string.`);
+  }
+}
 function checkNonNegative(value, name) {
-  if (typeof value !== "number" || value < 0) {
-    throw new ToolError(`${name} must be non-negative.`);
+  if (typeof value !== "number" || value < 0 || !Number.isInteger(value)) {
+    throw new ToolError(`${name} must be a non-negative integer.`);
   }
 }
 function checkBounds(index, count, name) {
@@ -18898,6 +18912,22 @@ function checkOccurrence(occurrence, count) {
   }
   return idx;
 }
+var MAX_SPACING_POINTS = 1584;
+var MAX_CUSTOM_PROPERTY_KEY_LENGTH = 255;
+function checkSpacingBounds(value, name) {
+  if (value > MAX_SPACING_POINTS) {
+    throw new ToolError(
+      `${name} value ${value} exceeds maximum (${MAX_SPACING_POINTS} points = 22 inches). Use a value between 0 and ${MAX_SPACING_POINTS}.`
+    );
+  }
+}
+function checkPropertyKeyLength(key) {
+  if (key.length > MAX_CUSTOM_PROPERTY_KEY_LENGTH) {
+    throw new ToolError(
+      `key must be ${MAX_CUSTOM_PROPERTY_KEY_LENGTH} characters or fewer (got ${key.length}).`
+    );
+  }
+}
 
 // src/server/tools/paragraphs.ts
 var getParagraphs = forwardTool(
@@ -18987,10 +19017,10 @@ var setParagraphStyle = forwardTool(
   },
   "setParagraphStyle"
 );
-var setParagraphSpacing = forwardTool(
-  "word_set_paragraph_spacing",
-  "[Paragraphs] Set line spacing, before/after spacing, and indentation on a paragraph by index.",
-  {
+var setParagraphSpacing = {
+  name: "word_set_paragraph_spacing",
+  description: "[Paragraphs] Set line spacing, before/after spacing, and indentation on a paragraph by index.",
+  schema: {
     properties: {
       index: { type: "number", description: "Paragraph index (0-based)" },
       lineSpacing: { type: "number", description: "Line spacing in points" },
@@ -19002,8 +19032,26 @@ var setParagraphSpacing = forwardTool(
     },
     required: ["index"]
   },
-  "setParagraphSpacing"
-);
+  async handler(args, bridge2) {
+    const index = args.index;
+    checkNonNegative(index, "index");
+    const spacingFields = [
+      ["lineSpacing", args.lineSpacing],
+      ["spaceBefore", args.spaceBefore],
+      ["spaceAfter", args.spaceAfter],
+      ["firstLineIndent", args.firstLineIndent],
+      ["leftIndent", args.leftIndent],
+      ["rightIndent", args.rightIndent]
+    ];
+    for (const [name, value] of spacingFields) {
+      if (value !== void 0 && typeof value === "number") {
+        checkSpacingBounds(value, name);
+      }
+    }
+    const result = await bridge2.send("setParagraphSpacing", args);
+    return jsonResult(result);
+  }
+};
 var moveParagraph = {
   name: "word_move_paragraph",
   description: "[Paragraphs] Move paragraph(s) to another position. Preserves all rich content including footnotes, hyperlinks, formatting, images, and comments.",
@@ -19023,6 +19071,7 @@ var moveParagraph = {
     const location = args.location ?? "After";
     checkNonNegative(fromIndex, "fromIndex");
     checkNonNegative(toIndex, "toIndex");
+    if (!Number.isInteger(count)) throw new ToolError("count must be an integer.");
     if (count < 1) throw new ToolError("count must be at least 1");
     if (fromIndex === toIndex && count === 1) throw new ToolError("fromIndex and toIndex must be different");
     if (toIndex >= fromIndex && toIndex < fromIndex + count) {
@@ -19071,6 +19120,7 @@ var copyParagraph = {
     const location = args.location ?? "After";
     checkNonNegative(fromIndex, "fromIndex");
     checkNonNegative(toIndex, "toIndex");
+    if (!Number.isInteger(count)) throw new ToolError("count must be an integer.");
     if (count < 1) throw new ToolError("count must be at least 1");
     const paraCount = await bridge2.send("getParagraphs", {});
     const total = paraCount.count;
@@ -19109,10 +19159,10 @@ var search = forwardTool(
   },
   "search"
 );
-var searchAndReplace = forwardTool(
-  "word_search_and_replace",
-  "[Search] Find and replace ALL occurrences. For single-paragraph edits, prefer word_replace_paragraph_text.",
-  {
+var searchAndReplace = {
+  name: "word_search_and_replace",
+  description: "[Search] Find and replace ALL occurrences. For single-paragraph edits, prefer word_replace_paragraph_text.",
+  schema: {
     properties: {
       find: { type: "string" },
       replace: { type: "string" },
@@ -19121,8 +19171,18 @@ var searchAndReplace = forwardTool(
     },
     required: ["find", "replace"]
   },
-  "searchAndReplace"
-);
+  async handler(args, bridge2) {
+    const find = args.find;
+    const replace = args.replace;
+    if (!find || typeof find !== "string" || find.trim() === "") {
+      throw new ToolError("find string cannot be empty.");
+    }
+    checkNoSpecialCodes(find, "find");
+    checkNoSpecialCodes(replace, "replace");
+    const result = await bridge2.send("searchAndReplace", args);
+    return jsonResult(result);
+  }
+};
 var insertTextAtMatch = forwardTool(
   "word_insert_text_at_match",
   '[Search] Insert text before or after a search match. Provide "after" OR "before" as the anchor text. Use occurrence for Nth match.',
@@ -19703,10 +19763,10 @@ var insertContentControl = forwardTool(
   },
   "insertContentControl"
 );
-var setContentControlText = forwardTool(
-  "word_set_content_control_text",
-  "[Content Controls] Set text in a content control identified by ID or tag. Does NOT work on CheckBox controls.",
-  {
+var setContentControlText = {
+  name: "word_set_content_control_text",
+  description: "[Content Controls] Set text in a content control identified by ID or tag. Does NOT work on CheckBox controls.",
+  schema: {
     properties: {
       id: { type: "number", description: "Content control ID" },
       tag: { type: "string", description: "Content control tag (alternative to ID)" },
@@ -19714,8 +19774,25 @@ var setContentControlText = forwardTool(
     },
     required: ["text"]
   },
-  "setContentControlText"
-);
+  async handler(args, bridge2) {
+    const tag = args.tag;
+    const id = args.id;
+    if (!tag && id === void 0) {
+      throw new ToolError('Provide "id" or "tag" to identify the content control. Use word_get_content_controls to list available controls.');
+    }
+    if (tag) {
+      const ccResult = await bridge2.send("getContentControls", {});
+      const matches = ccResult.controls.filter((c) => c.tag === tag);
+      if (matches.length > 1) {
+        throw new ToolError(
+          `Multiple content controls (${matches.length}) share tag "${tag}". Use "id" instead to target a specific control. Matching IDs: ${matches.map((m) => m.id).join(", ")}.`
+        );
+      }
+    }
+    const result = await bridge2.send("setContentControlText", args);
+    return jsonResult(result);
+  }
+};
 var contentControlTools = [
   getContentControls,
   insertContentControl,
@@ -19930,18 +20007,24 @@ var getCustomProperties = forwardTool(
   { properties: {} },
   "getCustomProperties"
 );
-var setCustomProperty = forwardTool(
-  "word_set_custom_property",
-  "[Properties] Set a custom document property. Creates or updates the key-value pair.",
-  {
+var setCustomProperty = {
+  name: "word_set_custom_property",
+  description: "[Properties] Set a custom document property. Creates or updates the key-value pair.",
+  schema: {
     properties: {
       key: { type: "string" },
       value: { type: "string" }
     },
     required: ["key", "value"]
   },
-  "setCustomProperty"
-);
+  async handler(args, bridge2) {
+    const key = args.key;
+    checkNonEmpty(key, "key");
+    checkPropertyKeyLength(key);
+    const result = await bridge2.send("setCustomProperty", args);
+    return jsonResult(result);
+  }
+};
 var deleteCustomProperty = forwardTool(
   "word_delete_custom_property",
   "[Properties] Delete a custom document property by key.",
@@ -20203,112 +20286,178 @@ function buildToolRegistry() {
 // src/server/usage-guide.ts
 var usageGuide = `# MCP Word Bridge \u2014 Usage Guide
 
-Controls a live Word document through an Office Add-in. All operations execute immediately in Word.
+Controls a live Word document. All operations execute immediately.
 
 ## Quick Start
 
-1. **Read before writing** \u2014 call \`word_get_document_outline\` or \`word_get_paragraphs\` to understand the document structure
-2. **Use the right tool for the job:**
-   - Appending content \u2192 \`word_insert_paragraph\` (Start/End)
-   - Inserting at a position \u2192 \`word_insert_paragraph_at_index\` (Before/After by index)
-   - Editing existing text \u2192 \`word_replace_paragraph_text\` (by index, safe for collaboration)
+1. **Read before writing** \u2014 call \`word_get_document_outline\` or \`word_get_paragraphs\` to understand structure
+2. **Use the right tool:**
+   - Append content \u2192 \`word_insert_paragraph\` (Start/End)
+   - Insert at position \u2192 \`word_insert_paragraph_at_index\` (Before/After by index)
+   - Edit existing text \u2192 \`word_replace_paragraph_text\` (by index, preferred)
    - Bulk find/replace \u2192 \`word_search_and_replace\` (all occurrences)
-   - Inserting adjacent to text \u2192 \`word_insert_text_at_match\` (searches then inserts)
-3. **Batch multiple operations** \u2014 use \`word_batch\` to send up to 50 operations in one call
+   - Insert adjacent to text \u2192 \`word_insert_text_at_match\` (searches then inserts)
+3. **Batch operations** \u2014 use \`word_batch\` for multiple operations in one call (faster, fewer round-trips)
 4. **Save explicitly** \u2014 call \`word_save\` after significant changes
 
-## Reading Content
-- \`word_get_document_outline\` \u2014 heading hierarchy (fast structural overview)
-- \`word_get_paragraphs\` \u2014 all paragraphs with text, style, alignment. Paginate with start/end.
-- \`word_get_text\` \u2014 quick plain-text dump
+## Reading
+
+- \`word_get_document_outline\` \u2014 heading tree (fast structural overview)
+- \`word_get_paragraphs\` \u2014 paragraphs with text, style, alignment. Paginate with start/end.
+- \`word_get_paragraph_by_index\` \u2014 full details of one paragraph (font, spacing, indent)
+- \`word_get_text\` \u2014 plain-text dump (no structure)
 - \`word_search\` \u2014 locate text before operating on it
 
-## Editing Text
-- \`word_replace_paragraph_text\` \u2014 replace text by paragraph index (PREFERRED for collaborative docs)
+## Editing
+
+- \`word_replace_paragraph_text\` \u2014 replace by index (safe for collaboration, preserves style)
 - \`word_search_and_replace\` \u2014 bulk find/replace across document
-- \`word_insert_text_at_match\` \u2014 insert before/after a search match
-- \`word_move_paragraph\` \u2014 reorder content (avoids index-shifting bugs with manual delete+insert)
-- \`word_copy_paragraph\` \u2014 duplicate content with full fidelity (footnotes, formatting, hyperlinks preserved)
+- \`word_insert_text_at_match\` \u2014 insert before/after a search match (use \`occurrence\` for Nth)
+- \`word_move_paragraph\` \u2014 reorder content (preserves footnotes, formatting, hyperlinks)
+- \`word_copy_paragraph\` \u2014 duplicate content with full fidelity
+- Verify edits with \`word_search\` or \`word_get_paragraphs\`
+
+## Batch
 
-## Batch Operations
-\`word_batch\` executes multiple operations in a single MCP call:
 \`\`\`json
 {"operations": [
   {"tool": "word_insert_paragraph", "args": {"text": "Hello", "style": "Heading 1"}},
-  {"tool": "word_insert_paragraph", "args": {"text": "World", "style": "Normal"}},
-  {"tool": "word_save", "args": {}}
+  {"tool": "word_insert_paragraph", "args": {"text": "World"}},
+  {"tool": "word_format_text", "args": {"text": "Hello", "bold": true}}
 ]}
 \`\`\`
-Operations run sequentially. If one fails, the rest are skipped. Maximum 50 per batch.
+Runs sequentially. Stops on first error. Maximum 50 per batch. Prefer batching over individual calls.
 
-## Search Behavior
-- Case-insensitive by default. Pass \`matchCase: true\` for exact case match.
-- Query must be \u2264255 characters.
-- Affected tools: search, search_and_replace, insert_text_at_match, format_text, insert_footnote, add_comment, insert_hyperlink, insert_bookmark, insert_content_control, clear_formatting, get_font_info, insert_line_break, remove_hyperlink, insert_endnote, insert_equation (inline with anchor).
+## Search
 
-## Alignment Values
-Accepts: Left, Center/Centered, Right, Justify/Justified.
+- Case-insensitive by default. Pass \`matchCase: true\` for exact case.
+- Text parameters must be \u2264255 characters.
+- Use \`occurrence\` (0-indexed) to target the Nth match when multiple exist.
 
-## Change Tracking
-- Call \`word_set_change_tracking({mode:"TrackAll"})\` BEFORE edits for tracked changes
-- \`search_and_replace\` with tracking may only expose the "Added" half
+## Comments \u2014 Important
 
-## Comments
-- \`word_get_comments\` returns all comments with their anchor text
-- **\`word_search_and_replace\` on text anchoring a comment deletes the comment** \u2014 check comments first
-- Safe pattern: get_comments \u2192 reply/resolve \u2192 then replace text
+- \`word_get_comments\` returns comments with their anchor text
+- **Replacing text that anchors a comment deletes the comment** \u2014 always check comments first
+- Safe pattern: \`word_get_comments\` \u2192 \`word_reply_to_comment\`/\`word_resolve_comment\` \u2192 then replace
 
 ## Tables
+
 - All indices 0-based: tableIndex, row, col
-- \`word_list_tables\` for metadata (no cell values) \u2192 \`word_get_table_data\` for content
-- Can't insert page/section breaks inside table cells
+- \`word_list_tables\` for metadata \u2192 \`word_get_table_data\` for cell values
+- Cannot insert page/section breaks inside table cells
 
 ## Footnotes & Endnotes
-- \`word_insert_footnote\` \u2014 anchor to text match
-- \`word_insert_footnote_at_index\` \u2014 anchor to paragraph by index (no search needed)
+
+- \`word_insert_footnote\` \u2014 anchor to a text match
+- \`word_insert_footnote_at_index\` \u2014 anchor to a paragraph by index (no search needed)
 
 ## Page Layout
+
 - Margins in points (72 pt = 1 inch)
-- \`lineSpacing\` in points, not a multiplier (12pt font: 12=single, 18=1.5x, 24=double)
+- \`lineSpacing\` 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 (cannot use set_content_control_text)
 
-## TOC Behavior
+- RichText/PlainText: wraps anchor text (non-destructive)
+- CheckBox: REPLACES anchor text with a checkbox (cannot set text after)
+
+## TOC
+
 After inserting a Table of Contents, heading text appears twice (in TOC and body). Search matches TOC entries first \u2014 use \`occurrence\` to target the body instance.
 
 ## Equations
-- Takes a LaTeX string, inserts a native Word equation
-- \`displayMode: true\` (default) = centered block, \`false\` = inline
-- For inline, provide \`anchorText\` to position after a search match
+
+- \`word_insert_equation\` takes LaTeX, inserts a native editable Word equation
+- \`displayMode: true\` (default) = centered block equation
+- \`displayMode: false\` = inline; provide \`anchorText\` to position after a match
 - Supports: fractions, roots, integrals, sums, matrices, Greek letters, AMS math
+- Examples: \`\\\\frac{a}{b}\`, \`\\\\int_0^\\\\infty e^{-x} dx\`, \`\\\\sum_{i=1}^n x_i\`
+
+## Change Tracking
 
-## Error Messages
-- "Word taskpane not connected" \u2014 user must open the MCP Word Bridge add-in in Word
-- "Anchor not found" \u2014 search text not found in document
-- "Occurrence N not found" \u2014 match index out of range
+- Call \`word_set_change_tracking({mode:"TrackAll"})\` BEFORE edits to track them
+- Tracked edits appear as revisions in Word (visible to collaborators)
 
 ## Best Practices
-1. Start with \`word_get_document_outline\` to understand structure
-2. \`word_get_comments\` before bulk replacements to avoid anchor damage
-3. Use \`word_batch\` for multiple sequential operations
-4. In collaborative editing, prefer index-based tools over search-based
-5. Enable change tracking for collaborative documents
-6. \`word_save\` explicitly after significant changes
-7. Resolve comments rather than deleting them (preserves audit trail)
-8. Use \`word_move_paragraph\` to reorder content
-9. Use \`word_copy_paragraph\` to duplicate content with full fidelity
+
+1. Read structure first (\`word_get_document_outline\`)
+2. Check comments before bulk replacements (\`word_get_comments\`)
+3. Batch multiple operations (\`word_batch\`)
+4. Prefer index-based tools over search-based in collaborative editing
+5. Use \`word_move_paragraph\` to reorder (not delete+insert)
+6. Use \`word_copy_paragraph\` to duplicate (preserves everything)
+7. Save explicitly after significant changes
+8. Resolve comments rather than deleting (preserves audit trail)
 `;
 
+// package.json
+var package_default = {
+  name: "mcp-word-bridge",
+  version: "4.0.4",
+  description: "MCP server for live Word document editing via Office Add-in",
+  main: "dist/server.js",
+  bin: {
+    "mcp-word-bridge": "dist/server.js",
+    "mcp-word-bridge-install": "scripts/install-manifest.js"
+  },
+  scripts: {
+    build: "node scripts/build.mjs",
+    start: "node dist/server.cjs",
+    dev: "node scripts/build.mjs --watch",
+    test: "vitest run",
+    "test:ci": "vitest run --reporter=default",
+    "test:live": "vitest run --config vitest.live.config.ts",
+    lint: "eslint src/",
+    typecheck: "tsc --noEmit",
+    prepublishOnly: "npm run build"
+  },
+  keywords: [
+    "mcp",
+    "word",
+    "office",
+    "add-in",
+    "document",
+    "editing"
+  ],
+  repository: {
+    type: "git",
+    url: "https://github.com/likelion/mcp-word-bridge.git"
+  },
+  author: "Leonid Mokrushin <likelion@gmail.com>",
+  license: "MIT",
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    mathml2omml: "^0.5.0",
+    temml: "^0.13.3",
+    ws: "^8.16.0"
+  },
+  devDependencies: {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.10",
+    "@vitest/coverage-v8": "^3.2.6",
+    esbuild: "^0.25.0",
+    eslint: "^10.4.1",
+    typescript: "^5.7.0",
+    "typescript-eslint": "^8.0.0",
+    vitest: "^3.0.0"
+  },
+  files: [
+    "dist/",
+    "certs/cert.conf",
+    "taskpane.html",
+    "manifest.xml",
+    "scripts/install-manifest.js"
+  ]
+};
+
 // src/server/mcp.ts
 function createMcpServer(bridge2) {
   const server = new import_server.Server(
-    { name: "mcp-word-bridge", version: "4.0.2" },
+    { name: "mcp-word-bridge", version: package_default.version },
     { capabilities: { tools: {}, resources: {} } }
   );
   const { tools, handlers } = buildToolRegistry();
-  server.setRequestHandler(import_types5.ListToolsRequestSchema, async () => ({
+  server.setRequestHandler(import_types7.ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({
       name: t.name,
       description: t.description,
@@ -20319,7 +20468,7 @@ function createMcpServer(bridge2) {
       }
     }))
   }));
-  server.setRequestHandler(import_types5.CallToolRequestSchema, async (request) => {
+  server.setRequestHandler(import_types7.CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const handler = handlers.get(name);
     if (!handler) {
@@ -20333,7 +20482,7 @@ function createMcpServer(bridge2) {
       return { content: [{ type: "text", text: msg }], isError: true };
     }
   });
-  server.setRequestHandler(import_types5.ListResourcesRequestSchema, async () => ({
+  server.setRequestHandler(import_types7.ListResourcesRequestSchema, async () => ({
     resources: [{
       uri: "word-bridge://usage-guide",
       name: "Word Bridge Usage Guide",
@@ -20341,7 +20490,7 @@ function createMcpServer(bridge2) {
       mimeType: "text/markdown"
     }]
   }));
-  server.setRequestHandler(import_types5.ReadResourceRequestSchema, async (request) => {
+  server.setRequestHandler(import_types7.ReadResourceRequestSchema, async (request) => {
     if (request.params.uri === "word-bridge://usage-guide") {
       return { contents: [{ uri: request.params.uri, mimeType: "text/markdown", text: usageGuide }] };
     }