mcp-word-bridge 3.5.3 → 4.0.0

package/README.md

@@ -1,48 +1,45 @@
 # 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
-
-```
-MCP Client←stdio→index.js←WebSocket→Taskpane (Office Add-in)←→Word JS API←→Word Document
-```
+## Quick Start
 
-Single process. The MCP client spawns `index.js`, which starts both the HTTPS bridge server (for the add-in) and the MCP server (on stdio). Everything starts and stops together.
+### 1. Add to your MCP client
 
-## Setup
+```json
+{
+  "mcpServers": {
+    "word-bridge": {
+      "command": "npx",
+      "args": ["-y", "mcp-word-bridge"]
+    }
+  }
+}
+```
 
-### 1. Install and sideload the add-in
+### 2. Install the Word add-in
 
 ```bash
 npx mcp-word-bridge-install
 ```
 
-This copies the manifest into Word's sideload directory. On macOS it's automatic; on Windows it attempts the standard location and prints manual steps if needed.
-
 Restart Word → Home → Add-ins → **MCP Word Bridge**
 
-### 2. Add MCP config
+### 3. Trust the TLS certificate (first time only)
 
-Add to your MCP client configuration:
+On first run the server auto-generates a self-signed localhost certificate and prints the trust command. Run it once:
 
-```json
-{
-  "mcpServers": {
-    "word-bridge": {
-      "command": "npx",
-      "args": ["-y", "mcp-word-bridge"]
-    }
-  }
-}
+```bash
+# macOS
+security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain-db "$(npm root -g)/mcp-word-bridge/certs/cert.pem"
+
+# Windows
+certutil -user -addstore Root "%APPDATA%\npm\node_modules\mcp-word-bridge\certs\cert.pem"
 ```
 
-### 3. Open Word and activate the add-in
+### 4. Open Word and activate
 
-Open Word → Home → Add-ins → MCP Word Bridge
+Open Word → Home → Add-ins → MCP Word Bridge. The taskpane shows "Word: connected ✓" and "WebSocket: connected ✓".
 
 That's it. The MCP server starts automatically when your MCP client loads the config, and stops when it unloads.
 
@@ -50,36 +47,16 @@ That's it. The MCP server starts automatically when your MCP client loads the co
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `MCP_WORD_BRIDGE_PORT` | `3000` | HTTPS port for the bridge server. Must match the manifest `SourceLocation`. |
+| `MCP_WORD_BRIDGE_PORT` | `3000` | HTTPS port for the bridge server |
 
-## File Layout
+## How It Works
 
 ```
-mcp-word-bridge/
-├── index.js              # Entry point: HTTPS server + MCP handlers + WebSocket relay
-├── lib/
-│   ├── tools.js          # Tool definitions 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
-├── 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
+MCP Client ←stdio→ Server ←WebSocket→ Taskpane (Office Add-in) ←→ Word JS API ←→ Document
 ```
 
+Single process. The MCP client spawns the server, which starts both the HTTPS bridge (for the add-in) and the MCP protocol handler (on stdio). Everything starts and stops together.
+
 ## Tools (92)
 
 ### Document
@@ -89,7 +66,7 @@ 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_clear` | Clear all document body content |
 | `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 |
@@ -132,7 +109,7 @@ mcp-word-bridge/
 | Tool | Description |
 |------|-------------|
 | `word_insert_table` | Insert a table with data and optional style |
-| `word_list_tables` | List table metadata (count, dimensions, style) — no cell values |
+| `word_list_tables` | List table metadata (count, dimensions, style) |
 | `word_get_table_data` | Get cell values from a specific table |
 | `word_set_table_cell` | Set text in a cell |
 | `word_add_table_row` | Add a row with optional values |
@@ -223,7 +200,7 @@ mcp-word-bridge/
 | `word_get_sections` | List all sections with page setup |
 | `word_insert_page_break` | Insert a page break after a paragraph |
 | `word_insert_section_break` | Insert a section break after a paragraph |
-| `word_get_page_info` | Get page count and per-page paragraphs with document indices (Desktop only) |
+| `word_get_page_info` | Get page count and per-page paragraph ranges (Desktop only) |
 
 ### Custom Properties
 | Tool | Description |
@@ -243,118 +220,73 @@ mcp-word-bridge/
 ### Equations
 | Tool | Description |
 |------|-------------|
-| `word_insert_equation` | Insert a LaTeX equation as a native editable Word equation. Display (block) or inline mode with optional anchor text positioning. |
+| `word_insert_equation` | Insert a LaTeX equation as a native editable Word equation |
 
 ### Batch
 | Tool | Description |
 |------|-------------|
-| `word_batch` | Execute up to 50 operations in a single call. Native ops are bundled into one message to Word for maximum speed. |
-
-## How it works
-
-1. The MCP client spawns `index.js` via stdio
-2. `index.js` starts an HTTPS server on port 3000 (serves taskpane + WebSocket relay)
-3. The Word add-in taskpane connects via WebSocket
-4. MCP tool calls are forwarded to the taskpane, which executes them via the Word JS API
-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.
+| `word_batch` | Execute up to 50 operations in a single call |
 
 ## Equations
 
-`word_insert_equation` converts LaTeX math to native Word equations via:
+`word_insert_equation` converts LaTeX math to native Word equations:
 
 ```
 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
-  - With `anchorText`: searches for the text and inserts the equation after the match (recommended — no manual cursor positioning needed)
-  - Without `anchorText`: inserts at wherever the cursor currently is
-- Supports: fractions, roots, integrals, sums, products, matrices, Greek letters, piecewise functions, aligned systems, and all standard LaTeX math
+- **Display mode** (default): centered block equation
+- **Inline mode** (`displayMode: false`): within a paragraph, optionally positioned via `anchorText`
+- Supports: fractions, roots, integrals, sums, matrices, Greek letters, AMS math
 - Equations are fully editable in Word's built-in equation editor
-- Invalid LaTeX returns a descriptive error message
+
+## Resources
+
+The server exposes an MCP resource at `word-bridge://usage-guide` containing patterns and best practices for LLMs operating on Word documents.
 
 ## 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:
+Auto-generated on first run. The server prints the trust command:
 
 ```
 [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"
+[mcp-word-bridge] Trust it: 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.
+Run it once. To regenerate: delete `certs/cert.pem` and `certs/key.pem`, then restart.
+
+## Development
 
-**To regenerate:**
 ```bash
-rm certs/cert.pem certs/key.pem
-# restart the MCP server — it will regenerate and print the trust command again
+git clone https://github.com/likelion/mcp-word-bridge.git
+cd mcp-word-bridge
+npm install
+npm run build        # build server + taskpane
+npm run dev          # watch mode
+npm run typecheck    # TypeScript type checking
+npm test             # unit tests (67 tests, <500ms)
+npm run test:live    # integration tests (requires Word)
 ```
 
-## Known Limitations & Word API Behavior
-
-### Search defaults
-
-All search-based operations (search, search_and_replace, format_text, insert_footnote, add_comment, etc.) are **case-insensitive by default**. Pass `matchCase: true` for exact case matching.
-
-### TOC paragraphs
-
-`get_paragraphs` includes a `isTocEntry` boolean field to distinguish Table of Contents entries from body content. TOC entries have styles starting with "TOC" (e.g., "TOC 1", "TOC 2").
-
-### Alignment values
-
-The Word JS API uses specific enum strings for paragraph alignment. The bridge accepts common aliases and normalizes them:
-
-| You can pass | API receives |
-|---|---|
-| `Left` | `Left` |
-| `Center` or `Centered` | `Centered` |
-| `Right` | `Right` |
-| `Justify` or `Justified` | `Justified` |
-
-### Content controls and search
-
-In heavily-mutated documents (many rapid operations in a single session), text adjacent to content controls may occasionally become invisible to `search`. This is a transient Word API state issue. If search fails to find text you know exists, saving and reopening the document typically resolves it.
-
-### CheckBox content controls
-
-CheckBox content controls are atomic widgets — they REPLACE the anchor text with a checkbox glyph (☐), unlike RichText and PlainText which wrap the text. `set_content_control_text` cannot modify CheckBox controls (they only support checked/unchecked state).
+### Project Structure
 
-### Table cell paragraphs
-
-Table cells always contain at least one paragraph. `delete_paragraph` on a table cell paragraph clears the cell text but cannot remove the structural cell itself. `insert_section_break` and `insert_page_break` cannot target paragraphs inside table cells (Word constraint).
-
-### Tracked changes coalescing
-
-Adjacent insertions by the same author at the same timestamp are merged into a single tracked change by Word. Two separate `insert_paragraph` calls may appear as one revision in `get_tracked_changes`.
-
-### Tracked changes and replacements
-
-When `search_and_replace` creates a tracked change with tracking enabled, the Word API may only expose the "Added" half of the replacement. The "Deleted" half can appear later (often with empty text) after the "Added" change is accepted. This is a Word API limitation. Use `accept_all_tracked_changes` when you don't need granular control.
-
-### TOC and duplicate text
-
-After inserting a Table of Contents, heading text appears twice in the document (once in the TOC, once in the body). Search-based operations will match TOC entries first. Use the `occurrence` parameter (0-indexed) to target the correct instance.
-
-### Hyperlink indices
-
-`get_hyperlinks` returns indices from the underlying fields collection (which includes non-hyperlink fields). Indices may be non-contiguous — this is by design for cross-referencing with `get_fields`.
-
-### Document path
-
-`path` in `get_document_properties` is only reliable for documents saved to a user-chosen location with a `.docx` extension. For unsaved documents or auto-saved container documents, it returns `null`. Save the document explicitly (File → Save As) if you need the file path.
-
-### Line spacing units
-
-`lineSpacing` in `set_paragraph_spacing` and `get_paragraph_by_index` is in **points** (not a multiplier). For a 12pt font: 12 = single spacing, 18 = 1.5x, 24 = double spacing.
+```
+src/
+├── server/           # MCP server (Node.js)
+│   ├── tools/        # One file per tool category
+│   ├── bridge.ts     # WebSocket bridge to taskpane
+│   ├── mcp.ts        # MCP protocol handlers
+│   └── validation.ts # Shared input validators
+├── taskpane/         # Runs inside Word's add-in webview
+│   ├── commands/     # One file per command category
+│   └── log.ts        # Taskpane UI logger
+├── shared/           # Types shared between server and taskpane
+│   ├── protocol.ts   # WebSocket message types
+│   └── constants.ts  # Limits and timeouts
+└── lib/
+    └── equations.ts  # LaTeX→OMML conversion pipeline
+```
 
-### Paragraph ordering with concurrent inserts
+## License
 
-When multiple paragraphs are inserted at `"End"` in rapid succession, Word may reorder them based on heading level or style hierarchy. For guaranteed ordering, insert sequentially and verify with `get_paragraphs`.
+MIT