@xevos117/mcp-zotero 2.0.3 → 2.0.4

package/build/tools/delete-collection.js

@@ -4,7 +4,7 @@ import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { canDeleteCollections } from "../utils/unsafe-operations.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
-import { COLLECTION_KEY_HINT, unsafeOperationsHint } from "../utils/error-hints.js";
+import { COLLECTION_KEY_HINT, unsafeOperationsHint, zoteroStatusHint } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "delete_collection",
     description: "Delete a collection (folder) from your Zotero library; confirm with the user first. Items inside the collection are NOT deleted — they remain in your library. Disabled unless the server setting UNSAFE_OPERATIONS is 'all'.",
@@ -27,28 +27,38 @@ export async function handleDeleteCollection(zoteroApi, userId, args, unsafeOps
         });
     }
     try {
-        const response = await zoteroApi
-            .library(libraryType, libraryId)
-            .collections(collection_key)
-            .get();
-        const collection = response.getData();
-        const version = response.getVersion();
-        if (version === null) {
-            return formatErrorResponse("Could not determine collection version", {
+        for (let attempt = 1;; attempt++) {
+            const response = await zoteroApi
+                .library(libraryType, libraryId)
+                .collections(collection_key)
+                .get();
+            const collection = response.getData();
+            const version = response.getVersion();
+            if (version === null) {
+                return formatErrorResponse("Could not determine collection version", {
+                    collection_key,
+                    hint: "Nothing was deleted. Retry the same call once.",
+                });
+            }
+            try {
+                await zoteroApi
+                    .library(libraryType, libraryId)
+                    .collections(collection_key)
+                    .version(version)
+                    .delete();
+            }
+            catch (err) {
+                // 412: the collection changed between the GET and the DELETE; read it again and retry once
+                if (attempt === 1 && isZoteroApiError(err) && err.response.status === 412)
+                    continue;
+                throw err;
+            }
+            return formatJsonResult({
+                deleted: true,
                 collection_key,
-                hint: "Nothing was deleted. Retry the same call once.",
+                name: collection.name || collection_key,
             });
         }
-        await zoteroApi
-            .library(libraryType, libraryId)
-            .collections(collection_key)
-            .version(version)
-            .delete();
-        return formatJsonResult({
-            deleted: true,
-            collection_key,
-            name: collection.name || collection_key,
-        });
     }
     catch (err) {
         if (isZoteroApiError(err)) {
@@ -60,9 +70,12 @@ export async function handleDeleteCollection(zoteroApi, userId, args, unsafeOps
                 });
             }
             if (err.response.status === 412) {
-                return formatErrorResponse("Collection was modified by another client, so it was not deleted. Retry the same call.", {
+                const { hint } = zoteroStatusHint(412);
+                return formatErrorResponse("Collection was modified by another client (HTTP 412 Precondition Failed), also on a second try with its new version, so it was not deleted.", {
                     collection_key,
                     status: "version_conflict",
+                    http_status: 412,
+                    hint,
                 });
             }
         }

package/build/tools/delete-items.js

@@ -5,7 +5,7 @@ import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.
 import { canDeleteItems } from "../utils/unsafe-operations.js";
 import { fetchItemsByKeys } from "../utils/pagination.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
-import { ITEM_KEY_HINT, unsafeOperationsHint } from "../utils/error-hints.js";
+import { ITEM_KEY_HINT, unsafeOperationsHint, zoteroStatusHint } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "delete_items",
     description: "Delete one or more items from your Zotero library: they are permanently deleted (not moved to the Zotero trash), so confirm with the user first. Accepts up to 50 item keys per call. Disabled unless the server setting UNSAFE_OPERATIONS is 'items' or 'all'.",
@@ -31,48 +31,64 @@ export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "no
         });
     }
     try {
-        const { items, version: libraryVersion } = await fetchItemsByKeys((params) => zoteroApi.library(libraryType, libraryId).items().get(params), item_keys);
-        const foundKeys = new Set(items.map((item) => item.key).filter(Boolean));
-        const notFoundKeys = item_keys.filter((k) => !foundKeys.has(k));
-        if (foundKeys.size === 0) {
-            return formatErrorResponse("No items found for the given keys", {
-                item_keys,
-                status: "not_found",
-                hint: `Nothing was deleted: none of these keys exists in this library (already deleted, or in another library). ${ITEM_KEY_HINT}`,
-            });
-        }
-        // Use library version from response header (Last-Modified-Version),
-        // not individual item versions — required for multi-object DELETE
-        if (libraryVersion === null) {
-            return formatErrorResponse("Could not determine library version", {
-                item_keys,
-                hint: "Nothing was deleted. Retry the same call once.",
-            });
-        }
-        // only keys the caller asked for, whatever the API returned
-        const keysToDelete = item_keys.filter((k) => foundKeys.has(k));
-        await zoteroApi
-            .library(libraryType, libraryId)
-            .items()
-            .version(libraryVersion)
-            .delete(keysToDelete);
-        const result = {
-            deleted_keys: keysToDelete,
-            deleted_count: keysToDelete.length,
-        };
-        if (notFoundKeys.length > 0) {
-            result.not_found = notFoundKeys;
-        }
-        return formatJsonResult(result);
-    }
-    catch (err) {
-        if (isZoteroApiError(err)) {
-            if (err.response.status === 412) {
-                return formatErrorResponse("Items were modified by another client, so nothing was deleted. Retry the same call.", {
+        const notFoundKeys = [];
+        let pending = item_keys;
+        for (let attempt = 1;; attempt++) {
+            const { items, version: libraryVersion } = await fetchItemsByKeys((params) => zoteroApi.library(libraryType, libraryId).items().get(params), pending);
+            const foundKeys = new Set(items.map((item) => item.key).filter(Boolean));
+            notFoundKeys.push(...pending.filter((k) => !foundKeys.has(k)));
+            if (foundKeys.size === 0) {
+                return formatErrorResponse("No items found for the given keys", {
+                    item_keys,
+                    status: "not_found",
+                    hint: `Nothing was deleted: none of these keys exists in this library (already deleted, or in another library). ${ITEM_KEY_HINT}`,
+                });
+            }
+            // Use library version from response header (Last-Modified-Version),
+            // not individual item versions — required for multi-object DELETE
+            if (libraryVersion === null) {
+                return formatErrorResponse("Could not determine library version", {
                     item_keys,
-                    status: "version_conflict",
+                    hint: "Nothing was deleted. Retry the same call once.",
                 });
             }
+            // only keys the caller asked for, whatever the API returned
+            const keysToDelete = pending.filter((k) => foundKeys.has(k));
+            try {
+                await zoteroApi
+                    .library(libraryType, libraryId)
+                    .items()
+                    .version(libraryVersion)
+                    .delete(keysToDelete);
+            }
+            catch (err) {
+                // 412: the library changed between the GET and the DELETE (another client, a sync). Read the new
+                // version and the keys that still exist, and retry once with those.
+                if (attempt === 1 && isZoteroApiError(err) && err.response.status === 412) {
+                    pending = keysToDelete;
+                    continue;
+                }
+                throw err;
+            }
+            const result = {
+                deleted_keys: keysToDelete,
+                deleted_count: keysToDelete.length,
+            };
+            if (notFoundKeys.length > 0) {
+                result.not_found = notFoundKeys;
+            }
+            return formatJsonResult(result);
+        }
+    }
+    catch (err) {
+        if (isZoteroApiError(err) && err.response.status === 412) {
+            const { hint } = zoteroStatusHint(412);
+            return formatErrorResponse("Items were modified by another client (HTTP 412 Precondition Failed), also on a second try with the new library version, so nothing was deleted.", {
+                item_keys,
+                status: "version_conflict",
+                http_status: 412,
+                hint,
+            });
         }
         throw err;
     }

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

@@ -123,8 +123,33 @@ const CSL_NAME_CREATOR_TYPES = [
     ["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 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];
@@ -138,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) {
@@ -193,6 +232,16 @@ function containerTitle(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 names = {};
     for (const [variable, creatorType] of CSL_NAME_CREATOR_TYPES) {
@@ -200,28 +249,34 @@ export function zoteroItemToCsl(item) {
         if (list.length > 0)
             names[variable] = list;
     }
-    let issued;
-    if (item.date) {
-        const parts = item.date.split("-").map(Number).filter((n) => !isNaN(n));
-        if (parts.length > 0) {
-            issued = { "date-parts": [parts] };
-        }
-    }
     // 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),
         ...names,
-        issued,
+        issued: cslDate(item.date),
         DOI: text(item.DOI),
         "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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xevos117/mcp-zotero",
   "type": "module",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "mcpName": "io.github.Xevos117/mcp-zotero",
   "description": "Unofficial MCP server for Zotero integration with citation management",
   "repository": {