@xevos117/mcp-zotero 2.0.2 → 2.0.4

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/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/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,5 +1,6 @@
 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";
@@ -161,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,
             },
         };

package/build/utils/unpaywall.js

@@ -2,15 +2,30 @@ 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);
 }
@@ -34,11 +49,15 @@ export async function lookupOaPdfWithFallbacks(doi) {
     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 {
@@ -48,7 +67,7 @@ export async function lookupOaPdfWithFallbacks(doi) {
         if (!(err instanceof InvalidJsonResponseError))
             throw err;
         logger.error("Unpaywall API returned an invalid response", { doi, error: err.message });
-        return { primary: { ...UNAVAILABLE_RESULT }, fallback_urls: [] };
+        return { primary: unavailableResult(err.message), fallback_urls: [] };
     }
     const locations = data.is_oa
         ? [data.best_oa_location, ...(data.oa_locations ?? [])].filter((l) => l !== null && l !== undefined)

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.2",
+  "version": "2.0.4",
+  "mcpName": "io.github.Xevos117/mcp-zotero",
   "description": "Unofficial MCP server for Zotero integration with citation management",
   "repository": {
     "type": "git",
@@ -26,6 +27,7 @@
     "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",
@@ -56,8 +58,10 @@
   },
   "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"