@xevos117/mcp-zotero 2.0.0 → 2.0.1

package/build/citation-injector/injector.js

@@ -123,6 +123,12 @@ export async function injectCitations(filePath, zoteroApi, libraryType, userId,
     }
     // Collect all unique item keys
     const uniqueKeys = new Set(matches.flatMap((m) => m.keys));
+    // Keys from the document go into API URL paths (one GET per key): only letters and digits, so a crafted
+    // <zcite> cannot point the request at another endpoint ("../", "?", "&"); unknown keys still give a 404
+    const invalid = [...uniqueKeys].filter((k) => !/^[A-Za-z0-9]{1,32}$/.test(k));
+    if (invalid.length > 0) {
+        throw new Error(`Invalid Zotero item key(s) in <zcite>: ${invalid.join(", ")} (letters and digits only)`);
+    }
     // Fetch CSL data from Zotero
     const cslData = await fetchCslData(uniqueKeys, zoteroApi, libraryType, userId);
     // Replace each zcite tag with a field code

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { resolveDois } from "../utils/doi-resolver.js";
 import { cslToZoteroItem } from "../utils/csl-to-zotero.js";
@@ -21,8 +22,7 @@ WORKFLOW TIPS:
         dois: z
             .array(z.string())
             .describe('Array of DOI strings (e.g. ["10.1038/s41586-023-06647-8"]). Each DOI will be resolved and added to Zotero.'),
-        collection_key: z
-            .string()
+        collection_key: zoteroKey()
             .optional()
             .describe("Zotero collection key to add items to. Get this from create_collection or get_collections."),
         tags: z

package/build/tools/add-items.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { postInBatches } from "../utils/write-results.js";
 import { ZOTERO_ITEM_TYPES, ITEM_TYPE_FIELDS, ITEM_TYPE_CREATOR_TYPES, TITLE_FIELD_NAME, } from "../utils/zotero-item-types.js";
@@ -81,8 +82,7 @@ Invalid fields or creatorTypes for a given type are rejected with helpful error
             .array(ItemSchema)
             .min(1)
             .describe("Array of items to add. Each item must have itemType and title. Additional fields depend on the item type."),
-        collection_key: z
-            .string()
+        collection_key: zoteroKey()
             .optional()
             .describe("Zotero collection key to add all items to. Get this from create_collection or get_collections."),
         tags: z

package/build/tools/add-linked-url-attachment.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { formatWriteErrors } from "../utils/write-results.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
@@ -15,12 +16,11 @@ export const toolConfig = {
             .string()
             .optional()
             .describe('MIME type of the linked resource (e.g. "application/pdf", "text/html")'),
-        parent_item: z
-            .string()
+        parent_item: zoteroKey()
             .optional()
             .describe("Item key of the parent item. If provided, the attachment becomes a child of that item."),
         collections: z
-            .array(z.string())
+            .array(zoteroKey())
             .optional()
             .describe("Collection keys to add the attachment to (only used for standalone attachments, ignored when parent_item is set)"),
         tags: z

package/build/tools/create-collection.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { formatWriteErrors } from "../utils/write-results.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
@@ -7,8 +8,7 @@ export const toolConfig = {
     description: "Create a new collection (folder) in your Zotero library. Optionally nest it under a parent collection. Returns the new collection key and name. Use the key with add_items_by_doi to organize imported papers.",
     inputSchema: {
         name: z.string().describe("Name of the new collection"),
-        parent_collection: z
-            .string()
+        parent_collection: zoteroKey()
             .optional()
             .describe("Zotero collection key of the parent collection. Get this from get_collections."),
         ...libraryArgsSchema,

package/build/tools/delete-collection.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { canDeleteCollections } from "../utils/unsafe-operations.js";
@@ -7,9 +8,7 @@ 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)
+        collection_key: zoteroKey()
             .describe("Zotero collection key to delete. Get this from get_collections."),
         ...libraryArgsSchema,
     },

package/build/tools/delete-items.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { canDeleteItems } from "../utils/unsafe-operations.js";
@@ -9,7 +10,7 @@ export const toolConfig = {
     description: "Delete one or more items from your Zotero library: they are permanently deleted (not moved to the Zotero 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())
+            .array(zoteroKey())
             .min(1)
             .max(50)
             .describe('Array of Zotero item keys to delete (e.g. ["EUHUT5K3", "F9UQM7N2"]). Max 50 per call.'),
@@ -44,7 +45,8 @@ export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "no
                 item_keys,
             });
         }
-        const keysToDelete = [...foundKeys];
+        // 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()

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse, formatEmptyResult, errorMessage, logToolError } from "../utils/error-formatter.js";
 import { attachOpenAccessPdfs } from "../utils/oa-pdf.js";
 import { fetchAllPages, fetchItemsByKeys } from "../utils/pagination.js";
@@ -8,11 +9,10 @@ export const toolConfig = {
     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'.",
     inputSchema: {
         item_keys: z
-            .array(z.string())
+            .array(zoteroKey())
             .optional()
             .describe("Array of Zotero item keys to process (mutually exclusive with collection_key)"),
-        collection_key: z
-            .string()
+        collection_key: zoteroKey()
             .optional()
             .describe("Process all items in this collection (mutually exclusive with item_keys)"),
         skip_if_attachment_exists: z

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatJsonResult, formatErrorResponse, formatEmptyResult } from "../utils/error-formatter.js";
 import { formatCreators, formatTags } from "../utils/item-formatter.js";
@@ -8,7 +9,7 @@ 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.",
     inputSchema: {
-        collectionKey: z.string().describe("The collection key/ID"),
+        collectionKey: zoteroKey().describe("The collection key/ID"),
         excludeAttachments: z
             .boolean()
             .default(true)

package/build/tools/get-item-fulltext.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
@@ -7,7 +8,7 @@ export const toolConfig = {
     name: "get_item_fulltext",
     description: "Get the full text content of a Zotero item's PDF attachment via Zotero's fulltext index. Zotero desktop automatically indexes PDFs when synced. Use this to read the full content of papers instead of relying on abstracts.",
     inputSchema: {
-        item_key: z.string().describe("The Zotero item key (parent item or attachment key)"),
+        item_key: zoteroKey().describe("The Zotero item key (parent item or attachment key)"),
         max_characters: z
             .number()
             .optional()

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse, formatEmptyResult } from "../utils/error-formatter.js";
 import { formatCreators } from "../utils/item-formatter.js";
 import { fetchItemsByKeys } from "../utils/pagination.js";
@@ -8,7 +9,7 @@ export const toolConfig = {
     description: "Get metadata for multiple Zotero items in a single call. Accepts an array of item keys and returns a map of key → metadata. Use this instead of one call per item. Returns all type-specific fields (e.g. bookTitle for bookSection, proceedingsTitle for conferencePaper, university for thesis). Set include_abstract to include abstracts (excluded by default to keep responses lightweight).",
     inputSchema: {
         item_keys: z
-            .array(z.string())
+            .array(zoteroKey())
             .describe('Array of Zotero item keys (e.g. ["EUHUT5K3", "F9UQM7N2"]). Get these from search_library, add_items_by_doi, or get_collection_items.'),
         include_abstract: z
             .boolean()

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse, errorMessage, logToolError } from "../utils/error-formatter.js";
 import { downloadAndUploadPdf } from "../utils/pdf-uploader.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
@@ -20,12 +21,11 @@ export const toolConfig = {
             .optional()
             .default("application/pdf")
             .describe('MIME type of the file (default: "application/pdf")'),
-        parent_item: z
-            .string()
+        parent_item: zoteroKey()
             .optional()
             .describe("Item key of the parent item. If provided, the attachment becomes a child of that item."),
         collections: z
-            .array(z.string())
+            .array(zoteroKey())
             .optional()
             .describe("Collection keys (only used for standalone attachments, ignored when parent_item is set)"),
         tags: z

package/build/utils/pagination.js

@@ -1,3 +1,4 @@
+import { ZOTERO_KEY } from "./zotero-keys.js";
 const PAGE_LIMIT = 100;
 /** getData() returns an object for single-item requests and an array otherwise. */
 export function asArray(data) {
@@ -30,15 +31,22 @@ export const MAX_KEYS_PER_REQUEST = 50;
  * Fetch items by key in chunks of MAX_KEYS_PER_REQUEST, each with an explicit `limit`
  * (the API default page size is 25, so a bare `itemKey` GET silently drops the rest).
  * Returns the items found and the library version of the last response.
+ *
+ * When no key in an `itemKey` filter is well-formed, the Web API ignores the filter and returns
+ * the whole library. Tools reject malformed keys up front (zoteroKey schema); as a second line of
+ * defense malformed keys are never sent here (no request at all if none is valid) and only items
+ * whose key was requested are returned.
  */
 export async function fetchItemsByKeys(buildRequest, keys) {
     const items = [];
     let version = null;
-    for (let start = 0; start < keys.length; start += MAX_KEYS_PER_REQUEST) {
-        const chunk = keys.slice(start, start + MAX_KEYS_PER_REQUEST);
+    const valid = [...new Set(keys.filter((k) => ZOTERO_KEY.test(k)))];
+    const requested = new Set(valid);
+    for (let start = 0; start < valid.length; start += MAX_KEYS_PER_REQUEST) {
+        const chunk = valid.slice(start, start + MAX_KEYS_PER_REQUEST);
         const response = await buildRequest({ itemKey: chunk.join(","), limit: chunk.length });
         const data = response.getData();
-        items.push(...asArray(data));
+        items.push(...asArray(data).filter((item) => typeof item.key === "string" && requested.has(item.key)));
         version = response.getVersion();
     }
     return { items, version };

package/build/utils/zotero-keys.js

@@ -0,0 +1,10 @@
+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";
+/**
+ * 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
+ * no key is well-formed): a malformed key must be rejected before any request.
+ */
+export const zoteroKey = () => z.string().regex(ZOTERO_KEY, INVALID_KEY_MESSAGE);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xevos117/mcp-zotero",
   "type": "module",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Unofficial MCP server for Zotero integration with citation management",
   "repository": {
     "type": "git",