@xevos117/mcp-zotero 2.0.1 → 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
@@ -226,10 +257,108 @@ claude mcp add-json "zotero" '{"command":"npx","args":["tsx","src/server.ts"],"e
 ```bash
 npm install
 npm run build          # Compile TypeScript
-npm test               # Run tests (vitest, 404 tests)
+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
 ```
 
+### Testing
+
+| Layer | Command | Runs on | What it covers |
+|---|---|---|---|
+| 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` ([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).
+
+**Live tests locally** use only `ZOTERO_TEST_*` variables, never your `ZOTERO_API_KEY`:
+
+```bash
+ZOTERO_TEST_API_KEY=... ZOTERO_TEST_USER_ID=... UNPAYWALL_EMAIL=you@example.org npm run test:live
+```
+
+Against a personal library add `ZOTERO_LIVE_SAFE_MODE=1`: the suite only creates items and collections
+named `mzt-<runId>…` and tagged `mzt-run:<runId>`, deletes only those, and skips collection deletion and
+group writes. A dedicated test account is marked by a collection named `__mzt_disposable__`.
+
+**Dependencies** are updated monthly by a Claude Code agent ([workflow](.github/workflows/deps-update.yml),
+skill [`.claude/skills/deps-update`](.claude/skills/deps-update/SKILL.md)); patch-only PRs are auto-merged after
+all required checks pass, anything else waits for review. GitHub Actions versions are updated by Dependabot.
+
+### CI setup (repository owner)
+
+| Environment | Secrets | Variables |
+|---|---|---|
+| `zotero-live` (live tests, agent smoke) | `ZOTERO_TEST_API_KEY`, `ZOTERO_TEST_USER_ID`, `ZOTERO_TEST_USERNAME`, `ZOTERO_TEST_GROUP_ID` (optional), `UNPAYWALL_EMAIL` | `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID`, `ANTHROPIC_WORKSPACE_ID` |
+| `claude-deps` (dependency agent) | — | the same four `ANTHROPIC_*` variables (the federation rule may differ) |
+
+The agents authenticate to the Claude API with Anthropic Workload Identity Federation (GitHub OIDC, no
+API key). Recommended: one federation rule per environment, as narrow as possible:
+
+| Rule for | subject (exact, no `*`) | claims (exact string pairs) | condition (CEL) |
+|---|---|---|---|
+| `zotero-live` | `repo:Xevos117/mcp-zotero:environment:zotero-live` | `repository_id: 1152178663`, `repository_owner_id: 86290818` | `claims.job_workflow_ref.startsWith("Xevos117/mcp-zotero/.github/workflows/claude-agent-smoke.yml@")` (PR runs use the PR ref) |
+| `claude-deps` | `repo:Xevos117/mcp-zotero:environment:claude-deps` | `repository_id: 1152178663`, `repository_owner_id: 86290818`, `job_workflow_ref: Xevos117/mcp-zotero/.github/workflows/deps-update.yml@refs/heads/main` | — |
+
+Claims are exact-match string pairs (only `subject_prefix` supports a trailing `*`), so a prefix such as
+"this workflow on any ref" must be written as a CEL `condition`, as above; an exact `job_workflow_ref`
+(claude-deps, main only) can be a plain claim.
+
+Audience `https://api.anthropic.com`. The subject is an exact match unless it ends with `*`; jobs that use
+an environment get the OIDC subject `repo:Xevos117/mcp-zotero:environment:<environment>`, so a rule
+written for a branch or PR subject never matches. Numeric ids (not names) keep a renamed or re-created
+repository/account from matching.
+
+Trade-off for `zotero-live`: the "any ref" condition is needed for the agent smoke test to run on pull
+requests, but it also accepts a modified copy of that workflow file pushed to any branch of this repository
+(only people with write access can push). Pinning it to the exact claim
+`job_workflow_ref: Xevos117/mcp-zotero/.github/workflows/claude-agent-smoke.yml@refs/heads/main` closes that
+gap but disables the agent smoke test on PRs (it would then run only on manual runs from `main`).
+
+Other owner settings:
+
+- The Zotero test account needs a collection named `__mzt_disposable__`.
+- Repository settings: "Allow auto-merge", and "Allow GitHub Actions to create and approve pull requests"
+  (the dependency workflow opens its PR with `GITHUB_TOKEN`). Keep the ruleset at **0 required approvals**:
+  auto-merge of the dependency PR relies on it, and it is also what makes the second setting acceptable. That
+  setting is a conscious trade-off: it lets workflows open PRs (needed) and approve them (not used by any
+  workflow here); if approvals are ever required, it would let a workflow approve its own PR, so revisit it
+  together with any approval requirement.
+- No GitHub App is used by any workflow (the agents authenticate to Anthropic with Workload Identity
+  Federation and use only `GITHUB_TOKEN` on GitHub, read-only for the agents). If the Claude GitHub App is
+  installed on this repository, uninstall it.
+- Set a monthly spend limit on the Anthropic workspace used by the federation rules: it is the real cap on
+  agent costs.
+- Residual risk: the agent smoke job that holds the OIDC token also runs the MCP server built from the PR's
+  code (that is what it tests). It runs only for same-repository PRs by the owner or a bot, the token is
+  bound to the `zotero-live` environment and the workspace spend limit caps any misuse.
+- Required checks after the stack merges: `test (node 22)`, `test (node 24)`, `test (node 26)`,
+  `live-tests`, `agent-smoke`.
+
+### Releasing
+
+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. 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
 
 ```bash

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

@@ -1,11 +1,17 @@
 import JSZip from "jszip";
 import { readFile, writeFile } from "node:fs/promises";
 import { format, parse } from "node:path";
+import { isZoteroApiError } from "../types/zotero-types.js";
 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 { 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 = [];
@@ -39,10 +45,19 @@ function parseZciteMatches(documentXml) {
 async function fetchCslData(keys, zoteroApi, libraryType, userId) {
     const cslData = new Map();
     for (const key of keys) {
-        const response = await zoteroApi
-            .library(libraryType, userId)
-            .items(key)
-            .get();
+        let response;
+        try {
+            response = await zoteroApi
+                .library(libraryType, userId)
+                .items(key)
+                .get();
+        }
+        catch (err) {
+            // Unknown keys are collected and reported together by the caller; any other failure aborts at once
+            if (isZoteroApiError(err) && err.response?.status === 404)
+                continue;
+            throw err;
+        }
         const zoteroItem = response.getData();
         cslData.set(key, zoteroItemToCsl(zoteroItem));
     }
@@ -100,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);
@@ -111,32 +132,44 @@ 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 ("../", "?", "&"); unknown keys still give a 404
-    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);
+    // No placeholder citations in the user's document: a citation of a nonexistent item fails the injection,
+    // 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(", ")}. 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) {
@@ -147,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

@@ -8,6 +8,7 @@ import { registerAllTools } from "./tools/index.js";
 import { logger } from "./utils/logger.js";
 import { parseUnsafeOperations } from "./utils/unsafe-operations.js";
 import { getDefaultLibrary } from "./utils/library-context.js";
+import { withRequestTimeout } from "./utils/timeouts.js";
 // Report the package version in the MCP handshake (package.json sits one level above both src/ and build/).
 const { version: SERVER_VERSION } = createRequire(import.meta.url)("../package.json");
 // Re-export for backward compatibility with existing tests
@@ -27,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);
@@ -44,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
@@ -54,7 +58,8 @@ class ZoteroServer {
             // global fetch; the old lib/main-node.cjs (cross-fetch polyfill) no longer exists.
             const require = createRequire(import.meta.url);
             const { default: zoteroApiFactory } = require("zotero-api-client");
-            this.zoteroApi = zoteroApiFactory(apiKey);
+            // every request carries its own AbortSignal.timeout (TIMEOUTS.zoteroApiMs)
+            this.zoteroApi = withRequestTimeout(zoteroApiFactory(apiKey));
         }
     }
     setupHandlers() {