@xevos117/mcp-zotero 1.0.6 → 1.0.8

package/README.md

@@ -17,12 +17,18 @@ 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 15 tools | No |
-| Remote/sandboxed LLM (Claude.ai Projects) | API tools (search, add, metadata) | Yes, for citation injection |
+| LLM with filesystem access (Claude Code, LM Studio, etc.) | All 15 tools | No |
+| LLM without filesystem access (Claude.ai Projects, Claude Desktop) | 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.
+LLMs with filesystem access can use all tools directly, including `inject_citations` which reads and writes `.docx` files on disk.
 
-Remote LLMs without filesystem access can use the included **Claude skill** (`skills/zotero-skill-mcp-integrations/`), which runs citation injection entirely inside the sandbox. MCP tools handle all Zotero API operations; the skill handles document assembly.
+LLMs without filesystem access — including Claude Desktop, which connects to MCP but cannot generate files locally — can use the included **Claude skill** (`skills/zotero-skill-mcp-integrations/`), which runs citation injection entirely inside a sandbox. MCP tools handle all Zotero API operations; the skill handles document assembly.
+
+### Claude Skill Setup (for Claude.ai Projects and Claude Desktop)
+
+1. Download the skill `.zip` from the latest [GitHub Release](https://github.com/Xevos117/mcp-zotero/releases)
+2. Extract it and upload the folder to your Claude.ai Project as a skill
+3. The skill enables citation injection directly inside the sandbox, without requiring local filesystem access
 
 ## Setup
 
@@ -126,7 +132,7 @@ claude mcp add-json "zotero" '{"command":"npx","args":["tsx","src/server.ts"],"e
 | `get_collections` | List all collections (folders) with keys, names, and parent relationships |
 | `get_collection_items` | Get items in a specific collection with keys, titles, authors, dates |
 | `search_library` | Search by query, or list items sorted by field (date, title, etc.) |
-| `get_items_details` | Batch metadata retrieval for multiple items in a single call |
+| `get_items_details` | Batch metadata retrieval for multiple items — returns all type-specific fields (bookTitle, proceedingsTitle, university, etc.) |
 | `get_item_fulltext` | Get full-text content of a PDF attachment via Zotero's fulltext index |
 
 ### Adding content
@@ -159,7 +165,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, 377 tests)
+npm test               # Run tests (vitest, 404 tests)
 npx tsx src/server.ts  # Run directly without building
 ```
 

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

@@ -105,12 +105,31 @@ export async function handleAddItemsByDoi(zoteroApi, userId, args) {
             .library("user", userId)
             .items()
             .post(zoteroItems);
+        if (!response.isSuccess()) {
+            const errors = response.getErrors();
+            const errorMessages = Object.entries(errors)
+                .map(([idx, msg]) => `Item ${idx}: ${typeof msg === "object" ? JSON.stringify(msg) : msg}`)
+                .join(", ");
+            return formatErrorResponse(`Zotero API write failed: ${errorMessages}`);
+        }
         const createdItems = response.getData();
-        const success = resolved.success.map((r, i) => ({
-            doi: r.doi,
-            item_key: createdItems[i]?.key ?? "unknown",
-            title: createdItems[i]?.title ?? r.data.title ?? "Untitled",
-        }));
+        if (!createdItems || !Array.isArray(createdItems) || createdItems.length === 0) {
+            return formatErrorResponse("Zotero API returned empty response - items may not have been created");
+        }
+        const success = [];
+        for (let i = 0; i < resolved.success.length; i++) {
+            const r = resolved.success[i];
+            const entity = response.getEntityByIndex(i);
+            const itemKey = entity?.key;
+            if (!itemKey) {
+                return formatErrorResponse(`Failed to get item key for DOI ${r.doi} at index ${i}. API response may be invalid.`);
+            }
+            success.push({
+                doi: r.doi,
+                item_key: itemKey,
+                title: entity?.title ?? r.data.title ?? "Untitled",
+            });
+        }
         let pdf_results;
         if (auto_attach_pdf) {
             const apiKey = process.env.ZOTERO_API_KEY;

package/build/tools/get-collections.js

@@ -1,21 +1,40 @@
+import { z } from "zod";
 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.",
-    inputSchema: {},
+    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. Trashed collections are excluded by default.",
+    inputSchema: {
+        include_trashed: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include trashed (deleted) collections. Default false."),
+    },
 };
-export async function handleGetCollections(zoteroApi, userId, _args) {
+const GetCollectionsSchema = z.object(toolConfig.inputSchema);
+export async function handleGetCollections(zoteroApi, userId, args) {
+    const { include_trashed } = GetCollectionsSchema.parse(args);
     try {
-        const { items: collections } = await fetchAllPages((params) => zoteroApi.library("user", userId).collections().get(params));
-        if (!Array.isArray(collections) || collections.length === 0) {
+        const { items: allCollections } = await fetchAllPages((params) => zoteroApi.library("user", userId).collections().get(params));
+        if (!Array.isArray(allCollections) || allCollections.length === 0) {
             return formatErrorResponse("No collections found", {
                 suggestion: "Create a collection in your Zotero library first",
                 helpUrl: "https://www.zotero.org/support/collections",
             });
         }
+        // Zotero API returns deleted collections despite not requesting them —
+        // filter client-side as a workaround
+        const collections = include_trashed
+            ? allCollections
+            : allCollections.filter((c) => !c.deleted);
+        if (collections.length === 0) {
+            return formatErrorResponse("No collections found", {
+                suggestion: "All collections are in the trash. Use include_trashed=true to see them.",
+            });
+        }
         return {
             content: [
                 { type: "text", text: JSON.stringify(collections, null, 2) },

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

@@ -5,7 +5,7 @@ import { formatCreators } from "../utils/item-formatter.js";
 import { logger } from "../utils/logger.js";
 export const toolConfig = {
     name: "get_items_details",
-    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 calling get_item_details multiple times. Returns title, authors, date, DOI, item type, publication title, and URL for each item. Set include_abstract to include abstracts (excluded by default to keep responses lightweight).",
+    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 calling get_item_details multiple times. 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())
@@ -18,6 +18,12 @@ export const toolConfig = {
     },
 };
 const GetItemsDetailsSchema = z.object(toolConfig.inputSchema);
+/** Fields excluded from the response (structural/internal, not bibliographic metadata). */
+const SKIP_FIELDS = new Set([
+    "key", "version", "dateAdded", "dateModified",
+    "collections", "tags", "relations", "creators",
+    "abstractNote",
+]);
 export async function handleGetItemsDetails(zoteroApi, userId, args) {
     const { item_keys, include_abstract } = GetItemsDetailsSchema.parse(args);
     if (item_keys.length === 0) {
@@ -40,18 +46,26 @@ export async function handleGetItemsDetails(zoteroApi, userId, args) {
             const key = item.key;
             if (!key)
                 continue;
-            result[key] = {
+            const entry = {
+                itemType: item.itemType || "document",
                 title: item.title || "Untitled",
                 authors: formatCreators(item.creators),
-                date: item.date || "No date",
-                doi: item.DOI || null,
-                itemType: item.itemType || "document",
-                publicationTitle: item.publicationTitle || null,
-                url: item.url || null,
             };
+            // Include all non-empty bibliographic fields from the Zotero response
+            const raw = item;
+            for (const [field, value] of Object.entries(raw)) {
+                if (SKIP_FIELDS.has(field))
+                    continue;
+                if (field in entry)
+                    continue;
+                if (value === undefined || value === null || value === "" || value === false)
+                    continue;
+                entry[field] = value;
+            }
             if (include_abstract && item.abstractNote) {
-                result[key].abstractNote = item.abstractNote;
+                entry.abstractNote = item.abstractNote;
             }
+            result[key] = entry;
         }
         return {
             content: [

package/build/utils/csl-to-zotero.js

@@ -1,4 +1,6 @@
+import { ITEM_TYPE_FIELDS } from "./zotero-item-types.js";
 const CSL_TO_ZOTERO_TYPE = {
+    // Standard CSL types
     "article": "journalArticle",
     "article-journal": "journalArticle",
     "article-magazine": "magazineArticle",
@@ -34,6 +36,23 @@ const CSL_TO_ZOTERO_TYPE = {
     "standard": "standard",
     "thesis": "thesis",
     "webpage": "webpage",
+    // Non-standard types returned by CrossRef/DataCite DOI content negotiation
+    "journal-article": "journalArticle",
+    "book-chapter": "bookSection",
+    "proceedings-article": "conferencePaper",
+    "posted-content": "preprint",
+    "dissertation": "thesis",
+    "monograph": "book",
+    "reference-entry": "encyclopediaArticle",
+    "component": "document",
+    "peer-review": "journalArticle",
+    "edited-book": "book",
+    "reference-book": "book",
+    "book-series": "book",
+    "book-part": "bookSection",
+    "proceedings": "book",
+    "journal": "journalArticle",
+    "report-series": "report",
 };
 const ZOTERO_TO_CSL_TYPE = {
     journalArticle: "article-journal",
@@ -74,7 +93,27 @@ const ZOTERO_TO_CSL_TYPE = {
     email: "personal_communication",
     instantMessage: "personal_communication",
 };
+/**
+ * Maps CSL `container-title` to the correct Zotero field name per item type.
+ * Types not listed here have no container-title equivalent.
+ */
+const CONTAINER_TITLE_FIELD = {
+    journalArticle: "publicationTitle",
+    magazineArticle: "publicationTitle",
+    newspaperArticle: "publicationTitle",
+    bookSection: "bookTitle",
+    dictionaryEntry: "dictionaryTitle",
+    conferencePaper: "proceedingsTitle",
+    blogPost: "blogTitle",
+    encyclopediaArticle: "encyclopediaTitle",
+    forumPost: "forumTitle",
+    webpage: "websiteTitle",
+    radioBroadcast: "programTitle",
+    tvBroadcast: "programTitle",
+    podcast: "programTitle",
+};
 export function cslToZoteroItem(csl, options) {
+    const itemType = (CSL_TO_ZOTERO_TYPE[csl.type] ?? "journalArticle");
     const creators = (csl.author ?? []).map((a) => ({
         firstName: a.given ?? "",
         lastName: a.family ?? a.literal ?? "",
@@ -87,13 +126,11 @@ export function cslToZoteroItem(csl, options) {
         collections.push(options.collectionKey);
     }
     const tags = (options?.tags ?? []).map((t) => ({ tag: t }));
-    return {
-        itemType: CSL_TO_ZOTERO_TYPE[csl.type] ?? "journalArticle",
+    // Build candidate fields (CSL → Zotero field names)
+    const candidates = {
         title: csl.title ?? "",
-        creators,
         date,
         DOI: csl.DOI ?? "",
-        publicationTitle: csl["container-title"] ?? "",
         volume: csl.volume ?? "",
         issue: csl.issue ?? "",
         pages: csl.page ?? "",
@@ -101,15 +138,35 @@ export function cslToZoteroItem(csl, options) {
         place: csl["publisher-place"] ?? "",
         url: csl.URL ?? "",
         abstractNote: csl.abstract ?? "",
-        ISBN: csl.ISBN ?? "",
-        ISSN: csl.ISSN ?? "",
+        ISBN: Array.isArray(csl.ISBN) ? csl.ISBN[0] : csl.ISBN ?? "",
+        ISSN: Array.isArray(csl.ISSN) ? csl.ISSN[0] : csl.ISSN ?? "",
         edition: csl.edition ?? "",
         numPages: csl["number-of-pages"] ?? "",
         series: csl["collection-title"] ?? "",
         language: csl.language ?? "",
-        collections,
-        tags,
     };
+    // Map container-title to the correct field for this item type
+    const containerTitleField = CONTAINER_TITLE_FIELD[itemType];
+    if (containerTitleField) {
+        candidates[containerTitleField] = csl["container-title"] ?? "";
+    }
+    // Filter: only include fields valid for this item type
+    const validFields = ITEM_TYPE_FIELDS[itemType];
+    const result = { itemType, creators, collections, tags };
+    if (validFields) {
+        for (const [field, value] of Object.entries(candidates)) {
+            if (validFields.has(field)) {
+                result[field] = value;
+            }
+        }
+    }
+    else {
+        // Unknown item type — include all fields as fallback
+        for (const [field, value] of Object.entries(candidates)) {
+            result[field] = value;
+        }
+    }
+    return result;
 }
 export function zoteroItemToCsl(item) {
     const authors = (item.creators ?? [])

package/package.json

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