@xevos117/mcp-zotero 1.0.4 → 1.0.6

package/README.md

@@ -5,7 +5,7 @@
 A Model Context Protocol server for Zotero integration. It gives any LLM full access to your Zotero library: search, organize, add papers by DOI, import PDFs, read full-text content, and inject live citations into Word documents.
 
 > Originally based on [mcp-zotero](https://github.com/kaliaboi/mcp-zotero) by Abhishek Kalia.
-> This project has since been extensively rewritten with a new architecture, 13 tools (up from 5), citation injection, PDF management, and Claude skill support.
+> This project has since been extensively rewritten with a new architecture, 15 tools (up from 5), citation injection, PDF management, and Claude skill support.
 
 ## How it works
 
@@ -17,7 +17,7 @@ For advanced use cases (PDF upload policy, citation style guidance, source trans
 
 | Scenario | MCP server | Skill needed? |
 |---|---|---|
-| Local LLM (Claude Code, LM Studio, etc.) | All 13 tools | No |
+| Local LLM (Claude Code, LM Studio, etc.) | All 15 tools | No |
 | Remote/sandboxed LLM (Claude.ai Projects) | API tools (search, add, metadata) | Yes, for citation injection |
 
 Local LLMs with filesystem access can use all tools directly, including `inject_citations` which reads and writes `.docx` files on disk.
@@ -41,6 +41,7 @@ Remote LLMs without filesystem access can use the included **Claude skill** (`sk
    export ZOTERO_API_KEY="your-api-key"
    export ZOTERO_USER_ID="user-id-from-curl"
    export UNPAYWALL_EMAIL="your@email.edu"   # Optional: enables OA PDF lookup via Unpaywall
+   export UNSAFE_OPERATIONS="none"           # Optional: "none" | "items" | "all" (see below)
    ```
 
 ## Environment Variables
@@ -50,6 +51,45 @@ Remote LLMs without filesystem access can use the included **Claude skill** (`sk
 | `ZOTERO_API_KEY` | Yes | API key for Zotero Web API v3. Create one at [zotero.org/settings/keys](https://www.zotero.org/settings/keys) with library read/write and file access permissions. |
 | `ZOTERO_USER_ID` | Yes | Your Zotero numeric user ID. Retrieve it with `curl -H "Zotero-API-Key: KEY" https://api.zotero.org/keys/current`. |
 | `UNPAYWALL_EMAIL` | No | Email for Unpaywall API requests ([rate-limit policy](https://unpaywall.org/products/api)). Enables OA PDF lookup in `add_items_by_doi` and `find_and_attach_pdfs`. If not set, OA PDF features are silently skipped. |
+| `UNSAFE_OPERATIONS` | No | Controls destructive operations (deletion). See [Unsafe Operations](#unsafe-operations) below. Default: `none` (all deletions blocked). |
+
+### Unsafe Operations
+
+By default, the MCP server **does not allow any deletion**. This is a safety measure to prevent an LLM from accidentally deleting items or collections from your library.
+
+To enable deletion, set the `UNSAFE_OPERATIONS` environment variable to one of the following values:
+
+| Value | `delete_items` | `delete_collection` | Use case |
+|---|---|---|---|
+| `none` (default) | Blocked | Blocked | Safe mode — no deletions possible |
+| `items` | **Allowed** | Blocked | Allow deleting items but protect collection structure |
+| `all` | **Allowed** | **Allowed** | Full access — items and collections can be deleted |
+
+**Important notes:**
+
+- If `UNSAFE_OPERATIONS` is not set, empty, or set to an unrecognized value, it defaults to `none`.
+- The value is **case-insensitive** (e.g. `ALL`, `Items`, `NONE` all work).
+- `delete_items` moves items to the Zotero trash (recoverable from the Zotero desktop client).
+- `delete_collection` removes the collection (folder) only — items inside it are **not** deleted and remain in your library.
+- The `all` value includes both item and collection deletion because managing collections inherently requires item-level access.
+
+**Configuration example:**
+
+```json
+{
+  "mcpServers": {
+    "zotero": {
+      "command": "npx",
+      "args": ["-y", "@xevos117/mcp-zotero"],
+      "env": {
+        "ZOTERO_API_KEY": "YOUR_API_KEY",
+        "ZOTERO_USER_ID": "YOUR_USER_ID",
+        "UNSAFE_OPERATIONS": "items"
+      }
+    }
+  }
+}
+```
 
 ## Integration with Claude Desktop
 
@@ -100,6 +140,13 @@ claude mcp add-json "zotero" '{"command":"npx","args":["tsx","src/server.ts"],"e
 | `find_and_attach_pdfs` | Batch OA PDF lookup and auto-attach via Unpaywall (by item keys or collection) |
 | `add_linked_url_attachment` | Attach a URL to an existing item or create a standalone link |
 
+### Deleting content
+
+| Tool | Description |
+|---|---|
+| `delete_items` | Delete up to 50 items per call (moves to Zotero trash). Requires `UNSAFE_OPERATIONS=items` or `all` |
+| `delete_collection` | Delete a collection (folder). Items inside are kept. Requires `UNSAFE_OPERATIONS=all` |
+
 ### Citation & documents
 
 | Tool | Description |
@@ -112,7 +159,7 @@ claude mcp add-json "zotero" '{"command":"npx","args":["tsx","src/server.ts"],"e
 ```bash
 npm install
 npm run build          # Compile TypeScript
-npm test               # Run tests (vitest, 328 tests)
+npm test               # Run tests (vitest, 377 tests)
 npx tsx src/server.ts  # Run directly without building
 ```
 

package/build/server.js

@@ -5,6 +5,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { createRequire } from "module";
 import { registerAllTools } from "./tools/index.js";
 import { logger } from "./utils/logger.js";
+import { parseUnsafeOperations } from "./utils/unsafe-operations.js";
 // Re-export for backward compatibility with existing tests
 export { formatErrorResponse } from "./utils/error-formatter.js";
 export { handleToolCall } from "./tools/index.js";
@@ -12,6 +13,7 @@ class ZoteroServer {
     server;
     zoteroApi;
     userId;
+    unsafeOps;
     constructor(options = {}) {
         this.server = new McpServer({ name: "zotero", version: "1.0.0" }, {
             capabilities: { tools: {} },
@@ -30,6 +32,7 @@ class ZoteroServer {
                 "- get_user_id is only needed by the standalone skill script (inject.js), not by the inject_citations tool.",
             ].join("\n"),
         });
+        this.unsafeOps = parseUnsafeOperations(process.env.UNSAFE_OPERATIONS);
         if (options.zoteroApi) {
             this.userId = options.userId || "";
             this.zoteroApi = options.zoteroApi;
@@ -46,7 +49,7 @@ class ZoteroServer {
         }
     }
     setupHandlers() {
-        registerAllTools(this.server, this.zoteroApi, this.userId);
+        registerAllTools(this.server, this.zoteroApi, this.userId, this.unsafeOps);
     }
     async start() {
         this.setupHandlers();

package/build/tools/delete-collection.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { isZoteroApiError } from "../types/zotero-types.js";
+import { formatErrorResponse } from "../utils/error-formatter.js";
+import { canDeleteCollections } from "../utils/unsafe-operations.js";
+import { logger } from "../utils/logger.js";
+export const toolConfig = {
+    name: "delete_collection",
+    description: "Delete a collection (folder) from your Zotero library. Items inside the collection are NOT deleted — they remain in your library. Requires UNSAFE_OPERATIONS environment variable set to 'all'.",
+    inputSchema: {
+        collection_key: z
+            .string()
+            .min(1)
+            .describe("Zotero collection key to delete. Get this from get_collections."),
+    },
+};
+const DeleteCollectionSchema = z.object(toolConfig.inputSchema);
+export async function handleDeleteCollection(zoteroApi, userId, args, unsafeOps = "none") {
+    const { collection_key } = DeleteCollectionSchema.parse(args);
+    if (!canDeleteCollections(unsafeOps)) {
+        return formatErrorResponse("Deletion of collections is not allowed. Set the UNSAFE_OPERATIONS environment variable to 'all' to enable this operation.", {
+            env_var: "UNSAFE_OPERATIONS",
+            current_value: unsafeOps,
+            required_values: ["all"],
+        });
+    }
+    try {
+        const response = await zoteroApi
+            .library("user", userId)
+            .collections(collection_key)
+            .get();
+        const collection = response.getData();
+        const version = response.getVersion();
+        if (version === null) {
+            return formatErrorResponse("Could not determine collection version", {
+                collection_key,
+            });
+        }
+        await zoteroApi
+            .library("user", userId)
+            .collections(collection_key)
+            .version(version)
+            .delete();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        deleted: true,
+                        collection_key,
+                        name: collection.name || collection_key,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        if (isZoteroApiError(err)) {
+            if (err.response.status === 404) {
+                return formatErrorResponse("Collection not found", {
+                    collection_key,
+                    status: "not_found",
+                });
+            }
+            if (err.response.status === 412) {
+                return formatErrorResponse("Collection was modified by another client. Retry the operation.", {
+                    collection_key,
+                    status: "version_conflict",
+                });
+            }
+            logger.error("Tool execution failed", {
+                tool: "delete_collection",
+                status: err.response.status,
+                errorMessage: err.message,
+                url: err.response.url,
+            });
+        }
+        throw err;
+    }
+}

package/build/tools/delete-items.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { isZoteroApiError } from "../types/zotero-types.js";
+import { formatErrorResponse } from "../utils/error-formatter.js";
+import { canDeleteItems } from "../utils/unsafe-operations.js";
+import { logger } from "../utils/logger.js";
+export const toolConfig = {
+    name: "delete_items",
+    description: "Delete one or more items from your Zotero library permanently (moves to trash). Accepts up to 50 item keys per call. Requires UNSAFE_OPERATIONS environment variable set to 'items' or 'all'.",
+    inputSchema: {
+        item_keys: z
+            .array(z.string())
+            .min(1)
+            .max(50)
+            .describe('Array of Zotero item keys to delete (e.g. ["EUHUT5K3", "F9UQM7N2"]). Max 50 per call.'),
+    },
+};
+const DeleteItemsSchema = z.object(toolConfig.inputSchema);
+export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "none") {
+    const { item_keys } = DeleteItemsSchema.parse(args);
+    if (!canDeleteItems(unsafeOps)) {
+        return formatErrorResponse("Deletion of items is not allowed. Set the UNSAFE_OPERATIONS environment variable to 'items' or 'all' to enable this operation.", {
+            env_var: "UNSAFE_OPERATIONS",
+            current_value: unsafeOps,
+            required_values: ["items", "all"],
+        });
+    }
+    try {
+        const response = await zoteroApi
+            .library("user", userId)
+            .items()
+            .get({ itemKey: item_keys.join(",") });
+        const items = response.getData();
+        const itemList = Array.isArray(items) ? items : [items];
+        const foundKeys = new Set(itemList.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",
+            });
+        }
+        // Use library version from response header (Last-Modified-Version),
+        // not individual item versions — required for multi-object DELETE
+        const libraryVersion = response.getVersion();
+        if (libraryVersion === null) {
+            return formatErrorResponse("Could not determine library version", {
+                item_keys,
+            });
+        }
+        const keysToDelete = [...foundKeys];
+        await zoteroApi
+            .library("user", userId)
+            .items()
+            .version(libraryVersion)
+            .delete(keysToDelete);
+        const result = {
+            deleted_keys: keysToDelete,
+            deleted_count: keysToDelete.length,
+        };
+        if (notFoundKeys.length > 0) {
+            result.not_found = notFoundKeys;
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        if (isZoteroApiError(err)) {
+            if (err.response.status === 412) {
+                return formatErrorResponse("Items were modified by another client. Retry the operation.", {
+                    item_keys,
+                    status: "version_conflict",
+                });
+            }
+            logger.error("Tool execution failed", {
+                tool: "delete_items",
+                status: err.response.status,
+                errorMessage: err.message,
+                url: err.response.url,
+            });
+        }
+        throw err;
+    }
+}

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

@@ -5,6 +5,7 @@ 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 { fetchAllPages } from "../utils/pagination.js";
 export const toolConfig = {
     name: "find_and_attach_pdfs",
     description: "For each Zotero item, check Unpaywall for open access PDFs and attach them. Items must have a DOI. Uses the same source as Zotero Desktop's 'Find Available PDFs'.",
@@ -45,14 +46,8 @@ export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
         // 1. Resolve item keys
         let keys;
         if (collection_key) {
-            const collResponse = await zoteroApi
-                .library("user", userId)
-                .collections(collection_key)
-                .items()
-                .get();
-            const collItems = collResponse.getData();
-            const itemsArray = Array.isArray(collItems) ? collItems : [collItems];
-            keys = itemsArray
+            const { items: collItems } = await fetchAllPages((params) => zoteroApi.library("user", userId).collections(collection_key).items().get(params));
+            keys = collItems
                 .filter((item) => item.itemType !== "attachment" && item.itemType !== "note")
                 .map((item) => item.key)
                 .filter(Boolean);

package/build/tools/get-collection-items.js

@@ -3,6 +3,7 @@ import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatErrorResponse } from "../utils/error-formatter.js";
 import { formatCreators, formatTags } from "../utils/item-formatter.js";
 import { logger } from "../utils/logger.js";
+import { fetchAllPages } from "../utils/pagination.js";
 export const toolConfig = {
     name: "get_collection_items",
     description: "Get all items in a specific Zotero collection. Returns item keys, titles, authors, and dates. Use the collectionKey from get_collections. Use the returned item keys with get_items_details, get_item_fulltext, or inject_citations.",
@@ -18,19 +19,15 @@ const CollectionItemsSchema = z.object(toolConfig.inputSchema);
 export async function handleGetCollectionItems(zoteroApi, userId, args) {
     const { collectionKey, excludeAttachments } = CollectionItemsSchema.parse(args);
     try {
-        const response = await zoteroApi
-            .library("user", userId)
-            .collections(collectionKey)
-            .items()
-            .get();
-        let items = response.getData();
-        if (!items || !Array.isArray(items) || items.length === 0) {
+        const { items: allItems, totalResults } = await fetchAllPages((params) => zoteroApi.library("user", userId).collections(collectionKey).items().get(params));
+        if (!allItems || allItems.length === 0) {
             return formatErrorResponse("Collection is empty", {
                 collectionKey,
                 suggestion: "Add some items to this collection in Zotero",
                 status: "empty",
             });
         }
+        let items = allItems;
         if (excludeAttachments) {
             items = items.filter((item) => item.itemType !== "attachment" && item.itemType !== "note");
         }
@@ -58,7 +55,11 @@ export async function handleGetCollectionItems(zoteroApi, userId, args) {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify(formatted, null, 2),
+                    text: JSON.stringify({
+                        total_items: totalResults,
+                        returned_items: formatted.length,
+                        items: formatted,
+                    }, null, 2),
                 },
             ],
         };

package/build/tools/get-collections.js

@@ -1,6 +1,7 @@
 import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatErrorResponse } from "../utils/error-formatter.js";
 import { logger } from "../utils/logger.js";
+import { fetchAllPages } from "../utils/pagination.js";
 export const toolConfig = {
     name: "get_collections",
     description: "List all collections (folders) in your Zotero library. Returns collection keys, names, and parent relationships. Use collection keys with get_collection_items or as parent_collection in create_collection.",
@@ -8,11 +9,7 @@ export const toolConfig = {
 };
 export async function handleGetCollections(zoteroApi, userId, _args) {
     try {
-        const response = await zoteroApi
-            .library("user", userId)
-            .collections()
-            .get();
-        const collections = response.getData();
+        const { items: collections } = await fetchAllPages((params) => zoteroApi.library("user", userId).collections().get(params));
         if (!Array.isArray(collections) || collections.length === 0) {
             return formatErrorResponse("No collections found", {
                 suggestion: "Create a collection in your Zotero library first",

package/build/tools/index.js

@@ -11,6 +11,8 @@ import { handleAddLinkedUrlAttachment, toolConfig as addLinkedUrlAttachmentConfi
 import { handleAddItems, toolConfig as addItemsConfig } from "./add-items.js";
 import { handleImportPdfToZotero, toolConfig as importPdfToZoteroConfig } from "./import-pdf-to-zotero.js";
 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";
 const handlers = {
     get_collections: handleGetCollections,
     get_collection_items: handleGetCollectionItems,
@@ -25,13 +27,15 @@ const handlers = {
     add_items: handleAddItems,
     import_pdf_to_zotero: handleImportPdfToZotero,
     find_and_attach_pdfs: handleFindAndAttachPdfs,
+    delete_collection: handleDeleteCollection,
+    delete_items: handleDeleteItems,
 };
-export async function handleToolCall(name, args, zoteroApi, userId) {
+export async function handleToolCall(name, args, zoteroApi, userId, unsafeOps = "none") {
     const handler = handlers[name];
     if (!handler) {
         throw new Error(`Unknown tool: ${name}`);
     }
-    return handler(zoteroApi, userId, args);
+    return handler(zoteroApi, userId, args, unsafeOps);
 }
 const toolConfigs = [
     { config: collectionsConfig, handler: handleGetCollections },
@@ -47,14 +51,16 @@ const toolConfigs = [
     { config: addItemsConfig, handler: handleAddItems },
     { config: importPdfToZoteroConfig, handler: handleImportPdfToZotero },
     { config: findAndAttachPdfsConfig, handler: handleFindAndAttachPdfs },
+    { config: deleteCollectionConfig, handler: handleDeleteCollection },
+    { config: deleteItemsConfig, handler: handleDeleteItems },
 ];
-export function registerAllTools(server, zoteroApi, userId) {
+export function registerAllTools(server, zoteroApi, userId, unsafeOps = "none") {
     for (const { config, handler } of toolConfigs) {
         server.registerTool(config.name, {
             description: config.description,
             inputSchema: config.inputSchema,
         }, async (args) => {
-            return handler(zoteroApi, userId, args);
+            return handler(zoteroApi, userId, args, unsafeOps);
         });
     }
 }

package/build/utils/pagination.js

@@ -0,0 +1,22 @@
+const PAGE_LIMIT = 100;
+export async function fetchAllPages(buildRequest) {
+    const firstResponse = await buildRequest({ limit: PAGE_LIMIT, start: 0 });
+    const firstData = firstResponse.getData();
+    const firstItems = Array.isArray(firstData) ? firstData : firstData ? [firstData] : [];
+    const totalResults = firstResponse.getTotalResults();
+    if (totalResults === null || firstItems.length >= totalResults) {
+        return { items: firstItems, totalResults };
+    }
+    const allItems = [...firstItems];
+    let start = firstItems.length;
+    while (start < totalResults) {
+        const response = await buildRequest({ limit: PAGE_LIMIT, start });
+        const data = response.getData();
+        const pageItems = Array.isArray(data) ? data : data ? [data] : [];
+        if (pageItems.length === 0)
+            break;
+        allItems.push(...pageItems);
+        start += pageItems.length;
+    }
+    return { items: allItems, totalResults };
+}

package/build/utils/unsafe-operations.js

@@ -0,0 +1,14 @@
+const VALID_MODES = new Set(["none", "items", "all"]);
+export function parseUnsafeOperations(value) {
+    const normalized = (value ?? "").trim().toLowerCase();
+    if (VALID_MODES.has(normalized)) {
+        return normalized;
+    }
+    return "none";
+}
+export function canDeleteCollections(mode) {
+    return mode === "all";
+}
+export function canDeleteItems(mode) {
+    return mode === "items" || mode === "all";
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xevos117/mcp-zotero",
   "type": "module",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Unofficial MCP server for Zotero integration with citation management",
   "repository": {
     "type": "git",
@@ -12,8 +12,9 @@
     "url": "https://github.com/Xevos117/mcp-zotero/issues"
   },
   "main": "build/server.js",
-
-  
+  "bin": {
+    "mcp-zotero": "build/server.js"
+  },
   "files": [
     "build"
   ],