@xevos117/mcp-zotero 1.0.3 → 1.0.5

package/LICENSE

@@ -1,24 +1,24 @@
-MIT License
-
-Copyright (c) 2025 Xevos117
-
-Based on mcp-zotero by Abhishek Kalia (https://github.com/kaliaboi/mcp-zotero),
-Copyright (c) 2024 Abhishek Kalia, licensed under the MIT License.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Xevos117
+
+Based on mcp-zotero by Abhishek Kalia (https://github.com/kaliaboi/mcp-zotero),
+Copyright (c) 2024 Abhishek Kalia, licensed under the MIT License.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,127 +1,127 @@
-# MCP Zotero
-
-> **Note:** This is an unofficial community project and is not affiliated with, endorsed by, or supported by the Zotero team or the Corporation for Digital Scholarship. "Zotero" is a registered trademark of the Corporation for Digital Scholarship.
-
-A Model Context Protocol server for Zotero integration. It gives any LLM full access to your Zotero library: search, organize, add papers by DOI, import PDFs, read full-text content, and inject live citations into Word documents.
-
-> Originally based on [mcp-zotero](https://github.com/kaliaboi/mcp-zotero) by Abhishek Kalia.
-> This project has since been extensively rewritten with a new architecture, 13 tools (up from 5), citation injection, PDF management, and Claude skill support.
-
-## How it works
-
-The server is designed to be **usable by any LLM without external documentation**. On connection, it sends workflow instructions via the MCP `instructions` field, and each tool description includes cross-references and usage guidance. An LLM that has never seen this server before can discover the full workflow — from adding papers to producing a cited Word document — directly from the tool listing.
-
-For advanced use cases (PDF upload policy, citation style guidance, source transparency), a **Claude skill** is included for Claude.ai Projects. But the skill is optional: the MCP server is fully self-documenting.
-
-## Local vs Remote LLMs
-
-| Scenario | MCP server | Skill needed? |
-|---|---|---|
-| Local LLM (Claude Code, LM Studio, etc.) | All 13 tools | No |
-| Remote/sandboxed LLM (Claude.ai Projects) | API tools (search, add, metadata) | Yes, for citation injection |
-
-Local LLMs with filesystem access can use all tools directly, including `inject_citations` which reads and writes `.docx` files on disk.
-
-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.
-
-## Setup
-
-1. Get your Zotero credentials:
-
-   ```bash
-   # Create an API key at https://www.zotero.org/settings/keys
-   # (enable library read/write + file access)
-   # Then retrieve your user ID:
-   curl -H "Zotero-API-Key: YOUR_API_KEY" https://api.zotero.org/keys/current
-   ```
-
-2. Set environment variables:
-
-   ```bash
-   export ZOTERO_API_KEY="your-api-key"
-   export ZOTERO_USER_ID="user-id-from-curl"
-   export UNPAYWALL_EMAIL="your@email.edu"   # Optional: enables OA PDF lookup via Unpaywall
-   ```
-
-## Environment Variables
-
-| Variable | Required | Description |
-|---|---|---|
-| `ZOTERO_API_KEY` | Yes | API key for Zotero Web API v3. Create one at [zotero.org/settings/keys](https://www.zotero.org/settings/keys) with library read/write and file access permissions. |
-| `ZOTERO_USER_ID` | Yes | Your Zotero numeric user ID. Retrieve it with `curl -H "Zotero-API-Key: KEY" https://api.zotero.org/keys/current`. |
-| `UNPAYWALL_EMAIL` | No | Email for Unpaywall API requests ([rate-limit policy](https://unpaywall.org/products/api)). Enables OA PDF lookup in `add_items_by_doi` and `find_and_attach_pdfs`. If not set, OA PDF features are silently skipped. |
-
-## Integration with Claude Desktop
-
-Add to your Claude Desktop configuration:
-
-```json
-{
-  "mcpServers": {
-    "zotero": {
-      "command": "npx",
-      "args": ["-y", "@xevos117/mcp-zotero"],
-      "env": {
-        "ZOTERO_API_KEY": "YOUR_API_KEY",
-        "ZOTERO_USER_ID": "YOUR_USER_ID",
-        "UNPAYWALL_EMAIL": "YOUR_EMAIL"
-      }
-    }
-  }
-}
-```
-
-## Integration with Claude Code
-
-```bash
-claude mcp add-json "zotero" '{"command":"npx","args":["tsx","src/server.ts"],"env":{"ZOTERO_API_KEY":"...","ZOTERO_USER_ID":"..."}}'
-```
-
-## Available Tools
-
-### Library browsing
-
-| Tool | Description |
-|---|---|
-| `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_item_fulltext` | Get full-text content of a PDF attachment via Zotero's fulltext index |
-
-### Adding content
-
-| Tool | Description |
-|---|---|
-| `add_items_by_doi` | Add papers by DOI with automatic metadata resolution. Auto-attaches OA PDFs via Unpaywall |
-| `add_web_item` | Save a web page as a Zotero item (for articles without DOI) |
-| `create_collection` | Create a new collection, optionally nested under a parent |
-| `import_pdf_to_zotero` | Download a PDF from URL, upload to Zotero storage, auto-index full text |
-| `find_and_attach_pdfs` | Batch OA PDF lookup and auto-attach via Unpaywall (by item keys or collection) |
-| `add_linked_url_attachment` | Attach a URL to an existing item or create a standalone link |
-
-### Citation & documents
-
-| Tool | Description |
-|---|---|
-| `inject_citations` | Inject live Zotero citations into a Word document. Supports APA, IEEE, Vancouver, Harvard, Chicago |
-| `get_user_id` | Returns the configured Zotero user ID |
-
-## Development
-
-```bash
-npm install
-npm run build          # Compile TypeScript
-npm test               # Run tests (vitest, 299 tests)
-npx tsx src/server.ts  # Run directly without building
-```
-
-### Debug with MCP Inspector
-
-```bash
-npx @modelcontextprotocol/inspector npx tsx src/server.ts
-```
-
-## License
-
-MIT - see [LICENSE](LICENSE) for details.
+# MCP Zotero
+
+> **Note:** This is an unofficial community project and is not affiliated with, endorsed by, or supported by the Zotero team or the Corporation for Digital Scholarship. "Zotero" is a registered trademark of the Corporation for Digital Scholarship.
+
+A Model Context Protocol server for Zotero integration. It gives any LLM full access to your Zotero library: search, organize, add papers by DOI, import PDFs, read full-text content, and inject live citations into Word documents.
+
+> Originally based on [mcp-zotero](https://github.com/kaliaboi/mcp-zotero) by Abhishek Kalia.
+> This project has since been extensively rewritten with a new architecture, 13 tools (up from 5), citation injection, PDF management, and Claude skill support.
+
+## How it works
+
+The server is designed to be **usable by any LLM without external documentation**. On connection, it sends workflow instructions via the MCP `instructions` field, and each tool description includes cross-references and usage guidance. An LLM that has never seen this server before can discover the full workflow — from adding papers to producing a cited Word document — directly from the tool listing.
+
+For advanced use cases (PDF upload policy, citation style guidance, source transparency), a **Claude skill** is included for Claude.ai Projects. But the skill is optional: the MCP server is fully self-documenting.
+
+## Local vs Remote LLMs
+
+| Scenario | MCP server | Skill needed? |
+|---|---|---|
+| Local LLM (Claude Code, LM Studio, etc.) | All 13 tools | No |
+| Remote/sandboxed LLM (Claude.ai Projects) | API tools (search, add, metadata) | Yes, for citation injection |
+
+Local LLMs with filesystem access can use all tools directly, including `inject_citations` which reads and writes `.docx` files on disk.
+
+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.
+
+## Setup
+
+1. Get your Zotero credentials:
+
+   ```bash
+   # Create an API key at https://www.zotero.org/settings/keys
+   # (enable library read/write + file access)
+   # Then retrieve your user ID:
+   curl -H "Zotero-API-Key: YOUR_API_KEY" https://api.zotero.org/keys/current
+   ```
+
+2. Set environment variables:
+
+   ```bash
+   export ZOTERO_API_KEY="your-api-key"
+   export ZOTERO_USER_ID="user-id-from-curl"
+   export UNPAYWALL_EMAIL="your@email.edu"   # Optional: enables OA PDF lookup via Unpaywall
+   ```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `ZOTERO_API_KEY` | Yes | API key for Zotero Web API v3. Create one at [zotero.org/settings/keys](https://www.zotero.org/settings/keys) with library read/write and file access permissions. |
+| `ZOTERO_USER_ID` | Yes | Your Zotero numeric user ID. Retrieve it with `curl -H "Zotero-API-Key: KEY" https://api.zotero.org/keys/current`. |
+| `UNPAYWALL_EMAIL` | No | Email for Unpaywall API requests ([rate-limit policy](https://unpaywall.org/products/api)). Enables OA PDF lookup in `add_items_by_doi` and `find_and_attach_pdfs`. If not set, OA PDF features are silently skipped. |
+
+## Integration with Claude Desktop
+
+Add to your Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "zotero": {
+      "command": "npx",
+      "args": ["-y", "@xevos117/mcp-zotero"],
+      "env": {
+        "ZOTERO_API_KEY": "YOUR_API_KEY",
+        "ZOTERO_USER_ID": "YOUR_USER_ID",
+        "UNPAYWALL_EMAIL": "YOUR_EMAIL"
+      }
+    }
+  }
+}
+```
+
+## Integration with Claude Code
+
+```bash
+claude mcp add-json "zotero" '{"command":"npx","args":["tsx","src/server.ts"],"env":{"ZOTERO_API_KEY":"...","ZOTERO_USER_ID":"..."}}'
+```
+
+## Available Tools
+
+### Library browsing
+
+| Tool | Description |
+|---|---|
+| `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_item_fulltext` | Get full-text content of a PDF attachment via Zotero's fulltext index |
+
+### Adding content
+
+| Tool | Description |
+|---|---|
+| `add_items_by_doi` | Add papers by DOI with automatic metadata resolution. Auto-attaches OA PDFs via Unpaywall |
+| `add_items` | Add items with direct metadata — supports all 37 Zotero item types (books, theses, reports, etc.), batch-capable |
+| `create_collection` | Create a new collection, optionally nested under a parent |
+| `import_pdf_to_zotero` | Download a PDF from URL, upload to Zotero storage, auto-index full text |
+| `find_and_attach_pdfs` | Batch OA PDF lookup and auto-attach via Unpaywall (by item keys or collection) |
+| `add_linked_url_attachment` | Attach a URL to an existing item or create a standalone link |
+
+### Citation & documents
+
+| Tool | Description |
+|---|---|
+| `inject_citations` | Inject live Zotero citations into a Word document. Supports APA, IEEE, Vancouver, Harvard, Chicago. Output is saved in the same folder as the input file with a `_cited` suffix (e.g. `paper.docx` → `paper_cited.docx`) |
+| `get_user_id` | Returns the configured Zotero user ID |
+
+## Development
+
+```bash
+npm install
+npm run build          # Compile TypeScript
+npm test               # Run tests (vitest, 328 tests)
+npx tsx src/server.ts  # Run directly without building
+```
+
+### Debug with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector npx tsx src/server.ts
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details.

package/build/server.js

@@ -19,7 +19,7 @@ class ZoteroServer {
                 "Zotero library management and citation injection for Word documents.",
                 "",
                 "CITATION WORKFLOW:",
-                "1. Collect item keys: use add_items_by_doi (or search_library for existing items)",
+                "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.",

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

@@ -9,10 +9,15 @@ import { downloadAndUploadPdf } from "../utils/pdf-uploader.js";
 import { mapWithConcurrency } from "../utils/concurrency.js";
 export const toolConfig = {
     name: "add_items_by_doi",
-    description: `Add papers to your Zotero library by resolving DOIs. For each DOI, resolves metadata via content negotiation and creates the item in Zotero. Returns a list of successfully added items (with item_key and title) and any failures.
-
-WORKFLOW TIPS:
-- To collect metadata for all added items, call get_items_details with the returned item_keys (single batch call).
+    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.
+
+WHEN TO USE vs add_items:
+- Use add_items_by_doi when the item HAS a DOI — it auto-resolves all metadata and attaches OA PDFs.
+- Use add_items when the item does NOT have a DOI, or when you need to override specific metadata fields (add_items_by_doi does not allow metadata overrides).
+- Mixed batch: if some items have DOIs and others don't, make two separate calls — add_items_by_doi for the DOIs and add_items for the rest.
+
+WORKFLOW TIPS:
+- To collect metadata for all added items, call get_items_details with the returned item_keys (single batch call).
 - To create a cited Word document, use the returned item_keys as <zcite keys="ITEMKEY"/> placeholders in a .docx, then call inject_citations. See inject_citations description for the full workflow.`,
     inputSchema: {
         dois: z

package/build/tools/add-items.js

@@ -0,0 +1,174 @@
+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 { ZOTERO_ITEM_TYPES, ITEM_TYPE_FIELDS, ITEM_TYPE_CREATOR_TYPES, TITLE_FIELD_NAME, } from "../utils/zotero-item-types.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",
+});
+const ItemSchema = z
+    .object({
+    itemType: z.enum(ZOTERO_ITEM_TYPES),
+    title: z.string(),
+    creators: z.array(CreatorSchema).optional(),
+})
+    .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: z.ZodIssueCode.custom,
+                message: `Field "${key}" is not valid for itemType "${data.itemType}". Valid fields: ${[...validFields].join(", ")}`,
+                path: [key],
+            });
+        }
+    }
+    const validCreatorTypes = ITEM_TYPE_CREATOR_TYPES[itemType];
+    for (const [i, creator] of (data.creators ?? []).entries()) {
+        if (!validCreatorTypes.has(creator.creatorType)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Invalid creatorType "${creator.creatorType}" for "${data.itemType}". Valid: ${[...validCreatorTypes].join(", ")}`,
+                path: ["creators", i, "creatorType"],
+            });
+        }
+    }
+});
+export const toolConfig = {
+    name: "add_items",
+    description: `Add items to Zotero by providing metadata directly. Supports ALL 37 Zotero item types.
+
+WHEN TO USE:
+- For items that do not have a DOI (books, theses, reports, etc.)
+- When you need full control over metadata (e.g., override a title, set a specific itemType, add custom fields) — even if a DOI exists, use add_items when the auto-resolved metadata would be incorrect or incomplete
+- Mixed batch: if some items have DOIs and others don't, call add_items_by_doi for the DOIs and add_items for the rest (two separate calls)
+- Prefer add_items_by_doi when DOIs are available AND you don't need to override metadata (it auto-resolves everything and attaches OA PDFs)
+
+BATCH: Pass multiple items in the 'items' array (single API call).
+
+COMMON FIELDS (available for most types):
+title, date, abstractNote, url, DOI, publisher, place, pages, volume, language, extra
+
+ITEM TYPE QUICK REFERENCE:
+- journalArticle: publicationTitle, volume, issue, pages, DOI, ISSN
+- book: publisher, ISBN, edition, numPages, series, seriesNumber
+- bookSection: bookTitle, publisher, pages, ISBN, edition
+- conferencePaper: proceedingsTitle, conferenceName, publisher, DOI
+- thesis: thesisType ("PhD thesis"|"Master's thesis"), university
+- report: reportType, reportNumber, institution
+- webpage: websiteTitle, websiteType, accessDate
+- preprint: repository, archiveID, genre ("Preprint")
+- patent: patentNumber, assignee, issuingAuthority, filingDate
+- computerProgram: versionNumber, company, system, programmingLanguage
+
+CREATORS: Array of {firstName, lastName, creatorType} or {name, creatorType} for institutional.
+Default creatorType is "author". Some types use different primary types (e.g., "director" for film, "inventor" for patent, "artist" for artwork).
+
+Invalid fields or creatorTypes for a given type are rejected with helpful error messages listing the valid options.`,
+    inputSchema: {
+        items: z
+            .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()
+            .optional()
+            .describe("Zotero collection key to add all items to. Get this from create_collection or get_collections."),
+        tags: z
+            .array(z.string())
+            .optional()
+            .describe("Tags to apply to all items"),
+    },
+};
+const AddItemsSchema = z.object(toolConfig.inputSchema);
+export async function handleAddItems(zoteroApi, userId, args) {
+    const { items, collection_key, tags } = AddItemsSchema.parse(args);
+    const payloads = items.map((item) => {
+        const { itemType, title, creators, ...fields } = item;
+        const titleFieldName = TITLE_FIELD_NAME[itemType] ?? "title";
+        const payload = {
+            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,
+                };
+            }),
+            collections: collection_key ? [collection_key] : [],
+            tags: (tags ?? []).map((t) => ({ tag: t })),
+        };
+        if (fields.url && !fields.accessDate) {
+            payload.accessDate = new Date().toISOString().split("T")[0];
+        }
+        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;
+    }
+}

package/build/tools/index.js

@@ -8,7 +8,7 @@ import { handleInjectCitations, toolConfig as injectCitationsConfig } from "./in
 import { handleGetItemFulltext, toolConfig as getItemFulltextConfig } from "./get-item-fulltext.js";
 import { handleGetUserId, toolConfig as getUserIdConfig } from "./get-user-id.js";
 import { handleAddLinkedUrlAttachment, toolConfig as addLinkedUrlAttachmentConfig } from "./add-linked-url-attachment.js";
-import { handleAddWebItem, toolConfig as addWebItemConfig } from "./add-web-item.js";
+import { handleAddItems, toolConfig as addItemsConfig } from "./add-items.js";
 import { handleImportPdfToZotero, toolConfig as importPdfToZoteroConfig } from "./import-pdf-to-zotero.js";
 import { handleFindAndAttachPdfs, toolConfig as findAndAttachPdfsConfig } from "./find-and-attach-pdfs.js";
 const handlers = {
@@ -22,7 +22,7 @@ const handlers = {
     get_item_fulltext: handleGetItemFulltext,
     get_user_id: handleGetUserId,
     add_linked_url_attachment: handleAddLinkedUrlAttachment,
-    add_web_item: handleAddWebItem,
+    add_items: handleAddItems,
     import_pdf_to_zotero: handleImportPdfToZotero,
     find_and_attach_pdfs: handleFindAndAttachPdfs,
 };
@@ -44,7 +44,7 @@ const toolConfigs = [
     { config: getItemFulltextConfig, handler: handleGetItemFulltext },
     { config: getUserIdConfig, handler: handleGetUserId },
     { config: addLinkedUrlAttachmentConfig, handler: handleAddLinkedUrlAttachment },
-    { config: addWebItemConfig, handler: handleAddWebItem },
+    { config: addItemsConfig, handler: handleAddItems },
     { config: importPdfToZoteroConfig, handler: handleImportPdfToZotero },
     { config: findAndAttachPdfsConfig, handler: handleFindAndAttachPdfs },
 ];

package/build/tools/inject-citations.js

@@ -5,31 +5,31 @@ import { injectCitations } from "../citation-injector/injector.js";
 import { logger } from "../utils/logger.js";
 export const toolConfig = {
     name: "inject_citations",
-    description: `Replace <zcite> placeholder tags in a .docx file with native Zotero field codes that Zotero for Word can recognize and manage. The tool fetches item metadata from Zotero automatically — you only need to provide the .docx file.
-
-WORKFLOW — how to create a Word document with live Zotero citations:
-1. Collect item keys: use add_items_by_doi (or search_library for existing items)
-2. Generate .docx: create a Word document (e.g. with the "docx" npm package) with <zcite keys="ITEMKEY"/> placeholders where citations should appear. Each <zcite> MUST be in its own dedicated TextRun — do NOT mix it with surrounding text.
-3. Call this tool with the .docx file path. It replaces every zcite tag with a Zotero field code and appends a bibliography.
-4. Tell the user to open the file in Word with the Zotero plugin and click Zotero → Refresh.
-
-CITATION STYLES — ask the user which style they want before generating:
-- apa (default): author-year — (Smith, 2023)
-- ieee / vancouver: numbered — [1], [2]
-  WARNING: for numbered styles every <zcite> MUST include a num="N" attribute with the sequential citation number. Without num, citations render as [?].
-
-ZCITE TAG FORMAT:
-  <zcite keys="ITEMKEY"/>
-Supported attributes (any order):
-  - keys (required): item key or comma-separated keys — "ABC12345" or "ABC12345,DEF67890"
-  - num: citation number for IEEE/Vancouver — "1" or "1,2" (required for numbered styles)
-  - locator: page reference — "pp. 12-15"
-  - prefix: text before citation — "see "
-  - suffix: text after citation — ", emphasis added"
-
-OUTPUT:
-A new .docx file (original filename with _cited suffix) with Zotero field codes and a ZOTERO_BIBL bibliography at the end.
-
+    description: `Replace <zcite> placeholder tags in a .docx file with native Zotero field codes that Zotero for Word can recognize and manage. The tool fetches item metadata from Zotero automatically — you only need to provide the .docx file.
+
+WORKFLOW — how to create a Word document with live Zotero citations:
+1. Collect item keys: use add_items_by_doi (or search_library for existing items)
+2. Generate .docx: create a Word document (e.g. with the "docx" npm package) with <zcite keys="ITEMKEY"/> placeholders where citations should appear. Each <zcite> MUST be in its own dedicated TextRun — do NOT mix it with surrounding text.
+3. Call this tool with the .docx file path. It replaces every zcite tag with a Zotero field code and appends a bibliography.
+4. Tell the user to open the file in Word with the Zotero plugin and click Zotero → Refresh.
+
+CITATION STYLES — ask the user which style they want before generating:
+- apa (default): author-year — (Smith, 2023)
+- ieee / vancouver: numbered — [1], [2]
+  WARNING: for numbered styles every <zcite> MUST include a num="N" attribute with the sequential citation number. Without num, citations render as [?].
+
+ZCITE TAG FORMAT:
+  <zcite keys="ITEMKEY"/>
+Supported attributes (any order):
+  - keys (required): item key or comma-separated keys — "ABC12345" or "ABC12345,DEF67890"
+  - num: citation number for IEEE/Vancouver — "1" or "1,2" (required for numbered styles)
+  - locator: page reference — "pp. 12-15"
+  - prefix: text before citation — "see "
+  - suffix: text after citation — ", emphasis added"
+
+OUTPUT:
+A new .docx file (original filename with _cited suffix) with Zotero field codes and a ZOTERO_BIBL bibliography at the end.
+
 NOTE: If the inject-citations skill is available, prefer the skill workflow (runs in sandbox, no filesystem dependency). This tool serves as the primary path when the skill is not available.`,
     inputSchema: {
         file_path: z

package/build/tools/search-library.js

@@ -5,16 +5,16 @@ import { formatCreators } from "../utils/item-formatter.js";
 import { logger } from "../utils/logger.js";
 export const toolConfig = {
     name: "search_library",
-    description: `Search your Zotero library or list items sorted by a field.
-
-When 'query' is provided, searches by title, author, or any field.
-When 'query' is omitted, lists items sorted by the chosen field (default: dateAdded, descending) — this replaces the old get_recent tool.
-
-Examples:
-  - Search: { "query": "deep learning" }
-  - Recent items: { "sort": "dateAdded", "limit": 10 }
-  - Recent with search: { "query": "transformers", "sort": "dateAdded", "limit": 5 }
-
+    description: `Search your Zotero library or list items sorted by a field.
+
+When 'query' is provided, searches by title, author, or any field.
+When 'query' is omitted, lists items sorted by the chosen field (default: dateAdded, descending) — this replaces the old get_recent tool.
+
+Examples:
+  - Search: { "query": "deep learning" }
+  - Recent items: { "sort": "dateAdded", "limit": 10 }
+  - Recent with search: { "query": "transformers", "sort": "dateAdded", "limit": 5 }
+
 Use the returned item keys with get_items_details, get_item_fulltext, or inject_citations.`,
     inputSchema: {
         query: z

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

@@ -1,23 +1,78 @@
 const CSL_TO_ZOTERO_TYPE = {
+    "article": "journalArticle",
     "article-journal": "journalArticle",
-    book: "book",
-    chapter: "bookSection",
+    "article-magazine": "magazineArticle",
+    "article-newspaper": "newspaperArticle",
+    "bill": "bill",
+    "book": "book",
+    "broadcast": "tvBroadcast",
+    "chapter": "bookSection",
+    "dataset": "dataset",
+    "document": "document",
+    "entry-dictionary": "dictionaryEntry",
+    "entry-encyclopedia": "encyclopediaArticle",
+    "figure": "artwork",
+    "graphic": "artwork",
+    "hearing": "hearing",
+    "interview": "interview",
+    "legal_case": "case",
+    "legislation": "statute",
+    "manuscript": "manuscript",
+    "map": "map",
+    "motion_picture": "film",
     "paper-conference": "conferencePaper",
-    report: "report",
-    thesis: "thesis",
-    webpage: "webpage",
-    dataset: "document",
-    article: "journalArticle",
+    "patent": "patent",
+    "personal_communication": "letter",
+    "post": "forumPost",
+    "post-weblog": "blogPost",
+    "report": "report",
+    "review": "journalArticle",
+    "review-book": "journalArticle",
+    "software": "computerProgram",
+    "song": "audioRecording",
+    "speech": "presentation",
+    "standard": "standard",
+    "thesis": "thesis",
+    "webpage": "webpage",
 };
 const ZOTERO_TO_CSL_TYPE = {
     journalArticle: "article-journal",
+    magazineArticle: "article-magazine",
+    newspaperArticle: "article-newspaper",
+    bill: "bill",
     book: "book",
+    tvBroadcast: "broadcast",
     bookSection: "chapter",
+    dataset: "dataset",
+    document: "document",
+    dictionaryEntry: "entry-dictionary",
+    encyclopediaArticle: "entry-encyclopedia",
+    artwork: "graphic",
+    hearing: "hearing",
+    interview: "interview",
+    case: "legal_case",
+    statute: "legislation",
+    manuscript: "manuscript",
+    map: "map",
+    film: "motion_picture",
     conferencePaper: "paper-conference",
+    patent: "patent",
+    letter: "personal_communication",
+    forumPost: "post",
+    blogPost: "post-weblog",
     report: "report",
+    computerProgram: "software",
+    audioRecording: "song",
+    presentation: "speech",
+    standard: "standard",
     thesis: "thesis",
     webpage: "webpage",
-    document: "dataset",
+    radioBroadcast: "broadcast",
+    videoRecording: "motion_picture",
+    preprint: "article",
+    podcast: "song",
+    email: "personal_communication",
+    instantMessage: "personal_communication",
 };
 export function cslToZoteroItem(csl, options) {
     const creators = (csl.author ?? []).map((a) => ({
@@ -46,6 +101,12 @@ export function cslToZoteroItem(csl, options) {
         place: csl["publisher-place"] ?? "",
         url: csl.URL ?? "",
         abstractNote: csl.abstract ?? "",
+        ISBN: csl.ISBN ?? "",
+        ISSN: csl.ISSN ?? "",
+        edition: csl.edition ?? "",
+        numPages: csl["number-of-pages"] ?? "",
+        series: csl["collection-title"] ?? "",
+        language: csl.language ?? "",
         collections,
         tags,
     };

package/build/utils/zotero-item-types.js

@@ -0,0 +1,280 @@
+/**
+ * Static registry of all 37 regular Zotero item types with their valid fields
+ * and creator types. Generated from the Zotero API (/itemTypes, /itemTypeFields,
+ * /itemTypeCreatorTypes).
+ *
+ * Used for data-driven validation in the add_items tool — a single superRefine
+ * handles all types via O(1) Set lookups instead of per-type switch-cases.
+ */
+export const ZOTERO_ITEM_TYPES = [
+    "artwork", "audioRecording", "bill", "blogPost", "book", "bookSection",
+    "case", "computerProgram", "conferencePaper", "dataset", "dictionaryEntry",
+    "document", "email", "encyclopediaArticle", "film", "forumPost", "hearing",
+    "instantMessage", "interview", "journalArticle", "letter", "magazineArticle",
+    "manuscript", "map", "newspaperArticle", "patent", "podcast", "preprint",
+    "presentation", "radioBroadcast", "report", "standard", "statute",
+    "thesis", "tvBroadcast", "videoRecording", "webpage",
+];
+/**
+ * Item types where the "title" field has a different API name.
+ * The add_items tool always accepts `title` as a universal required field,
+ * then maps it to the correct API field name for these types.
+ */
+export const TITLE_FIELD_NAME = {
+    case: "caseName",
+    email: "subject",
+    statute: "nameOfAct",
+};
+/** Per-type valid fields — ReadonlySet for O(1) lookup. */
+export const ITEM_TYPE_FIELDS = {
+    artwork: new Set([
+        "title", "abstractNote", "artworkMedium", "artworkSize", "date", "eventPlace",
+        "DOI", "citationKey", "url", "accessDate", "archive", "archiveLocation",
+        "shortTitle", "language", "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    audioRecording: new Set([
+        "title", "abstractNote", "audioRecordingFormat", "seriesTitle", "volume",
+        "numberOfVolumes", "label", "place", "date", "runningTime", "ISBN", "DOI",
+        "citationKey", "url", "accessDate", "archive", "archiveLocation", "shortTitle",
+        "language", "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    bill: new Set([
+        "title", "abstractNote", "billNumber", "code", "codeVolume", "section",
+        "codePages", "legislativeBody", "session", "history", "date", "DOI",
+        "citationKey", "url", "accessDate", "shortTitle", "language", "rights", "extra",
+    ]),
+    blogPost: new Set([
+        "title", "abstractNote", "blogTitle", "websiteType", "date", "DOI",
+        "citationKey", "url", "accessDate", "ISSN", "shortTitle", "language",
+        "rights", "extra",
+    ]),
+    book: new Set([
+        "title", "abstractNote", "series", "seriesNumber", "volume", "numberOfVolumes",
+        "edition", "date", "publisher", "place", "originalDate", "originalPublisher",
+        "originalPlace", "format", "numPages", "ISBN", "DOI", "citationKey", "url",
+        "accessDate", "ISSN", "archive", "archiveLocation", "shortTitle", "language",
+        "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    bookSection: new Set([
+        "title", "abstractNote", "bookTitle", "series", "seriesNumber", "volume",
+        "numberOfVolumes", "edition", "date", "publisher", "place", "originalDate",
+        "originalPublisher", "originalPlace", "format", "pages", "ISBN", "DOI",
+        "citationKey", "url", "accessDate", "ISSN", "archive", "archiveLocation",
+        "shortTitle", "language", "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    case: new Set([
+        "caseName", "abstractNote", "court", "dateDecided", "docketNumber", "reporter",
+        "reporterVolume", "firstPage", "history", "DOI", "citationKey", "url",
+        "accessDate", "shortTitle", "language", "rights", "extra",
+    ]),
+    computerProgram: new Set([
+        "title", "abstractNote", "seriesTitle", "versionNumber", "date", "system",
+        "company", "place", "programmingLanguage", "rights", "citationKey", "url",
+        "accessDate", "DOI", "ISBN", "archive", "archiveLocation", "libraryCatalog",
+        "callNumber", "shortTitle", "extra",
+    ]),
+    conferencePaper: new Set([
+        "title", "abstractNote", "proceedingsTitle", "conferenceName", "publisher",
+        "place", "date", "eventPlace", "volume", "issue", "numberOfVolumes", "pages",
+        "series", "seriesNumber", "DOI", "ISBN", "citationKey", "url", "accessDate",
+        "ISSN", "archive", "archiveLocation", "shortTitle", "language",
+        "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    dataset: new Set([
+        "title", "abstractNote", "identifier", "type", "versionNumber", "date",
+        "repository", "repositoryLocation", "format", "DOI", "citationKey", "url",
+        "accessDate", "archive", "archiveLocation", "shortTitle", "language",
+        "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    dictionaryEntry: new Set([
+        "title", "abstractNote", "dictionaryTitle", "series", "seriesNumber", "volume",
+        "numberOfVolumes", "edition", "date", "publisher", "place", "pages", "ISBN",
+        "DOI", "citationKey", "url", "accessDate", "archive", "archiveLocation",
+        "shortTitle", "language", "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    document: new Set([
+        "title", "abstractNote", "type", "date", "publisher", "place", "DOI",
+        "citationKey", "url", "accessDate", "archive", "archiveLocation", "shortTitle",
+        "language", "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    email: new Set([
+        "subject", "abstractNote", "date", "DOI", "citationKey", "url", "accessDate",
+        "shortTitle", "language", "rights", "extra",
+    ]),
+    encyclopediaArticle: new Set([
+        "title", "abstractNote", "encyclopediaTitle", "series", "seriesNumber", "volume",
+        "numberOfVolumes", "edition", "date", "publisher", "place", "pages", "ISBN",
+        "DOI", "citationKey", "url", "accessDate", "archive", "archiveLocation",
+        "shortTitle", "language", "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    film: new Set([
+        "title", "abstractNote", "distributor", "place", "date", "genre",
+        "videoRecordingFormat", "runningTime", "DOI", "citationKey", "url",
+        "accessDate", "archive", "archiveLocation", "shortTitle", "language",
+        "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    forumPost: new Set([
+        "title", "abstractNote", "forumTitle", "postType", "date", "DOI", "citationKey",
+        "url", "accessDate", "shortTitle", "language", "rights", "extra",
+    ]),
+    hearing: new Set([
+        "title", "abstractNote", "committee", "publisher", "numberOfVolumes",
+        "documentNumber", "pages", "legislativeBody", "session", "history", "date",
+        "place", "DOI", "citationKey", "url", "accessDate", "shortTitle", "language",
+        "rights", "extra",
+    ]),
+    instantMessage: new Set([
+        "title", "abstractNote", "date", "DOI", "citationKey", "url", "accessDate",
+        "shortTitle", "language", "rights", "extra",
+    ]),
+    interview: new Set([
+        "title", "abstractNote", "interviewMedium", "date", "publisher", "place", "DOI",
+        "citationKey", "url", "accessDate", "archive", "archiveLocation", "shortTitle",
+        "language", "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    journalArticle: new Set([
+        "title", "abstractNote", "publicationTitle", "publisher", "place", "date",
+        "volume", "issue", "section", "partNumber", "partTitle", "pages", "series",
+        "seriesTitle", "seriesText", "journalAbbreviation", "DOI", "citationKey", "url",
+        "accessDate", "PMID", "PMCID", "ISSN", "archive", "archiveLocation",
+        "shortTitle", "language", "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    letter: new Set([
+        "title", "abstractNote", "letterType", "date", "eventPlace", "DOI",
+        "citationKey", "url", "accessDate", "archive", "archiveLocation", "shortTitle",
+        "language", "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    magazineArticle: new Set([
+        "title", "abstractNote", "publicationTitle", "publisher", "place", "date",
+        "volume", "issue", "pages", "ISSN", "DOI", "citationKey", "url", "accessDate",
+        "archive", "archiveLocation", "shortTitle", "language", "libraryCatalog",
+        "callNumber", "rights", "extra",
+    ]),
+    manuscript: new Set([
+        "title", "abstractNote", "manuscriptType", "institution", "place", "date",
+        "numPages", "number", "DOI", "citationKey", "url", "accessDate", "archive",
+        "archiveLocation", "shortTitle", "language", "libraryCatalog", "callNumber",
+        "rights", "extra",
+    ]),
+    map: new Set([
+        "title", "abstractNote", "mapType", "scale", "seriesTitle", "edition",
+        "publisher", "place", "date", "DOI", "ISBN", "citationKey", "url", "accessDate",
+        "archive", "archiveLocation", "shortTitle", "language", "libraryCatalog",
+        "callNumber", "rights", "extra",
+    ]),
+    newspaperArticle: new Set([
+        "title", "abstractNote", "publicationTitle", "publisher", "place", "date",
+        "volume", "issue", "edition", "section", "pages", "ISSN", "DOI", "citationKey",
+        "url", "accessDate", "archive", "archiveLocation", "shortTitle", "language",
+        "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    patent: new Set([
+        "title", "abstractNote", "place", "country", "assignee", "issuingAuthority",
+        "patentNumber", "filingDate", "pages", "applicationNumber", "priorityNumbers",
+        "issueDate", "priorityDate", "references", "legalStatus", "DOI", "citationKey",
+        "url", "accessDate", "shortTitle", "language", "rights", "extra",
+    ]),
+    podcast: new Set([
+        "title", "abstractNote", "seriesTitle", "episodeNumber", "audioFileType", "date",
+        "publisher", "place", "runningTime", "DOI", "citationKey", "url", "accessDate",
+        "shortTitle", "language", "rights", "extra",
+    ]),
+    preprint: new Set([
+        "title", "abstractNote", "genre", "repository", "archiveID", "place", "date",
+        "series", "seriesNumber", "DOI", "citationKey", "url", "accessDate", "archive",
+        "archiveLocation", "shortTitle", "language", "libraryCatalog", "callNumber",
+        "rights", "extra",
+    ]),
+    presentation: new Set([
+        "title", "abstractNote", "presentationType", "date", "meetingName", "place",
+        "series", "sessionTitle", "DOI", "citationKey", "url", "accessDate",
+        "shortTitle", "language", "rights", "extra",
+    ]),
+    radioBroadcast: new Set([
+        "title", "abstractNote", "programTitle", "episodeNumber", "audioRecordingFormat",
+        "network", "place", "date", "runningTime", "DOI", "citationKey", "url",
+        "accessDate", "archive", "archiveLocation", "shortTitle", "language",
+        "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    report: new Set([
+        "title", "abstractNote", "reportNumber", "reportType", "institution", "place",
+        "date", "seriesTitle", "seriesNumber", "pages", "DOI", "ISBN", "citationKey",
+        "url", "accessDate", "ISSN", "archive", "archiveLocation", "shortTitle",
+        "language", "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    standard: new Set([
+        "title", "abstractNote", "organization", "committee", "type", "number",
+        "versionNumber", "edition", "status", "date", "publisher", "place", "partNumber",
+        "partTitle", "ISBN", "DOI", "citationKey", "url", "accessDate", "archive",
+        "archiveLocation", "shortTitle", "numPages", "language", "libraryCatalog",
+        "callNumber", "rights", "extra",
+    ]),
+    statute: new Set([
+        "nameOfAct", "abstractNote", "code", "codeNumber", "publicLawNumber",
+        "dateEnacted", "pages", "section", "session", "history", "DOI", "citationKey",
+        "url", "accessDate", "shortTitle", "language", "rights", "extra",
+    ]),
+    thesis: new Set([
+        "title", "abstractNote", "thesisType", "university", "place", "date", "series",
+        "seriesNumber", "numPages", "DOI", "ISBN", "citationKey", "url", "accessDate",
+        "ISSN", "archive", "archiveLocation", "shortTitle", "language",
+        "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    tvBroadcast: new Set([
+        "title", "abstractNote", "programTitle", "episodeNumber", "videoRecordingFormat",
+        "network", "place", "date", "runningTime", "DOI", "citationKey", "url",
+        "accessDate", "archive", "archiveLocation", "shortTitle", "language",
+        "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    videoRecording: new Set([
+        "title", "abstractNote", "videoRecordingFormat", "seriesTitle", "volume",
+        "numberOfVolumes", "studio", "place", "date", "runningTime", "ISBN", "DOI",
+        "citationKey", "url", "accessDate", "archive", "archiveLocation", "shortTitle",
+        "language", "libraryCatalog", "callNumber", "rights", "extra",
+    ]),
+    webpage: new Set([
+        "title", "abstractNote", "websiteTitle", "websiteType", "date", "publisher",
+        "place", "DOI", "citationKey", "url", "accessDate", "shortTitle", "language",
+        "rights", "extra",
+    ]),
+};
+/** Per-type valid creator types — ReadonlySet for O(1) lookup. */
+export const ITEM_TYPE_CREATOR_TYPES = {
+    artwork: new Set(["artist", "contributor"]),
+    audioRecording: new Set(["performer", "composer", "contributor", "originalCreator", "translator", "wordsBy"]),
+    bill: new Set(["sponsor", "contributor", "cosponsor"]),
+    blogPost: new Set(["author", "commenter", "contributor", "translator"]),
+    book: new Set(["author", "contributor", "editor", "seriesEditor", "translator"]),
+    bookSection: new Set(["author", "bookAuthor", "contributor", "editor", "seriesEditor", "translator"]),
+    case: new Set(["author", "contributor", "counsel"]),
+    computerProgram: new Set(["programmer", "contributor"]),
+    conferencePaper: new Set(["author", "contributor", "editor", "seriesEditor", "translator"]),
+    dataset: new Set(["author", "contributor"]),
+    dictionaryEntry: new Set(["author", "contributor", "editor", "seriesEditor", "translator"]),
+    document: new Set(["author", "contributor", "editor", "reviewedAuthor", "translator"]),
+    email: new Set(["author", "contributor", "recipient", "translator"]),
+    encyclopediaArticle: new Set(["author", "contributor", "editor", "seriesEditor", "translator"]),
+    film: new Set(["director", "castMember", "contributor", "guest", "host", "narrator", "producer", "scriptwriter", "translator"]),
+    forumPost: new Set(["author", "contributor"]),
+    hearing: new Set(["contributor"]),
+    instantMessage: new Set(["author", "contributor", "recipient"]),
+    interview: new Set(["interviewee", "contributor", "interviewer", "translator"]),
+    journalArticle: new Set(["author", "contributor", "editor", "reviewedAuthor", "translator"]),
+    letter: new Set(["author", "contributor", "recipient", "translator"]),
+    magazineArticle: new Set(["author", "contributor", "reviewedAuthor", "translator"]),
+    manuscript: new Set(["author", "contributor", "translator"]),
+    map: new Set(["cartographer", "contributor", "seriesEditor"]),
+    newspaperArticle: new Set(["author", "contributor", "reviewedAuthor", "translator"]),
+    patent: new Set(["inventor", "attorneyAgent", "contributor"]),
+    podcast: new Set(["podcaster", "castMember", "contributor", "director", "executiveProducer", "guest", "producer", "scriptwriter", "seriesCreator", "translator"]),
+    preprint: new Set(["author", "contributor", "editor", "reviewedAuthor", "translator"]),
+    presentation: new Set(["presenter", "chair", "contributor", "organizer", "translator"]),
+    radioBroadcast: new Set(["creator", "castMember", "contributor", "director", "executiveProducer", "guest", "host", "producer", "scriptwriter", "seriesCreator", "translator"]),
+    report: new Set(["author", "contributor", "editor", "seriesEditor", "translator"]),
+    standard: new Set(["author", "contributor", "editor"]),
+    statute: new Set(["author", "contributor"]),
+    thesis: new Set(["author", "contributor"]),
+    tvBroadcast: new Set(["director", "castMember", "contributor", "executiveProducer", "guest", "host", "narrator", "producer", "scriptwriter", "seriesCreator", "translator"]),
+    videoRecording: new Set(["creator", "castMember", "contributor", "director", "executiveProducer", "guest", "host", "narrator", "producer", "scriptwriter", "translator"]),
+    webpage: new Set(["author", "contributor", "translator"]),
+};

package/package.json

@@ -1,58 +1,58 @@
-{
-  "name": "@xevos117/mcp-zotero",
-  "type": "module",
-  "version": "1.0.3",
-  "description": "Unofficial MCP server for Zotero integration with citation management",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Xevos117/mcp-zotero.git"
-  },
-  "homepage": "https://github.com/Xevos117/mcp-zotero#readme",
-  "bugs": {
-    "url": "https://github.com/Xevos117/mcp-zotero/issues"
-  },
-  "main": "build/server.js",
-  "bin": {
-    "mcp-zotero": "build/server.js"
-  },
-  "files": [
-    "build"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "build": "tsc",
-    "start": "node build/server.js",
-    "prepublishOnly": "npm test && npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "zotero",
-    "zotero-api",
-    "citation",
-    "bibliography",
-    "reference-manager",
-    "claude",
-    "ai"
-  ],
-  "author": "Xevos17",
-  "license": "MIT",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4",
-    "dotenv": "^16.4.7",
-    "fast-xml-parser": "^5.3.5",
-    "jszip": "^3.10.1",
-    "unpdf": "^1.4.0",
-    "zod": "^3.24.1",
-    "zotero-api-client": "^0.46.0"
-  },
-  "devDependencies": {
-    "@types/node": "latest",
-    "typescript": "latest",
-    "vitest": "^4.0.18"
-  }
-}
+{
+  "name": "@xevos117/mcp-zotero",
+  "type": "module",
+  "version": "1.0.5",
+  "description": "Unofficial MCP server for Zotero integration with citation management",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xevos117/mcp-zotero.git"
+  },
+  "homepage": "https://github.com/Xevos117/mcp-zotero#readme",
+  "bugs": {
+    "url": "https://github.com/Xevos117/mcp-zotero/issues"
+  },
+  "main": "build/server.js",
+  "bin": {
+    "mcp-zotero": "build/server.js"
+  },
+  "files": [
+    "build"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsc",
+    "start": "node build/server.js",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "zotero",
+    "zotero-api",
+    "citation",
+    "bibliography",
+    "reference-manager",
+    "claude",
+    "ai"
+  ],
+  "author": "Xevos17",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "dotenv": "^16.4.7",
+    "fast-xml-parser": "^5.3.5",
+    "jszip": "^3.10.1",
+    "unpdf": "^1.4.0",
+    "zod": "^3.24.1",
+    "zotero-api-client": "^0.46.0"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "typescript": "latest",
+    "vitest": "^4.0.18"
+  }
+}

package/build/tools/add-web-item.js

@@ -1,97 +0,0 @@
-import { z } from "zod";
-import { isZoteroApiError } from "../types/zotero-types.js";
-import { formatErrorResponse } from "../utils/error-formatter.js";
-import { logger } from "../utils/logger.js";
-export const toolConfig = {
-    name: "add_web_item",
-    description: "Save a web page as a Zotero item of type 'webpage'. Use this for online articles, blog posts, or any web resource that does not have a DOI. Returns the new item key and metadata.",
-    inputSchema: {
-        url: z.string().url().describe("URL of the web page"),
-        title: z.string().describe("Title of the web page or article"),
-        website_title: z
-            .string()
-            .optional()
-            .describe('Name of the website or online publication (e.g. "Nature News", "Ars Technica")'),
-        date: z
-            .string()
-            .optional()
-            .describe("Publication date (e.g. \"2024-03-15\")"),
-        creators: z
-            .array(z.object({
-            firstName: z.string(),
-            lastName: z.string(),
-        }))
-            .optional()
-            .describe("Authors of the web page"),
-        collection_key: z
-            .string()
-            .optional()
-            .describe("Zotero collection key to add the item to. Get this from create_collection or get_collections."),
-        tags: z
-            .array(z.string())
-            .optional()
-            .describe("Tags to apply to the item"),
-    },
-};
-const AddWebItemSchema = z.object(toolConfig.inputSchema);
-export async function handleAddWebItem(zoteroApi, userId, args) {
-    const { url, title, website_title, date, creators, collection_key, tags } = AddWebItemSchema.parse(args);
-    const itemData = {
-        itemType: "webpage",
-        title,
-        url,
-        accessDate: new Date().toISOString().split("T")[0],
-        creators: creators?.map((c) => ({
-            ...c,
-            creatorType: "author",
-        })) ?? [],
-        collections: collection_key ? [collection_key] : [],
-        tags: tags?.map((t) => ({ tag: t })) ?? [],
-    };
-    if (website_title) {
-        itemData.websiteTitle = website_title;
-    }
-    if (date) {
-        itemData.date = date;
-    }
-    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 web page item", {
-                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,
-                        website_title: website_title ?? null,
-                        item_type: "webpage",
-                    }, null, 2),
-                },
-            ],
-        };
-    }
-    catch (err) {
-        if (isZoteroApiError(err)) {
-            logger.error("Tool execution failed", {
-                tool: "add_web_item",
-                status: err.response?.status,
-                errorMessage: err.message,
-                url: err.response?.url,
-            });
-        }
-        throw err;
-    }
-}