@xevos117/mcp-zotero 2.0.4 → 2.1.0

package/README.md

@@ -2,10 +2,23 @@
 
 > **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.
+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, edit items and notes, check a bibliography for retractions and duplicates, and put live Zotero citations into Word and LibreOffice 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, 15 tools (up from 5), citation injection, PDF management, and Claude skill support.
+> This project has since been extensively rewritten with a new architecture, 20 tools (up from 5), citation injection, PDF management, and Claude skill support.
+
+## Features
+
+- **Live citations in Word and LibreOffice.** `inject_citations` turns placeholders in an existing `.docx` or `.odt` into native Zotero citations and a bibliography, which the Zotero plugin of either app can refresh and restyle. Placeholders can be `<zcite>` tags or Pandoc markers (`[@KEY]`), with Zotero item keys or Better BibTeX citation keys ([details](#citation-placeholders)).
+- **Cited documents from Markdown.** `create_cited_document` writes a new `.docx` or `.odt` from Markdown with Pandoc-style citations, real heading styles and a bibliography.
+- **Five citation styles:** APA, IEEE, Vancouver, Harvard and Chicago.
+- **Adding references** by DOI or with full metadata (all 37 Zotero item types), with open-access PDFs attached automatically through Unpaywall.
+- **Editing:** `update_item` changes fields and creators with a version check (never overwrites a concurrent edit); `create_note` attaches a plain-text note to an item.
+- **Checking a bibliography:** `check_retractions` flags retracted papers, expressions of concern and corrections (Crossref, with Retraction Watch data); `find_duplicates` finds items with the same DOI or title, or tells which DOIs are already in the library before importing them.
+- **Safe deletion:** `delete_items` moves items to the Zotero trash by default; permanent deletion needs `permanent: true`, and every deletion is off unless `UNSAFE_OPERATIONS` allows it.
+- **Group libraries,** set for the whole server or per call.
+- **MCP prompts** for common workflows: citing a document, writing a cited document, importing references, summarizing an item into a note, checking a bibliography before submission.
+- **Claude skill** for clients without filesystem access (Claude.ai Projects, Claude Desktop): the same citation injection, run inside the sandbox.
 
 ## How it works
 
@@ -17,10 +30,10 @@ For advanced use cases (PDF upload policy, citation style guidance, source trans
 
 | Scenario | MCP server | Skill needed? |
 |---|---|---|
-| LLM with filesystem access (Claude Code, LM Studio, etc.) | All 15 tools | No |
+| LLM with filesystem access (Claude Code, LM Studio, etc.) | All 20 tools | No |
 | LLM without filesystem access (Claude.ai Projects, Claude Desktop) | API tools (search, add, metadata) | Yes, for citation injection |
 
-LLMs with filesystem access can use all tools directly, including `inject_citations` which reads and writes `.docx` files on disk.
+LLMs with filesystem access can use all tools directly, including `inject_citations` which reads and writes `.docx` (Word) and `.odt` (LibreOffice) files on disk.
 
 LLMs without filesystem access — including Claude Desktop, which connects to MCP but cannot generate files locally — can use the included **Claude skill** (`skills/zotero-skill-mcp-integrations/`), which runs citation injection entirely inside a sandbox. MCP tools handle all Zotero API operations; the skill handles document assembly.
 
@@ -140,8 +153,8 @@ To enable deletion, set the `UNSAFE_OPERATIONS` environment variable to one of t
 
 - If `UNSAFE_OPERATIONS` is not set, empty, or set to an unrecognized value, it defaults to `none`.
 - The value is **case-insensitive** (e.g. `ALL`, `Items`, `NONE` all work).
-- `delete_items` deletes items **permanently**: the Zotero Web API multi-item DELETE does not move them to the Zotero trash, so they cannot be restored from the desktop client.
-- `delete_collection` removes the collection (folder) only — items inside it are **not** deleted and remain in your library.
+- `delete_items` **moves items to the Zotero trash by default**, so the user can restore them from the desktop client (Zotero → Trash). Pass `permanent: true` to delete them for good instead; the same `UNSAFE_OPERATIONS` setting gates both the trash and the permanent path.
+- `delete_collection` is always **permanent**: the Zotero Web API has no trash for collections, so a deleted collection cannot be restored. It removes the collection (folder) only — items inside it are **not** deleted and remain in your library.
 - The `all` value includes both item and collection deletion because managing collections inherently requires item-level access.
 
 **Configuration example:**
@@ -224,8 +237,10 @@ available in every project (the default `local` scope covers only the current pr
 | `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 — returns all type-specific fields (bookTitle, proceedingsTitle, university, etc.), the `authors` string and the structured `creators`; keys not in the library are listed in `not_found` |
+| `get_items_details` | Batch metadata retrieval for multiple items — returns all type-specific fields (bookTitle, proceedingsTitle, university, etc.), the `authors` string, the structured `creators` and each item's current `version` (needed by `update_item`); keys not in the library are listed in `not_found` |
 | `get_item_fulltext` | Get full-text content of a PDF attachment via Zotero's fulltext index |
+| `check_retractions` | Check items (by `item_keys` or `collection_key`) for retractions, expressions of concern or corrections via Crossref (Retraction Watch data). Read-only; reports a `status` per item with any notices |
+| `find_duplicates` | Find duplicate items (same DOI or normalized title/year) in the library or a collection; or, given DOIs, report which are already present (use before `add_items_by_doi`). Read-only — never merges or deletes |
 
 ### Adding content
 
@@ -238,26 +253,65 @@ available in every project (the default `local` scope covers only the current pr
 | `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 |
 
+### Editing content
+
+| Tool | Description |
+|---|---|
+| `update_item` | Edit an existing item's fields and/or creators. Needs the item's current `version` (from `get_items_details`); a stale version returns `version_conflict` instead of overwriting |
+| `create_note` | Attach a plain-text child note to an existing regular item (blank lines become paragraphs) |
+
 ### Deleting content
 
 | Tool | Description |
 |---|---|
-| `delete_items` | Permanently delete up to 50 items per call (not moved to the Zotero trash). Requires `UNSAFE_OPERATIONS=items` or `all` |
-| `delete_collection` | Delete a collection (folder). Items inside are kept. Requires `UNSAFE_OPERATIONS=all` |
+| `delete_items` | Delete up to 50 items per call: moved to the Zotero trash by default (recoverable), or permanently with `permanent: true`. Requires `UNSAFE_OPERATIONS=items` or `all` |
+| `delete_collection` | Delete a collection (folder) permanently — collections have no trash. Items inside are kept. Requires `UNSAFE_OPERATIONS=all` |
 
 ### Citation & documents
 
 | Tool | Description |
 |---|---|
-| `inject_citations` | Inject live Zotero citations into a Word document. Supports APA, IEEE, Vancouver, Harvard, Chicago. Output is saved in the same folder as the input file with a `_cited` suffix (e.g. `paper.docx` → `paper_cited.docx`) |
+| `inject_citations` | Inject live Zotero citations into a Word (`.docx`) or LibreOffice (`.odt`) document (native fields in Word, reference marks in LibreOffice; format from the extension or the `format` argument). Recognizes two placeholder styles automatically: `<zcite keys="ITEMKEY"/>` tags, or — when the document has no `<zcite>` — Pandoc markers (`[@KEY]`, `[@K1; @K2]`, `[see @KEY, p. 12]`, `-@KEY`, inline `@KEY`), where `KEY` is a Zotero key or a case-sensitive Better BibTeX citation key (resolved via the item's `citationKey` field or a `Citation Key:` line in Extra). Prefer the bracketed `[@KEY]` form: an inline `@word` that doesn't resolve (a handle or code) is kept as text with a warning, while an unknown key in `[@…]` is an error. Supports APA, IEEE, Vancouver, Harvard, Chicago. Output is saved in the same folder as the input file with a `_cited` suffix (e.g. `paper.docx` → `paper_cited.docx`, `paper.odt` → `paper_cited.odt`) |
+| `create_cited_document` | Create a new `.docx` or `.odt` from Markdown (headings, bold/italic, one-level lists) with pandoc-style citations (`[@KEY]`, `[@K1; @K2]`, `[see @KEY, p. 12]`, `-@KEY`) turned into native Zotero citations and a bibliography. Never overwrites an existing file |
 | `get_user_id` | Returns the configured Zotero user ID |
 
+### Citation placeholders
+
+`inject_citations` (and the skill's `inject.js`) recognizes the placeholder style by itself, so there is no argument to set:
+
+| The document contains | What happens |
+|---|---|
+| `<zcite keys="ITEMKEY"/>` tags | The tags become Zotero citations. Any Pandoc markers in the same document are left alone and reported in a warning |
+| Only Pandoc markers | `[@KEY]`, `[@K1; @K2]`, `[see @KEY, p. 12]`, `-@KEY` (year only) and inline `@KEY` become Zotero citations |
+| Neither | The copy is written unchanged, with a warning |
+
+- `KEY` is a Zotero item key (8 characters) or a **Better BibTeX citation key** such as `rossi2020`, found through the item's citation key field or a `Citation Key:` line in Extra. Citation keys are case-sensitive.
+- Prefer the bracketed form `[@KEY]`. An unknown or ambiguous key inside brackets is an error and nothing is written. An inline `@word` that doesn't resolve (a social handle, `@media`, a code decorator) stays text with a warning. Word may split an inline `@KEY` across formatting runs; the bracketed form is always recognized.
+- A document with both styles: run `inject_citations` on the `_cited` output again to convert the Pandoc markers too. The second run adds the citations without a second bibliography; Zotero → Refresh updates the existing one.
+- Footnotes and comments are not scanned, in either style.
+
+### After injection
+
+Open the `_cited` file in Word or LibreOffice with the [Zotero plugin](https://www.zotero.org/support/word_processor_integration) installed and use Zotero → Refresh: the plugin formats the citations and the bibliography in the chosen style, and from then on you can add, edit or restyle citations from the plugin as usual. The document stays in its format: a `.docx` keeps Word fields, an `.odt` keeps LibreOffice reference marks.
+
+### Prompts
+
+User-initiated MCP prompts (`prompts/list`, `prompts/get`) that walk a client through a workflow in terms of the tools above:
+
+| Prompt | Description |
+|---|---|
+| `cite_word_document` | Turn the placeholders in an existing `.docx`/`.odt` into Zotero citations (`inject_citations`) |
+| `write_cited_document` | Draft a cited document from scratch and save it (`create_cited_document`) |
+| `import_references` | Import references by DOI: skip those already in the library (`find_duplicates`), add the rest (`add_items_by_doi`), check them for retractions (`check_retractions`) and attach open-access PDFs (`find_and_attach_pdfs`) |
+| `note_from_item` | Read an item and attach a summary note (`create_note`) |
+| `check_bibliography` | Check a collection for retracted items (`check_retractions`) and duplicates (`find_duplicates`) before handing it in |
+
 ## Development
 
 ```bash
 npm install
 npm run build          # Compile TypeScript
-npm test               # Unit and per-tool tests (vitest, fetch faked, ~1000 tests)
+npm test               # Unit and per-tool tests (vitest, fetch faked, ~1900 tests)
 npm run test:e2e       # Built server over stdio against a local fake Zotero API
 npm run smoke          # Quick stdio smoke test of the built server (user + group library)
 npm run bundle         # Claude Desktop extension: dist/mcp-zotero.mcpb (production dependencies only)
@@ -350,7 +404,7 @@ Other owner settings:
    and record the results in its log.
 4. Before the first release that ships the Claude Desktop extension (and whenever `manifest.json` or the Node.js
    requirement changes): build it with `npm run bundle`, install `dist/mcp-zotero.mcpb` once in a real Claude
-   Desktop (macOS or Windows), fill in a test key and user ID, and check that the 15 tools appear and
+   Desktop (macOS or Windows), fill in a test key and user ID, and check that the 20 tools appear and
    `get_collections` answers.
 5. Publish the GitHub release: the [release workflow](.github/workflows/release.yml) runs the tests, publishes
    to npm, publishes `server.json` to the [MCP Registry](https://registry.modelcontextprotocol.io) and attaches

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

@@ -65,6 +65,9 @@ export function formatCitationText(items, style, opts = {}) {
         const authors = item.author;
         const name = (a) => a.family ?? a.literal ?? "Unknown";
         const year = item.issued?.["date-parts"]?.[0]?.[0]?.toString() ?? "n.d.";
+        // suppress-author (pandoc -@K): solo l'anno, con eventuali locator/prefix/suffix
+        if (opts.suppressAuthor)
+            return `${prefix}${year}${locator}${suffix}`;
         let authorText;
         if (!authors || authors.length === 0) {
             const title = item.title;

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

@@ -0,0 +1,37 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Parte neutra rispetto al formato della citazione: la costruzione delle voci CSL (itemData + URI) e del
+ * JSON CSL_CITATION che Zotero legge. La usano sia i campi Word (field-codes.ts) sia i reference mark ODT.
+ */
+const CSL_SCHEMA_URL = "https://github.com/citation-style-language/schema/raw/master/csl-citation.json";
+/** Voci `citationItems` di una citazione: una per chiave, con URI Zotero e itemData. */
+export function buildCitationItems(request, cslData, libraryType, userId) {
+    return request.keys.map((key, idx) => {
+        const itemData = cslData.get(key) ?? { type: "article-journal" };
+        const uri = `http://zotero.org/${libraryType}s/${userId}/items/${key}`;
+        const item = {
+            id: idx,
+            uris: [uri],
+            uri: [uri],
+            itemData,
+        };
+        if (request.locator)
+            item.locator = request.locator;
+        if (request.prefix)
+            item.prefix = request.prefix;
+        if (request.suffix)
+            item.suffix = request.suffix;
+        if (request.suppressAuthor)
+            item["suppress-author"] = true;
+        return item;
+    });
+}
+/** Oggetto CSL_CITATION (citationID casuale, formattedCitation, citationItems, schema). */
+export function buildCslCitation(citationItems, formattedText) {
+    return {
+        citationID: randomUUID().slice(0, 8),
+        properties: { formattedCitation: formattedText },
+        citationItems,
+        schema: CSL_SCHEMA_URL,
+    };
+}

package/build/citation-injector/citekey-resolver.js

@@ -0,0 +1,122 @@
+import { InjectionError } from "./model.js";
+// Same rule as ZOTERO_KEY in src/utils/zotero-keys.ts, inlined so this module (shared with the skill
+// bundle) stays free of the zod import that file carries.
+const ZOTERO_KEY = /^[23456789ABCDEFGHIJKLMNPQRSTUVWXYZ]{8}$/;
+/** The citekeys an item carries: the native `citationKey` field and every `Citation Key: <key>` line of Extra. */
+export function itemCitekeys(item) {
+    const out = [];
+    if (typeof item.citationKey === "string" && item.citationKey)
+        out.push(item.citationKey);
+    if (typeof item.extra === "string") {
+        for (const line of item.extra.split(/\r?\n/)) {
+            const m = /^[ \t]*citation ?key[ \t]*:[ \t]*(\S+)[ \t]*$/i.exec(line);
+            if (m)
+                out.push(m[1]);
+        }
+    }
+    return out;
+}
+/** Exact (case-sensitive) match of `citekey` against an item's citationKey field or Extra line. */
+export function itemMatchesCitekey(item, citekey) {
+    return itemCitekeys(item).includes(citekey);
+}
+/** The citekeys in these requests that are not already well-formed Zotero item keys. */
+export function citekeysOf(requests) {
+    const out = new Set();
+    for (const r of requests)
+        for (const k of r.keys)
+            if (!ZOTERO_KEY.test(k))
+                out.add(k);
+    return out;
+}
+/**
+ * Resolve Better BibTeX citekeys to Zotero keys. An inline `@key` that does not resolve (unknown or
+ * ambiguous) is DROPPED and kept as text, with a warning — a stray handle or code like `@Component` must
+ * not fail the whole document. A bracketed `[@key]` that is unknown or ambiguous is an error (nothing is
+ * written), the same contract as a missing Zotero key.
+ *
+ * Inline-only citekeys are looked up at most INLINE_LOOKUP_CAP distinct tokens per call, so a technical
+ * document full of `@decorator`/`@media` does not fan out into unbounded API searches: tokens past the cap
+ * are left as text with one summary warning. Zotero 8-char keys (no lookup) and bracketed `[@…]` forms (a
+ * real citation) never count toward the cap.
+ */
+export const INLINE_LOOKUP_CAP = 25;
+export async function resolveCitekeys(requests, lookup) {
+    const citekeys = citekeysOf(requests);
+    if (citekeys.size === 0)
+        return { requests, warnings: [] };
+    // Citekeys used by a bracketed form must always be resolved (they error if unknown); inline-only
+    // citekeys are capped.
+    const bracketKeys = new Set();
+    for (const r of requests)
+        if (!r.inline)
+            for (const k of r.keys)
+                if (!ZOTERO_KEY.test(k))
+                    bracketKeys.add(k);
+    const inlineOnly = [...citekeys].filter((k) => !bracketKeys.has(k)); // first-appearance order
+    const cappedOut = new Set(inlineOnly.slice(INLINE_LOOKUP_CAP));
+    const toLookup = new Set([...bracketKeys, ...inlineOnly.slice(0, INLINE_LOOKUP_CAP)]);
+    const found = toLookup.size > 0 ? await lookup(toLookup) : new Map();
+    const status = (ck) => {
+        const match = found.get(ck) ?? { keys: [] };
+        if (match.keys.length === 1)
+            return { ok: match.keys[0], detail: ck };
+        if (match.keys.length === 0) {
+            const sim = match.similar && match.similar.length ? ` (case-sensitive; did you mean ${match.similar.join(", ")}?)` : "";
+            return { problem: "unknown", detail: `${ck}${sim}` };
+        }
+        return { problem: "ambiguous", detail: `${ck} → ${match.keys.join(", ")}` };
+    };
+    const unknownBracket = [];
+    const ambiguousBracket = [];
+    const warnings = [];
+    const out = [];
+    for (const r of requests) {
+        const resolvedKeys = [];
+        let drop = false;
+        for (const k of r.keys) {
+            if (ZOTERO_KEY.test(k)) {
+                resolvedKeys.push(k);
+                continue;
+            }
+            if (r.inline && cappedOut.has(k)) {
+                // over the inline lookup cap: left as text, no per-key lookup (summary warning added below)
+                drop = true;
+                break;
+            }
+            const s = status(k);
+            if (s.ok) {
+                resolvedKeys.push(s.ok);
+            }
+            else if (r.inline) {
+                // an inline marker that does not resolve stays text (no error)
+                drop = true;
+                warnings.push(`"${r.raw}" did not match any item (citation key or Zotero key); kept as text.`);
+                break;
+            }
+            else if (s.problem === "ambiguous") {
+                ambiguousBracket.push(s.detail);
+            }
+            else {
+                unknownBracket.push(s.detail);
+            }
+        }
+        if (!drop && resolvedKeys.length === r.keys.length)
+            out.push({ ...r, keys: resolvedKeys });
+    }
+    if (cappedOut.size > 0) {
+        warnings.push(`${cappedOut.size} inline @ citation key(s) were left as text without a lookup (over the ${INLINE_LOOKUP_CAP}-key ` +
+            "limit for inline markers); use the [@key] form for citations beyond that limit.");
+    }
+    if (unknownBracket.length > 0) {
+        throw new InjectionError("missing_keys", `${unknownBracket.length} citation key(s) not found in the library: ${unknownBracket.join("; ")}. No file was written. ` +
+            "Citation keys are case-sensitive and matched against each item's citationKey field or a \"Citation Key: <key>\" line " +
+            "in Extra (Better BibTeX). Fix these keys, or cite the item by its 8-character Zotero key, and call again; for a group " +
+            "library pass library_type and library_id.");
+    }
+    if (ambiguousBracket.length > 0) {
+        throw new InjectionError("invalid_key", `${ambiguousBracket.length} citation key(s) match more than one item: ${ambiguousBracket.join("; ")}. No file was written. ` +
+            "Make the citation key unique in Zotero, or cite the item by its 8-character Zotero key, and call again.");
+    }
+    return { requests: out, warnings };
+}

package/build/citation-injector/document-prefs.js

@@ -26,11 +26,14 @@ const escapeXml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(
 function sessionId() {
     return [...randomBytes(8)].map((b) => SESSION_ALPHABET[b % SESSION_ALPHABET.length]).join("");
 }
-/** The document data Zotero serializes (data-version 3), citations in the text (no noteType), fields as Word fields. */
-export function zoteroDocumentData(styleId, session = sessionId()) {
+/**
+ * The document data Zotero serializes (data-version 3), citations in the text (no noteType). `fieldType`
+ * is Field for Word fields and ReferenceMark for LibreOffice reference marks.
+ */
+export function zoteroDocumentData(styleId, fieldType = "Field", session = sessionId()) {
     return (`<data data-version="3"><session id="${session}"/>` +
         `<style id="${escapeXml(styleId)}" locale="en-US" hasBibliography="1" bibliographyStyleHasBeenSet="0"/>` +
-        `<prefs><pref name="fieldType" value="Field"/></prefs></data>`);
+        `<prefs><pref name="fieldType" value="${fieldType}"/></prefs></data>`);
 }
 /** The value split into ZOTERO_PREF_1…n chunks. */
 export function prefChunks(value) {

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

@@ -1,13 +1,7 @@
-import { randomUUID } from "node:crypto";
 import { escapeXml } from "./xml-utils.js";
+import { buildCslCitation } from "./citation-json.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 cslCitation = buildCslCitation(citationItems, formattedText);
     const instrText = ` ADDIN ZOTERO_ITEM CSL_CITATION ${JSON.stringify(cslCitation)} `;
     const escapedInstrText = escapeXml(instrText);
     return [

package/build/citation-injector/formats/docx.js

@@ -0,0 +1,83 @@
+import JSZip from "jszip";
+import { InjectionError } from "../model.js";
+import { regexEscape } from "../xml-utils.js";
+import { normalizeZciteTags, normalizePandocMarkers } from "../zcite-normalizer.js";
+import { generateZoteroFieldCode, generateBibliographyFieldCode } from "../field-codes.js";
+import { EXISTING_PREFS_WARNING, PREFS_NOT_WRITTEN_WARNING, writeZoteroDocumentPrefs, } from "../document-prefs.js";
+const REGENERATE_DOCX = "The file is not a Word document or is corrupted: create it again as .docx (e.g. with the docx npm package) and call again.";
+/**
+ * Sostituisce il tag <zcite> (escapato) con il field code Word. Caso A (il tag è l'unico contenuto di un
+ * <w:r>), caso B (il tag è inline con altro testo). La `<w:r>` iniziale può avere attributi
+ * (`<w:r w:rsidR="…">`, scritti da Word quando tiene traccia delle revisioni): `<w:r[^>]*>` li tollera.
+ * Prima venivano saltati in silenzio (found ma non injected); i documenti senza attributi non cambiano.
+ */
+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;
+}
+/** Scrittore Word: involucro sulle funzioni di oggi, l'output docx non cambia byte per byte. */
+export const docxWriter = {
+    format: "docx",
+    fieldType: "Field",
+    bodyPart: "word/document.xml",
+    app: "Word",
+    invalidPackageMessage: (detail) => `Invalid .docx file: not a readable ZIP archive (${detail}). ${REGENERATE_DOCX}`,
+    bodyMissingMessage: `Invalid .docx file: word/document.xml not found. ${REGENERATE_DOCX}`,
+    sniff(zip) {
+        // un .odt passato come .docx: errore chiaro invece di "word/document.xml not found"
+        if (zip.file("content.xml") && !zip.file("word/document.xml")) {
+            throw new InjectionError("format_mismatch", 'This looks like a LibreOffice .odt, not a Word .docx. Use format "odt" (or a .odt file).');
+        }
+    },
+    normalize: (bodyXml) => normalizeZciteTags(bodyXml),
+    normalizePandoc: (bodyXml) => normalizePandocMarkers(bodyXml),
+    citationXml: (prepared) => generateZoteroFieldCode(prepared.items, prepared.formattedText),
+    replaceTag: (bodyXml, rawTag, citationXml) => replaceZciteInXml(bodyXml, rawTag, citationXml),
+    appendBibliography: (bodyXml) => bodyXml.replace("</w:body>", `${generateBibliographyFieldCode()}</w:body>`),
+    writePrefs: (zip, style) => writeZoteroDocumentPrefs(zip, style),
+    prefsWarnings: (outcome) => {
+        if (outcome === "kept")
+            return [EXISTING_PREFS_WARNING];
+        if (outcome === "skipped")
+            return [PREFS_NOT_WRITTEN_WARNING];
+        return [];
+    },
+    async skeleton() {
+        const W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+        const zip = new JSZip();
+        zip.file("[Content_Types].xml", '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/><Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/></Types>');
+        zip.file("_rels/.rels", '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>');
+        zip.file("word/_rels/document.xml.rels", '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/></Relationships>');
+        // Heading 1..6 con outlineLvl: così il pannello di navigazione e il sommario di Word funzionano
+        const sizes = [36, 32, 28, 26, 24, 22];
+        const headings = sizes
+            .map((sz, i) => `<w:style w:type="paragraph" w:styleId="Heading${i + 1}"><w:name w:val="heading ${i + 1}"/><w:basedOn w:val="Normal"/><w:pPr><w:outlineLvl w:val="${i}"/></w:pPr><w:rPr><w:b/><w:sz w:val="${sz}"/></w:rPr></w:style>`)
+            .join("");
+        zip.file("word/styles.xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:styles xmlns:w="${W}"><w:style w:type="paragraph" w:styleId="Normal" w:default="1"><w:name w:val="Normal"/></w:style>${headings}</w:styles>`);
+        zip.file("word/document.xml", `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="${W}"><w:body><w:sectPr/></w:body></w:document>`);
+        return zip;
+    },
+};

package/build/citation-injector/formats/odt.js

@@ -0,0 +1,149 @@
+import JSZip from "jszip";
+import { randomBytes } from "node:crypto";
+import { InjectionError } from "../model.js";
+import { escapeXml } from "../xml-utils.js";
+import { buildCslCitation } from "../citation-json.js";
+import { normalizeOdtZciteTags, normalizeOdtPandocMarkers } from "../odt-normalizer.js";
+import { ZOTERO_STYLE_IDS, prefChunks, zoteroDocumentData } from "../document-prefs.js";
+/**
+ * Scrittore LibreOffice (ODT): le citazioni sono reference mark, la bibliografia una text:section, le
+ * preferenze vanno in meta.xml con fieldType ReferenceMark. Condivide con Word tutto il nucleo neutro
+ * (parsing <zcite>, JSON CSL della citazione, risoluzione delle chiavi); qui vive solo ciò che è ODF.
+ */
+const ODT_MIME = "application/vnd.oasis.opendocument.text";
+const REGENERATE_ODT = "The file is not a LibreOffice document or is corrupted: create it again as .odt and call again.";
+/** 10 caratteri [0-9A-Za-z], il suffisso RND che Zotero accoda ai nomi dei reference mark. */
+const RND_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+function rnd10() {
+    return [...randomBytes(10)].map((b) => RND_ALPHABET[b % RND_ALPHABET.length]).join("");
+}
+/** Reference mark di una citazione: start/end con lo stesso nome ZOTERO_ITEM CSL_CITATION {json} RND…, testo in mezzo. */
+function citationXml(prepared) {
+    const csl = buildCslCitation(prepared.items, prepared.formattedText);
+    const name = escapeXml(`ZOTERO_ITEM CSL_CITATION ${JSON.stringify(csl)} RND${rnd10()}`);
+    return (`<text:reference-mark-start text:name="${name}"/>` +
+        escapeXml(prepared.formattedText) +
+        `<text:reference-mark-end text:name="${name}"/>`);
+}
+/** Sezione ZOTERO_BIBL seguita da un paragrafo vuoto, prima di </office:text>. */
+function appendBibliography(contentXml) {
+    const name = escapeXml(`ZOTERO_BIBL {"uncited":[],"omitted":[],"custom":[]} CSL_BIBLIOGRAPHY RND${rnd10()}`);
+    const section = `<text:section text:name="${name}">` +
+        `<text:p text:style-name="Bibliography_20_1">[Bibliography will be generated by Zotero]</text:p>` +
+        `</text:section><text:p/>`;
+    return contentXml.replace("</office:text>", `${section}</office:text>`);
+}
+const BIBLIOGRAPHY_STYLE = '<style:style style:name="Bibliography_20_1" style:display-name="Bibliography 1" style:family="paragraph" style:parent-style-name="Standard" style:class="list"/>';
+/** Definisce lo stile Bibliography_20_1 in styles.xml se manca (dentro office:styles, o creando il blocco). */
+async function ensureBibliographyStyle(zip) {
+    const entry = zip.file("styles.xml");
+    if (!entry)
+        return;
+    let styles = await entry.async("string");
+    if (styles.includes('style:name="Bibliography_20_1"'))
+        return;
+    if (styles.includes("</office:styles>")) {
+        styles = styles.replace("</office:styles>", `${BIBLIOGRAPHY_STYLE}</office:styles>`);
+    }
+    else if (/<office:styles\s*\/>/.test(styles)) {
+        styles = styles.replace(/<office:styles\s*\/>/, `<office:styles>${BIBLIOGRAPHY_STYLE}</office:styles>`);
+    }
+    else {
+        return; // nessun posto riconoscibile: lo stile non è definito, LibreOffice userà Standard
+    }
+    zip.file("styles.xml", styles);
+}
+export const EXISTING_ODT_PREFS_WARNING = "The document already has Zotero document preferences (ZOTERO_PREF_* in meta.xml): kept as they are, so on the " +
+    "first Refresh Zotero uses the style saved there, not the style of this injection.";
+export const ODT_PREFS_NOT_WRITTEN_WARNING = "Zotero document preferences not written: meta.xml has no <office:meta> to merge into, so Zotero may ask for the " +
+    "document style (Document Preferences) on the first Refresh.";
+/** Preferenze in meta.xml: meta:user-defined ZOTERO_PREF_1…n (255 caratteri), fieldType ReferenceMark. */
+async function writeOdtPrefs(zip, style) {
+    const styleId = ZOTERO_STYLE_IDS[style];
+    if (!styleId)
+        return "skipped";
+    const entry = zip.file("meta.xml");
+    const meta = entry ? await entry.async("string") : undefined;
+    if (meta === undefined)
+        return "skipped";
+    if (/\bmeta:name=["']ZOTERO_PREF_\d+["']/.test(meta))
+        return "kept";
+    const value = zoteroDocumentData(styleId, "ReferenceMark");
+    const props = prefChunks(value)
+        .map((chunk, i) => `<meta:user-defined meta:name="ZOTERO_PREF_${i + 1}">${escapeXml(chunk)}</meta:user-defined>`)
+        .join("");
+    const close = "</office:meta>";
+    const at = meta.lastIndexOf(close);
+    if (at < 0) {
+        // office:meta vuoto <office:meta/>
+        const m = /<office:meta\b([^>]*)\/>/.exec(meta);
+        if (!m)
+            return "skipped";
+        zip.file("meta.xml", meta.replace(m[0], `<office:meta${m[1]}>${props}</office:meta>`));
+        return "written";
+    }
+    zip.file("meta.xml", meta.slice(0, at) + props + meta.slice(at));
+    return "written";
+}
+export const odtWriter = {
+    format: "odt",
+    fieldType: "ReferenceMark",
+    bodyPart: "content.xml",
+    app: "LibreOffice",
+    invalidPackageMessage: (detail) => `Invalid .odt file: not a readable ZIP archive (${detail}). ${REGENERATE_ODT}`,
+    bodyMissingMessage: `Invalid .odt file: content.xml not found. ${REGENERATE_ODT}`,
+    sniff(zip) {
+        // un .docx passato come .odt (o viceversa): meglio un errore chiaro di un "content.xml not found"
+        if (zip.file("word/document.xml")) {
+            throw new InjectionError("format_mismatch", "This looks like a Word .docx, not a LibreOffice .odt. Use format \"docx\" (or a .docx file).");
+        }
+    },
+    normalize: (bodyXml) => normalizeOdtZciteTags(bodyXml),
+    normalizePandoc: (bodyXml) => normalizeOdtPandocMarkers(bodyXml),
+    citationXml,
+    replaceTag: (bodyXml, rawTag, cite) => {
+        const at = bodyXml.indexOf(rawTag);
+        return at < 0 ? bodyXml : bodyXml.slice(0, at) + cite + bodyXml.slice(at + rawTag.length);
+    },
+    appendBibliography,
+    writePrefs: writeOdtPrefs,
+    prefsWarnings: (outcome) => {
+        if (outcome === "kept")
+            return [EXISTING_ODT_PREFS_WARNING];
+        if (outcome === "skipped")
+            return [ODT_PREFS_NOT_WRITTEN_WARNING];
+        return [];
+    },
+    async finalize(zip) {
+        await ensureBibliographyStyle(zip);
+        // mimetype deve restare STORED (non compresso): lo riscrivo con STORE, mantenendo la posizione
+        const mimetype = zip.file("mimetype");
+        if (mimetype)
+            zip.file("mimetype", await mimetype.async("uint8array"), { compression: "STORE" });
+    },
+    generateOptions: { compression: "DEFLATE" },
+    async skeleton() {
+        const NS = 'xmlns:office="urn:oasis:names:tc:opendocument:xmlns:office:1.0" xmlns:text="urn:oasis:names:tc:opendocument:xmlns:text:1.0" ' +
+            'xmlns:style="urn:oasis:names:tc:opendocument:xmlns:style:1.0" xmlns:fo="urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0" ' +
+            'xmlns:meta="urn:oasis:names:tc:opendocument:xmlns:meta:1.0"';
+        const zip = new JSZip();
+        zip.file("mimetype", ODT_MIME, { compression: "STORE" });
+        zip.file("META-INF/manifest.xml", '<?xml version="1.0" encoding="UTF-8"?><manifest:manifest xmlns:manifest="urn:oasis:names:tc:opendocument:xmlns:manifest:1.0" manifest:version="1.3">' +
+            `<manifest:file-entry manifest:full-path="/" manifest:version="1.3" manifest:media-type="${ODT_MIME}"/>` +
+            '<manifest:file-entry manifest:full-path="content.xml" manifest:media-type="text/xml"/>' +
+            '<manifest:file-entry manifest:full-path="styles.xml" manifest:media-type="text/xml"/>' +
+            '<manifest:file-entry manifest:full-path="meta.xml" manifest:media-type="text/xml"/></manifest:manifest>');
+        zip.file("content.xml", `<?xml version="1.0" encoding="UTF-8"?><office:document-content ${NS}>` +
+            '<office:automatic-styles>' +
+            '<style:style style:name="T_Bold" style:family="text"><style:text-properties fo:font-weight="bold"/></style:style>' +
+            '<style:style style:name="T_Italic" style:family="text"><style:text-properties fo:font-style="italic"/></style:style>' +
+            '</office:automatic-styles><office:body><office:text></office:text></office:body></office:document-content>');
+        const headingSizes = ["18pt", "16pt", "14pt", "13pt", "12pt", "11pt"];
+        const headings = headingSizes
+            .map((sz, i) => `<style:style style:name="Heading_20_${i + 1}" style:display-name="Heading ${i + 1}" style:family="paragraph" style:default-outline-level="${i + 1}" style:class="text"><style:text-properties fo:font-weight="bold" fo:font-size="${sz}"/></style:style>`)
+            .join("");
+        zip.file("styles.xml", `<?xml version="1.0" encoding="UTF-8"?><office:document-styles ${NS}><office:styles>${headings}</office:styles></office:document-styles>`);
+        zip.file("meta.xml", `<?xml version="1.0" encoding="UTF-8"?><office:document-meta ${NS}><office:meta/></office:document-meta>`);
+        return zip;
+    },
+};

package/build/citation-injector/formats/types.js

@@ -0,0 +1 @@
+export {};