@xevos117/mcp-zotero 1.0.8 → 2.0.0

package/README.md

@@ -32,6 +32,8 @@ LLMs without filesystem access — including Claude Desktop, which connects to M
 
 ## Setup
 
+Requires **Node.js 22 or newer**.
+
 1. Get your Zotero credentials:
 
    ```bash
@@ -50,6 +52,65 @@ LLMs without filesystem access — including Claude Desktop, which connects to M
    export UNSAFE_OPERATIONS="none"           # Optional: "none" | "items" | "all" (see below)
    ```
 
+### Targeting a group library
+
+By default the server targets your personal Zotero library (`/users/<ZOTERO_USER_ID>/...`).
+To target a group library instead, set two additional environment variables:
+
+| Variable | Values | Required? | Default |
+|---|---|---|---|
+| `ZOTERO_LIBRARY_TYPE` | `user` \| `group` | No | `user` |
+| `ZOTERO_LIBRARY_ID` | numeric library ID | Yes when type=`group`; otherwise falls back to `ZOTERO_USER_ID` | — |
+
+Example for a group library:
+
+```
+ZOTERO_API_KEY=...
+ZOTERO_USER_ID=12345               # optional for groups: used by get_user_id and per-call library_type="user"
+ZOTERO_LIBRARY_TYPE=group
+ZOTERO_LIBRARY_ID=6178978          # the group ID
+```
+
+The API key in `ZOTERO_API_KEY` must have access to the target group library — generate or scope keys at https://www.zotero.org/settings/keys.
+
+The server refuses to start if `ZOTERO_LIBRARY_TYPE=group` is set without `ZOTERO_LIBRARY_ID`, or if a library ID is not numeric.
+
+
+### Per-call library override
+
+Every tool accepts two optional args that override the env defaults for that single call:
+
+- `library_type` — `"user"` or `"group"`
+- `library_id` — numeric library ID
+
+Resolution order: per-call arg > env var > implicit default (`user`, `ZOTERO_USER_ID`). `library_id` must be numeric. Overriding `library_type` to `group` on a server configured for a user library requires `library_id`; overriding to `user` on a group server without `library_id` uses `ZOTERO_USER_ID`.
+
+Note that per-call overrides let the LLM reach any library the API key can access. Scope the key to the libraries you want exposed; deletions remain gated by `UNSAFE_OPERATIONS`.
+
+This lets a single MCP instance target multiple libraries (e.g., a staging group and a final-output group) without restarting:
+
+```jsonc
+// First call targets the staging group
+{
+  "tool": "add_items",
+  "args": {
+    "items": [...],
+    "library_type": "group",
+    "library_id": "5597114"
+  }
+}
+
+// Second call targets DART-output (different group)
+{
+  "tool": "add_items",
+  "args": {
+    "items": [...],
+    "library_type": "group",
+    "library_id": "6178978"
+  }
+}
+```
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -75,7 +136,7 @@ To enable deletion, set the `UNSAFE_OPERATIONS` environment variable to one of t
 
 - 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_items` deletes items **permanently**: the Zotero Web API multi-item DELETE does not move them to the Zotero trash, so they cannot be restored from the 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.
 
@@ -132,7 +193,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 — returns all type-specific fields (bookTitle, proceedingsTitle, university, etc.) |
+| `get_items_details` | Batch metadata retrieval for multiple items — returns all type-specific fields (bookTitle, proceedingsTitle, university, etc.), the `authors` string and the structured `creators` |
 | `get_item_fulltext` | Get full-text content of a PDF attachment via Zotero's fulltext index |
 
 ### Adding content
@@ -150,7 +211,7 @@ claude mcp add-json "zotero" '{"command":"npx","args":["tsx","src/server.ts"],"e
 
 | Tool | Description |
 |---|---|
-| `delete_items` | Delete up to 50 items per call (moves to Zotero trash). Requires `UNSAFE_OPERATIONS=items` or `all` |
+| `delete_items` | Permanently delete up to 50 items per call (not moved to the Zotero trash). Requires `UNSAFE_OPERATIONS=items` or `all` |
 | `delete_collection` | Delete a collection (folder). Items inside are kept. Requires `UNSAFE_OPERATIONS=all` |
 
 ### Citation & documents

package/build/citation-injector/injector.js

@@ -1,5 +1,6 @@
 import JSZip from "jszip";
 import { readFile, writeFile } from "node:fs/promises";
+import { format, parse } from "node:path";
 import { generateZoteroFieldCode, generateBibliographyFieldCode } from "./field-codes.js";
 import { formatCitationText } from "./citation-formatter.js";
 import { regexEscape, unescapeXml } from "./xml-utils.js";
@@ -20,11 +21,13 @@ function parseZciteMatches(documentXml) {
             // and values like "pp. 12 & 15" need a second unescape
             attrs[attrMatch[1]] = unescapeXml(attrMatch[2]);
         }
-        if (!attrs["keys"])
+        // Tolerate "KEY1, KEY2": a stray space would otherwise become part of the key (404 on fetch)
+        const keys = (attrs["keys"] ?? "").split(",").map((k) => k.trim()).filter(Boolean);
+        if (keys.length === 0)
             continue;
         matches.push({
             fullMatch,
-            keys: attrs["keys"].split(","),
+            keys,
             locator: attrs["locator"] || undefined,
             prefix: attrs["prefix"] || undefined,
             suffix: attrs["suffix"] || undefined,
@@ -33,11 +36,11 @@ function parseZciteMatches(documentXml) {
     }
     return matches;
 }
-async function fetchCslData(keys, zoteroApi, userId) {
+async function fetchCslData(keys, zoteroApi, libraryType, userId) {
     const cslData = new Map();
     for (const key of keys) {
         const response = await zoteroApi
-            .library("user", userId)
+            .library(libraryType, userId)
             .items(key)
             .get();
         const zoteroItem = response.getData();
@@ -45,13 +48,13 @@ async function fetchCslData(keys, zoteroApi, userId) {
     }
     return cslData;
 }
-function buildCitationItems(match, cslData, userId) {
+function buildCitationItems(match, cslData, libraryType, userId) {
     return match.keys.map((key, idx) => {
         const itemData = cslData.get(key) ?? { type: "article-journal" };
         const item = {
             id: idx,
-            uris: [`http://zotero.org/users/${userId}/items/${key}`],
-            uri: [`http://zotero.org/users/${userId}/items/${key}`],
+            uris: [`http://zotero.org/${libraryType}s/${userId}/items/${key}`],
+            uri: [`http://zotero.org/${libraryType}s/${userId}/items/${key}`],
             itemData,
         };
         if (match.locator)
@@ -92,7 +95,10 @@ function replaceZciteInXml(xml, escapedZciteTag, fieldCodeXml) {
     }
     return xml;
 }
-export async function injectCitations(filePath, zoteroApi, userId, style) {
+export async function injectCitations(filePath, zoteroApi, libraryType, userId, style) {
+    // Derive "<name>_cited<ext>" from the basename only: a directory containing ".docx" stays untouched
+    const { dir, name, ext } = parse(filePath);
+    const outputPath = format({ dir, name: `${name}_cited`, ext });
     const fileBuffer = await readFile(filePath);
     const zip = await JSZip.loadAsync(fileBuffer);
     const documentEntry = zip.file("word/document.xml");
@@ -103,7 +109,6 @@ export async function injectCitations(filePath, zoteroApi, userId, style) {
     documentXml = normalizeZciteTags(documentXml);
     const matches = parseZciteMatches(documentXml);
     if (matches.length === 0) {
-        const outputPath = filePath.replace(".docx", "_cited.docx");
         const buffer = await zip.generateAsync({ type: "nodebuffer" });
         await writeFile(outputPath, buffer);
         return { outputPath, found: 0, injected: 0, warnings: [] };
@@ -119,11 +124,11 @@ export async function injectCitations(filePath, zoteroApi, userId, style) {
     // Collect all unique item keys
     const uniqueKeys = new Set(matches.flatMap((m) => m.keys));
     // Fetch CSL data from Zotero
-    const cslData = await fetchCslData(uniqueKeys, zoteroApi, userId);
+    const cslData = await fetchCslData(uniqueKeys, zoteroApi, libraryType, userId);
     // Replace each zcite tag with a field code
     let injected = 0;
     for (const match of matches) {
-        const citationItems = buildCitationItems(match, cslData, userId);
+        const citationItems = buildCitationItems(match, cslData, libraryType, userId);
         const itemDataList = match.keys.map((k) => cslData.get(k) ?? { type: "article-journal" });
         const formattedText = formatCitationText(itemDataList, style, match.num);
         const fieldCodeXml = generateZoteroFieldCode(citationItems, formattedText);
@@ -138,7 +143,6 @@ export async function injectCitations(filePath, zoteroApi, userId, style) {
     documentXml = documentXml.replace("</w:body>", `${biblXml}</w:body>`);
     // Save
     zip.file("word/document.xml", documentXml);
-    const outputPath = filePath.replace(".docx", "_cited.docx");
     const buffer = await zip.generateAsync({ type: "nodebuffer" });
     await writeFile(outputPath, buffer);
     return { outputPath, found: matches.length, injected, warnings };

package/build/server.js

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
-import "dotenv/config";
+import dotenv from "dotenv";
+dotenv.config({ quiet: true });
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 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";
+import { getDefaultLibrary } from "./utils/library-context.js";
+// Report the package version in the MCP handshake (package.json sits one level above both src/ and build/).
+const { version: SERVER_VERSION } = createRequire(import.meta.url)("../package.json");
 // Re-export for backward compatibility with existing tests
 export { formatErrorResponse } from "./utils/error-formatter.js";
 export { handleToolCall } from "./tools/index.js";
@@ -15,7 +19,7 @@ class ZoteroServer {
     userId;
     unsafeOps;
     constructor(options = {}) {
-        this.server = new McpServer({ name: "zotero", version: "1.0.0" }, {
+        this.server = new McpServer({ name: "zotero", version: SERVER_VERSION }, {
             capabilities: { tools: {} },
             instructions: [
                 "Zotero library management and citation injection for Word documents.",
@@ -24,7 +28,7 @@ class ZoteroServer {
                 "1. Collect item keys: use add_items_by_doi for items with DOIs, add_items for items without DOIs (or search_library for existing items)",
                 "2. Generate .docx: create a Word document with <zcite keys=\"ITEMKEY\"/> placeholders where citations should appear. Each <zcite> must be in its own TextRun.",
                 "3. Call inject_citations with the .docx file path — it fetches metadata from Zotero automatically.",
-                "4. Tell the user to open in Word with Zotero plugin → click Zotero → Refresh.",
+                "4. Tell the user to open it in Word with the Zotero plugin → Zotero → Add/Edit Bibliography, then Zotero → Refresh.",
                 "",
                 "KEY NOTES:",
                 "- add_items_by_doi auto-attaches OA PDFs via Unpaywall at no cost. Do not disable auto_attach_pdf unless it causes errors.",
@@ -38,13 +42,18 @@ class ZoteroServer {
             this.zoteroApi = options.zoteroApi;
         }
         else {
-            this.userId = process.env.ZOTERO_USER_ID || "";
             const apiKey = process.env.ZOTERO_API_KEY || "";
-            if (!apiKey || !this.userId) {
-                throw new Error("Missing ZOTERO_API_KEY or ZOTERO_USER_ID environment variables");
+            if (!apiKey) {
+                throw new Error("Missing ZOTERO_API_KEY environment variable");
             }
+            // Validate the library configuration eagerly so a misconfigured server fails
+            // fast at startup rather than on the first tool call. ZOTERO_LIBRARY_ID takes
+            // precedence (group libraries); ZOTERO_USER_ID is the user-library fallback.
+            this.userId = getDefaultLibrary().id;
+            // zotero-api-client >= 0.51 ships a single CJS entry (lib/main.cjs) that relies on the
+            // global fetch; the old lib/main-node.cjs (cross-fetch polyfill) no longer exists.
             const require = createRequire(import.meta.url);
-            const zoteroApiFactory = require("zotero-api-client/lib/main-node.cjs").default;
+            const { default: zoteroApiFactory } = require("zotero-api-client");
             this.zoteroApi = zoteroApiFactory(apiKey);
         }
     }

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

@@ -1,12 +1,10 @@
 import { z } from "zod";
-import { isZoteroApiError } from "../types/zotero-types.js";
-import { formatErrorResponse } from "../utils/error-formatter.js";
+import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { resolveDois } from "../utils/doi-resolver.js";
 import { cslToZoteroItem } from "../utils/csl-to-zotero.js";
-import { logger } from "../utils/logger.js";
-import { lookupOaPdf } from "../utils/unpaywall.js";
-import { downloadAndUploadPdf } from "../utils/pdf-uploader.js";
-import { mapWithConcurrency } from "../utils/concurrency.js";
+import { postInBatches } from "../utils/write-results.js";
+import { attachOpenAccessPdfs } from "../utils/oa-pdf.js";
+import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
 export const toolConfig = {
     name: "add_items_by_doi",
     description: `Add items to your Zotero library by resolving DOIs. Works with ANY item type that has a DOI — journal articles, books, datasets, preprints, conference papers, reports, etc. For each DOI, resolves metadata via content negotiation and creates the item in Zotero with the correct type automatically. Returns a list of successfully added items (with item_key and title) and any failures.
@@ -35,130 +33,62 @@ WORKFLOW TIPS:
             .boolean()
             .default(true)
             .describe("Attach freely available OA PDFs via Unpaywall (default: true). This is lightweight and adds no cost — leave enabled. Only set to false if PDF attachment is causing errors."),
+        ...libraryArgsSchema,
     },
 };
 const AddItemsByDoiSchema = z.object(toolConfig.inputSchema);
-async function attachPdfsToItems(items, zoteroApi, userId, apiKey) {
-    const itemsWithDoi = items.filter((item) => item.doi);
-    if (itemsWithDoi.length === 0)
-        return [];
-    // Probe Unpaywall config with the first DOI — if email is bad, skip entirely
-    const probe = await lookupOaPdf(itemsWithDoi[0].doi);
-    if (probe.warning) {
-        return [{
-                item_key: itemsWithDoi[0].item_key,
-                doi: itemsWithDoi[0].doi,
-                pdf_attached: false,
-                source: null,
-                error: probe.warning,
-            }];
-    }
-    // Email is valid — process all items in parallel (reuse probe for first)
-    const settled = await mapWithConcurrency(itemsWithDoi, async (item, i) => {
-        const oaResult = i === 0 ? probe : await lookupOaPdf(item.doi);
-        if (oaResult.found && oaResult.pdf_url) {
-            const uploadResult = await downloadAndUploadPdf(zoteroApi, userId, apiKey, {
-                url: oaResult.pdf_url,
-                parentItem: item.item_key,
-            });
-            return {
-                item_key: item.item_key,
-                doi: item.doi,
-                pdf_attached: uploadResult.success,
-                source: oaResult.source,
-                error: uploadResult.success ? undefined : uploadResult.error.message,
-            };
-        }
-        return {
-            item_key: item.item_key,
-            doi: item.doi,
-            pdf_attached: false,
-            source: null,
-            oa_status: oaResult.oa_status ?? undefined,
-            landing_url: oaResult.landing_url ?? undefined,
-            error: oaResult.landing_url
-                ? "Open access copy exists at a repository but no direct PDF link is available. The user can download it manually from the landing page and use import_pdf_to_zotero to attach it."
-                : "No open access PDF found",
-        };
-    });
-    return settled
-        .filter((r) => r.status === "fulfilled")
-        .map((r) => r.value);
-}
 export async function handleAddItemsByDoi(zoteroApi, userId, args) {
-    const { dois, collection_key, tags, auto_attach_pdf } = AddItemsByDoiSchema.parse(args);
+    const { dois, collection_key, tags, auto_attach_pdf, library_type, library_id } = AddItemsByDoiSchema.parse(args);
+    const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     if (dois.length === 0) {
         return formatErrorResponse("At least one DOI is required");
     }
-    try {
-        const resolved = await resolveDois(dois);
-        if (resolved.success.length === 0) {
-            return formatErrorResponse("All DOI resolutions failed", {
-                failed: resolved.failed,
-            });
-        }
-        const zoteroItems = resolved.success.map((r) => cslToZoteroItem(r.data, {
-            collectionKey: collection_key,
-            tags,
-        }));
-        const response = await zoteroApi
-            .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();
-        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;
-            if (apiKey) {
-                pdf_results = await attachPdfsToItems(success, zoteroApi, userId, apiKey);
-            }
-        }
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        success,
-                        failed: resolved.failed,
-                        ...(pdf_results !== undefined ? { pdf_results } : {}),
-                    }, null, 2),
-                },
-            ],
-        };
+    const resolved = await resolveDois(dois);
+    if (resolved.success.length === 0) {
+        return formatErrorResponse("All DOI resolutions failed", {
+            failed: resolved.failed,
+        });
     }
-    catch (err) {
-        if (isZoteroApiError(err)) {
-            logger.error("Tool execution failed", {
-                tool: "add_items_by_doi",
-                status: err.response?.status,
-                errorMessage: err.message,
-                url: err.response?.url,
-            });
-        }
-        throw err;
+    const zoteroItems = resolved.success.map((r) => cslToZoteroItem(r.data, {
+        collectionKey: collection_key,
+        tags,
+    }));
+    const write = await postInBatches((batch) => zoteroApi.library(libraryType, libraryId).items().post(batch), zoteroItems);
+    // Report resolution and write failures together, so a partial write never hides created items
+    const failed = [
+        ...resolved.failed,
+        ...write.failed.map(({ index, error }) => ({ doi: resolved.success[index].doi, error })),
+    ];
+    if (write.created.length === 0) {
+        const errorMessages = write.failed.map(({ index, error }) => `Item ${index}: ${error}`).join("; ");
+        return formatErrorResponse(`Zotero API write failed: ${errorMessages}`, { failed });
     }
+    const success = write.created.map(({ index, entity }) => {
+        const { doi, data } = resolved.success[index];
+        return { doi, item_key: entity.key, title: entity.title ?? data.title ?? "Untitled" };
+    });
+    let pdf_results;
+    const apiKey = process.env.ZOTERO_API_KEY;
+    if (auto_attach_pdf && apiKey) {
+        const targets = success.filter((s) => s.doi).map((s) => ({ itemKey: s.item_key, doi: s.doi }));
+        const results = await attachOpenAccessPdfs(targets, {
+            zoteroApi,
+            library: { type: libraryType, id: libraryId },
+            apiKey,
+        });
+        pdf_results = results.map((r) => r.status === "attached"
+            ? { ...r, pdf_attached: true, pdf_url: r.url_used }
+            : { ...r, pdf_attached: false, error: r.reason });
+    }
+    const quotaHit = pdf_results?.some((r) => r.status === "quota_exceeded");
+    return formatJsonResult({
+        success,
+        failed,
+        ...(pdf_results !== undefined ? { pdf_results } : {}),
+        ...(quotaHit
+            ? {
+                storage_quota_warning: "Zotero storage quota is full. Some PDF attachments were skipped. All items were created successfully (metadata only). Free up space at https://www.zotero.org/settings/storage or upgrade your plan.",
+            }
+            : {}),
+    });
 }

package/build/tools/add-items.js

@@ -1,8 +1,8 @@
 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 { 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";
+import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
 const CreatorSchema = z
     .object({
     firstName: z.string().optional(),
@@ -28,7 +28,7 @@ const ItemSchema = z
             continue;
         if (!validFields.has(key)) {
             ctx.addIssue({
-                code: z.ZodIssueCode.custom,
+                code: "custom",
                 message: `Field "${key}" is not valid for itemType "${data.itemType}". Valid fields: ${[...validFields].join(", ")}`,
                 path: [key],
             });
@@ -38,7 +38,7 @@ const ItemSchema = z
     for (const [i, creator] of (data.creators ?? []).entries()) {
         if (!validCreatorTypes.has(creator.creatorType)) {
             ctx.addIssue({
-                code: z.ZodIssueCode.custom,
+                code: "custom",
                 message: `Invalid creatorType "${creator.creatorType}" for "${data.itemType}". Valid: ${[...validCreatorTypes].join(", ")}`,
                 path: ["creators", i, "creatorType"],
             });
@@ -89,11 +89,13 @@ Invalid fields or creatorTypes for a given type are rejected with helpful error
             .array(z.string())
             .optional()
             .describe("Tags to apply to all items"),
+        ...libraryArgsSchema,
     },
 };
 const AddItemsSchema = z.object(toolConfig.inputSchema);
 export async function handleAddItems(zoteroApi, userId, args) {
-    const { items, collection_key, tags } = AddItemsSchema.parse(args);
+    const { items, collection_key, tags, library_type, library_id } = AddItemsSchema.parse(args);
+    const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     const payloads = items.map((item) => {
         const { itemType, title, creators, ...fields } = item;
         const titleFieldName = TITLE_FIELD_NAME[itemType] ?? "title";
@@ -119,56 +121,19 @@ export async function handleAddItems(zoteroApi, userId, args) {
         }
         return payload;
     });
-    try {
-        const response = await zoteroApi
-            .library("user", userId)
-            .items()
-            .post(payloads);
-        const errors = response.getErrors();
-        const errorIndices = new Set(Object.keys(errors));
-        const success = [];
-        const failed = [];
-        for (const [idx, msg] of Object.entries(errors)) {
-            const i = Number(idx);
-            failed.push({ index: i, title: items[i].title, error: msg });
-        }
-        const created = response.getData();
-        let successIdx = 0;
-        for (let i = 0; i < items.length; i++) {
-            if (!errorIndices.has(String(i))) {
-                const entity = created[successIdx++];
-                success.push({
-                    index: i,
-                    item_key: entity?.key ?? "unknown",
-                    title: entity?.title ?? items[i].title,
-                    item_type: items[i].itemType,
-                });
-            }
-        }
-        if (success.length === 0 && failed.length > 0) {
-            return formatErrorResponse("All items failed to create", { failed });
-        }
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        success,
-                        ...(failed.length > 0 ? { failed } : {}),
-                    }, null, 2),
-                },
-            ],
-        };
-    }
-    catch (err) {
-        if (isZoteroApiError(err)) {
-            logger.error("Tool execution failed", {
-                tool: "add_items",
-                status: err.response?.status,
-                errorMessage: err.message,
-                url: err.response?.url,
-            });
-        }
-        throw err;
+    const write = await postInBatches((batch) => zoteroApi.library(libraryType, libraryId).items().post(batch), payloads);
+    const success = write.created.map(({ index, entity }) => ({
+        index,
+        item_key: entity.key,
+        title: entity.title ?? items[index].title,
+        item_type: items[index].itemType,
+    }));
+    const failed = write.failed.map(({ index, error }) => ({ index, title: items[index].title, error }));
+    if (success.length === 0 && failed.length > 0) {
+        return formatErrorResponse("All items failed to create", { failed });
     }
+    return formatJsonResult({
+        success,
+        ...(failed.length > 0 ? { failed } : {}),
+    });
 }

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

@@ -1,7 +1,7 @@
 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 { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
+import { formatWriteErrors } from "../utils/write-results.js";
+import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
 export const toolConfig = {
     name: "add_linked_url_attachment",
     description: "Attach a linked URL to an existing Zotero item, or create a standalone linked-URL attachment. Use this to link external PDFs, web pages, or other resources to items already in your library. If parent_item is provided, the attachment is added as a child; otherwise it is standalone.",
@@ -27,11 +27,13 @@ export const toolConfig = {
             .array(z.string())
             .optional()
             .describe("Tags to apply to the attachment"),
+        ...libraryArgsSchema,
     },
 };
 const AddLinkedUrlAttachmentSchema = z.object(toolConfig.inputSchema);
 export async function handleAddLinkedUrlAttachment(zoteroApi, userId, args) {
-    const { url, title, content_type, parent_item, collections, tags } = AddLinkedUrlAttachmentSchema.parse(args);
+    const { url, title, content_type, parent_item, collections, tags, library_type, library_id } = AddLinkedUrlAttachmentSchema.parse(args);
+    const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     const itemData = {
         itemType: "attachment",
         linkMode: "linked_url",
@@ -49,44 +51,23 @@ export async function handleAddLinkedUrlAttachment(zoteroApi, userId, args) {
     else {
         itemData.collections = collections ?? [];
     }
-    try {
-        const response = await zoteroApi
-            .library("user", userId)
-            .items()
-            .post([itemData]);
-        if (!response.isSuccess()) {
-            const errors = response.getErrors();
-            const errorMsg = Object.values(errors).join("; ") || "Unknown error";
-            return formatErrorResponse("Failed to create linked URL attachment", {
-                details: errorMsg,
-            });
-        }
-        const created = response.getData();
-        const item = created[0];
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        item_key: item.key,
-                        title: item.title ?? title ?? url,
-                        url,
-                        parent_item: parent_item ?? null,
-                        link_mode: "linked_url",
-                    }, null, 2),
-                },
-            ],
-        };
-    }
-    catch (err) {
-        if (isZoteroApiError(err)) {
-            logger.error("Tool execution failed", {
-                tool: "add_linked_url_attachment",
-                status: err.response?.status,
-                errorMessage: err.message,
-                url: err.response?.url,
-            });
-        }
-        throw err;
+    const response = await zoteroApi
+        .library(libraryType, libraryId)
+        .items()
+        .post([itemData]);
+    if (!response.isSuccess()) {
+        const errorMsg = formatWriteErrors(response.getErrors());
+        return formatErrorResponse("Failed to create linked URL attachment", {
+            details: errorMsg,
+        });
     }
+    const created = response.getData();
+    const item = created[0];
+    return formatJsonResult({
+        item_key: item.key,
+        title: item.title ?? title ?? url,
+        url,
+        parent_item: parent_item ?? null,
+        link_mode: "linked_url",
+    });
 }