@xevos117/mcp-zotero 2.0.1 → 2.0.3

package/build/utils/html-entities.js

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

package/build/utils/item-formatter.js

@@ -1,6 +1,7 @@
 export function formatCreators(creators) {
     return (creators
-        ?.map((c) => `${c.firstName || ""} ${c.lastName || ""}`.trim())
+        // single-field names (institutions, consortia) are stored in `name`
+        ?.map((c) => (c.name?.trim() || `${c.firstName || ""} ${c.lastName || ""}`.trim()))
         .filter(Boolean)
         .join(", ") || "No authors listed");
 }

package/build/utils/json-response.js

@@ -0,0 +1,29 @@
+/**
+ * A response body that is not the JSON object the API documents: an HTML error or landing page (doi.org answers
+ * an unresolvable DOI with HTML), an empty body, or a bare value. The message names the status and content type,
+ * never the raw JSON.parse error.
+ */
+export class InvalidJsonResponseError extends Error {
+    status;
+    constructor(response) {
+        const type = response.headers?.get?.("content-type")?.split(";")[0].trim();
+        super(`response is not a JSON object (HTTP ${response.status}${type ? `, ${type}` : ""})`);
+        this.name = "InvalidJsonResponseError";
+        this.status = response.status;
+    }
+}
+/** Body of `response` as a JSON object; InvalidJsonResponseError otherwise. Timeouts while reading propagate. */
+export async function readJsonObject(response) {
+    let data;
+    try {
+        data = await response.json();
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            throw new InvalidJsonResponseError(response);
+        throw err;
+    }
+    if (data === null || typeof data !== "object" || Array.isArray(data))
+        throw new InvalidJsonResponseError(response);
+    return data;
+}

package/build/utils/library-context.js

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

package/build/utils/pdf-uploader.js

@@ -1,9 +1,12 @@
+import { InvalidJsonResponseError, readJsonObject } from "./json-response.js";
 import { createHash } from "node:crypto";
+import { isZoteroApiError } from "../types/zotero-types.js";
 import { logger } from "./logger.js";
 import { extractPdfText } from "./pdf-text-extractor.js";
 import { putFulltext } from "./zotero-fulltext.js";
 import { formatWriteErrors } from "./write-results.js";
 import { errorMessage } from "./error-formatter.js";
+import { fetchWithTimeout, isTimeoutAbort, timeoutError, RequestTimeoutError, TIMEOUTS } from "./timeouts.js";
 const MAX_FILE_SIZE = 100 * 1024 * 1024; // 100 MB
 function safeBasename(name) {
     return (name.split(/[\\/]/).pop() ?? "").replace(/[\x00-\x1f"]/g, "").trim();
@@ -53,11 +56,7 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
     // 1. Download the file
     let downloadResponse;
     try {
-        downloadResponse = await fetch(options.url, {
-            headers: {
-                "User-Agent": "mcp-zotero/1.0 (Open Access PDF retrieval)",
-            },
-        });
+        downloadResponse = await fetchWithTimeout(options.url, { headers: { "User-Agent": "mcp-zotero/1.0 (Open Access PDF retrieval)" } }, TIMEOUTS.pdfTransferMs, "PDF download");
     }
     catch (err) {
         const detail = errorMessage(err);
@@ -87,8 +86,18 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
             contentType: responseContentType,
         });
     }
-    const arrayBuffer = await downloadResponse.arrayBuffer();
-    const buffer = Buffer.from(arrayBuffer);
+    let buffer;
+    try {
+        buffer = Buffer.from(await downloadResponse.arrayBuffer());
+    }
+    catch (err) {
+        // the download bound also covers the body: a server that stalls mid-file ends here
+        const detail = isTimeoutAbort(err) ? timeoutError("PDF download", options.url, TIMEOUTS.pdfTransferMs).message : errorMessage(err);
+        return {
+            success: false,
+            error: { code: "network_error", message: `Network error downloading file: ${detail}.`, networkDetail: detail },
+        };
+    }
     const filename = options.filename ??
         resolvePdfFilename(options.url, downloadResponse.headers.get("content-disposition"), options.doi);
     const title = options.title ?? filename;
@@ -153,6 +162,7 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
             error: {
                 code: "item_creation_failed",
                 message: `Failed to create attachment item: ${detail}`,
+                ...(isZoteroApiError(err) ? { status: err.response.status } : {}),
                 networkDetail: detail,
             },
         };
@@ -179,7 +189,7 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
     });
     let authResponse;
     try {
-        authResponse = await fetch(authUrl, {
+        authResponse = await fetchWithTimeout(authUrl, {
             method: "POST",
             headers: {
                 "Zotero-API-Key": apiKey,
@@ -187,7 +197,7 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
                 "If-None-Match": "*",
             },
             body: authBody.toString(),
-        });
+        }, TIMEOUTS.zoteroApiMs, "Upload authorization");
     }
     catch (err) {
         const detail = errorMessage(err);
@@ -223,7 +233,19 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
             },
         };
     }
-    const authData = (await authResponse.json());
+    let authData;
+    try {
+        authData = await readJsonObject(authResponse);
+    }
+    catch (err) {
+        if (!(err instanceof InvalidJsonResponseError))
+            throw err;
+        return {
+            success: false,
+            itemKey,
+            error: { code: "auth_failed", message: `Upload authorization failed: ${err.message}`, status: authResponse.status, networkDetail: err.message },
+        };
+    }
     // 6-7. Upload binary + register (skip if already exists)
     if (!("exists" in authData)) {
         const auth = authData;
@@ -232,11 +254,11 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
         const uploadBody = Buffer.concat([prefix, buffer, suffix]);
         let uploadResponse;
         try {
-            uploadResponse = await fetch(auth.url, {
+            uploadResponse = await fetchWithTimeout(auth.url, {
                 method: "POST",
                 headers: { "Content-Type": auth.contentType },
                 body: uploadBody,
-            });
+            }, TIMEOUTS.pdfTransferMs, "File upload");
         }
         catch (err) {
             const detail = errorMessage(err);
@@ -263,7 +285,7 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
         }
         let registerResponse;
         try {
-            registerResponse = await fetch(authUrl, {
+            registerResponse = await fetchWithTimeout(authUrl, {
                 method: "POST",
                 headers: {
                     "Zotero-API-Key": apiKey,
@@ -271,7 +293,7 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
                     "If-None-Match": "*",
                 },
                 body: `upload=${auth.uploadKey}`,
-            });
+            }, TIMEOUTS.zoteroApiMs, "Upload registration");
         }
         catch (err) {
             const detail = errorMessage(err);
@@ -309,8 +331,11 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
                 ? "Fulltext indexed successfully. Use get_item_fulltext to retrieve content."
                 : `Fulltext PUT failed: ${putResult.error}. Sync with Zotero Desktop to index the PDF.`;
         }
-        catch {
-            fulltextStatus = "PDF text extraction failed. Sync with Zotero Desktop to index the PDF.";
+        catch (err) {
+            fulltextStatus =
+                err instanceof RequestTimeoutError
+                    ? `Fulltext indexing failed: ${err.message}. Sync with Zotero Desktop to index the PDF.`
+                    : "PDF text extraction failed. Sync with Zotero Desktop to index the PDF.";
         }
     }
     else {

package/build/utils/timeouts.js

@@ -0,0 +1,97 @@
+/**
+ * Bounds for every network call the server makes. A remote that accepts the connection and then
+ * never answers would otherwise block a tool until the MCP client gives up, with no useful error.
+ * Values are read at call time, so tests can lower them.
+ */
+export const TIMEOUTS = {
+    /** Zotero Web API: metadata reads/writes, fulltext, upload authorization and registration. */
+    zoteroApiMs: 30_000,
+    /** DOI resolution (doi.org / Crossref) and Unpaywall lookups, per attempt. */
+    metadataMs: 30_000,
+    /**
+     * PDF download and upload to Zotero storage, body included. Files are capped at 100 MB, so this
+     * allows ~0.6 MB/s for the largest file; typical papers (1-10 MB) finish in seconds.
+     */
+    pdfTransferMs: 180_000,
+};
+/** A network call that hit its bound. The message names the operation, host and bound. */
+export class RequestTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RequestTimeoutError";
+    }
+}
+/** True for the abort raised by AbortSignal.timeout (DOMException "TimeoutError"). */
+export function isTimeoutAbort(err) {
+    return typeof err === "object" && err !== null && err.name === "TimeoutError";
+}
+function host(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+}
+function seconds(ms) {
+    return `${ms / 1000} s`;
+}
+export function timeoutError(label, url, timeoutMs) {
+    return new RequestTimeoutError(`${label} timed out after ${seconds(timeoutMs)} (${host(url)})`);
+}
+/** Signal that aborts after `timeoutMs`, combined with the caller's signal when there is one. */
+export function timeoutSignal(timeoutMs, signal) {
+    const bound = AbortSignal.timeout(timeoutMs);
+    return signal ? AbortSignal.any([signal, bound]) : bound;
+}
+/**
+ * fetch() with a bound. The signal stays attached to the response, so reading the body is bounded
+ * too: callers that read it should map isTimeoutAbort() errors with timeoutError().
+ */
+export async function fetchWithTimeout(url, init, timeoutMs, label) {
+    try {
+        return await fetch(url, { ...init, signal: timeoutSignal(timeoutMs, init.signal) });
+    }
+    catch (err) {
+        if (isTimeoutAbort(err))
+            throw timeoutError(label, url, timeoutMs);
+        throw err;
+    }
+}
+const VERB_OPTS_INDEX = { get: 0, post: 1, put: 1, patch: 1, delete: 1 };
+/**
+ * Wraps a zotero-api-client instance so every request carries a fresh AbortSignal.timeout
+ * (the client forwards `signal` to fetch). Chain methods return wrapped chains; terminal verbs get
+ * the signal merged into their options, and a timeout becomes a RequestTimeoutError.
+ */
+export function withRequestTimeout(api, timeoutMs) {
+    return new Proxy(api, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function" || typeof prop !== "string")
+                return value;
+            const optsIndex = VERB_OPTS_INDEX[prop];
+            if (optsIndex === undefined) {
+                return (...args) => {
+                    const result = value.apply(target, args);
+                    return result && typeof result === "object" ? withRequestTimeout(result, timeoutMs) : result;
+                };
+            }
+            return async (...args) => {
+                const bound = timeoutMs ?? TIMEOUTS.zoteroApiMs;
+                const opts = (args[optsIndex] ?? {});
+                const callArgs = [...args];
+                callArgs[optsIndex] = { ...opts, signal: timeoutSignal(bound, opts.signal) };
+                try {
+                    return await value.apply(target, callArgs);
+                }
+                catch (err) {
+                    if (isTimeoutAbort(err)) {
+                        throw new RequestTimeoutError(`Zotero API request (${prop.toUpperCase()}) timed out after ${seconds(bound)} (api.zotero.org)`);
+                    }
+                    throw err;
+                }
+            };
+        },
+    });
+}

package/build/utils/unpaywall.js

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

package/build/utils/zotero-fulltext.js

@@ -1,6 +1,7 @@
+import { fetchWithTimeout, TIMEOUTS } from "./timeouts.js";
 export async function putFulltext(libraryType, userId, itemKey, apiKey, content, totalPages) {
     const url = `https://api.zotero.org/${libraryType}s/${userId}/items/${itemKey}/fulltext`;
-    const response = await fetch(url, {
+    const response = await fetchWithTimeout(url, {
         method: "PUT",
         headers: {
             "Content-Type": "application/json",
@@ -11,7 +12,7 @@ export async function putFulltext(libraryType, userId, itemKey, apiKey, content,
             indexedPages: totalPages,
             totalPages,
         }),
-    });
+    }, TIMEOUTS.zoteroApiMs, "Zotero fulltext upload");
     if (response.status === 204) {
         return { success: true };
     }

package/build/utils/zotero-keys.js

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

package/package.json

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