@xevos117/mcp-zotero 2.0.2 → 2.0.4

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
@@ -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,48 +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}`,
                     });
             }
         }
@@ -118,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 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,50 @@ 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"],
+];
+/** Zotero field holding the CSL publisher, for the types that call it otherwise (Zotero's base field mappings). */
+const PUBLISHER_FIELD = {
+    thesis: "university",
+    report: "institution",
+    preprint: "repository",
+};
+/** Zotero field holding the CSL number (report number, standard or manuscript number). */
+const NUMBER_FIELD = {
+    report: "reportNumber",
+    standard: "number",
+    manuscript: "number",
+};
+/** arXiv DOIs (DataCite): the item is a preprint in the arXiv repository. */
+const ARXIV_DOI = /^10\.48550\/arxiv\.(.+)$/i;
+/** JATS abstract (Crossref: <jats:p>, <jats:italic>, …) → plain text, one line per paragraph, as Zotero's import does. */
+function plainAbstract(abstract) {
+    if (!/<jats:/.test(abstract))
+        return abstract;
+    return abstract
+        .split(/<\/jats:p>/)
+        .map((p) => p.replace(/<\/?jats:[^>]*>/g, " ").replace(/\s+/g, " ").trim())
+        .filter(Boolean)
+        .join("\n");
+}
 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",
-    }));
+    const arxiv = ARXIV_DOI.exec(csl.DOI ?? "");
+    const itemType = (arxiv ? "preprint" : (CSL_TO_ZOTERO_TYPE[csl.type] ?? "journalArticle"));
+    // 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 = [];
@@ -126,25 +163,39 @@ export function cslToZoteroItem(csl, options) {
         collections.push(options.collectionKey);
     }
     const tags = (options?.tags ?? []).map((t) => ({ tag: t }));
+    // Zotero joins the subtitle to the title; the article number is the item's number, or its pages when it has none
+    const subtitle = Array.isArray(csl.subtitle) ? csl.subtitle[0] : csl.subtitle;
+    const title = subtitle ? `${csl.title ?? ""}: ${subtitle}` : (csl.title ?? "");
+    const number = csl.number ?? csl["article-number"] ?? "";
+    const numberField = NUMBER_FIELD[itemType];
     // Build candidate fields (CSL → Zotero field names)
     const candidates = {
-        title: csl.title ?? "",
+        title,
         date,
         DOI: csl.DOI ?? "",
         volume: csl.volume ?? "",
         issue: csl.issue ?? "",
-        pages: csl.page ?? "",
+        pages: csl.page ?? (numberField ? "" : (csl["article-number"] ?? "")),
         publisher: csl.publisher ?? "",
         place: csl["publisher-place"] ?? "",
         url: csl.URL ?? "",
-        abstractNote: csl.abstract ?? "",
+        abstractNote: csl.abstract ? plainAbstract(csl.abstract) : "",
         ISBN: Array.isArray(csl.ISBN) ? csl.ISBN[0] : csl.ISBN ?? "",
         ISSN: Array.isArray(csl.ISSN) ? csl.ISSN[0] : csl.ISSN ?? "",
         edition: csl.edition ?? "",
         numPages: csl["number-of-pages"] ?? "",
         series: csl["collection-title"] ?? "",
         language: csl.language ?? "",
+        journalAbbreviation: csl["container-title-short"] ?? "",
+        conferenceName: csl["event-title"] ?? csl.event ?? "",
     };
+    if (numberField)
+        candidates[numberField] = number;
+    const publisherField = PUBLISHER_FIELD[itemType];
+    if (publisherField)
+        candidates[publisherField] = arxiv ? "arXiv" : (csl.publisher ?? "");
+    if (arxiv)
+        candidates.archiveID = `arXiv:${arxiv[1]}`;
     // Map container-title to the correct field for this item type
     const containerTitleField = CONTAINER_TITLE_FIELD[itemType];
     if (containerTitleField) {
@@ -168,35 +219,64 @@ 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;
+}
+/**
+ * CSL date of a Zotero date: "YYYY-MM-DD" (or a prefix of it) as date-parts; a date that does not start that way
+ * ("October 2023", "Spring 2023") as `raw`, which citeproc parses itself, instead of being dropped.
+ */
+export function cslDate(value) {
+    if (!value)
+        return undefined;
+    const parts = value.split("-").map(Number).filter((n) => !isNaN(n));
+    return parts.length > 0 ? { "date-parts": [parts] } : { raw: value };
+}
 export function zoteroItemToCsl(item) {
-    const authors = (item.creators ?? [])
-        .filter((c) => c.creatorType === "author")
-        .map((c) => ({
-        family: c.lastName ?? c.name ?? "",
-        given: c.firstName ?? "",
-    }));
-    let issued;
-    if (item.date) {
-        const parts = item.date.split("-").map(Number).filter((n) => !isNaN(n));
-        if (parts.length > 0) {
-            issued = { "date-parts": [parts] };
-        }
+    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;
     }
     // The Zotero API returns every field of the item type, empty ones as "": keep them out of the field code
-    const text = (v) => (v ? v : undefined);
+    const fields = item;
+    const text = (...values) => values.find((v) => typeof v === "string" && v !== "") ?? undefined;
+    // accessDate is "YYYY-MM-DD hh:mm:ss" or ISO: only the day
+    const accessDate = text(fields.accessDate)?.replace(/[T ].*$/, "");
     return {
         type: ZOTERO_TO_CSL_TYPE[item.itemType ?? ""] ?? "article-journal",
         title: text(item.title),
-        author: authors.length > 0 ? authors : undefined,
-        issued,
+        ...names,
+        issued: cslDate(item.date),
         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),
-        publisher: text(item.publisher),
+        // Zotero's base fields: university (thesis), institution (report), repository (preprint) are the publisher;
+        // reportNumber and archiveID the number; thesisType and reportType the genre
+        publisher: text(item.publisher, fields.university, fields.institution, fields.repository),
         "publisher-place": text(item.place),
+        number: text(fields.reportNumber, fields.archiveID),
+        genre: text(fields.thesisType, fields.reportType),
         URL: text(item.url),
+        accessed: cslDate(accessDate),
+        ISBN: text(fields.ISBN),
+        ISSN: text(fields.ISSN),
+        edition: text(fields.edition),
+        language: text(fields.language),
+        "number-of-pages": text(fields.numPages),
         // abstract deliberately omitted: it bloats every field code (same choice as the skill's inject.js)
     };
 }

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