@xevos117/mcp-zotero 2.0.1 → 2.0.3

package/build/tools/import-pdf-to-zotero.js

@@ -3,9 +3,10 @@ import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse, errorMessage, logToolError } from "../utils/error-formatter.js";
 import { downloadAndUploadPdf } from "../utils/pdf-uploader.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { COLLECTION_KEY_HINT, ITEM_KEY_HINT, MISSING_API_KEY, MISSING_API_KEY_HINT, describeAnyError, zoteroStatusHint } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "import_pdf_to_zotero",
-    description: "Download a PDF from a URL and upload it to Zotero storage as an imported_url attachment. Unlike linked URL attachments, imported files are stored in Zotero's storage and become fulltext-indexed (searchable via get_item_fulltext). Use this when you need the PDF content to be indexed by Zotero.",
+    description: "Download a PDF from a URL and upload it to Zotero storage as an imported_url attachment. Unlike linked URL attachments, imported files are stored in Zotero's storage and become fulltext-indexed (searchable via get_item_fulltext). Use this when you need the PDF content to be indexed by Zotero. The URL must lead straight to the PDF file (no login, paywall or HTML landing page); files up to 100 MB, counted against the user's Zotero file storage. For items with a DOI, find_and_attach_pdfs finds open-access PDFs by itself.",
     inputSchema: {
         url: z.string().url().describe("URL of the PDF to download and import"),
         filename: z
@@ -20,7 +21,7 @@ export const toolConfig = {
             .string()
             .optional()
             .default("application/pdf")
-            .describe('MIME type of the file (default: "application/pdf")'),
+            .describe('MIME type recorded on the attachment (default: "application/pdf"). This tool imports PDFs only: the downloaded file must start with %PDF- or the import is rejected, whatever this value says. Full text is extracted only for "application/pdf".'),
         parent_item: zoteroKey()
             .optional()
             .describe("Item key of the parent item. If provided, the attachment becomes a child of that item."),
@@ -36,12 +37,33 @@ export const toolConfig = {
     },
 };
 const ImportPdfSchema = z.object(toolConfig.inputSchema);
+/** Next step for an HTTP error from the site serving the PDF. */
+function downloadFailureHint(status) {
+    if (status === 401 || status === 402 || status === 403) {
+        return "The site refuses the download (login, paywall or bot protection): try an open-access copy (find_and_attach_pdfs for an item with a DOI, or a repository link), or the user downloads it in a browser and adds it in Zotero desktop.";
+    }
+    if (status === 404 || status === 410)
+        return "The URL does not exist: check it for typos or find the current PDF link.";
+    if (status === 429 || (status !== undefined && status >= 500))
+        return "The site is busy or failing: wait a minute and retry once.";
+    return "Check that the URL leads straight to the PDF file and retry.";
+}
+/** Zotero storage step failed after the attachment record was created: say so, and what to do next. */
+function uploadFailureHint(status, itemKey) {
+    const next = status === 401 || status === 403
+        ? zoteroStatusHint(status).hint
+        : "Retry once after a short wait (timeouts and 5xx errors are usually temporary).";
+    return {
+        ...(itemKey ? { item_key: itemKey } : {}),
+        hint: `${itemKey ? "An attachment record (item_key) was created without the file; a retry creates a new one, so mention it to the user (they can delete it in Zotero). " : ""}${next}`,
+    };
+}
 export async function handleImportPdfToZotero(zoteroApi, userId, args) {
     const { url, filename, title, content_type, parent_item, collections, tags, library_type, library_id } = ImportPdfSchema.parse(args);
     const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     const apiKey = process.env.ZOTERO_API_KEY;
     if (!apiKey) {
-        return formatErrorResponse("ZOTERO_API_KEY environment variable is not set");
+        return formatErrorResponse(MISSING_API_KEY, { hint: MISSING_API_KEY_HINT });
     }
     try {
         const result = await downloadAndUploadPdf(zoteroApi, libraryType, libraryId, apiKey, {
@@ -59,45 +81,59 @@ export async function handleImportPdfToZotero(zoteroApi, userId, args) {
                     return formatErrorResponse("Network error downloading file", {
                         url,
                         details: result.error.networkDetail,
-                        suggestion: "The server may be blocking automated requests, the URL may redirect to an HTML page, or it may require authentication. Try a direct PDF link from another source (e.g. PubMed Central, Sci-Hub, or the publisher's direct PDF endpoint).",
+                        suggestion: "The site may be unreachable, block automated downloads or require a login. Retry once if it looks temporary (timeout, connection reset); otherwise try a direct PDF link from an open source (PubMed Central, arXiv, an institutional repository, the publisher's PDF link) or, for an item with a DOI, find_and_attach_pdfs. If the user has the PDF, they can add it in Zotero desktop.",
                     });
                 case "download_failed":
-                    return formatErrorResponse("Failed to download file from URL", {
+                    return formatErrorResponse(`Failed to download file from URL (HTTP ${result.error.status})`, {
                         url,
                         status: result.error.status,
+                        suggestion: downloadFailureHint(result.error.status),
                     });
                 case "file_too_large":
                     return formatErrorResponse("File exceeds 100 MB limit", {
                         size_bytes: result.error.sizeBytes,
+                        suggestion: "This tool imports files up to 100 MB; nothing was created. The user can add larger files in Zotero desktop.",
                     });
                 case "storage_quota_exceeded":
                     return formatErrorResponse("Zotero storage quota exceeded", {
                         status: result.error.status,
                         suggestion: "Your Zotero cloud storage is full. Free up space by deleting stored files in your Zotero library, or upgrade your storage plan at https://www.zotero.org/settings/storage. Note: item metadata and linked URL attachments do not consume storage — only imported file attachments do.",
                         item_key: result.itemKey,
-                        note: "An attachment metadata record was created but the file could not be uploaded. You may want to delete it with delete_items or retry after freeing storage.",
+                        note: "An attachment record (item_key) was created without the file. Tell the user: they can delete it in Zotero (or with delete_items, if deletion is enabled) and retry after freeing storage.",
                     });
                 case "auth_failed":
                     return formatErrorResponse("Upload authorization failed", {
                         status: result.error.status,
+                        details: result.error.networkDetail, // e.g. the timeout or connection error
+                        ...uploadFailureHint(result.error.status, result.itemKey),
                     });
                 case "upload_failed":
                     return formatErrorResponse("File upload failed", {
                         status: result.error.status,
+                        details: result.error.networkDetail, // e.g. the timeout or connection error
+                        ...uploadFailureHint(result.error.status, result.itemKey),
                     });
                 case "not_pdf":
                     return formatErrorResponse("Downloaded file is not a valid PDF", {
                         url,
                         details: result.error.message,
-                        suggestion: "The URL may redirect to an HTML page or require browser access. Try a direct PDF link.",
+                        suggestion: "Nothing was created. The URL may redirect to an HTML page or require browser access: use the direct PDF link (on arXiv /pdf/ instead of /abs/), or for an item with a DOI try find_and_attach_pdfs.",
                     });
                 case "registration_failed":
                     return formatErrorResponse("Upload registration failed", {
                         status: result.error.status,
+                        details: result.error.networkDetail, // e.g. the timeout or connection error
+                        ...uploadFailureHint(result.error.status, result.itemKey),
                     });
                 case "item_creation_failed":
                     return formatErrorResponse("import_pdf_to_zotero failed", {
                         details: result.error.message,
+                        ...(result.error.status !== undefined ? { status: result.error.status } : {}),
+                        hint: result.error.status !== undefined && result.error.status !== 400
+                            ? `Nothing was created. ${zoteroStatusHint(result.error.status).hint}`
+                            : parent_item
+                                ? `Zotero refused to create the attachment (details). parent_item must be an existing regular item, not an attachment or note: ${ITEM_KEY_HINT}`
+                                : `Zotero refused to create the attachment (details). Check the collections keys: ${COLLECTION_KEY_HINT}`,
                     });
             }
         }
@@ -115,6 +151,7 @@ export async function handleImportPdfToZotero(zoteroApi, userId, args) {
     }
     catch (err) {
         logToolError("import_pdf_to_zotero", err);
-        return formatErrorResponse("import_pdf_to_zotero failed", { details: errorMessage(err) });
+        const { error, ...described } = describeAnyError(err);
+        return formatErrorResponse(`import_pdf_to_zotero failed: ${error}`, { ...described, details: errorMessage(err) });
     }
 }

package/build/tools/index.js

@@ -13,7 +13,8 @@ import { handleImportPdfToZotero, toolConfig as importPdfToZoteroConfig } from "
 import { handleFindAndAttachPdfs, toolConfig as findAndAttachPdfsConfig } from "./find-and-attach-pdfs.js";
 import { handleDeleteCollection, toolConfig as deleteCollectionConfig } from "./delete-collection.js";
 import { handleDeleteItems, toolConfig as deleteItemsConfig } from "./delete-items.js";
-import { logToolError } from "../utils/error-formatter.js";
+import { formatErrorResponse, logToolError } from "../utils/error-formatter.js";
+import { describeError } from "../utils/error-hints.js";
 const tools = [
     { config: collectionsConfig, handler: handleGetCollections },
     { config: collectionItemsConfig, handler: handleGetCollectionItems },
@@ -32,14 +33,21 @@ const tools = [
     { config: deleteItemsConfig, handler: handleDeleteItems },
 ];
 const handlers = new Map(tools.map(({ config, handler }) => [config.name, handler]));
-/** Run a tool handler; Zotero API errors it throws are logged here once for every tool. */
+/**
+ * Run a tool handler; Zotero API errors it throws are logged here once for every tool. API, timeout and
+ * network errors become a structured error with a hint on what to do next; anything else (a bug) is rethrown.
+ */
 async function runTool(name, handler, zoteroApi, userId, args, unsafeOps) {
     try {
         return await handler(zoteroApi, userId, args, unsafeOps);
     }
     catch (err) {
         logToolError(name, err);
-        throw err;
+        const described = describeError(err);
+        if (!described)
+            throw err;
+        const { error, ...details } = described;
+        return formatErrorResponse(error, details);
     }
 }
 export async function handleToolCall(name, args, zoteroApi, userId, unsafeOps = "none") {

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 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/attachments.js

@@ -2,8 +2,19 @@ import { asArray } from "./pagination.js";
 export function isPdfAttachment(item) {
     return item.itemType === "attachment" && item.contentType === "application/pdf";
 }
+/**
+ * A link to a PDF on the web (linkMode "linked_url"): Zotero stores no file for it, so it has no
+ * full text on the server and cannot be opened or indexed in Zotero desktop.
+ */
+export function isLinkedUrl(item) {
+    return item.linkMode === "linked_url";
+}
+/** All PDF attachments (stored files and links) among the children of an item. */
+export async function findPdfAttachments(zoteroApi, library, itemKey) {
+    const response = await zoteroApi.library(library.type, library.id).items(itemKey).children().get();
+    return asArray(response.getData()).filter(isPdfAttachment);
+}
 /** First PDF attachment among the children of an item, if any. */
 export async function findPdfAttachment(zoteroApi, library, itemKey) {
-    const response = await zoteroApi.library(library.type, library.id).items(itemKey).children().get();
-    return asArray(response.getData()).find(isPdfAttachment);
+    return (await findPdfAttachments(zoteroApi, library, itemKey))[0];
 }

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

@@ -1,17 +1,34 @@
 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: {
             Accept: "application/vnd.citationstyles.csl+json",
         },
         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 {
+        // 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
+        if (err instanceof InvalidJsonResponseError)
+            throw new Error(`DOI not found or not resolvable: ${doi} (${err.message})`);
+        throw err;
     }
-    return (await response.json());
 }
 export async function resolveDois(dois, concurrency) {
     const settled = await mapWithConcurrency(dois, (doi) => resolveDoi(doi), concurrency);

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/fetch-retry.js

@@ -1,3 +1,4 @@
+import { fetchWithTimeout, TIMEOUTS } from "./timeouts.js";
 const DEFAULT_MAX_RETRIES = 3;
 const DEFAULT_BASE_DELAY_MS = 1000;
 const DEFAULT_RETRYABLE_STATUSES = [429, 503];
@@ -21,7 +22,7 @@ export async function fetchWithRetry(url, init, options) {
     const retryableStatuses = options?.retryableStatuses ?? DEFAULT_RETRYABLE_STATUSES;
     let lastResponse;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        const response = await fetch(url, init);
+        const response = await fetchWithTimeout(url, init ?? {}, options?.timeoutMs ?? TIMEOUTS.metadataMs, options?.label ?? "Request");
         lastResponse = response;
         if (!retryableStatuses.includes(response.status) || attempt === maxRetries) {
             return response;