@xevos117/mcp-zotero 1.0.2

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2025 Xevos117
+
+Based on mcp-zotero by Abhishek Kalia (https://github.com/kaliaboi/mcp-zotero),
+Copyright (c) 2024 Abhishek Kalia, licensed under the MIT License.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# MCP Zotero
+
+> **Note:** This is an unofficial community project and is not affiliated with, endorsed by, or supported by the Zotero team or the Corporation for Digital Scholarship. "Zotero" is a registered trademark of the Corporation for Digital Scholarship.
+
+A Model Context Protocol server for Zotero integration. It gives any LLM full access to your Zotero library: search, organize, add papers by DOI, import PDFs, read full-text content, and inject live citations into Word documents.
+
+> Originally based on [mcp-zotero](https://github.com/kaliaboi/mcp-zotero) by Abhishek Kalia.
+> This project has since been extensively rewritten with a new architecture, 13 tools (up from 5), citation injection, PDF management, and Claude skill support.
+
+## How it works
+
+The server is designed to be **usable by any LLM without external documentation**. On connection, it sends workflow instructions via the MCP `instructions` field, and each tool description includes cross-references and usage guidance. An LLM that has never seen this server before can discover the full workflow — from adding papers to producing a cited Word document — directly from the tool listing.
+
+For advanced use cases (PDF upload policy, citation style guidance, source transparency), a **Claude skill** is included for Claude.ai Projects. But the skill is optional: the MCP server is fully self-documenting.
+
+## Local vs Remote LLMs
+
+| Scenario | MCP server | Skill needed? |
+|---|---|---|
+| Local LLM (Claude Code, LM Studio, etc.) | All 13 tools | No |
+| Remote/sandboxed LLM (Claude.ai Projects) | API tools (search, add, metadata) | Yes, for citation injection |
+
+Local LLMs with filesystem access can use all tools directly, including `inject_citations` which reads and writes `.docx` files on disk.
+
+Remote LLMs without filesystem access can use the included **Claude skill** (`skills/zotero-skill-mcp-integrations/`), which runs citation injection entirely inside the sandbox. MCP tools handle all Zotero API operations; the skill handles document assembly.
+
+## Setup
+
+1. Get your Zotero credentials:
+
+   ```bash
+   # Create an API key at https://www.zotero.org/settings/keys
+   # (enable library read/write + file access)
+   # Then retrieve your user ID:
+   curl -H "Zotero-API-Key: YOUR_API_KEY" https://api.zotero.org/keys/current
+   ```
+
+2. Set environment variables:
+
+   ```bash
+   export ZOTERO_API_KEY="your-api-key"
+   export ZOTERO_USER_ID="user-id-from-curl"
+   export UNPAYWALL_EMAIL="your@email.edu"   # Optional: enables OA PDF lookup via Unpaywall
+   ```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `ZOTERO_API_KEY` | Yes | API key for Zotero Web API v3. Create one at [zotero.org/settings/keys](https://www.zotero.org/settings/keys) with library read/write and file access permissions. |
+| `ZOTERO_USER_ID` | Yes | Your Zotero numeric user ID. Retrieve it with `curl -H "Zotero-API-Key: KEY" https://api.zotero.org/keys/current`. |
+| `UNPAYWALL_EMAIL` | No | Email for Unpaywall API requests ([rate-limit policy](https://unpaywall.org/products/api)). Enables OA PDF lookup in `add_items_by_doi` and `find_and_attach_pdfs`. If not set, OA PDF features are silently skipped. |
+
+## Integration with Claude Desktop
+
+Add to your Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "zotero": {
+      "command": "npx",
+      "args": ["-y", "@xevos117/mcp-zotero"],
+      "env": {
+        "ZOTERO_API_KEY": "YOUR_API_KEY",
+        "ZOTERO_USER_ID": "YOUR_USER_ID",
+        "UNPAYWALL_EMAIL": "YOUR_EMAIL"
+      }
+    }
+  }
+}
+```
+
+## Integration with Claude Code
+
+```bash
+claude mcp add-json "zotero" '{"command":"npx","args":["tsx","src/server.ts"],"env":{"ZOTERO_API_KEY":"...","ZOTERO_USER_ID":"..."}}'
+```
+
+## Available Tools
+
+### Library browsing
+
+| Tool | Description |
+|---|---|
+| `get_collections` | List all collections (folders) with keys, names, and parent relationships |
+| `get_collection_items` | Get items in a specific collection with keys, titles, authors, dates |
+| `search_library` | Search by query, or list items sorted by field (date, title, etc.) |
+| `get_items_details` | Batch metadata retrieval for multiple items in a single call |
+| `get_item_fulltext` | Get full-text content of a PDF attachment via Zotero's fulltext index |
+
+### Adding content
+
+| Tool | Description |
+|---|---|
+| `add_items_by_doi` | Add papers by DOI with automatic metadata resolution. Auto-attaches OA PDFs via Unpaywall |
+| `add_web_item` | Save a web page as a Zotero item (for articles without DOI) |
+| `create_collection` | Create a new collection, optionally nested under a parent |
+| `import_pdf_to_zotero` | Download a PDF from URL, upload to Zotero storage, auto-index full text |
+| `find_and_attach_pdfs` | Batch OA PDF lookup and auto-attach via Unpaywall (by item keys or collection) |
+| `add_linked_url_attachment` | Attach a URL to an existing item or create a standalone link |
+
+### Citation & documents
+
+| Tool | Description |
+|---|---|
+| `inject_citations` | Inject live Zotero citations into a Word document. Supports APA, IEEE, Vancouver, Harvard, Chicago |
+| `get_user_id` | Returns the configured Zotero user ID |
+
+## Development
+
+```bash
+npm install
+npm run build          # Compile TypeScript
+npm test               # Run tests (vitest, 299 tests)
+npx tsx src/server.ts  # Run directly without building
+```
+
+### Debug with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector npx tsx src/server.ts
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details.

package/build/citation-injector/citation-formatter.js

@@ -0,0 +1,30 @@
+export function formatCitationText(items, style, num) {
+    if (style === "ieee" || style === "vancouver") {
+        return num ? `[${num}]` : "[?]";
+    }
+    const parts = items.map((item) => {
+        const authors = item.author;
+        const firstAuthor = authors?.[0]?.family ?? "Unknown";
+        const year = item.issued?.["date-parts"]?.[0]?.[0]?.toString() ?? "n.d.";
+        let authorText;
+        if (!authors || authors.length === 0) {
+            const title = item.title;
+            authorText = title
+                ? title.length > 30
+                    ? `"${title.substring(0, 30)}..."`
+                    : `"${title}"`
+                : "Unknown";
+        }
+        else if (authors.length > 2) {
+            authorText = `${firstAuthor} et al.`;
+        }
+        else if (authors.length === 2) {
+            authorText = `${firstAuthor} & ${authors[1].family}`;
+        }
+        else {
+            authorText = firstAuthor;
+        }
+        return `${authorText}, ${year}`;
+    });
+    return `(${parts.join("; ")})`;
+}

package/build/citation-injector/field-codes.js

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto";
+import { escapeXml } from "./xml-utils.js";
+export function generateZoteroFieldCode(citationItems, formattedText) {
+    const citationId = randomUUID().slice(0, 8);
+    const cslCitation = {
+        citationID: citationId,
+        properties: { formattedCitation: formattedText },
+        citationItems,
+        schema: "https://github.com/citation-style-language/schema/raw/master/csl-citation.json",
+    };
+    const instrText = ` ADDIN ZOTERO_ITEM CSL_CITATION ${JSON.stringify(cslCitation)} `;
+    const escapedInstrText = escapeXml(instrText);
+    return [
+        '<w:r><w:fldChar w:fldCharType="begin"/></w:r>',
+        `<w:r><w:instrText xml:space="preserve">${escapedInstrText}</w:instrText></w:r>`,
+        '<w:r><w:fldChar w:fldCharType="separate"/></w:r>',
+        `<w:r><w:rPr><w:noProof/></w:rPr><w:t>${escapeXml(formattedText)}</w:t></w:r>`,
+        '<w:r><w:fldChar w:fldCharType="end"/></w:r>',
+    ].join("");
+}
+export function generateBibliographyFieldCode() {
+    return [
+        "<w:p>",
+        '<w:r><w:fldChar w:fldCharType="begin"/></w:r>',
+        '<w:r><w:instrText xml:space="preserve">',
+        " ADDIN ZOTERO_BIBL {&quot;uncited&quot;:[],&quot;omitted&quot;:[],&quot;custom&quot;:[]} CSL_BIBLIOGRAPHY ",
+        "</w:instrText></w:r>",
+        '<w:r><w:fldChar w:fldCharType="separate"/></w:r>',
+        "<w:r><w:rPr><w:noProof/></w:rPr><w:t>[Bibliography will be generated by Zotero]</w:t></w:r>",
+        '<w:r><w:fldChar w:fldCharType="end"/></w:r>',
+        "</w:p>",
+    ].join("");
+}

package/build/citation-injector/injector.js

@@ -0,0 +1,145 @@
+import JSZip from "jszip";
+import { readFile, writeFile } from "node:fs/promises";
+import { generateZoteroFieldCode, generateBibliographyFieldCode } from "./field-codes.js";
+import { formatCitationText } from "./citation-formatter.js";
+import { regexEscape, unescapeXml } from "./xml-utils.js";
+import { normalizeZciteTags } from "./zcite-normalizer.js";
+import { zoteroItemToCsl } from "../utils/csl-to-zotero.js";
+function parseZciteMatches(documentXml) {
+    const findRegex = /<zcite\s+[\s\S]*?\/>/g;
+    const matches = [];
+    let findMatch;
+    while ((findMatch = findRegex.exec(documentXml)) !== null) {
+        const fullMatch = findMatch[0];
+        const cleanTag = unescapeXml(fullMatch);
+        const attrRegex = /(\w+)="([^"]*)"/g;
+        const attrs = {};
+        let attrMatch;
+        while ((attrMatch = attrRegex.exec(cleanTag)) !== null) {
+            // Unescape attribute values since the zcite tag is XML
+            // and values like "pp. 12 & 15" need a second unescape
+            attrs[attrMatch[1]] = unescapeXml(attrMatch[2]);
+        }
+        if (!attrs["keys"])
+            continue;
+        matches.push({
+            fullMatch,
+            keys: attrs["keys"].split(","),
+            locator: attrs["locator"] || undefined,
+            prefix: attrs["prefix"] || undefined,
+            suffix: attrs["suffix"] || undefined,
+            num: attrs["num"] || undefined,
+        });
+    }
+    return matches;
+}
+async function fetchCslData(keys, zoteroApi, userId) {
+    const cslData = new Map();
+    for (const key of keys) {
+        const response = await zoteroApi
+            .library("user", userId)
+            .items(key)
+            .get();
+        const zoteroItem = response.getData();
+        cslData.set(key, zoteroItemToCsl(zoteroItem));
+    }
+    return cslData;
+}
+function buildCitationItems(match, cslData, userId) {
+    return match.keys.map((key, idx) => {
+        const itemData = cslData.get(key) ?? { type: "article-journal" };
+        const item = {
+            id: idx,
+            uris: [`http://zotero.org/users/${userId}/items/${key}`],
+            uri: [`http://zotero.org/users/${userId}/items/${key}`],
+            itemData,
+        };
+        if (match.locator)
+            item.locator = match.locator;
+        if (match.prefix)
+            item.prefix = match.prefix;
+        if (match.suffix)
+            item.suffix = match.suffix;
+        return item;
+    });
+}
+function replaceZciteInXml(xml, escapedZciteTag, fieldCodeXml) {
+    // Case A (preferred): tag is the sole content of a <w:r>
+    // Use [^<]*(?:<(?!/w:rPr>)[^<]*)* instead of .*? inside <w:rPr> to prevent
+    // matching across element boundaries in minified (single-line) XML.
+    const soloRunRegex = new RegExp(`<w:r>(?:<w:rPr>[^<]*(?:<(?!/w:rPr>)[^<]*)*</w:rPr>)?<w:t[^>]*>${regexEscape(escapedZciteTag)}</w:t></w:r>`);
+    if (soloRunRegex.test(xml)) {
+        return xml.replace(soloRunRegex, fieldCodeXml);
+    }
+    // Case B (fallback): tag is inline with other text
+    const inlineRegex = new RegExp(`(<w:r>(?:<w:rPr>([^<]*(?:<(?!/w:rPr>)[^<]*)*)</w:rPr>)?<w:t[^>]*>)([^<]*)${regexEscape(escapedZciteTag)}([^<]*)(</w:t></w:r>)`);
+    const inlineMatch = xml.match(inlineRegex);
+    if (inlineMatch) {
+        const rPr = inlineMatch[2]
+            ? `<w:rPr>${inlineMatch[2]}</w:rPr>`
+            : "";
+        const textBefore = inlineMatch[3];
+        const textAfter = inlineMatch[4];
+        let replacement = "";
+        if (textBefore) {
+            replacement += `<w:r>${rPr}<w:t xml:space="preserve">${textBefore}</w:t></w:r>`;
+        }
+        replacement += fieldCodeXml;
+        if (textAfter) {
+            replacement += `<w:r>${rPr}<w:t xml:space="preserve">${textAfter}</w:t></w:r>`;
+        }
+        return xml.replace(inlineRegex, replacement);
+    }
+    return xml;
+}
+export async function injectCitations(filePath, zoteroApi, userId, style) {
+    const fileBuffer = await readFile(filePath);
+    const zip = await JSZip.loadAsync(fileBuffer);
+    const documentEntry = zip.file("word/document.xml");
+    if (!documentEntry) {
+        throw new Error("Invalid .docx file: word/document.xml not found");
+    }
+    let documentXml = await documentEntry.async("string");
+    documentXml = normalizeZciteTags(documentXml);
+    const matches = parseZciteMatches(documentXml);
+    if (matches.length === 0) {
+        const outputPath = filePath.replace(".docx", "_cited.docx");
+        const buffer = await zip.generateAsync({ type: "nodebuffer" });
+        await writeFile(outputPath, buffer);
+        return { outputPath, found: 0, injected: 0, warnings: [] };
+    }
+    // Warn if using a numbered style but tags are missing the num attribute
+    const warnings = [];
+    if (style === "ieee" || style === "vancouver") {
+        const withNum = matches.filter((m) => m.num !== undefined).length;
+        if (withNum < matches.length) {
+            warnings.push(`Style '${style}' requires 'num' attribute on <zcite> tags. Found ${withNum}/${matches.length} tags with num.`);
+        }
+    }
+    // Collect all unique item keys
+    const uniqueKeys = new Set(matches.flatMap((m) => m.keys));
+    // Fetch CSL data from Zotero
+    const cslData = await fetchCslData(uniqueKeys, zoteroApi, userId);
+    // Replace each zcite tag with a field code
+    let injected = 0;
+    for (const match of matches) {
+        const citationItems = buildCitationItems(match, cslData, userId);
+        const itemDataList = match.keys.map((k) => cslData.get(k) ?? { type: "article-journal" });
+        const formattedText = formatCitationText(itemDataList, style, match.num);
+        const fieldCodeXml = generateZoteroFieldCode(citationItems, formattedText);
+        const newXml = replaceZciteInXml(documentXml, match.fullMatch, fieldCodeXml);
+        if (newXml !== documentXml) {
+            documentXml = newXml;
+            injected++;
+        }
+    }
+    // Append bibliography before </w:body>
+    const biblXml = generateBibliographyFieldCode();
+    documentXml = documentXml.replace("</w:body>", `${biblXml}</w:body>`);
+    // Save
+    zip.file("word/document.xml", documentXml);
+    const outputPath = filePath.replace(".docx", "_cited.docx");
+    const buffer = await zip.generateAsync({ type: "nodebuffer" });
+    await writeFile(outputPath, buffer);
+    return { outputPath, found: matches.length, injected, warnings };
+}

package/build/citation-injector/xml-utils.js

@@ -0,0 +1,19 @@
+export function escapeXml(text) {
+    return text
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+export function unescapeXml(text) {
+    return text
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&"); // MUST be last to avoid double-unescaping
+}
+export function regexEscape(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/build/citation-injector/zcite-normalizer.js

@@ -0,0 +1,232 @@
+import { XMLParser, XMLBuilder } from "fast-xml-parser";
+// Pattern to detect a complete zcite tag in entity-encoded text
+// (processEntities: false keeps < etc. as literals)
+const ZCITE_PATTERN = /<zcite\s+[\s\S]*?\/>/;
+const PARSER_OPTIONS = {
+    preserveOrder: true,
+    ignoreAttributes: false,
+    processEntities: false,
+    trimValues: false,
+    // Prevent fast-xml-parser from parsing numeric/boolean text
+    parseTagValue: false,
+    parseAttributeValue: false,
+};
+const BUILDER_OPTIONS = {
+    preserveOrder: true,
+    ignoreAttributes: false,
+    processEntities: false,
+    format: false,
+    suppressEmptyNode: false,
+    suppressBooleanAttributes: false,
+};
+/**
+ * Extract text content from a w:r (run) node in the parsed tree.
+ * Returns the concatenated #text of all w:t children, or "" if none.
+ */
+function extractRunText(runChildren) {
+    let text = "";
+    for (const child of runChildren) {
+        if ("w:t" in child) {
+            const wtChildren = child["w:t"];
+            for (const tc of wtChildren) {
+                if ("#text" in tc) {
+                    text += String(tc["#text"]);
+                }
+            }
+        }
+    }
+    return text;
+}
+/**
+ * Check if a node is a w:r element (run).
+ */
+function isRunNode(node) {
+    return "w:r" in node;
+}
+/**
+ * Check if a run has any w:t children (text elements).
+ */
+function hasTextContent(runChildren) {
+    return runChildren.some((child) => "w:t" in child);
+}
+/**
+ * Collect groups of consecutive w:r nodes that have text content.
+ * Non-w:r nodes or w:r nodes without w:t break the group.
+ */
+function collectConsecutiveRunGroups(children) {
+    const groups = [];
+    let currentGroup = null;
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        if (isRunNode(child)) {
+            const runChildren = child["w:r"];
+            if (hasTextContent(runChildren)) {
+                const text = extractRunText(runChildren);
+                if (currentGroup) {
+                    currentGroup.endIndex = i;
+                    currentGroup.texts.push(text);
+                }
+                else {
+                    currentGroup = { startIndex: i, endIndex: i, texts: [text] };
+                }
+                continue;
+            }
+        }
+        // Non-w:r or w:r without w:t → flush current group
+        if (currentGroup && currentGroup.texts.length >= 2) {
+            groups.push(currentGroup);
+        }
+        currentGroup = null;
+    }
+    // Flush final group
+    if (currentGroup && currentGroup.texts.length >= 2) {
+        groups.push(currentGroup);
+    }
+    return groups;
+}
+/**
+ * Given a group of consecutive runs, find a zcite tag that spans multiple runs.
+ * Returns the sub-range [startOffset, endOffset] within the group (0-indexed),
+ * or null if no split zcite found.
+ */
+function findSplitZcite(group) {
+    const { texts } = group;
+    // Sliding window: try all start positions
+    for (let start = 0; start < texts.length; start++) {
+        let concat = "";
+        for (let end = start; end < texts.length; end++) {
+            concat += texts[end];
+            // Only interested in splits (spanning 2+ runs)
+            if (end <= start)
+                continue;
+            const m = ZCITE_PATTERN.exec(concat);
+            if (m) {
+                // Verify the match actually spans runs: the zcite must start before
+                // the last run's text and end at or after the last run's start.
+                // i.e., it's not entirely within one run of this sub-range.
+                const matchStart = m.index;
+                const matchEnd = m.index + m[0].length;
+                // Calculate where the last run's text starts in the concatenated string
+                const lastRunStart = concat.length - texts[end].length;
+                // The zcite is split if it starts before lastRunStart AND extends
+                // into the last run's territory, OR if it starts in a prior run.
+                if (matchStart < lastRunStart && matchEnd > lastRunStart) {
+                    return { startOffset: start, endOffset: end };
+                }
+                // Also check: could a zcite fully within a single earlier run exist?
+                // If so, skip this end and continue — no split needed for this combo.
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Merge runs from startIdx to endIdx (inclusive) in the children array.
+ * The merged run gets the w:rPr from the first run and a single w:t with
+ * the concatenated text of all merged runs.
+ */
+function mergeRunsInPlace(children, group, startOffset, endOffset) {
+    const absStart = group.startIndex + startOffset;
+    const absEnd = group.startIndex + endOffset;
+    const count = absEnd - absStart + 1;
+    // Concatenate text from all runs in the range
+    let mergedText = "";
+    for (let i = absStart; i <= absEnd; i++) {
+        const runChildren = children[i]["w:r"];
+        mergedText += extractRunText(runChildren);
+    }
+    // Build new run node
+    const firstRunChildren = children[absStart]["w:r"];
+    const newRunChildren = [];
+    // Copy w:rPr from first run if present
+    for (const child of firstRunChildren) {
+        if ("w:rPr" in child) {
+            newRunChildren.push(child);
+            break;
+        }
+    }
+    // Add single w:t with merged text
+    newRunChildren.push({
+        "w:t": [{ "#text": mergedText }],
+        ":@": { "@_xml:space": "preserve" },
+    });
+    const newRun = { "w:r": newRunChildren };
+    // Copy attributes from first run if any
+    const firstRunAttrs = children[absStart][":@"];
+    if (firstRunAttrs) {
+        newRun[":@"] = firstRunAttrs;
+    }
+    // Splice: replace N runs with 1 merged run
+    children.splice(absStart, count, newRun);
+}
+/**
+ * Scan a paragraph's children for split zcite tags and merge them.
+ * Returns true if any modifications were made.
+ */
+function normalizeParagraphRuns(children) {
+    let modified = false;
+    // Use a while loop since indices shift after each merge
+    let changed = true;
+    while (changed) {
+        changed = false;
+        const groups = collectConsecutiveRunGroups(children);
+        for (const group of groups) {
+            const split = findSplitZcite(group);
+            if (split) {
+                mergeRunsInPlace(children, group, split.startOffset, split.endOffset);
+                modified = true;
+                changed = true;
+                break; // Restart scan since indices shifted
+            }
+        }
+    }
+    return modified;
+}
+/**
+ * Recursively walk the parsed tree, finding w:p elements and normalizing
+ * their runs.
+ */
+function walkAndNormalize(nodes) {
+    let modified = false;
+    for (const node of nodes) {
+        if ("w:p" in node) {
+            const pChildren = node["w:p"];
+            if (normalizeParagraphRuns(pChildren)) {
+                modified = true;
+            }
+        }
+        // Recurse into all child arrays
+        for (const key of Object.keys(node)) {
+            if (key === ":@" || key === "#text")
+                continue;
+            const value = node[key];
+            if (Array.isArray(value)) {
+                if (walkAndNormalize(value)) {
+                    modified = true;
+                }
+            }
+        }
+    }
+    return modified;
+}
+/**
+ * Pre-process document.xml to merge zcite tags that Word has split across
+ * multiple w:r runs (e.g. due to language or font changes mid-tag).
+ *
+ * If no split zcites are found, returns the original string unchanged
+ * (zero risk of round-trip encoding differences).
+ */
+export function normalizeZciteTags(documentXml) {
+    // Quick check: if no zcite at all, skip parsing entirely
+    if (!documentXml.includes("zcite")) {
+        return documentXml;
+    }
+    const parser = new XMLParser(PARSER_OPTIONS);
+    const parsed = parser.parse(documentXml);
+    const modified = walkAndNormalize(parsed);
+    if (!modified) {
+        return documentXml; // Return original string, no changes
+    }
+    const builder = new XMLBuilder(BUILDER_OPTIONS);
+    return builder.build(parsed);
+}