@xevos117/mcp-zotero 1.0.8 → 1.0.9

package/build/server.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import "dotenv/config";
+import dotenv from "dotenv";
+dotenv.config({ quiet: true });
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createRequire } from "module";

package/build/tools/add-items-by-doi.js

@@ -6,7 +6,7 @@ import { cslToZoteroItem } from "../utils/csl-to-zotero.js";
 import { logger } from "../utils/logger.js";
 import { lookupOaPdf } from "../utils/unpaywall.js";
 import { downloadAndUploadPdf } from "../utils/pdf-uploader.js";
-import { mapWithConcurrency } from "../utils/concurrency.js";
+import { mapWithConcurrency, createCancellationToken } from "../utils/concurrency.js";
 export const toolConfig = {
     name: "add_items_by_doi",
     description: `Add items to your Zotero library by resolving DOIs. Works with ANY item type that has a DOI — journal articles, books, datasets, preprints, conference papers, reports, etc. For each DOI, resolves metadata via content negotiation and creates the item in Zotero with the correct type automatically. Returns a list of successfully added items (with item_key and title) and any failures.
@@ -54,6 +54,7 @@ async function attachPdfsToItems(items, zoteroApi, userId, apiKey) {
             }];
     }
     // Email is valid — process all items in parallel (reuse probe for first)
+    const cancelToken = createCancellationToken();
     const settled = await mapWithConcurrency(itemsWithDoi, async (item, i) => {
         const oaResult = i === 0 ? probe : await lookupOaPdf(item.doi);
         if (oaResult.found && oaResult.pdf_url) {
@@ -61,6 +62,9 @@ async function attachPdfsToItems(items, zoteroApi, userId, apiKey) {
                 url: oaResult.pdf_url,
                 parentItem: item.item_key,
             });
+            if (!uploadResult.success && uploadResult.error.code === "storage_quota_exceeded") {
+                cancelToken.cancelled = true;
+            }
             return {
                 item_key: item.item_key,
                 doi: item.doi,
@@ -80,7 +84,7 @@ async function attachPdfsToItems(items, zoteroApi, userId, apiKey) {
                 ? "Open access copy exists at a repository but no direct PDF link is available. The user can download it manually from the landing page and use import_pdf_to_zotero to attach it."
                 : "No open access PDF found",
         };
-    });
+    }, undefined, cancelToken);
     return settled
         .filter((r) => r.status === "fulfilled")
         .map((r) => r.value);
@@ -131,12 +135,20 @@ export async function handleAddItemsByDoi(zoteroApi, userId, args) {
             });
         }
         let pdf_results;
+        let pdf_attach_error;
         if (auto_attach_pdf) {
             const apiKey = process.env.ZOTERO_API_KEY;
             if (apiKey) {
-                pdf_results = await attachPdfsToItems(success, zoteroApi, userId, apiKey);
+                try {
+                    pdf_results = await attachPdfsToItems(success, zoteroApi, userId, apiKey);
+                }
+                catch (err) {
+                    pdf_attach_error = `PDF attachment failed: ${err instanceof Error ? err.message : String(err)}. Items were created successfully.`;
+                    logger.error("PDF attach phase failed", { error: pdf_attach_error });
+                }
             }
         }
+        const quotaHit = pdf_results?.some((r) => r.error?.includes("storage quota"));
         return {
             content: [
                 {
@@ -145,6 +157,12 @@ export async function handleAddItemsByDoi(zoteroApi, userId, args) {
                         success,
                         failed: resolved.failed,
                         ...(pdf_results !== undefined ? { pdf_results } : {}),
+                        ...(pdf_attach_error !== undefined ? { pdf_attach_error } : {}),
+                        ...(quotaHit
+                            ? {
+                                storage_quota_warning: "Zotero storage quota is full. Some PDF attachments were skipped. All items were created successfully (metadata only). Free up space at https://www.zotero.org/settings/storage or upgrade your plan.",
+                            }
+                            : {}),
                     }, null, 2),
                 },
             ],

package/build/tools/add-items.js

@@ -28,7 +28,7 @@ const ItemSchema = z
             continue;
         if (!validFields.has(key)) {
             ctx.addIssue({
-                code: z.ZodIssueCode.custom,
+                code: "custom",
                 message: `Field "${key}" is not valid for itemType "${data.itemType}". Valid fields: ${[...validFields].join(", ")}`,
                 path: [key],
             });
@@ -38,7 +38,7 @@ const ItemSchema = z
     for (const [i, creator] of (data.creators ?? []).entries()) {
         if (!validCreatorTypes.has(creator.creatorType)) {
             ctx.addIssue({
-                code: z.ZodIssueCode.custom,
+                code: "custom",
                 message: `Invalid creatorType "${creator.creatorType}" for "${data.itemType}". Valid: ${[...validCreatorTypes].join(", ")}`,
                 path: ["creators", i, "creatorType"],
             });

package/build/tools/find-and-attach-pdfs.js

@@ -4,7 +4,7 @@ import { formatErrorResponse } from "../utils/error-formatter.js";
 import { logger } from "../utils/logger.js";
 import { lookupOaPdfWithFallbacks } from "../utils/unpaywall.js";
 import { downloadAndUploadPdf } from "../utils/pdf-uploader.js";
-import { mapWithConcurrency } from "../utils/concurrency.js";
+import { mapWithConcurrency, createCancellationToken } from "../utils/concurrency.js";
 import { fetchAllPages } from "../utils/pagination.js";
 export const toolConfig = {
     name: "find_and_attach_pdfs",
@@ -72,6 +72,7 @@ export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
             }
         }
         // 3. Process each item in parallel
+        const cancelToken = createCancellationToken();
         const settled = await mapWithConcurrency(keys, async (key) => {
             const item = itemMap.get(key);
             if (!item) {
@@ -145,6 +146,15 @@ export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
                         pdf_url: pdfUrl,
                     };
                 }
+                if (!uploadResult.success && uploadResult.error.code === "storage_quota_exceeded") {
+                    cancelToken.cancelled = true;
+                    return {
+                        item_key: key,
+                        doi,
+                        status: "quota_exceeded",
+                        reason: uploadResult.error.message,
+                    };
+                }
             }
             return {
                 item_key: key,
@@ -153,7 +163,7 @@ export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
                 reason: `Download failed for all ${urlsToTry.length} URL(s)`,
                 source: primary.source ?? undefined,
             };
-        });
+        }, undefined, cancelToken);
         const results = settled
             .filter((r) => r.status === "fulfilled")
             .map((r) => r.value);
@@ -161,6 +171,7 @@ export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
         let notFound = 0;
         let skipped = 0;
         let errors = 0;
+        let quotaExceeded = 0;
         for (const r of results) {
             if (r.status === "attached")
                 attached++;
@@ -170,6 +181,8 @@ export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
                 skipped++;
             else if (r.status === "error")
                 errors++;
+            else if (r.status === "quota_exceeded")
+                quotaExceeded++;
         }
         return {
             content: [
@@ -181,7 +194,13 @@ export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
                         not_found: notFound,
                         skipped,
                         errors,
+                        quota_exceeded: quotaExceeded,
                         dry_run,
+                        ...(quotaExceeded > 0
+                            ? {
+                                storage_quota_warning: "Zotero storage quota is full. Remaining PDF uploads were skipped. Free up space at https://www.zotero.org/settings/storage or upgrade your plan.",
+                            }
+                            : {}),
                         results,
                     }, null, 2),
                 },

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

@@ -69,6 +69,13 @@ export async function handleImportPdfToZotero(zoteroApi, userId, args) {
                     return formatErrorResponse("File exceeds 100 MB limit", {
                         size_bytes: result.error.sizeBytes,
                     });
+                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.",
+                    });
                 case "auth_failed":
                     return formatErrorResponse("Upload authorization failed", {
                         status: result.error.status,

package/build/utils/concurrency.js

@@ -1,13 +1,23 @@
 export const DEFAULT_CONCURRENCY = 5;
+export function createCancellationToken() {
+    return { cancelled: false };
+}
 /**
  * Runs `fn` over `items` with at most `concurrency` invocations in flight.
  * Returns results in input order as `PromiseSettledResult<R>[]`.
+ *
+ * When `cancel` is provided and `cancel.cancelled` is set to `true`,
+ * workers stop picking up new items. Items that were never started
+ * have `undefined` slots in the returned array — callers that filter
+ * with `.filter(r => r?.status === "fulfilled")` handle this safely.
  */
-export async function mapWithConcurrency(items, fn, concurrency = DEFAULT_CONCURRENCY) {
+export async function mapWithConcurrency(items, fn, concurrency = DEFAULT_CONCURRENCY, cancel) {
     const results = new Array(items.length);
     let nextIndex = 0;
     async function worker() {
         while (nextIndex < items.length) {
+            if (cancel?.cancelled)
+                break;
             const i = nextIndex++;
             try {
                 const value = await fn(items[i], i);

package/build/utils/pdf-uploader.js

@@ -110,10 +110,24 @@ export async function downloadAndUploadPdf(zoteroApi, userId, apiKey, options) {
     else {
         itemData.collections = options.collections ?? [];
     }
-    const createResponse = await zoteroApi
-        .library("user", userId)
-        .items()
-        .post([itemData]);
+    let createResponse;
+    try {
+        createResponse = await zoteroApi
+            .library("user", userId)
+            .items()
+            .post([itemData]);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+            success: false,
+            error: {
+                code: "item_creation_failed",
+                message: `Failed to create attachment item: ${detail}`,
+                networkDetail: detail,
+            },
+        };
+    }
     if (!createResponse.isSuccess()) {
         const errors = createResponse.getErrors();
         const errorMsg = Object.values(errors).join("; ") || "Unknown error";
@@ -135,16 +149,42 @@ export async function downloadAndUploadPdf(zoteroApi, userId, apiKey, options) {
         filesize: String(buffer.length),
         mtime: String(Date.now()),
     });
-    const authResponse = await fetch(authUrl, {
-        method: "POST",
-        headers: {
-            "Zotero-API-Key": apiKey,
-            "Content-Type": "application/x-www-form-urlencoded",
-            "If-None-Match": "*",
-        },
-        body: authBody.toString(),
-    });
+    let authResponse;
+    try {
+        authResponse = await fetch(authUrl, {
+            method: "POST",
+            headers: {
+                "Zotero-API-Key": apiKey,
+                "Content-Type": "application/x-www-form-urlencoded",
+                "If-None-Match": "*",
+            },
+            body: authBody.toString(),
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+            success: false,
+            itemKey,
+            error: {
+                code: "auth_failed",
+                message: `Upload authorization failed: ${detail}`,
+                networkDetail: detail,
+            },
+        };
+    }
     if (!authResponse.ok) {
+        if (authResponse.status === 413) {
+            return {
+                success: false,
+                itemKey,
+                error: {
+                    code: "storage_quota_exceeded",
+                    message: "Zotero storage quota exceeded. The file cannot be uploaded because your Zotero cloud storage is full. Free up space by deleting stored files in Zotero, or upgrade your storage plan at https://www.zotero.org/settings/storage.",
+                    status: 413,
+                },
+            };
+        }
         return {
             success: false,
             itemKey,
@@ -162,11 +202,26 @@ export async function downloadAndUploadPdf(zoteroApi, userId, apiKey, options) {
         const prefix = Buffer.from(auth.prefix, "utf-8");
         const suffix = Buffer.from(auth.suffix, "utf-8");
         const uploadBody = Buffer.concat([prefix, buffer, suffix]);
-        const uploadResponse = await fetch(auth.url, {
-            method: "POST",
-            headers: { "Content-Type": auth.contentType },
-            body: uploadBody,
-        });
+        let uploadResponse;
+        try {
+            uploadResponse = await fetch(auth.url, {
+                method: "POST",
+                headers: { "Content-Type": auth.contentType },
+                body: uploadBody,
+            });
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            return {
+                success: false,
+                itemKey,
+                error: {
+                    code: "upload_failed",
+                    message: `File upload failed: ${detail}`,
+                    networkDetail: detail,
+                },
+            };
+        }
         if (!uploadResponse.ok) {
             return {
                 success: false,
@@ -178,15 +233,30 @@ export async function downloadAndUploadPdf(zoteroApi, userId, apiKey, options) {
                 },
             };
         }
-        const registerResponse = await fetch(authUrl, {
-            method: "POST",
-            headers: {
-                "Zotero-API-Key": apiKey,
-                "Content-Type": "application/x-www-form-urlencoded",
-                "If-None-Match": "*",
-            },
-            body: `upload=${auth.uploadKey}`,
-        });
+        let registerResponse;
+        try {
+            registerResponse = await fetch(authUrl, {
+                method: "POST",
+                headers: {
+                    "Zotero-API-Key": apiKey,
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "If-None-Match": "*",
+                },
+                body: `upload=${auth.uploadKey}`,
+            });
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            return {
+                success: false,
+                itemKey,
+                error: {
+                    code: "registration_failed",
+                    message: `Upload registration failed: ${detail}`,
+                    networkDetail: detail,
+                },
+            };
+        }
         if (!registerResponse.ok) {
             return {
                 success: false,

package/build/utils/zotero-fulltext.js

@@ -15,6 +15,12 @@ export async function putFulltext(userId, itemKey, apiKey, content, totalPages)
     if (response.status === 204) {
         return { success: true };
     }
+    if (response.status === 413) {
+        return {
+            success: false,
+            error: "Fulltext content too large for Zotero API (status 413). The PDF text may exceed the fulltext size limit.",
+        };
+    }
     return {
         success: false,
         error: `Fulltext PUT failed with status ${response.status}`,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xevos117/mcp-zotero",
   "type": "module",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Unofficial MCP server for Zotero integration with citation management",
   "repository": {
     "type": "git",
@@ -42,17 +42,17 @@
   "author": "Xevos17",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4",
-    "dotenv": "^16.4.7",
-    "fast-xml-parser": "^5.3.5",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "dotenv": "^17.3.1",
+    "fast-xml-parser": "^5.5.8",
     "jszip": "^3.10.1",
     "unpdf": "^1.4.0",
-    "zod": "^3.24.1",
-    "zotero-api-client": "^0.46.0"
+    "zod": "^4.3.6",
+    "zotero-api-client": "^0.48.0"
   },
   "devDependencies": {
-    "@types/node": "latest",
+    "@types/node": "^25.5.0",
     "typescript": "latest",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   }
 }