@xevos117/mcp-zotero 2.0.2 → 2.0.3

package/README.md

@@ -34,6 +34,10 @@ LLMs without filesystem access — including Claude Desktop, which connects to M
 
 Requires **Node.js 22 or newer**.
 
+The server is listed in the official [MCP Registry](https://registry.modelcontextprotocol.io) as
+`io.github.Xevos117/mcp-zotero` (starting with the first release after 2.0.2), so registry-aware clients can find and install it from
+there; the configuration below works with any MCP client.
+
 1. Get your Zotero credentials:
 
    ```bash
@@ -160,7 +164,30 @@ To enable deletion, set the `UNSAFE_OPERATIONS` environment variable to one of t
 
 ## Integration with Claude Desktop
 
-Add to your Claude Desktop configuration:
+### Install as a Claude Desktop extension (one click)
+
+1. Download `mcp-zotero.mcpb` from the [latest release](https://github.com/Xevos117/mcp-zotero/releases/latest)
+   (available from the first release after 2.0.2).
+2. Open the file with Claude Desktop (macOS or Windows; e.g. double-click it) and confirm in the installation dialog.
+   The bundle itself is not platform-specific (`manifest.json` lists macOS, Windows and Linux, and CI runs it on
+   Linux), so other MCPB-compatible clients can install it too.
+3. Fill in your **Zotero API key** and **Zotero user ID** (see [Setup](#setup)). Optional settings: library type and
+   group ID (for a group library), the email for Unpaywall (open-access PDF lookup) and which deletions are allowed
+   (default: none, see [Unsafe Operations](#unsafe-operations)).
+
+The extension bundles the server and all its dependencies, so no npm install is needed. It needs Node.js 22 or newer
+(`compatibility.runtimes.node` in the manifest): according to the MCPB documentation, Claude Desktop runs Node.js
+extensions with the runtime that ships with the app. The API key is declared as a sensitive setting (masked
+input, stored securely by the client). Deletions stay disabled unless you change *Deletions allowed* in the
+extension settings.
+
+The extension contains only the MCP server: the Claude skills in [`skills/`](skills/) (citation injection inside
+the sandbox, scientific writing) are installed separately from their `.zip` files in the same release, as described
+in [Claude Skill Setup](#claude-skill-setup-for-claudeai-projects-and-claude-desktop).
+
+### Manual configuration (any MCP client)
+
+Add to your Claude Desktop configuration (or the equivalent file of another MCP client):
 
 ```json
 {
@@ -181,9 +208,13 @@ Add to your Claude Desktop configuration:
 ## Integration with Claude Code
 
 ```bash
-claude mcp add-json "zotero" '{"command":"npx","args":["tsx","src/server.ts"],"env":{"ZOTERO_API_KEY":"...","ZOTERO_USER_ID":"..."}}'
+claude mcp add zotero -e ZOTERO_API_KEY=YOUR_API_KEY -e ZOTERO_USER_ID=YOUR_USER_ID -- npx -y @xevos117/mcp-zotero
 ```
 
+Add `-e UNPAYWALL_EMAIL=...` or `-e UNSAFE_OPERATIONS=items` as needed, and `--scope user` to make the server
+available in every project (the default `local` scope covers only the current project). From a clone of this repository,
+`npx tsx src/server.ts` runs the server from source instead (see [Development](#development)).
+
 ## Available Tools
 
 ### Library browsing
@@ -193,7 +224,7 @@ claude mcp add-json "zotero" '{"command":"npx","args":["tsx","src/server.ts"],"e
 | `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` |
+| `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_item_fulltext` | Get full-text content of a PDF attachment via Zotero's fulltext index |
 
 ### Adding content
@@ -229,6 +260,8 @@ npm run build          # Compile TypeScript
 npm test               # Unit and per-tool tests (vitest, fetch faked, ~1000 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)
+npm run smoke -- --bundle dist/mcp-zotero.mcpb   # smoke test of the unpacked bundle, started from its manifest
 npx tsx src/server.ts  # Run directly without building
 ```
 
@@ -238,8 +271,8 @@ npx tsx src/server.ts  # Run directly without building
 |---|---|---|---|
 | Unit / per tool | `npm test` | every PR (Node 22, 24, 26) | every tool through a real MCP client, Zotero faked at the `fetch` level; produced `.docx` files are validated against the official CSL schemas and rendered with citeproc-js ([test/helpers/docx-validate.ts](test/helpers/docx-validate.ts)) |
 | E2E + smoke | `npm run test:e2e`, `npm run smoke` | every PR | the compiled server over stdio, user and group libraries |
-| Live | `npm run test:live` | PRs from this repository, `main`, nightly | the real Zotero Web API on a dedicated test account ([test/live](test/live)); skipped unless `ZOTERO_TEST_API_KEY` is set |
-| Agent smoke | [workflow](.github/workflows/claude-agent-smoke.yml) | PRs from this repository, manual runs (e.g. on `main` after a merge) | a Claude Code agent uses the server like a user, following the versioned skill [`.claude/skills/test-mcp-zotero`](.claude/skills/test-mcp-zotero/SKILL.md): `inject_citations` ⇄ `inject.js` parity in every style, fixed edge cases and up to 5 exploratory scenarios on what the PR changes. The workflow sets up the MCP server, the tool set and guard hooks (Bash allowlist, delete policy, audit log); local runs use the same pieces ([test/live/agent/README.md](test/live/agent/README.md)). The verdict comes from [test/live/verify-claims.mjs](test/live/verify-claims.mjs), not from the agent |
+| Live | `npm run test:live` ([workflow](.github/workflows/claude-agent-smoke.yml), shared with the agent smoke test) | PRs from this repository, `main`, weekly (Friday), manual runs | the real Zotero Web API on a dedicated test account ([test/live](test/live)); skipped unless `ZOTERO_TEST_API_KEY` is set |
+| Agent smoke | [workflow](.github/workflows/claude-agent-smoke.yml), after the live suite passed | PRs from this repository, manual runs (e.g. on `main` after a merge) | a Claude Code agent uses the server like a user, following the versioned skill [`.claude/skills/test-mcp-zotero`](.claude/skills/test-mcp-zotero/SKILL.md): `inject_citations` ⇄ `inject.js` parity in every style, fixed edge cases and up to 5 exploratory scenarios on what the PR changes. The workflow sets up the MCP server, the tool set and guard hooks (Bash allowlist, delete policy, audit log); local runs use the same pieces ([test/live/agent/README.md](test/live/agent/README.md)). The verdict comes from [test/live/verify-claims.mjs](test/live/verify-claims.mjs), not from the agent; each run writes a Job Summary (verdict, scenarios, exploratory findings, friction, turns/cost/duration) and keeps one comment on the PR up to date, both scrubbed of anything that identifies the test account |
 | Word | manual | every release | [test/WORD_CHECKLIST.md](test/WORD_CHECKLIST.md): open an injected document in Word with the Zotero plugin |
 
 Every test case is listed in [test/TEST_CASES.md](test/TEST_CASES.md).
@@ -310,12 +343,21 @@ Other owner settings:
 
 ### Releasing
 
-1. Update `CHANGELOG.md` (move `Unreleased` to the new version) and `version` in `package.json`.
+1. Update `CHANGELOG.md` (move `Unreleased` to the new version) and the version in `package.json`, in
+   `server.json` (`version` and `packages[0].version`) and in `manifest.json` (`npm test` fails if they differ).
 2. Make sure CI, live tests and the agent smoke test are green on `main`.
 3. Run the manual [Word checklist](test/WORD_CHECKLIST.md) on a document injected by the release candidate
    and record the results in its log.
-4. Publish the GitHub release: the [release workflow](.github/workflows/release.yml) runs the tests, publishes
-   to npm and attaches the skill zips.
+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
+   `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
+   the skill zips and the Claude Desktop extension (`mcp-zotero.mcpb`). The release tag must be the version
+   (e.g. `2.0.3`): the registry and bundle jobs check out the tag and fail if `package.json` differs.
+6. If only the `mcp-registry` job fails, use **Re-run failed jobs** on the run: **Re-run all jobs** stops at the
+   npm publish (the version already exists) and so never reaches the registry.
 
 ### Debug with MCP Inspector
 

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

@@ -1,10 +1,69 @@
-export function formatCitationText(items, style, num) {
+/**
+ * What differs between the author-date styles in the placeholder text, as citeproc renders them
+ * with the CSL styles bundled with Zotero: "(Smith, 2023, p. 12)" in apa/harvard, "(Smith 2023, 12)"
+ * in chicago; "Doe & Roe" only in apa.
+ */
+const AUTHOR_DATE = {
+    apa: { yearSep: ", ", and: "&", pageLabel: true },
+    harvard: { yearSep: ", ", and: "and", pageLabel: true },
+    chicago: { yearSep: " ", and: "and", pageLabel: false },
+};
+/**
+ * Locator as citeproc renders a locator without label (= page): "12" → "p. 12", "12-15" → "pp. 12–15";
+ * a leading "p."/"pp." written by the user is replaced, any other label ("chap. 3", "fig. 2") is kept.
+ */
+export function formatLocator(locator, pageLabel) {
+    const bare = locator.trim().replace(/^pp?\.\s*/i, "");
+    if (!/^[\divxlcdm]/i.test(bare) || /^[a-z]{2,}\.?\s/i.test(bare))
+        return locator.trim();
+    const pages = bare.replace(/(\d)\s*-+\s*(\d)/g, "$1–$2");
+    if (!pageLabel)
+        return pages;
+    return `${/[–,&]/.test(pages) ? "pp." : "p."} ${pages}`;
+}
+/** prefix/suffix the way citeproc joins them: a space after the prefix, before a suffix that does not start with punctuation. */
+function affixes(opts) {
+    const prefix = opts.prefix?.trim() ? `${opts.prefix.trim()} ` : "";
+    const s = opts.suffix?.trim() ?? "";
+    const suffix = !s ? "" : /^[,;.:)\]]/.test(s) ? s : ` ${s}`;
+    return { prefix, suffix };
+}
+/** "2,3" or "5-7" → one number per item when the count matches, otherwise undefined. */
+function numbersPerItem(num, count) {
+    const out = [];
+    for (const part of num.split(",").map((p) => p.trim())) {
+        const range = /^(\d+)\s*[-–]\s*(\d+)$/.exec(part);
+        if (range)
+            for (let n = Number(range[1]); n <= Number(range[2]); n++)
+                out.push(String(n));
+        else
+            out.push(part);
+    }
+    return out.length === count ? out : undefined;
+}
+function numberedText(count, style, opts) {
+    const num = opts.num ?? "?";
+    const { prefix, suffix } = affixes(opts);
+    // nlm-citation-sequence (vancouver) does not print locators
+    const locator = opts.locator && style === "ieee" ? `, ${formatLocator(opts.locator, true)}` : "";
+    if (!prefix && !suffix && !locator)
+        return `[${num}]`;
+    const perItem = numbersPerItem(num, count) ?? [num];
+    // ieee: each item in its own brackets ("see [1, p. 12], see [2, p. 12]"); vancouver: one group
+    if (style === "ieee")
+        return perItem.map((n) => `${prefix}[${n}${locator}]${suffix}`).join(", ");
+    return `[${perItem.map((n) => `${prefix}${n}${suffix}`).join(",")}]`;
+}
+export function formatCitationText(items, style, opts = {}) {
     if (style === "ieee" || style === "vancouver") {
-        return num ? `[${num}]` : "[?]";
+        return numberedText(items.length, style, opts);
     }
+    const rules = AUTHOR_DATE[style] ?? AUTHOR_DATE.apa;
+    const { prefix, suffix } = affixes(opts);
+    const locator = opts.locator ? `, ${formatLocator(opts.locator, rules.pageLabel)}` : "";
     const parts = items.map((item) => {
         const authors = item.author;
-        const firstAuthor = authors?.[0]?.family ?? "Unknown";
+        const name = (a) => a.family ?? a.literal ?? "Unknown";
         const year = item.issued?.["date-parts"]?.[0]?.[0]?.toString() ?? "n.d.";
         let authorText;
         if (!authors || authors.length === 0) {
@@ -16,15 +75,15 @@ export function formatCitationText(items, style, num) {
                 : "Unknown";
         }
         else if (authors.length > 2) {
-            authorText = `${firstAuthor} et al.`;
+            authorText = `${name(authors[0])} et al.`;
         }
         else if (authors.length === 2) {
-            authorText = `${firstAuthor} & ${authors[1].family}`;
+            authorText = `${name(authors[0])} ${rules.and} ${name(authors[1])}`;
         }
         else {
-            authorText = firstAuthor;
+            authorText = name(authors[0]);
         }
-        return `${authorText}, ${year}`;
+        return `${prefix}${authorText}${rules.yearSep}${year}${locator}${suffix}`;
     });
     return `(${parts.join("; ")})`;
 }

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

@@ -0,0 +1,121 @@
+import { randomBytes } from "node:crypto";
+/**
+ * Zotero document preferences (style, field type) in docProps/custom.xml, as Zotero for Word writes them: the
+ * serialized document data split into the custom properties ZOTERO_PREF_1…n, at most 255 characters each (Word's
+ * limit for a property; the plugin concatenates _1, _2… until one is missing). Without them the first Refresh opens
+ * Document Preferences and proposes Zotero's last used style instead of the injected one (H-W1, word-proxy job).
+ * A document that already has ZOTERO_PREF_* properties is already managed by Zotero and is left as it is.
+ * The skill's inject.js writes the same properties (keep both in sync).
+ */
+/** Tool style → id of the CSL style shipped with Zotero (class in-text). */
+export const ZOTERO_STYLE_IDS = {
+    apa: "http://www.zotero.org/styles/apa",
+    ieee: "http://www.zotero.org/styles/ieee",
+    vancouver: "http://www.zotero.org/styles/nlm-citation-sequence",
+    harvard: "http://www.zotero.org/styles/harvard-cite-them-right",
+    chicago: "http://www.zotero.org/styles/chicago-author-date",
+};
+const CUSTOM_PART = "docProps/custom.xml";
+const CUSTOM_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.custom-properties+xml";
+const CUSTOM_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties";
+/** fmtid of user-defined custom properties. */
+const FMTID = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}";
+export const PREF_CHUNK = 255;
+const SESSION_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const escapeXml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+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()) {
+    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>`);
+}
+/** The value split into ZOTERO_PREF_1…n chunks. */
+export function prefChunks(value) {
+    const out = [];
+    for (let i = 0; i < value.length; i += PREF_CHUNK)
+        out.push(value.slice(i, i + PREF_CHUNK));
+    return out;
+}
+export const EXISTING_PREFS_WARNING = "The document already has Zotero document preferences (ZOTERO_PREF_* in docProps/custom.xml): kept as they are, so on the " +
+    "first Refresh Zotero uses the style saved there, not the style of this injection.";
+export const PREFS_NOT_WRITTEN_WARNING = "Zotero document preferences not written: the document's custom properties part could not be merged into, so Zotero may " +
+    "ask for the document style (Document Preferences) on the first Refresh.";
+/** Part name of the custom properties: the target of the package relationship if there is one, else docProps/custom.xml. */
+function customPartName(rels) {
+    for (const m of (rels ?? "").matchAll(/<Relationship\b[^>]*>/g)) {
+        if (!m[0].includes(CUSTOM_REL_TYPE))
+            continue;
+        const target = /\bTarget=["']([^"']+)["']/.exec(m[0])?.[1];
+        if (target)
+            return target.replace(/^\/+/, "");
+    }
+    return CUSTOM_PART;
+}
+/**
+ * Writes the Zotero document preferences for `style` into the docx: the custom properties part (merged into an
+ * existing one, with its root's namespace prefix), its content type and its package relationship, each only when
+ * missing. Never rewrites an existing part it cannot merge into: then nothing changes ("skipped"). A document that
+ * already has ZOTERO_PREF_* properties is left as it is ("kept").
+ */
+export async function writeZoteroDocumentPrefs(zip, style) {
+    const styleId = ZOTERO_STYLE_IDS[style];
+    if (!styleId)
+        return "skipped";
+    const rels = await zip.file("_rels/.rels")?.async("string");
+    const part = customPartName(rels);
+    const existing = await zip.file(part)?.async("string");
+    if (existing && /\bname=["']ZOTERO_PREF_\d+["']/.test(existing))
+        return "kept";
+    const pids = [...(existing ?? "").matchAll(/\bpid=["'](\d+)["']/g)].map((m) => Number(m[1]));
+    let pid = Math.max(1, ...pids);
+    const root = existing ? /<(\w+:)?Properties\b([^>]*?)(\/?)>/.exec(existing) : null;
+    const prefix = root?.[1] ?? "";
+    const properties = prefChunks(zoteroDocumentData(styleId))
+        .map((chunk, i) => `<${prefix}property fmtid="${FMTID}" pid="${++pid}" name="ZOTERO_PREF_${i + 1}"><vt:lpwstr>${escapeXml(chunk)}</vt:lpwstr></${prefix}property>`)
+        .join("");
+    if (existing) {
+        if (!root)
+            return "skipped";
+        let merged;
+        if (root[3]) {
+            // empty root <Properties …/>
+            merged = existing.replace(root[0], `<${prefix}Properties${root[2]}>${properties}</${prefix}Properties>`);
+        }
+        else {
+            const close = `</${prefix}Properties>`;
+            const at = existing.lastIndexOf(close);
+            if (at < 0)
+                return "skipped";
+            merged = existing.slice(0, at) + properties + existing.slice(at);
+        }
+        // the vt prefix of the new properties must be declared on the root
+        if (!/xmlns:vt=/.test(merged))
+            merged = merged.replace(`<${prefix}Properties`, `<${prefix}Properties xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes"`);
+        if (merged === existing || !merged.includes(properties))
+            return "skipped";
+        zip.file(part, merged);
+    }
+    else {
+        zip.file(part, '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+            '<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/custom-properties" ' +
+            `xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes">${properties}</Properties>`);
+    }
+    const typesEntry = zip.file("[Content_Types].xml");
+    if (typesEntry) {
+        const types = await typesEntry.async("string");
+        if (!types.includes(`PartName="/${part}"`)) {
+            zip.file("[Content_Types].xml", types.replace("</Types>", `<Override PartName="/${part}" ContentType="${CUSTOM_CONTENT_TYPE}"/></Types>`));
+        }
+    }
+    if (rels !== undefined && !rels.includes(CUSTOM_REL_TYPE)) {
+        const ids = new Set([...rels.matchAll(/\bId=["']([^"']+)["']/g)].map((m) => m[1]));
+        let n = 1;
+        while (ids.has(`rId${n}`))
+            n++;
+        zip.file("_rels/.rels", rels.replace("</Relationships>", `<Relationship Id="rId${n}" Type="${CUSTOM_REL_TYPE}" Target="${part}"/></Relationships>`));
+    }
+    return "written";
+}

package/build/citation-injector/injector.js

@@ -6,7 +6,12 @@ import { generateZoteroFieldCode, generateBibliographyFieldCode } from "./field-
 import { formatCitationText } from "./citation-formatter.js";
 import { regexEscape, unescapeXml } from "./xml-utils.js";
 import { normalizeZciteTags } from "./zcite-normalizer.js";
+import { EXISTING_PREFS_WARNING, PREFS_NOT_WRITTEN_WARNING, writeZoteroDocumentPrefs } from "./document-prefs.js";
 import { zoteroItemToCsl } from "../utils/csl-to-zotero.js";
+import { ZOTERO_KEY } from "../utils/zotero-keys.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.";
+const NO_ZCITE_WARNING = 'No <zcite> placeholders found: the output is an unchanged copy. Write them in the document body as <zcite keys="ITEMKEY"/> ' +
+    "(headers, footers, footnotes and comments are not scanned).";
 function parseZciteMatches(documentXml) {
     const findRegex = /&lt;zcite\s+[\s\S]*?\/&gt;/g;
     const matches = [];
@@ -110,10 +115,16 @@ export async function injectCitations(filePath, zoteroApi, libraryType, userId,
     const { dir, name, ext } = parse(filePath);
     const outputPath = format({ dir, name: `${name}_cited`, ext });
     const fileBuffer = await readFile(filePath);
-    const zip = await JSZip.loadAsync(fileBuffer);
+    let zip;
+    try {
+        zip = await JSZip.loadAsync(fileBuffer);
+    }
+    catch (err) {
+        throw new Error(`Invalid .docx file: not a readable ZIP archive (${err instanceof Error ? err.message : String(err)}). ${REGENERATE_DOCX}`);
+    }
     const documentEntry = zip.file("word/document.xml");
     if (!documentEntry) {
-        throw new Error("Invalid .docx file: word/document.xml not found");
+        throw new Error(`Invalid .docx file: word/document.xml not found. ${REGENERATE_DOCX}`);
     }
     let documentXml = await documentEntry.async("string");
     documentXml = normalizeZciteTags(documentXml);
@@ -121,23 +132,27 @@ export async function injectCitations(filePath, zoteroApi, libraryType, userId,
     if (matches.length === 0) {
         const buffer = await zip.generateAsync({ type: "nodebuffer" });
         await writeFile(outputPath, buffer);
-        return { outputPath, found: 0, injected: 0, warnings: [] };
+        return { outputPath, found: 0, injected: 0, warnings: [NO_ZCITE_WARNING] };
     }
     // 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.`);
+            warnings.push(`Style '${style}' requires 'num' attribute on <zcite> tags. Found ${withNum}/${matches.length} tags with num. ` +
+                "Citations without num show [?] until the user runs Zotero → Refresh in Word; to get the numbers now, add " +
+                'num="N" (order of first citation) to every <zcite> in the original file and run again.');
         }
     }
     // Collect all unique item keys
     const uniqueKeys = new Set(matches.flatMap((m) => m.keys));
-    // Keys from the document go into API URL paths (one GET per key): only letters and digits, so a crafted
-    // <zcite> cannot point the request at another endpoint ("../", "?", "&"). The skill's inject.js applies the same check
-    const invalid = [...uniqueKeys].filter((k) => !/^[A-Za-z0-9]{1,32}$/.test(k));
+    // Keys from the document go into API URL paths (one GET per key) and Zotero URIs: only well-formed Zotero
+    // keys, so a crafted <zcite> cannot point the request at another endpoint ("../", "?", "&"), and a key Zotero
+    // would reject never reaches the document. The skill's inject.js applies the same check
+    const invalid = [...uniqueKeys].filter((k) => !ZOTERO_KEY.test(k));
     if (invalid.length > 0) {
-        throw new Error(`Invalid Zotero item key(s) in <zcite>: ${invalid.join(", ")} (letters and digits only)`);
+        throw new Error(`Invalid Zotero item key(s) in <zcite>: ${invalid.join(", ")} (a key is 8 characters from 23456789ABCDEFGHIJKLMNPQRSTUVWXYZ). ` +
+            "No file was written. Use the keys returned by search_library, add_items_by_doi or add_items.");
     }
     // Fetch CSL data from Zotero
     const cslData = await fetchCslData(uniqueKeys, zoteroApi, libraryType, userId);
@@ -145,14 +160,16 @@ export async function injectCitations(filePath, zoteroApi, libraryType, userId,
     // like the skill's inject.js with a key missing from metadata.json
     const missingKeys = [...uniqueKeys].filter((k) => !cslData.has(k));
     if (missingKeys.length > 0) {
-        throw new Error(`${missingKeys.length} cited key(s) not found in the library: ${missingKeys.join(", ")}`);
+        throw new Error(`${missingKeys.length} cited key(s) not found in the library: ${missingKeys.join(", ")}. No file was written. ` +
+            "Fix these keys in the document (find existing items with search_library, or add the missing ones with add_items_by_doi " +
+            "or add_items) and call again; for a group library pass library_type and library_id.");
     }
     // Replace each zcite tag with a field code
     let injected = 0;
     for (const match of matches) {
         const citationItems = buildCitationItems(match, cslData, libraryType, userId);
         const itemDataList = match.keys.map((k) => cslData.get(k) ?? { type: "article-journal" });
-        const formattedText = formatCitationText(itemDataList, style, match.num);
+        const formattedText = formatCitationText(itemDataList, style, match);
         const fieldCodeXml = generateZoteroFieldCode(citationItems, formattedText);
         const newXml = replaceZciteInXml(documentXml, match.fullMatch, fieldCodeXml);
         if (newXml !== documentXml) {
@@ -163,8 +180,15 @@ export async function injectCitations(filePath, zoteroApi, libraryType, userId,
     // Append bibliography before </w:body>
     const biblXml = generateBibliographyFieldCode();
     documentXml = documentXml.replace("</w:body>", `${biblXml}</w:body>`);
-    // Save
+    // Document preferences (style, field type) where Zotero for Word reads them: no Document Preferences dialog
+    // on the first Refresh, the injected style is applied (H-W1)
     zip.file("word/document.xml", documentXml);
+    const prefs = await writeZoteroDocumentPrefs(zip, style);
+    if (prefs === "kept")
+        warnings.push(EXISTING_PREFS_WARNING);
+    if (prefs === "skipped")
+        warnings.push(PREFS_NOT_WRITTEN_WARNING);
+    // Save
     const buffer = await zip.generateAsync({ type: "nodebuffer" });
     await writeFile(outputPath, buffer);
     return { outputPath, found: matches.length, injected, warnings };

package/build/server.js

@@ -28,13 +28,16 @@ class ZoteroServer {
                 "CITATION WORKFLOW:",
                 "1. Collect item keys: use add_items_by_doi for items with DOIs, add_items for items without DOIs (or search_library for existing items)",
                 "2. Generate .docx: create a Word document with <zcite keys=\"ITEMKEY\"/> placeholders where citations should appear. Each <zcite> must be in its own TextRun.",
-                "3. Call inject_citations with the .docx file path — it fetches metadata from Zotero automatically.",
+                "3. Call inject_citations with the .docx file path — it fetches metadata from Zotero automatically. The file must be on the machine where this server runs.",
                 "4. Tell the user to open it in Word with the Zotero plugin → Zotero → Add/Edit Bibliography, then Zotero → Refresh.",
                 "",
                 "KEY NOTES:",
-                "- add_items_by_doi auto-attaches OA PDFs via Unpaywall at no cost. Do not disable auto_attach_pdf unless it causes errors.",
+                "- add_items_by_doi auto-attaches open-access PDFs found via Unpaywall (needs UNPAYWALL_EMAIL in the server settings; uses the user's Zotero storage). Do not disable auto_attach_pdf unless it causes errors.",
                 "- For IEEE/Vancouver (numbered) citation styles, every <zcite> MUST include a num attribute. num is the citation number assigned in order of first appearance in the text (first cited = num=\"1\", second = num=\"2\", etc.). For multi-item citations use comma-separated values: keys=\"KEY1,KEY2\" num=\"1,2\". Without num, citations render as [?].",
-                "- get_user_id is only needed by the standalone skill script (inject.js), not by the inject_citations tool.",
+                "- If the .docx is in a sandbox or cloud workspace this server cannot see (code execution in Claude.ai or Claude Desktop), use the zotero-mcp-integrations skill instead of inject_citations. If it is not installed, recommend zotero-skill-mcp-integrations.zip from https://github.com/Xevos117/mcp-zotero/releases/latest.",
+                "- get_user_id is only needed by the skill script (inject.js), not by the inject_citations tool.",
+                "- Deleting is off unless the server setting UNSAFE_OPERATIONS (\"Deletions allowed\" in the Claude Desktop extension) allows it ('items': delete_items; 'all': also delete_collection). Never work around a blocked deletion with other tools.",
+                "- Errors carry a hint with the next step. When it says the fix is on the user's side (API key, server settings), tell the user instead of retrying.",
             ].join("\n"),
         });
         this.unsafeOps = parseUnsafeOperations(process.env.UNSAFE_OPERATIONS);
@@ -45,7 +48,7 @@ class ZoteroServer {
         else {
             const apiKey = process.env.ZOTERO_API_KEY || "";
             if (!apiKey) {
-                throw new Error("Missing ZOTERO_API_KEY environment variable");
+                throw new Error("Missing ZOTERO_API_KEY environment variable (create a key at https://www.zotero.org/settings/keys)");
             }
             // Validate the library configuration eagerly so a misconfigured server fails
             // fast at startup rather than on the first tool call. ZOTERO_LIBRARY_ID takes

package/build/tools/add-items-by-doi.js

@@ -6,12 +6,13 @@ import { cslToZoteroItem } from "../utils/csl-to-zotero.js";
 import { postInBatches } from "../utils/write-results.js";
 import { attachOpenAccessPdfs } from "../utils/oa-pdf.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { UNPAYWALL_EMAIL_HINT, UNPAYWALL_EMAIL_MISSING } from "../utils/unpaywall.js";
 export const toolConfig = {
     name: "add_items_by_doi",
     description: `Add items to your Zotero library by resolving DOIs. Works with ANY item type that has a DOI — journal articles, books, datasets, preprints, conference papers, reports, etc. For each DOI, resolves metadata via content negotiation and creates the item in Zotero with the correct type automatically. Returns a list of successfully added items (with item_key and title) and any failures.
 
 WHEN TO USE vs add_items:
-- Use add_items_by_doi when the item HAS a DOI — it auto-resolves all metadata and attaches OA PDFs.
+- Use add_items_by_doi when the item HAS a DOI — it auto-resolves all metadata and attaches open-access PDFs (when the server has UNPAYWALL_EMAIL set).
 - Use add_items when the item does NOT have a DOI, or when you need to override specific metadata fields (add_items_by_doi does not allow metadata overrides).
 - Mixed batch: if some items have DOIs and others don't, make two separate calls — add_items_by_doi for the DOIs and add_items for the rest.
 
@@ -21,7 +22,7 @@ WORKFLOW TIPS:
     inputSchema: {
         dois: z
             .array(z.string().trim().min(1, "DOI must not be empty"))
-            .describe('Array of DOI strings (e.g. ["10.1038/s41586-023-06647-8"]). Each DOI will be resolved and added to Zotero.'),
+            .describe('Array of bare DOIs (e.g. ["10.1038/s41586-023-06647-8"], without "https://doi.org/"). Each DOI will be resolved and added to Zotero.'),
         collection_key: zoteroKey()
             .optional()
             .describe("Zotero collection key to add items to. Get this from create_collection or get_collections."),
@@ -32,7 +33,7 @@ WORKFLOW TIPS:
         auto_attach_pdf: z
             .boolean()
             .default(true)
-            .describe("Attach freely available OA PDFs via Unpaywall (default: true). This is lightweight and adds no cost — leave enabled. Only set to false if PDF attachment is causing errors."),
+            .describe("Attach open-access PDFs found via Unpaywall (default: true; needs UNPAYWALL_EMAIL in the server settings, uses the user's Zotero file storage). Leave enabled unless the user does not want PDFs or attachment is causing errors."),
         ...libraryArgsSchema,
     },
 };
@@ -41,12 +42,14 @@ export async function handleAddItemsByDoi(zoteroApi, userId, args) {
     const { dois, collection_key, tags, auto_attach_pdf, library_type, library_id } = AddItemsByDoiSchema.parse(args);
     const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     if (dois.length === 0) {
-        return formatErrorResponse("At least one DOI is required");
+        return formatErrorResponse('At least one DOI is required: pass dois as an array, e.g. ["10.1038/s41586-023-06647-8"].');
     }
     const resolved = await resolveDois(dois);
     if (resolved.success.length === 0) {
         return formatErrorResponse("All DOI resolutions failed", {
             failed: resolved.failed,
+            hint: "Nothing was created; failed[].error gives the reason per DOI. Pass bare DOIs (10.xxxx/...) and check them for typos. " +
+                "For a DOI that does not resolve, add the item with add_items and its metadata instead. If every DOI failed with a timeout, network or 5xx error, retry later.",
         });
     }
     const zoteroItems = resolved.success.map((r) => cslToZoteroItem(r.data, {
@@ -61,7 +64,10 @@ export async function handleAddItemsByDoi(zoteroApi, userId, args) {
     ];
     if (write.created.length === 0) {
         const errorMessages = write.failed.map(({ index, error }) => `Item ${index}: ${error}`).join("; ");
-        return formatErrorResponse(`Zotero API write failed: ${errorMessages}`, { failed });
+        return formatErrorResponse(`Zotero API write failed: ${errorMessages}`, {
+            failed,
+            hint: "Nothing was created. Fix what failed[].error reports (an invalid collection_key: check it with get_collections) and retry; for a rate limit or server error, wait a minute and retry once.",
+        });
     }
     const success = write.created.map(({ index, entity }) => {
         const { doi, data } = resolved.success[index];
@@ -81,14 +87,16 @@ export async function handleAddItemsByDoi(zoteroApi, userId, args) {
             : { ...r, pdf_attached: false, error: r.reason });
     }
     const quotaHit = pdf_results?.some((r) => r.status === "quota_exceeded");
+    const unpaywallOff = pdf_results?.some((r) => r.reason === UNPAYWALL_EMAIL_MISSING);
     return formatJsonResult({
         success,
         failed,
         ...(pdf_results !== undefined ? { pdf_results } : {}),
         ...(quotaHit
             ? {
-                storage_quota_warning: "Zotero storage quota is full. Some PDF attachments were skipped. All items were created successfully (metadata only). Free up space at https://www.zotero.org/settings/storage or upgrade your plan.",
+                storage_quota_warning: "Zotero storage quota is full. Some PDF attachments were skipped. All items were created successfully (metadata only). Tell the user they can free up space or upgrade at https://www.zotero.org/settings/storage, then attach the PDFs with find_and_attach_pdfs.",
             }
             : {}),
+        ...(unpaywallOff ? { hint: UNPAYWALL_EMAIL_HINT } : {}),
     });
 }

package/build/tools/add-items.js

@@ -56,7 +56,7 @@ WHEN TO USE:
 - Mixed batch: if some items have DOIs and others don't, call add_items_by_doi for the DOIs and add_items for the rest (two separate calls)
 - Prefer add_items_by_doi when DOIs are available AND you don't need to override metadata (it auto-resolves everything and attaches OA PDFs)
 
-BATCH: Pass multiple items in the 'items' array (single API call).
+BATCH: Pass multiple items in the 'items' array (one tool call).
 
 COMMON FIELDS (available for most types):
 title, date, abstractNote, url, DOI, publisher, place, pages, volume, language, extra
@@ -130,7 +130,10 @@ export async function handleAddItems(zoteroApi, userId, args) {
     }));
     const failed = write.failed.map(({ index, error }) => ({ index, title: items[index].title, error }));
     if (success.length === 0 && failed.length > 0) {
-        return formatErrorResponse("All items failed to create", { failed });
+        return formatErrorResponse("All items failed to create", {
+            failed,
+            hint: "Nothing was created. failed[].error gives Zotero's reason per item: fix those items (an invalid collection_key: check it with get_collections) and call again; retrying unchanged will fail again.",
+        });
     }
     return formatJsonResult({
         success,

package/build/tools/add-linked-url-attachment.js

@@ -3,9 +3,10 @@ import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { formatWriteErrors } from "../utils/write-results.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { COLLECTION_KEY_HINT, ITEM_KEY_HINT } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "add_linked_url_attachment",
-    description: "Attach a linked URL to an existing Zotero item, or create a standalone linked-URL attachment. Use this to link external PDFs, web pages, or other resources to items already in your library. If parent_item is provided, the attachment is added as a child; otherwise it is standalone.",
+    description: "Attach a linked URL to an existing Zotero item, or create a standalone linked-URL attachment. Use this to link external PDFs, web pages, or other resources to items already in your library. If parent_item is provided, the attachment is added as a child; otherwise it is standalone. A linked URL stores no file and no full text (get_item_fulltext cannot read it): to store a PDF in Zotero use import_pdf_to_zotero.",
     inputSchema: {
         url: z.string().url().describe("URL of the resource to link"),
         title: z
@@ -18,7 +19,7 @@ export const toolConfig = {
             .describe('MIME type of the linked resource (e.g. "application/pdf", "text/html")'),
         parent_item: zoteroKey()
             .optional()
-            .describe("Item key of the parent item. If provided, the attachment becomes a child of that item."),
+            .describe("Key of the parent item (a regular item, not an attachment or note), from search_library or get_collection_items. If provided, the attachment becomes a child of that item."),
         collections: z
             .array(zoteroKey())
             .optional()
@@ -59,6 +60,9 @@ export async function handleAddLinkedUrlAttachment(zoteroApi, userId, args) {
         const errorMsg = formatWriteErrors(response.getErrors());
         return formatErrorResponse("Failed to create linked URL attachment", {
             details: errorMsg,
+            hint: parent_item
+                ? `details has Zotero's reason. parent_item must be an existing regular item, not an attachment or note: ${ITEM_KEY_HINT}`
+                : `details has Zotero's reason. Check the collections keys: ${COLLECTION_KEY_HINT}`,
         });
     }
     const created = response.getData();

package/build/tools/create-collection.js

@@ -3,9 +3,10 @@ import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { formatWriteErrors } from "../utils/write-results.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { COLLECTION_KEY_HINT } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "create_collection",
-    description: "Create a new collection (folder) in your Zotero library. Optionally nest it under a parent collection. Returns the new collection key and name. Use the key with add_items_by_doi to organize imported papers.",
+    description: "Create a new collection (folder) in your Zotero library. Optionally nest it under a parent collection. Returns the new collection key and name. Use the key as collection_key in add_items_by_doi or add_items to organize imported papers.",
     inputSchema: {
         name: z.string().describe("Name of the new collection"),
         parent_collection: zoteroKey()
@@ -19,7 +20,7 @@ export async function handleCreateCollection(zoteroApi, userId, args) {
     const { name, parent_collection, library_type, library_id } = CreateCollectionSchema.parse(args);
     const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     if (!name?.trim()) {
-        return formatErrorResponse("Collection name is required");
+        return formatErrorResponse("Collection name is required: pass a non-empty name.");
     }
     const collectionData = { name: name.trim() };
     if (parent_collection) {
@@ -33,6 +34,9 @@ export async function handleCreateCollection(zoteroApi, userId, args) {
         const errorMsg = formatWriteErrors(response.getErrors());
         return formatErrorResponse("Failed to create collection", {
             details: errorMsg,
+            hint: parent_collection
+                ? `details has Zotero's reason. Check that parent_collection exists: ${COLLECTION_KEY_HINT}`
+                : "details has Zotero's reason: fix the name if it is the cause and retry.",
         });
     }
     const created = response.getData();