@xevos117/mcp-zotero 2.0.2 → 2.0.3

package/build/tools/inject-citations.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
+import { isAbsolute } from "node:path";
 import { injectCitations } from "../citation-injector/injector.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
 export const toolConfig = {
@@ -7,13 +8,14 @@ export const toolConfig = {
     description: `Replace <zcite> placeholder tags in a .docx file with native Zotero field codes that Zotero for Word can recognize and manage. The tool fetches item metadata from Zotero automatically — you only need to provide the .docx file.
 
 WORKFLOW — how to create a Word document with live Zotero citations:
-1. Collect item keys: use add_items_by_doi (or search_library for existing items)
+1. Collect item keys: use add_items_by_doi or add_items (or search_library for existing items)
 2. Generate .docx: create a Word document (e.g. with the "docx" npm package) with <zcite keys="ITEMKEY"/> placeholders where citations should appear. Each <zcite> MUST be in its own dedicated TextRun — do NOT mix it with surrounding text.
 3. Call this tool with the .docx file path. It replaces every zcite tag with a Zotero field code and appends a bibliography.
 4. Tell the user to open the file in Word with the Zotero plugin, click Zotero → Add/Edit Bibliography, then Zotero → Refresh.
 
 CITATION STYLES — ask the user which style they want before generating:
 - apa (default): author-year — (Smith, 2023)
+- harvard / chicago: author-date — (Smith, 2023) / (Smith 2023)
 - ieee / vancouver: numbered — [1], [2]
   WARNING: for numbered styles every <zcite> MUST include a num="N" attribute with the sequential citation number. Without num, citations render as [?].
 
@@ -22,14 +24,14 @@ ZCITE TAG FORMAT:
 Supported attributes (any order):
   - keys (required): item key or comma-separated keys — "ABC12345" or "ABC12345,DEF67890"
   - num: citation number for IEEE/Vancouver — "1" or "1,2" (required for numbered styles)
-  - locator: page reference — "pp. 12-15"
-  - prefix: text before citation — "see "
+  - locator: page reference — "12-15" (shown as "pp. 12–15"; other labels explicit, e.g. "chap. 3")
+  - prefix: text before citation — "see"
   - suffix: text after citation — ", emphasis added"
 
 OUTPUT:
-A new .docx file (original filename with _cited suffix) with Zotero field codes and a ZOTERO_BIBL bibliography at the end. A cited key that is not in the library, or that is not letters and digits only, is an error and no file is written.
+A new .docx file (original filename with _cited suffix) with Zotero field codes and a ZOTERO_BIBL bibliography at the end. A cited key that is not in the library, or that is not a Zotero key (8 characters from 23456789ABCDEFGHIJKLMNPQRSTUVWXYZ), is an error and no file is written.
 
-NOTE: If the inject-citations skill is available, prefer the skill workflow (runs in sandbox, no filesystem dependency). This tool serves as the primary path when the skill is not available.`,
+WHERE THE FILE LIVES: this tool reads and writes files on the machine where this MCP server runs. If you create the .docx in a sandbox or cloud workspace that the server cannot see (for example code execution in Claude.ai or Claude Desktop, paths like /mnt/user-data/...), do not call this tool: use the zotero-mcp-integrations skill, which injects the citations inside the sandbox with metadata from get_items_details. If that skill is not installed, recommend it to the user: zotero-skill-mcp-integrations.zip from https://github.com/Xevos117/mcp-zotero/releases/latest.`,
     inputSchema: {
         file_path: z
             .string()
@@ -43,15 +45,40 @@ NOTE: If the inject-citations skill is available, prefer the skill workflow (run
     },
 };
 const InjectCitationsSchema = z.object(toolConfig.inputSchema);
+const FILE_NOT_FOUND = "File not found on the machine where this MCP server runs. If the document is in a sandbox or cloud workspace " +
+    "(for example code execution in Claude.ai or Claude Desktop), this server cannot read it: use the " +
+    "zotero-mcp-integrations skill, which injects the citations inside the sandbox. If the skill is not installed, " +
+    "ask the user to add zotero-skill-mcp-integrations.zip from https://github.com/Xevos117/mcp-zotero/releases/latest.";
 export async function handleInjectCitations(zoteroApi, userId, args) {
     const { file_path, style, library_type, library_id } = InjectCitationsSchema.parse(args);
     const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     if (!file_path.endsWith(".docx")) {
         return formatErrorResponse("File must be a .docx file", {
             file_path,
+            hint: "Only Word .docx files are supported and the name must end in lowercase .docx: convert .doc, .odt or .rtf to .docx first, or create the document as .docx with <zcite> placeholders.",
+        });
+    }
+    let result;
+    try {
+        result = await injectCitations(file_path, zoteroApi, libraryType, libraryId, style);
+    }
+    catch (err) {
+        // A path from a sandbox or cloud workspace (Claude.ai, Claude Desktop code execution) does not exist here:
+        // say so and point to the skill instead of a bare ENOENT.
+        const code = err.code;
+        if (code === "EACCES" || code === "EPERM" || code === "EROFS") {
+            return formatErrorResponse(`Cannot read the file or write the _cited copy next to it (${code}).`, {
+                file_path,
+                hint: "Copy the .docx to a folder this server can write to (e.g. the user's Documents) and call again with that path.",
+            });
+        }
+        if (code !== "ENOENT")
+            throw err;
+        return formatErrorResponse(FILE_NOT_FOUND, {
+            file_path,
+            ...(isAbsolute(file_path) ? {} : { hint: "Pass an absolute path." }),
         });
     }
-    const result = await injectCitations(file_path, zoteroApi, libraryType, libraryId, style);
     const responseObj = {
         output_path: result.outputPath,
         citations_found: result.found,

package/build/tools/search-library.js

@@ -6,8 +6,8 @@ export const toolConfig = {
     name: "search_library",
     description: `Search your Zotero library or list items sorted by a field.
 
-When 'query' is provided, searches by title, author, or any field.
-When 'query' is omitted, lists items sorted by the chosen field (default: dateAdded, descending) — this replaces the old get_recent tool.
+When 'query' is provided, matches it against titles, creator names and years (not abstracts, tags or full text).
+When 'query' is omitted, lists items sorted by the chosen field (default: dateAdded, descending).
 
 Examples:
   - Search: { "query": "deep learning" }
@@ -32,9 +32,11 @@ Use the returned item keys with get_items_details, get_item_fulltext, or inject_
             .describe("Sort direction (default: desc)"),
         limit: z
             .number()
+            .int()
+            .min(1)
             .optional()
             .default(25)
-            .describe("Maximum number of items to return (default: 25, max: 100)"),
+            .describe("Maximum number of items to return, 1-100 (default: 25; above 100 returns 100)"),
         ...libraryArgsSchema,
     },
 };
@@ -59,11 +61,11 @@ export async function handleSearchLibrary(zoteroApi, userId, args) {
         if (query) {
             return formatEmptyResult("No results found", {
                 query,
-                suggestion: "Try a different search term or verify your library contains matching items",
+                suggestion: "Nothing in this library matches the query in title, creator or year. Try fewer or different words (one author surname or a title keyword), or omit query to list recent items. For a group library pass library_type and library_id.",
             });
         }
         return formatEmptyResult("No items found", {
-            suggestion: "Add some items to your Zotero library first",
+            suggestion: "This library has no items yet. Add some with add_items_by_doi (items with a DOI) or add_items.",
         });
     }
     const formatted = items.map((item) => ({

package/build/utils/csl-to-zotero.js

@@ -1,4 +1,4 @@
-import { ITEM_TYPE_FIELDS } from "./zotero-item-types.js";
+import { ITEM_TYPE_CREATOR_TYPES, ITEM_TYPE_FIELDS } from "./zotero-item-types.js";
 const CSL_TO_ZOTERO_TYPE = {
     // Standard CSL types
     "article": "journalArticle",
@@ -112,13 +112,25 @@ const CONTAINER_TITLE_FIELD = {
     tvBroadcast: "programTitle",
     podcast: "programTitle",
 };
+/**
+ * CSL name variables ⇄ Zotero creator types, as in Zotero's CSL mappings. Authors first: the
+ * order of the CSL arrays becomes the order of the Zotero creators.
+ */
+const CSL_NAME_CREATOR_TYPES = [
+    ["author", "author"],
+    ["editor", "editor"],
+    ["container-author", "bookAuthor"],
+    ["collection-editor", "seriesEditor"],
+    ["translator", "translator"],
+];
 export function cslToZoteroItem(csl, options) {
     const itemType = (CSL_TO_ZOTERO_TYPE[csl.type] ?? "journalArticle");
-    const creators = (csl.author ?? []).map((a) => ({
-        firstName: a.given ?? "",
-        lastName: a.family ?? a.literal ?? "",
-        creatorType: "author",
-    }));
+    // Authors always (as before); other roles only where the item type has them, or the API rejects the item.
+    // A CSL `literal` (institution, consortium) is Zotero's single-field name
+    const validCreatorTypes = ITEM_TYPE_CREATOR_TYPES[itemType];
+    const creators = CSL_NAME_CREATOR_TYPES.flatMap(([variable, creatorType]) => creatorType !== "author" && !validCreatorTypes?.has(creatorType)
+        ? []
+        : (csl[variable] ?? []).map((a) => a.literal && !a.family ? { name: a.literal, creatorType } : { firstName: a.given ?? "", lastName: a.family ?? "", creatorType }));
     const dateParts = csl.issued?.["date-parts"]?.[0];
     const date = dateParts ? dateParts.join("-") : csl.issued?.literal ?? csl.issued?.raw ?? "";
     const collections = [];
@@ -168,13 +180,26 @@ export function cslToZoteroItem(csl, options) {
     }
     return result;
 }
+/** Zotero creator → CSL name: a single-field name (institution) is a CSL `literal`. */
+function cslName(c) {
+    if (c.name && !c.lastName)
+        return { literal: c.name };
+    return { family: c.lastName ?? "", given: c.firstName ?? "" };
+}
+/** CSL title of the container, from the item type's own field (bookTitle, proceedingsTitle, ...) or publicationTitle. */
+function containerTitle(item) {
+    const field = CONTAINER_TITLE_FIELD[item.itemType];
+    const fields = item;
+    const value = (field && fields[field]) || item.publicationTitle;
+    return typeof value === "string" && value ? value : undefined;
+}
 export function zoteroItemToCsl(item) {
-    const authors = (item.creators ?? [])
-        .filter((c) => c.creatorType === "author")
-        .map((c) => ({
-        family: c.lastName ?? c.name ?? "",
-        given: c.firstName ?? "",
-    }));
+    const names = {};
+    for (const [variable, creatorType] of CSL_NAME_CREATOR_TYPES) {
+        const list = (item.creators ?? []).filter((c) => c.creatorType === creatorType).map(cslName);
+        if (list.length > 0)
+            names[variable] = list;
+    }
     let issued;
     if (item.date) {
         const parts = item.date.split("-").map(Number).filter((n) => !isNaN(n));
@@ -187,10 +212,10 @@ export function zoteroItemToCsl(item) {
     return {
         type: ZOTERO_TO_CSL_TYPE[item.itemType ?? ""] ?? "article-journal",
         title: text(item.title),
-        author: authors.length > 0 ? authors : undefined,
+        ...names,
         issued,
         DOI: text(item.DOI),
-        "container-title": text(item.publicationTitle),
+        "container-title": containerTitle(item),
         volume: text(item.volume),
         issue: text(item.issue),
         page: text(item.pages),

package/build/utils/doi-resolver.js

@@ -2,6 +2,7 @@ import { mapWithConcurrency } from "./concurrency.js";
 import { fetchWithRetry } from "./fetch-retry.js";
 import { errorMessage } from "./error-formatter.js";
 import { InvalidJsonResponseError, readJsonObject } from "./json-response.js";
+import { decodeEntitiesDeep } from "./html-entities.js";
 export async function resolveDoi(doi) {
     const response = await fetchWithRetry(`https://doi.org/${encodeURIComponent(doi)}`, {
         headers: {
@@ -10,10 +11,17 @@ export async function resolveDoi(doi) {
         redirect: "follow",
     }, { label: "DOI resolution" });
     if (!response.ok) {
-        throw new Error(`DOI resolution failed for ${doi}: ${response.status} ${response.statusText}`);
+        const why = response.status === 404
+            ? " (DOI not registered or mistyped)"
+            : response.status === 429 || response.status >= 500
+                ? " (doi.org or the registry is busy or failing: retry later)"
+                : "";
+        const status = [response.status, response.statusText].filter(Boolean).join(" ");
+        throw new Error(`DOI resolution failed for ${doi}: ${status}${why}`);
     }
     try {
-        return await readJsonObject(response);
+        // the registries send some strings HTML-escaped ("Computers & Operations Research"): store the characters
+        return decodeEntitiesDeep(await readJsonObject(response));
     }
     catch (err) {
         // doi.org answers some unresolvable DOIs with an HTML page and status 200

package/build/utils/error-hints.js

@@ -0,0 +1,179 @@
+import { isZoteroApiError } from "../types/zotero-types.js";
+import { errorMessage } from "./error-formatter.js";
+import { RequestTimeoutError } from "./timeouts.js";
+/**
+ * Wording shared by the tool errors: each one says what happened, what the model can do next and,
+ * when the fix is on the user's side, what to tell the user. No secrets: status codes and hosts only.
+ */
+/**
+ * Server settings as the user sees them: the variable name, and the title of the same setting in the Claude Desktop
+ * extension (user_config of manifest.json), which has no env block.
+ */
+export const SETTINGS = {
+    apiKey: { env: "ZOTERO_API_KEY", title: "Zotero API key" },
+    userId: { env: "ZOTERO_USER_ID", title: "Zotero user ID" },
+    libraryId: { env: "ZOTERO_LIBRARY_ID", title: "Group library ID" },
+    unpaywallEmail: { env: "UNPAYWALL_EMAIL", title: "Email for Unpaywall" },
+    unsafeOperations: { env: "UNSAFE_OPERATIONS", title: "Deletions allowed" },
+};
+/** Where the user changes these settings, for every "tell the user" hint: extension or MCP config, then a restart. */
+export function whereToSet(...settings) {
+    const titles = settings.map((s) => `"${s.title}"`).join(" / ");
+    const envs = settings.map((s) => s.env).join(" / ");
+    return (`the server's settings: with the Claude Desktop extension, ${titles} in Settings → Extensions → MCP Zotero; ` +
+        `in other clients, ${envs} in the env block of this server in the MCP config (e.g. claude_desktop_config.json or .mcp.json). ` +
+        "Then restart the client");
+}
+export const API_KEYS_PAGE = "https://www.zotero.org/settings/keys";
+/** Hint for an argument that must be an existing item key. */
+export const ITEM_KEY_HINT = "Get valid item keys from search_library or get_collection_items (for a group library pass the same library_type and library_id); never guess keys.";
+/** Hint for an argument that must be an existing collection key. */
+export const COLLECTION_KEY_HINT = "Get valid collection keys from get_collections (for a group library pass the same library_type and library_id); never guess keys.";
+export const MISSING_API_KEY = "ZOTERO_API_KEY is not set in the server's environment";
+export const MISSING_API_KEY_HINT = `Tell the user to create a Zotero API key at ${API_KEYS_PAGE} and set it in ${whereToSet(SETTINGS.apiKey)}.`;
+const ACCESS_HINT = "Retrying or using other tools will not help. Tell the user to check the API key at " +
+    `${API_KEYS_PAGE}: it needs "Allow library access", "Allow write access" for tools that add or delete, ` +
+    "and access to the group for a group library; ZOTERO_USER_ID must be the userID shown on that page. " +
+    `They fix it by updating the key / user ID in ${whereToSet(SETTINGS.apiKey, SETTINGS.userId)}.`;
+const STATUS_NAMES = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    409: "Conflict",
+    412: "Precondition Failed",
+    413: "Request Entity Too Large",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+};
+function statusLabel(status) {
+    return STATUS_NAMES[status] ? `HTTP ${status} ${STATUS_NAMES[status]}` : `HTTP ${status}`;
+}
+function retryWait(retryAfterS) {
+    return retryAfterS !== undefined ? `${retryAfterS} s` : "about a minute";
+}
+/** What a Zotero Web API status means for the model: the error text and the next step. */
+export function zoteroStatusHint(status, retryAfterS) {
+    const label = statusLabel(status);
+    if (status === 401 || status === 403) {
+        return {
+            error: `Zotero refused access (${label}): the API key is invalid or revoked, cannot access this library, or lacks write access for this operation.`,
+            hint: ACCESS_HINT,
+        };
+    }
+    if (status === 404) {
+        return {
+            error: `Zotero returned ${label}: the library, item or collection does not exist or this API key cannot see it.`,
+            hint: `Do not retry with the same item or collection key. ${ITEM_KEY_HINT} Collection keys come from get_collections. If every call fails like this, the configured library id is wrong: tell the user to check the user ID (the userID at ${API_KEYS_PAGE}) or group library ID in ${whereToSet(SETTINGS.userId, SETTINGS.libraryId)}.`,
+        };
+    }
+    if (status === 409 || status === 412) {
+        return {
+            error: `The Zotero library changed or was locked during the request (${label}).`,
+            hint: "Retry the same call once.",
+        };
+    }
+    if (status === 429) {
+        return {
+            error: `Zotero rate limit reached (${label}).`,
+            hint: `Wait ${retryWait(retryAfterS)} and retry once; avoid parallel calls and send fewer items per call.`,
+        };
+    }
+    if (status >= 500) {
+        return {
+            error: `The Zotero API is temporarily unavailable (${label}).`,
+            hint: `Wait ${retryWait(retryAfterS)} and retry once. If it keeps failing, tell the user that Zotero's servers seem to have problems and to try again later.`,
+        };
+    }
+    if (status === 400 || status === 413) {
+        return {
+            error: `Zotero rejected the request (${label}).`,
+            hint: "Retrying unchanged will fail again: check the arguments (and details, if present), fix them and retry; for large batches send fewer items per call.",
+        };
+    }
+    return { error: `Zotero API error (${label}).`, hint: "Retry once; if it fails again, tell the user what failed." };
+}
+const NETWORK_ERROR = /fetch failed|socket hang up|ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH/;
+/**
+ * A failed connection (DNS, refused, reset), as thrown by fetch: a TypeError, the cause carrying the code. Only these
+ * markers count: a bug's TypeError that merely mentions a network is not reported as a retryable network error.
+ */
+function networkDetail(err) {
+    if (!(err instanceof TypeError))
+        return undefined;
+    const cause = err.cause;
+    const causeMessage = cause instanceof Error ? cause.message : undefined;
+    const text = causeMessage ? `${err.message} (${causeMessage})` : err.message;
+    return NETWORK_ERROR.test(text) ? text : undefined;
+}
+function retryAfterSeconds(response) {
+    const raw = response.headers?.get?.("Retry-After");
+    const seconds = raw ? Number(raw) : NaN;
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;
+}
+/**
+ * Short plain-text reason from a Zotero error body ("Write access denied"), never an HTML page. Library paths and
+ * long digit runs (user and group ids) are masked: the account behind the server must not be identifiable.
+ */
+function apiReason(err) {
+    const reason = err.reason;
+    if (typeof reason !== "string")
+        return undefined;
+    const text = reason
+        .trim()
+        .replace(/\b(users|groups)\/\d+/g, "$1/<id>")
+        .replace(/\b\d{5,}\b/g, "<id>");
+    if (!text || /^</.test(text))
+        return undefined;
+    return text.length > 300 ? `${text.slice(0, 300)}…` : text;
+}
+/**
+ * Error text and next step for a failure a tool did not handle itself: Zotero API errors, timeouts and
+ * network errors. Undefined for anything else (a bug), which keeps its own message.
+ */
+export function describeError(err) {
+    if (isZoteroApiError(err)) {
+        const status = err.response.status;
+        const retry_after_s = retryAfterSeconds(err.response);
+        const { error, hint } = zoteroStatusHint(status, retry_after_s);
+        const details = apiReason(err);
+        return {
+            error,
+            hint,
+            http_status: status,
+            ...(retry_after_s !== undefined ? { retry_after_s } : {}),
+            ...(details ? { details } : {}),
+        };
+    }
+    if (err instanceof RequestTimeoutError) {
+        return {
+            error: err.message,
+            hint: "Retry once. A write that timed out may still have been saved: check with search_library before repeating it, to avoid duplicates. " +
+                "If it keeps timing out, tell the user to check the network connection of the machine running this server.",
+        };
+    }
+    const network = networkDetail(err);
+    if (network) {
+        return {
+            error: `Network error: ${network}`,
+            hint: "Retry once. If it keeps failing, tell the user that the machine running this server cannot reach the service (internet connection, DNS, proxy or firewall).",
+        };
+    }
+    return undefined;
+}
+/** describeError, falling back to the raw message (with no hint) for unexpected errors. */
+export function describeAnyError(err) {
+    return describeError(err) ?? { error: errorMessage(err) };
+}
+/** Hint for a deletion blocked by UNSAFE_OPERATIONS: tell the user how to enable it, never work around it. */
+export function unsafeOperationsHint(target) {
+    const values = target === "items"
+        ? "'items' (allows delete_items) or 'all' (also delete_collection)"
+        : "'all' (allows delete_collection and delete_items; 'items' allows only delete_items)";
+    return ("Do not try to get around this with other tools (moving to the trash, editing, removing from collections). " +
+        `Tell the user that deleting is disabled in the server configuration and that, if they want to allow it, they can set ${values} ` +
+        `in ${whereToSet(SETTINGS.unsafeOperations)}, and then ask again.`);
+}

package/build/utils/html-entities.js

@@ -0,0 +1,55 @@
+/**
+ * HTML entities in registry metadata. doi.org / Crossref return some strings HTML-escaped
+ * ("Computers & Operations Research"); Zotero stores what it is given, so the entity ends up in the library
+ * and in every bibliography. Decoding only turns entities into the characters they stand for: the text stays
+ * plain text (no HTML is parsed or built), and every output that needs escaping (the .docx XML, JSON field codes)
+ * escapes it again where it is written.
+ */
+const NAMED = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: " ",
+    ndash: "–",
+    mdash: "—",
+    lsquo: "‘",
+    rsquo: "’",
+    ldquo: "“",
+    rdquo: "”",
+    hellip: "…",
+};
+const ENTITY = /&(?:#(\d{1,7})|#[xX]([0-9a-fA-F]{1,6})|([a-zA-Z]+));/g;
+function fromCodePoint(cp) {
+    // NUL, surrogates and out-of-range values are not characters: keep the entity as it is
+    if (cp === 0 || cp > 0x10ffff || (cp >= 0xd800 && cp <= 0xdfff))
+        return undefined;
+    return String.fromCodePoint(cp);
+}
+/**
+ * Decodes HTML entities in ONE pass: the output is never scanned again, so "&amp;lt;" becomes the text "&lt;",
+ * not "<". Unknown or invalid entities are left unchanged.
+ */
+export function decodeHtmlEntities(text) {
+    if (!text.includes("&"))
+        return text;
+    return text.replace(ENTITY, (whole, dec, hex, name) => {
+        if (dec !== undefined)
+            return fromCodePoint(Number.parseInt(dec, 10)) ?? whole;
+        if (hex !== undefined)
+            return fromCodePoint(Number.parseInt(hex, 16)) ?? whole;
+        return NAMED[name.toLowerCase()] ?? whole;
+    });
+}
+/** decodeHtmlEntities on every string inside a JSON value (keys untouched); other values are returned as they are. */
+export function decodeEntitiesDeep(value) {
+    if (typeof value === "string")
+        return decodeHtmlEntities(value);
+    if (Array.isArray(value))
+        return value.map((v) => decodeEntitiesDeep(v));
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, decodeEntitiesDeep(v)]));
+    }
+    return value;
+}

package/build/utils/library-context.js

@@ -18,6 +18,7 @@
  * the personal library (ZOTERO_USER_ID); a group needs an explicit id.
  */
 import { z } from "zod";
+import { SETTINGS, whereToSet } from "./error-hints.js";
 /** Zotero user and group IDs are numeric; also keeps ids safe to interpolate into API URLs. */
 const LIBRARY_ID_PATTERN = /^\d+$/;
 export function getLibraryType() {
@@ -48,7 +49,7 @@ export function getDefaultLibrary() {
     }
     const id = getLibraryId();
     if (!id) {
-        throw new Error("Missing ZOTERO_USER_ID or ZOTERO_LIBRARY_ID environment variable");
+        throw new Error("Missing ZOTERO_USER_ID or ZOTERO_LIBRARY_ID environment variable (the userID is shown at https://www.zotero.org/settings/keys)");
     }
     assertLibraryId(id, process.env.ZOTERO_LIBRARY_ID ? "ZOTERO_LIBRARY_ID" : "ZOTERO_USER_ID");
     return { type, id };
@@ -58,16 +59,13 @@ export const libraryArgsSchema = {
     library_type: z
         .enum(["user", "group"])
         .optional()
-        .describe("Override the configured Zotero library type for this call. " +
-        "Defaults to ZOTERO_LIBRARY_TYPE env (or 'user'). " +
-        "Use to target a different library per call without restarting the server."),
+        .describe("Library for this call: 'user' (personal) or 'group'. Default: the library configured on the server."),
     library_id: z
         .string()
-        .regex(LIBRARY_ID_PATTERN, "library_id must be a numeric Zotero library ID")
+        .regex(LIBRARY_ID_PATTERN, "library_id must be a numeric Zotero user or group ID (a group's ID is the number in its zotero.org/groups/<id> URL)")
         .optional()
-        .describe("Override the configured library ID for this call. " +
-        "Defaults to ZOTERO_LIBRARY_ID env (or ZOTERO_USER_ID). " +
-        "Required when library_type is 'group' and the server is configured for a user library."),
+        .describe("Numeric user or group ID for this call (a group's ID is the number in its zotero.org/groups/<id> URL). " +
+        "Default: the configured library. Required with library_type 'group' when the server is configured for a user library."),
 };
 /**
  * Resolve the library context for a single tool call. Per-call args win,
@@ -87,12 +85,14 @@ export function resolveLibrary(args, defaultLibraryId) {
         }
         else {
             // The default id belongs to a user library: never reuse it as a group id
-            throw new Error("library_id is required when library_type is 'group' and the server is configured for a user library.");
+            throw new Error("library_id is required when library_type is 'group' and the server is configured for a user library: " +
+                "pass the numeric group ID (the number in the group's zotero.org/groups/<id> URL).");
         }
     }
     if (!id) {
-        throw new Error("Zotero library ID is not set. Provide library_id arg, or set " +
-            "ZOTERO_LIBRARY_ID / ZOTERO_USER_ID in the server environment.");
+        throw new Error("Zotero library ID is not set: the server has no ZOTERO_USER_ID for the personal library. Pass library_id " +
+            "(the numeric user ID), or tell the user to set their userID (shown at https://www.zotero.org/settings/keys) in " +
+            `${whereToSet(SETTINGS.userId)}.`);
     }
     assertLibraryId(id, "library_id");
     return { type, id };

package/build/utils/pdf-uploader.js

@@ -1,5 +1,6 @@
 import { InvalidJsonResponseError, readJsonObject } from "./json-response.js";
 import { createHash } from "node:crypto";
+import { isZoteroApiError } from "../types/zotero-types.js";
 import { logger } from "./logger.js";
 import { extractPdfText } from "./pdf-text-extractor.js";
 import { putFulltext } from "./zotero-fulltext.js";
@@ -161,6 +162,7 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
             error: {
                 code: "item_creation_failed",
                 message: `Failed to create attachment item: ${detail}`,
+                ...(isZoteroApiError(err) ? { status: err.response.status } : {}),
                 networkDetail: detail,
             },
         };

package/build/utils/unpaywall.js

@@ -2,15 +2,30 @@ import { InvalidJsonResponseError, readJsonObject } from "./json-response.js";
 import { fetchWithRetry } from "./fetch-retry.js";
 import { logger } from "./logger.js";
 import { errorMessage } from "./error-formatter.js";
+import { SETTINGS, whereToSet } from "./error-hints.js";
+/** Per-item reason when the lookup is disabled; tools add UNPAYWALL_EMAIL_HINT once at top level. */
+export const UNPAYWALL_EMAIL_MISSING = "UNPAYWALL_EMAIL is not set or invalid in the server configuration: open-access PDF lookup skipped.";
+export const UNPAYWALL_EMAIL_HINT = "No PDF lookup was done (the items themselves are fine). Tell the user that open-access PDF lookup needs UNPAYWALL_EMAIL " +
+    `(a valid email address of theirs, which Unpaywall requires with each request) in ${whereToSet(SETTINGS.unpaywallEmail)}, and then run find_and_attach_pdfs.`;
 const SKIPPED_RESULT = {
     found: false,
     pdf_url: null,
     source: null,
     license: null,
     oa_status: null,
-    warning: "UNPAYWALL_EMAIL environment variable is not set or invalid. Set it to a valid email address to enable OA PDF lookup.",
+    warning: UNPAYWALL_EMAIL_MISSING,
 };
-const UNAVAILABLE_RESULT = { found: false, pdf_url: null, source: null, license: null, oa_status: null };
+/** Unpaywall unreachable or failing: not the same as "no open access copy", so say so. */
+function unavailableResult(what) {
+    return {
+        found: false,
+        pdf_url: null,
+        source: null,
+        license: null,
+        oa_status: null,
+        warning: `Unpaywall lookup failed (${what}): this does not mean there is no open access PDF. Retry later with find_and_attach_pdfs.`,
+    };
+}
 function isValidEmail(email) {
     return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
 }
@@ -34,11 +49,15 @@ export async function lookupOaPdfWithFallbacks(doi) {
     catch (err) {
         const detail = errorMessage(err);
         logger.error("Unpaywall API network error", { doi, error: detail });
-        return { primary: { ...UNAVAILABLE_RESULT }, fallback_urls: [] };
+        return { primary: unavailableResult(detail), fallback_urls: [] };
     }
     if (!response.ok) {
         logger.error("Unpaywall API error", { doi, status: response.status });
-        return { primary: { ...UNAVAILABLE_RESULT }, fallback_urls: [] };
+        if (response.status === 404) {
+            // Unpaywall does not know the DOI (not a Crossref DOI, e.g. DataCite): nothing to look up
+            return { primary: { found: false, pdf_url: null, source: null, license: null, oa_status: null }, fallback_urls: [] };
+        }
+        return { primary: unavailableResult(`HTTP ${response.status}`), fallback_urls: [] };
     }
     let data;
     try {
@@ -48,7 +67,7 @@ export async function lookupOaPdfWithFallbacks(doi) {
         if (!(err instanceof InvalidJsonResponseError))
             throw err;
         logger.error("Unpaywall API returned an invalid response", { doi, error: err.message });
-        return { primary: { ...UNAVAILABLE_RESULT }, fallback_urls: [] };
+        return { primary: unavailableResult(err.message), fallback_urls: [] };
     }
     const locations = data.is_oa
         ? [data.best_oa_location, ...(data.oa_locations ?? [])].filter((l) => l !== null && l !== undefined)

package/build/utils/zotero-keys.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 /** Zotero object keys (items, collections): 8 characters from this alphabet, never 0, 1, O or lowercase. */
 export const ZOTERO_KEY = /^[23456789ABCDEFGHIJKLMNPQRSTUVWXYZ]{8}$/;
-export const INVALID_KEY_MESSAGE = "Invalid Zotero key: expected 8 characters from 23456789ABCDEFGHIJKLMNPQRSTUVWXYZ";
+export const INVALID_KEY_MESSAGE = "Invalid Zotero key: expected 8 characters from 23456789ABCDEFGHIJKLMNPQRSTUVWXYZ (e.g. ABCD2345). " +
+    "Use a key returned by search_library, get_collection_items, get_collections or the add_* tools; never guess keys";
 /**
  * Schema for every key argument of every tool. Keys end up in API URL paths (zotero-api-client does not
  * encode path segments, and URL parsing resolves "..") and in itemKey filters (ignored by the API when

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@xevos117/mcp-zotero",
   "type": "module",
-  "version": "2.0.2",
+  "version": "2.0.3",
+  "mcpName": "io.github.Xevos117/mcp-zotero",
   "description": "Unofficial MCP server for Zotero integration with citation management",
   "repository": {
     "type": "git",
@@ -26,6 +27,7 @@
     "test:watch": "vitest",
     "build": "tsc",
     "smoke": "node scripts/smoke-stdio.mjs",
+    "bundle": "node scripts/build-mcpb.mjs",
     "start": "node build/server.js",
     "prepublishOnly": "npm test && npm run build",
     "test:e2e": "npm run build && vitest run --config vitest.e2e.config.ts",
@@ -56,8 +58,10 @@
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.296",
+    "@anthropic-ai/mcpb": "2.1.2",
     "@types/node": "^26.6.4",
     "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "citeproc": "^2.4.63",
     "typescript": "^7.0.2",
     "vitest": "^5.0.3"