@xevos117/mcp-zotero 2.0.3 → 2.1.0

package/build/prompts/index.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+const STYLES = "apa, chicago, harvard, ieee or vancouver";
+export const PROMPTS = [
+    {
+        name: "cite_word_document",
+        title: "Add Zotero citations to a Word document",
+        description: "Turn the <zcite> placeholders in an existing .docx (or .odt) into live Zotero citations and a bibliography.",
+        argsSchema: {
+            file_path: z
+                .string()
+                .describe("Absolute path to the .docx/.odt file on the machine running this server"),
+            style: z
+                .string()
+                .optional()
+                .describe(`Citation style: ${STYLES} (default apa)`),
+        },
+        template: (a) => [
+            `I have a Word document at ${a.file_path} and I want to add Zotero citations to it.`,
+            "",
+            "Please:",
+            "1. Make sure each place a citation should appear contains a <zcite keys=\"ITEMKEY\"/> placeholder in its own text run (keys are Zotero item keys from search_library, add_items or add_items_by_doi). For a numbered style (ieee/vancouver) every <zcite> also needs a num attribute, numbered in order of first appearance.",
+            `2. Call inject_citations with file_path "${a.file_path}" and style "${a.style ?? "apa"}". It fetches the metadata from Zotero and writes a new <name>_cited file next to the original.`,
+            "3. Tell me to open the result in Word with the Zotero plugin and run Zotero → Refresh, so the citations become editable.",
+        ].join("\n"),
+    },
+    {
+        name: "write_cited_document",
+        title: "Write a cited document from scratch",
+        description: "Draft a document on a topic with inline Zotero citations and a bibliography, saved as .docx or .odt.",
+        argsSchema: {
+            topic: z.string().describe("What the document should be about"),
+            output_path: z
+                .string()
+                .describe("Absolute path where the finished document is written"),
+            format: z
+                .string()
+                .optional()
+                .describe("Output format: docx or odt (default docx)"),
+            style: z
+                .string()
+                .optional()
+                .describe(`Citation style: ${STYLES} (default apa)`),
+        },
+        template: (a) => [
+            `Write a well-structured document about "${a.topic}" with Zotero citations, and save it to ${a.output_path} as ${a.format ?? "docx"}.`,
+            "",
+            "Please:",
+            "1. Gather the references in Zotero first: add_items_by_doi for items with a DOI, add_items for the rest, or search_library to reuse items already in the library. Keep track of each item key.",
+            "2. Write the body as Markdown and cite sources inline with pandoc-style keys: [@ITEMKEY] for one source, [@KEY1; @KEY2] for several, [see @ITEMKEY, p. 12] with a locator, and -@ITEMKEY to suppress the author.",
+            `3. Call create_cited_document with that Markdown as the markdown argument, output_path "${a.output_path}", format "${a.format ?? "docx"}" and style "${a.style ?? "apa"}". It resolves the citations against Zotero, numbers them in order of first appearance and appends the bibliography.`,
+            "4. Tell me the citations are live Zotero fields: open the result in Word or LibreOffice with the Zotero plugin and run Refresh to edit them.",
+        ].join("\n"),
+    },
+    {
+        name: "import_references",
+        title: "Import references by DOI",
+        description: "Add one or more references to Zotero from their DOIs, attaching open-access PDFs when available.",
+        argsSchema: {
+            dois: z
+                .string()
+                .describe("The DOIs to import, separated by commas or newlines"),
+        },
+        template: (a) => [
+            `Import these references into Zotero by DOI: ${a.dois}`,
+            "",
+            "Please:",
+            "1. Call find_duplicates once with all these DOIs in a single dois array (strip any surrounding text, keep only the bare DOIs) to see which are already in the library.",
+            "2. Call add_items_by_doi with the DOIs that are not already present. It resolves the metadata automatically and attaches an open-access PDF when one is found.",
+            "3. Call check_retractions with item_keys set to the keys of the items just added, to flag anything retracted or under an expression of concern (if the response has truncated: true, call again with start = next_start).",
+            "4. For any imported item still without a PDF, try find_and_attach_pdfs.",
+            "Report which DOIs were added, which were skipped as already present and which failed, and any retraction warnings; suggest add_items for anything without a usable DOI.",
+        ].join("\n"),
+    },
+    {
+        name: "note_from_item",
+        title: "Summarize an item as a note",
+        description: "Read an existing Zotero item and attach a concise summary as a child note.",
+        argsSchema: {
+            item_key: z.string().describe("The Zotero item key to summarize"),
+        },
+        template: (a) => [
+            `Read the Zotero item ${a.item_key} and attach a short summary note to it.`,
+            "",
+            "Please:",
+            `1. Fetch the item with get_items_details (item_keys ["${a.item_key}"], include_abstract true); if it has a PDF, get_item_fulltext for more detail.`,
+            `2. Write a concise plain-text summary (key points, method, findings) and attach it with create_note (parent_item_key "${a.item_key}"). Use blank lines between paragraphs; no HTML or Markdown.`,
+        ].join("\n"),
+    },
+    {
+        name: "check_bibliography",
+        title: "Check a collection before handing it in",
+        description: "Check a Zotero collection for retracted items and duplicates before using it in a document.",
+        argsSchema: {
+            collection_key: z.string().describe("The Zotero collection key to check (from get_collections)"),
+        },
+        template: (a) => [
+            `Check the Zotero collection ${a.collection_key} before I use it in a bibliography.`,
+            "",
+            "Please:",
+            `1. Call find_duplicates with collection_key "${a.collection_key}" to list duplicate items (same DOI or normalized title). Report each group and suggest which to keep; do not delete anything without asking.`,
+            `2. Call check_retractions with collection_key "${a.collection_key}" to flag any retracted items or expressions of concern (if the response has truncated: true, continue with start = next_start).`,
+            "3. Summarize what you found and what I should fix before handing the bibliography in.",
+        ].join("\n"),
+    },
+];
+/** Register every prompt on the server (call once, before connect, with the prompts capability declared). */
+export function registerAllPrompts(server) {
+    for (const p of PROMPTS) {
+        server.registerPrompt(p.name, { title: p.title, description: p.description, argsSchema: p.argsSchema }, (args) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: { type: "text", text: p.template(args) },
+                },
+            ],
+        }));
+    }
+}
+/** The argument names of a prompt, in manifest order. */
+export function promptArgumentNames(p) {
+    return Object.keys(p.argsSchema);
+}
+/** The prompt text with every argument left as a ${arguments.x} placeholder, as manifest.json stores it. */
+export function promptManifestText(p) {
+    const placeholders = Object.fromEntries(promptArgumentNames(p).map((k) => [k, "${arguments." + k + "}"]));
+    return p.template(placeholders);
+}

package/build/server.js

@@ -5,6 +5,7 @@ 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 { registerAllPrompts } from "./prompts/index.js";
 import { logger } from "./utils/logger.js";
 import { parseUnsafeOperations } from "./utils/unsafe-operations.js";
 import { getDefaultLibrary } from "./utils/library-context.js";
@@ -21,22 +22,27 @@ class ZoteroServer {
     unsafeOps;
     constructor(options = {}) {
         this.server = new McpServer({ name: "zotero", version: SERVER_VERSION }, {
-            capabilities: { tools: {} },
+            capabilities: { tools: {}, prompts: {} },
             instructions: [
                 "Zotero library management and citation injection for Word documents.",
                 "",
                 "CITATION WORKFLOW:",
                 "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. The file must be on the machine where this server runs.",
-                "4. Tell the user to open it in Word with the Zotero plugin → Zotero → Add/Edit Bibliography, then Zotero → Refresh.",
+                "2. Generate the document: create a .docx (Word) or .odt (LibreOffice) with <zcite keys=\"ITEMKEY\"/> placeholders where citations should appear. Each <zcite> must be in its own run.",
+                "3. Call inject_citations with the file path — it fetches metadata from Zotero automatically and picks the format from the extension (.docx or .odt; pass format to override). The file must be on the machine where this server runs.",
+                "4. Tell the user to open it in Word or LibreOffice with the Zotero plugin → Zotero → Add/Edit Bibliography, then Zotero → Refresh.",
+                "",
+                "To write a whole document from scratch (not fill placeholders in an existing one), use create_cited_document: give it Markdown with pandoc-style citations ([@KEY], [@K1; @K2], [see @KEY, p. 12], -@KEY) and an output .docx/.odt path. It never overwrites an existing file.",
                 "",
                 "KEY NOTES:",
                 "- add_items_by_doi auto-attaches open-access PDFs found via Unpaywall (needs UNPAYWALL_EMAIL in the server settings; uses the user's Zotero storage). Do not disable auto_attach_pdf unless it causes errors.",
+                "- find_duplicates is read-only. Call it with dois before add_items_by_doi to skip DOIs already in the library, and without dois to list duplicate groups (same DOI, or same normalized title and year) in the library or a collection. It never merges or deletes; let the user choose which item to keep.",
                 "- For IEEE/Vancouver (numbered) citation styles, every <zcite> MUST include a num attribute. num is the citation number assigned in order of first appearance in the text (first cited = num=\"1\", second = num=\"2\", etc.). For multi-item citations use comma-separated values: keys=\"KEY1,KEY2\" num=\"1,2\". Without num, citations render as [?].",
                 "- If the .docx is in a sandbox or cloud workspace this server cannot see (code execution in Claude.ai or Claude Desktop), use the zotero-mcp-integrations skill instead of inject_citations. If it is not installed, recommend zotero-skill-mcp-integrations.zip from https://github.com/Xevos117/mcp-zotero/releases/latest.",
                 "- get_user_id is only needed by the skill script (inject.js), not by the inject_citations tool.",
-                "- Deleting is off unless the server setting UNSAFE_OPERATIONS (\"Deletions allowed\" in the Claude Desktop extension) allows it ('items': delete_items; 'all': also delete_collection). Never work around a blocked deletion with other tools.",
+                "- To edit an existing item, call get_items_details first (it returns each item's version), then update_item with that version; if it returns version_conflict, re-read and retry. Use create_note to attach a plain-text note to an item.",
+                "- To check whether items have been retracted, flagged with an expression of concern, or corrected, use check_retractions with item_keys (up to 50) or a collection_key: it looks up each DOI on Crossref (read-only) and returns a status per item. Rerun only the items that come back lookup_failed.",
+                "- Deleting is off unless the server setting UNSAFE_OPERATIONS (\"Deletions allowed\" in the Claude Desktop extension) allows it ('items': delete_items; 'all': also delete_collection). delete_items moves items to the Zotero trash by default (recoverable); pass permanent: true to delete for good. delete_collection is always permanent (collections have no trash). Never work around a blocked deletion with other tools.",
                 "- Errors carry a hint with the next step. When it says the fix is on the user's side (API key, server settings), tell the user instead of retrying.",
             ].join("\n"),
         });
@@ -64,6 +70,7 @@ class ZoteroServer {
     }
     setupHandlers() {
         registerAllTools(this.server, this.zoteroApi, this.userId, this.unsafeOps);
+        registerAllPrompts(this.server);
     }
     async start() {
         this.setupHandlers();

package/build/tools/add-items.js

@@ -2,18 +2,11 @@ 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";
+import { ZOTERO_ITEM_TYPES, TITLE_FIELD_NAME, } from "../utils/zotero-item-types.js";
+import { CreatorSchema, fieldValidationIssues, creatorValidationIssues, toZoteroCreator, } from "../utils/item-fields.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
-const CreatorSchema = z
-    .object({
-    firstName: z.string().optional(),
-    lastName: z.string().optional(),
-    name: z.string().optional(),
-    creatorType: z.string().default("author"),
-})
-    .refine((data) => data.name != null || (data.firstName != null && data.lastName != null), {
-    message: "Provide either 'name' (institutional) or both firstName+lastName",
-});
+/** Keys that are not type-specific fields (handled as dedicated inputs), so excluded from field validation. */
+const NON_FIELD_KEYS = new Set(["itemType", "title", "creators"]);
 const ItemSchema = z
     .object({
     itemType: z.enum(ZOTERO_ITEM_TYPES),
@@ -23,27 +16,11 @@ const ItemSchema = z
     .catchall(z.string())
     .superRefine((data, ctx) => {
     const itemType = data.itemType;
-    const validFields = ITEM_TYPE_FIELDS[itemType];
-    for (const key of Object.keys(data)) {
-        if (key === "itemType" || key === "title" || key === "creators")
-            continue;
-        if (!validFields.has(key)) {
-            ctx.addIssue({
-                code: "custom",
-                message: `Field "${key}" is not valid for itemType "${data.itemType}". Valid fields: ${[...validFields].join(", ")}`,
-                path: [key],
-            });
-        }
+    for (const issue of fieldValidationIssues(itemType, Object.keys(data), NON_FIELD_KEYS)) {
+        ctx.addIssue({ code: "custom", message: issue.message, path: issue.path });
     }
-    const validCreatorTypes = ITEM_TYPE_CREATOR_TYPES[itemType];
-    for (const [i, creator] of (data.creators ?? []).entries()) {
-        if (!validCreatorTypes.has(creator.creatorType)) {
-            ctx.addIssue({
-                code: "custom",
-                message: `Invalid creatorType "${creator.creatorType}" for "${data.itemType}". Valid: ${[...validCreatorTypes].join(", ")}`,
-                path: ["creators", i, "creatorType"],
-            });
-        }
+    for (const issue of creatorValidationIssues(itemType, data.creators ?? [])) {
+        ctx.addIssue({ code: "custom", message: issue.message, path: issue.path });
     }
 });
 export const toolConfig = {
@@ -103,16 +80,7 @@ export async function handleAddItems(zoteroApi, userId, args) {
             itemType,
             ...fields,
             [titleFieldName]: title,
-            creators: (creators ?? []).map((c) => {
-                if (c.name) {
-                    return { name: c.name, creatorType: c.creatorType };
-                }
-                return {
-                    firstName: c.firstName,
-                    lastName: c.lastName,
-                    creatorType: c.creatorType,
-                };
-            }),
+            creators: (creators ?? []).map(toZoteroCreator),
             collections: collection_key ? [collection_key] : [],
             tags: (tags ?? []).map((t) => ({ tag: t })),
         };

package/build/tools/check-retractions.js

@@ -0,0 +1,131 @@
+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 { fetchItemsByKeys, fetchAllPages } from "../utils/pagination.js";
+import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { mapWithConcurrency } from "../utils/concurrency.js";
+import { itemDoi } from "../utils/doi.js";
+import { lookupRetraction } from "../utils/crossref-retractions.js";
+import { isValidEmail } from "../utils/unpaywall.js";
+import { COLLECTION_KEY_HINT, ITEM_KEY_HINT } from "../utils/error-hints.js";
+const MAX_ITEM_KEYS = 50;
+// Cap the Crossref lookups per call by the number of distinct DOIs; the rest is left for a follow-up call (start)
+const MAX_LOOKUPS = 200;
+export const toolConfig = {
+    name: "check_retractions",
+    description: "Check whether Zotero items have been retracted, flagged with an expression of concern, or corrected. Pass EITHER item_keys (up to 50) OR collection_key, exactly one. Read-only: it never changes the library. For each item it reads the DOI (the DOI field, or a 'DOI: …' line in Extra) and looks it up on Crossref (Retraction Watch data), then reports a status: retracted, expression_of_concern, corrected, ok, no_doi (no DOI to check), not_in_crossref (the DOI is unknown to Crossref), or lookup_failed (a transient error — rerun just those). The response opens with a summary of the counts and then lists, per item, its key, title, doi, status and any notices (type, date, source, the notice's own DOI). A failed lookup never fails the rest; rerun the lookup_failed items. At most 200 distinct DOIs are looked up per call: if the response has truncated=true, call again with start=next_start to continue (useful for a large collection).",
+    inputSchema: {
+        item_keys: z
+            .array(zoteroKey())
+            .max(MAX_ITEM_KEYS, `At most ${MAX_ITEM_KEYS} item keys per call`)
+            .optional()
+            .describe('Zotero item keys to check (up to 50), e.g. ["EUHUT5K3", "F9UQM7N2"]. Provide this OR collection_key, not both. Get keys from search_library or get_collection_items.'),
+        collection_key: zoteroKey()
+            .optional()
+            .describe("Check every item directly in this collection (not its subcollections). Provide this OR item_keys, not both. Get the key from get_collections."),
+        start: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .default(0)
+            .describe("Item offset to start from (default 0). Only needed to continue a truncated response: pass the next_start it returned."),
+        ...libraryArgsSchema,
+    },
+};
+const CheckRetractionsSchema = z.object(toolConfig.inputSchema);
+export async function handleCheckRetractions(zoteroApi, userId, args) {
+    const { item_keys, collection_key, start, library_type, library_id } = CheckRetractionsSchema.parse(args);
+    const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
+    const hasKeys = item_keys !== undefined && item_keys.length > 0;
+    const hasCollection = collection_key !== undefined;
+    if (hasKeys === hasCollection) {
+        return formatErrorResponse("Pass exactly one of item_keys or collection_key.", {
+            hint: "item_keys (up to 50) checks those items; collection_key checks every item directly in a collection.",
+        });
+    }
+    let items;
+    let notFound = [];
+    if (hasKeys) {
+        const res = await fetchItemsByKeys((params) => zoteroApi.library(libraryType, libraryId).items().get(params), item_keys);
+        items = res.items.filter((i) => typeof i.key === "string");
+        const found = new Set(items.map((i) => i.key));
+        notFound = [...new Set(item_keys)].filter((k) => !found.has(k));
+        if (items.length === 0) {
+            return formatEmptyResult("No items found for the given keys", { item_keys, suggestion: ITEM_KEY_HINT });
+        }
+    }
+    else {
+        try {
+            const { items: all } = await fetchAllPages((params) => zoteroApi.library(libraryType, libraryId).collections(collection_key).items().get(params));
+            items = (all ?? []).filter((i) => i && typeof i.key === "string" && i.itemType !== "attachment" && i.itemType !== "note");
+        }
+        catch (err) {
+            if (isZoteroApiError(err) && err.response?.status === 404) {
+                return formatErrorResponse("Collection not found: no collection with this key in this library, or the API key cannot access it.", { collection_key, suggestion: COLLECTION_KEY_HINT });
+            }
+            throw err;
+        }
+        if (items.length === 0) {
+            return formatEmptyResult("No items to check in this collection", {
+                collection_key,
+                suggestion: "The collection is empty or holds only attachments and notes (those are not checked).",
+            });
+        }
+    }
+    // Crossref's polite pool: reuse the server's contact email only if it is a valid address (as unpaywall.ts checks);
+    // optional, Crossref works without it.
+    const email = process.env.UNPAYWALL_EMAIL?.trim();
+    const mailto = email && isValidEmail(email) ? email : undefined;
+    const prepared = items.map((item) => ({
+        key: item.key,
+        title: item.title || "Untitled",
+        doi: itemDoi(item) ?? null,
+    }));
+    // Cap the lookups per call by the number of DISTINCT DOIs (MAX_LOOKUPS): a large collection would otherwise make
+    // thousands of Crossref requests and the MCP client could time out and lose everything. `start` is the item
+    // offset; when the page fills the budget the rest is left for a follow-up call (truncated + next_start).
+    const page = prepared.slice(start);
+    const pageItems = [];
+    const uniqueDois = new Set();
+    let truncated = false;
+    let nextStart;
+    for (let i = 0; i < page.length; i++) {
+        const p = page[i];
+        if (p.doi && !uniqueDois.has(p.doi)) {
+            if (uniqueDois.size >= MAX_LOOKUPS) {
+                truncated = true;
+                nextStart = start + i;
+                break;
+            }
+            uniqueDois.add(p.doi);
+        }
+        pageItems.push(p);
+    }
+    // One lookup per distinct DOI (deduplicated), then remapped to every item that carries it
+    const dois = [...uniqueDois];
+    const settled = await mapWithConcurrency(dois, (doi) => lookupRetraction(doi, mailto));
+    const byDoi = new Map();
+    dois.forEach((doi, i) => {
+        const r = settled[i];
+        byDoi.set(doi, r.status === "fulfilled" ? r.value : { status: "lookup_failed", notices: [] });
+    });
+    const results = pageItems.map((p) => {
+        if (!p.doi)
+            return { key: p.key, title: p.title, doi: null, status: "no_doi", notices: [] };
+        const l = byDoi.get(p.doi) ?? { status: "lookup_failed", notices: [] };
+        return { key: p.key, title: p.title, doi: p.doi, status: l.status, notices: l.notices };
+    });
+    const summary = { checked: results.length };
+    for (const r of results)
+        summary[r.status] = (summary[r.status] ?? 0) + 1;
+    const flagged = results.filter((r) => r.status === "retracted" || r.status === "expression_of_concern");
+    return formatJsonResult({
+        summary,
+        flagged_count: flagged.length,
+        ...(truncated ? { truncated: true, next_start: nextStart } : {}),
+        ...(notFound.length ? { not_found: notFound } : {}),
+        items: results,
+    });
+}

package/build/tools/create-cited-document.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { isAbsolute } from "node:path";
+import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
+import { createCitedDocument } from "../cited-document/create.js";
+import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+export const toolConfig = {
+    name: "create_cited_document",
+    description: `Create a Word (.docx) or LibreOffice (.odt) document from Markdown with native Zotero citations and a bibliography, ready for the Zotero plugin's Refresh. Unlike inject_citations (which fills <zcite> placeholders in an existing file), this writes a new document from Markdown text.
+
+WORKFLOW:
+1. Collect item keys with add_items_by_doi, add_items or search_library.
+2. Write the body as Markdown, with pandoc-style citations where they belong.
+3. Call this tool with the Markdown and an output path. It fetches metadata from Zotero, renders the document and appends the bibliography. It never overwrites an existing file.
+4. Tell the user to open it in Word or LibreOffice with the Zotero plugin → Add/Edit Bibliography, then Refresh.
+
+MARKDOWN SUBSET: headings (#…), paragraphs, bold (**…**), italic (*…*), one-level bullet lists (-). Anything else is kept as text, with a warning.
+
+CITATIONS (pandoc style): [@KEY] one item; [@KEY1; @KEY2] several; [see @KEY, p. 12] with prefix and locator; -@KEY to suppress the author. KEY is a Zotero item key. For IEEE/Vancouver the numbers follow the order of first citation automatically.
+
+OUTPUT: a new .docx or .odt (format from the extension, or the format argument). A cited key that is not in the library, or is not a Zotero key, is an error and nothing is written. If the output file already exists it is an error (never overwritten).`,
+    inputSchema: {
+        markdown: z.string().describe("The document body as Markdown, with pandoc-style citations like [@ITEMKEY]."),
+        output_path: z
+            .string()
+            .describe("Absolute path of the .docx or .odt file to create. Must not already exist."),
+        style: z
+            .enum(["apa", "ieee", "vancouver", "harvard", "chicago"])
+            .optional()
+            .default("apa")
+            .describe("Citation style for the visible placeholder text. Zotero reformats on refresh. Default: apa"),
+        format: z
+            .enum(["docx", "odt"])
+            .optional()
+            .describe("docx for Word, odt for LibreOffice. Defaults to the output extension; an error if it disagrees."),
+        ...libraryArgsSchema,
+    },
+};
+const Schema = z.object(toolConfig.inputSchema);
+export async function handleCreateCitedDocument(zoteroApi, userId, args) {
+    const { markdown, output_path, style, format, library_type, library_id } = Schema.parse(args);
+    const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
+    if (!isAbsolute(output_path)) {
+        return formatErrorResponse("output_path must be an absolute path", {
+            output_path,
+            hint: "Pass an absolute path (e.g. the user's Documents folder), as the tool description requires.",
+        });
+    }
+    const extFormat = output_path.endsWith(".docx") ? "docx" : output_path.endsWith(".odt") ? "odt" : undefined;
+    if (!extFormat) {
+        return formatErrorResponse("Output must be a .docx (Word) or .odt (LibreOffice) file", {
+            output_path,
+            hint: "The output name must end in lowercase .docx or .odt.",
+        });
+    }
+    if (format && format !== extFormat) {
+        return formatErrorResponse(`format '${format}' does not match the output extension of ${output_path}`, {
+            output_path,
+            hint: `The file ends in .${extFormat}: pass format "${extFormat}" or omit it.`,
+        });
+    }
+    let result;
+    try {
+        result = await createCitedDocument(markdown, output_path, zoteroApi, libraryType, libraryId, style, format ?? extFormat);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EEXIST") {
+            return formatErrorResponse("The output file already exists; it was not overwritten.", {
+                output_path,
+                hint: "Choose a different output_path, or delete/rename the existing file and call again.",
+            });
+        }
+        if (code === "EBUSY") {
+            return formatErrorResponse("Cannot write the document: the output file is locked (EBUSY).", {
+                output_path,
+                hint: "Close the file if it is open in Word or LibreOffice and call again.",
+            });
+        }
+        if (code === "ENOENT") {
+            return formatErrorResponse("Cannot write the document: the output folder does not exist.", {
+                output_path,
+                hint: "Create the folder or pass an output_path in an existing folder.",
+            });
+        }
+        if (code === "EACCES" || code === "EPERM" || code === "EROFS") {
+            return formatErrorResponse(`Cannot write the document (${code}).`, {
+                output_path,
+                hint: "Pass an output_path in a folder this server can write to.",
+            });
+        }
+        throw err;
+    }
+    const responseObj = {
+        output_path: result.outputPath,
+        blocks: result.blocks,
+        citations: result.citations,
+    };
+    if (result.warnings.length > 0)
+        responseObj.warnings = result.warnings;
+    return formatJsonResult(responseObj);
+}

package/build/tools/create-note.js

@@ -0,0 +1,77 @@
+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 { formatWriteErrors } from "../utils/write-results.js";
+import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { escapeXml } from "../citation-injector/xml-utils.js";
+import { ITEM_KEY_HINT } from "../utils/error-hints.js";
+export const toolConfig = {
+    name: "create_note",
+    description: "Add a child note to an existing Zotero item. Provide the note as PLAIN TEXT (no HTML or Markdown): blank lines become separate paragraphs and single line breaks are preserved. The parent must be a regular item (not a note or attachment). Use this to attach a summary, annotation, or reading note to a reference. For top-level, item-wide editing of fields use update_item; to add references use add_items or add_items_by_doi.",
+    inputSchema: {
+        parent_item_key: zoteroKey().describe("Key of the regular item the note is attached to (from search_library, get_items_details, get_collection_items or an add_* tool). It must not be a note or an attachment."),
+        note: z
+            .string()
+            .min(1)
+            .describe("The note text, PLAIN TEXT only (no HTML/Markdown). Blank lines separate paragraphs; single newlines are kept as line breaks."),
+        tags: z
+            .array(z.string())
+            .optional()
+            .describe("Tags to apply to the note"),
+        ...libraryArgsSchema,
+    },
+};
+const CreateNoteSchema = z.object(toolConfig.inputSchema);
+/**
+ * Plain text → the minimal HTML Zotero stores in a note: one <p> per paragraph (blocks separated by a
+ * blank line), single newlines as <br/>. Everything is XML-escaped first, so user text can never inject markup.
+ */
+export function noteTextToHtml(text) {
+    return text
+        .split(/\n[ \t]*\n/)
+        .map((para) => `<p>${escapeXml(para).replace(/\n/g, "<br/>")}</p>`)
+        .join("");
+}
+export async function handleCreateNote(zoteroApi, userId, args) {
+    const { parent_item_key, note, tags, library_type, library_id } = CreateNoteSchema.parse(args);
+    const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
+    // Fetch the parent first: a note can only hang off a regular item.
+    let parent;
+    try {
+        const resp = await zoteroApi.library(libraryType, libraryId).items(parent_item_key).get();
+        parent = resp.getData();
+    }
+    catch (err) {
+        if (isZoteroApiError(err) && err.response.status === 404) {
+            return formatErrorResponse(`Parent item ${parent_item_key} not found`, {
+                hint: ITEM_KEY_HINT,
+            });
+        }
+        throw err;
+    }
+    if (parent.itemType === "note" || parent.itemType === "attachment") {
+        const article = /^[aeiou]/i.test(parent.itemType) ? "an" : "a";
+        return formatErrorResponse(`Parent item ${parent_item_key} is ${article} ${parent.itemType}; a note can only be attached to a regular item`, { hint: ITEM_KEY_HINT });
+    }
+    const payload = {
+        itemType: "note",
+        parentItem: parent_item_key,
+        note: noteTextToHtml(note),
+        tags: (tags ?? []).map((t) => ({ tag: t })),
+        collections: [],
+    };
+    const response = await zoteroApi.library(libraryType, libraryId).items().post([payload]);
+    if (!response.isSuccess()) {
+        const errorMsg = formatWriteErrors(response.getErrors());
+        return formatErrorResponse("Failed to create note", {
+            details: errorMsg,
+            hint: `details has Zotero's reason. parent_item_key must be an existing regular item: ${ITEM_KEY_HINT}`,
+        });
+    }
+    const created = response.getData();
+    return formatJsonResult({
+        item_key: created[0].key,
+        parent_item_key,
+    });
+}

package/build/tools/delete-collection.js

@@ -4,10 +4,10 @@ import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { canDeleteCollections } from "../utils/unsafe-operations.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
-import { COLLECTION_KEY_HINT, unsafeOperationsHint } from "../utils/error-hints.js";
+import { COLLECTION_KEY_HINT, unsafeOperationsHint, zoteroStatusHint } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "delete_collection",
-    description: "Delete a collection (folder) from your Zotero library; confirm with the user first. Items inside the collection are NOT deleted — they remain in your library. Disabled unless the server setting UNSAFE_OPERATIONS is 'all'.",
+    description: "Permanently delete a collection (folder) from your Zotero library; confirm with the user first. Unlike delete_items, this cannot be undone: the Zotero Web API has no trash for collections, so a deleted collection is not recoverable. Items inside the collection are NOT deleted — they remain in your library. Disabled unless the server setting UNSAFE_OPERATIONS is 'all'.",
     inputSchema: {
         collection_key: zoteroKey()
             .describe("Zotero collection key to delete. Get this from get_collections."),
@@ -27,28 +27,38 @@ export async function handleDeleteCollection(zoteroApi, userId, args, unsafeOps
         });
     }
     try {
-        const response = await zoteroApi
-            .library(libraryType, libraryId)
-            .collections(collection_key)
-            .get();
-        const collection = response.getData();
-        const version = response.getVersion();
-        if (version === null) {
-            return formatErrorResponse("Could not determine collection version", {
+        for (let attempt = 1;; attempt++) {
+            const response = await zoteroApi
+                .library(libraryType, libraryId)
+                .collections(collection_key)
+                .get();
+            const collection = response.getData();
+            const version = response.getVersion();
+            if (version === null) {
+                return formatErrorResponse("Could not determine collection version", {
+                    collection_key,
+                    hint: "Nothing was deleted. Retry the same call once.",
+                });
+            }
+            try {
+                await zoteroApi
+                    .library(libraryType, libraryId)
+                    .collections(collection_key)
+                    .version(version)
+                    .delete();
+            }
+            catch (err) {
+                // 412: the collection changed between the GET and the DELETE; read it again and retry once
+                if (attempt === 1 && isZoteroApiError(err) && err.response.status === 412)
+                    continue;
+                throw err;
+            }
+            return formatJsonResult({
+                deleted: true,
                 collection_key,
-                hint: "Nothing was deleted. Retry the same call once.",
+                name: collection.name || collection_key,
             });
         }
-        await zoteroApi
-            .library(libraryType, libraryId)
-            .collections(collection_key)
-            .version(version)
-            .delete();
-        return formatJsonResult({
-            deleted: true,
-            collection_key,
-            name: collection.name || collection_key,
-        });
     }
     catch (err) {
         if (isZoteroApiError(err)) {
@@ -60,9 +70,12 @@ export async function handleDeleteCollection(zoteroApi, userId, args, unsafeOps
                 });
             }
             if (err.response.status === 412) {
-                return formatErrorResponse("Collection was modified by another client, so it was not deleted. Retry the same call.", {
+                const { hint } = zoteroStatusHint(412);
+                return formatErrorResponse("Collection was modified by another client (HTTP 412 Precondition Failed), also on a second try with its new version, so it was not deleted.", {
                     collection_key,
                     status: "version_conflict",
+                    http_status: 412,
+                    hint,
                 });
             }
         }