@xevos117/mcp-zotero 2.0.0 → 2.0.2

package/README.md

@@ -226,10 +226,97 @@ claude mcp add-json "zotero" '{"command":"npx","args":["tsx","src/server.ts"],"e
 ```bash
 npm install
 npm run build          # Compile TypeScript
-npm test               # Run tests (vitest, 404 tests)
+npm test               # Unit and per-tool tests (vitest, fetch faked, ~1000 tests)
+npm run test:e2e       # Built server over stdio against a local fake Zotero API
+npm run smoke          # Quick stdio smoke test of the built server (user + group library)
 npx tsx src/server.ts  # Run directly without building
 ```
 
+### Testing
+
+| Layer | Command | Runs on | What it covers |
+|---|---|---|---|
+| Unit / per tool | `npm test` | every PR (Node 22, 24, 26) | every tool through a real MCP client, Zotero faked at the `fetch` level; produced `.docx` files are validated against the official CSL schemas and rendered with citeproc-js ([test/helpers/docx-validate.ts](test/helpers/docx-validate.ts)) |
+| E2E + smoke | `npm run test:e2e`, `npm run smoke` | every PR | the compiled server over stdio, user and group libraries |
+| Live | `npm run test:live` | PRs from this repository, `main`, nightly | the real Zotero Web API on a dedicated test account ([test/live](test/live)); skipped unless `ZOTERO_TEST_API_KEY` is set |
+| Agent smoke | [workflow](.github/workflows/claude-agent-smoke.yml) | PRs from this repository, manual runs (e.g. on `main` after a merge) | a Claude Code agent uses the server like a user, following the versioned skill [`.claude/skills/test-mcp-zotero`](.claude/skills/test-mcp-zotero/SKILL.md): `inject_citations` ⇄ `inject.js` parity in every style, fixed edge cases and up to 5 exploratory scenarios on what the PR changes. The workflow sets up the MCP server, the tool set and guard hooks (Bash allowlist, delete policy, audit log); local runs use the same pieces ([test/live/agent/README.md](test/live/agent/README.md)). The verdict comes from [test/live/verify-claims.mjs](test/live/verify-claims.mjs), not from the agent |
+| Word | manual | every release | [test/WORD_CHECKLIST.md](test/WORD_CHECKLIST.md): open an injected document in Word with the Zotero plugin |
+
+Every test case is listed in [test/TEST_CASES.md](test/TEST_CASES.md).
+
+**Live tests locally** use only `ZOTERO_TEST_*` variables, never your `ZOTERO_API_KEY`:
+
+```bash
+ZOTERO_TEST_API_KEY=... ZOTERO_TEST_USER_ID=... UNPAYWALL_EMAIL=you@example.org npm run test:live
+```
+
+Against a personal library add `ZOTERO_LIVE_SAFE_MODE=1`: the suite only creates items and collections
+named `mzt-<runId>…` and tagged `mzt-run:<runId>`, deletes only those, and skips collection deletion and
+group writes. A dedicated test account is marked by a collection named `__mzt_disposable__`.
+
+**Dependencies** are updated monthly by a Claude Code agent ([workflow](.github/workflows/deps-update.yml),
+skill [`.claude/skills/deps-update`](.claude/skills/deps-update/SKILL.md)); patch-only PRs are auto-merged after
+all required checks pass, anything else waits for review. GitHub Actions versions are updated by Dependabot.
+
+### CI setup (repository owner)
+
+| Environment | Secrets | Variables |
+|---|---|---|
+| `zotero-live` (live tests, agent smoke) | `ZOTERO_TEST_API_KEY`, `ZOTERO_TEST_USER_ID`, `ZOTERO_TEST_USERNAME`, `ZOTERO_TEST_GROUP_ID` (optional), `UNPAYWALL_EMAIL` | `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID`, `ANTHROPIC_WORKSPACE_ID` |
+| `claude-deps` (dependency agent) | — | the same four `ANTHROPIC_*` variables (the federation rule may differ) |
+
+The agents authenticate to the Claude API with Anthropic Workload Identity Federation (GitHub OIDC, no
+API key). Recommended: one federation rule per environment, as narrow as possible:
+
+| Rule for | subject (exact, no `*`) | claims (exact string pairs) | condition (CEL) |
+|---|---|---|---|
+| `zotero-live` | `repo:Xevos117/mcp-zotero:environment:zotero-live` | `repository_id: 1152178663`, `repository_owner_id: 86290818` | `claims.job_workflow_ref.startsWith("Xevos117/mcp-zotero/.github/workflows/claude-agent-smoke.yml@")` (PR runs use the PR ref) |
+| `claude-deps` | `repo:Xevos117/mcp-zotero:environment:claude-deps` | `repository_id: 1152178663`, `repository_owner_id: 86290818`, `job_workflow_ref: Xevos117/mcp-zotero/.github/workflows/deps-update.yml@refs/heads/main` | — |
+
+Claims are exact-match string pairs (only `subject_prefix` supports a trailing `*`), so a prefix such as
+"this workflow on any ref" must be written as a CEL `condition`, as above; an exact `job_workflow_ref`
+(claude-deps, main only) can be a plain claim.
+
+Audience `https://api.anthropic.com`. The subject is an exact match unless it ends with `*`; jobs that use
+an environment get the OIDC subject `repo:Xevos117/mcp-zotero:environment:<environment>`, so a rule
+written for a branch or PR subject never matches. Numeric ids (not names) keep a renamed or re-created
+repository/account from matching.
+
+Trade-off for `zotero-live`: the "any ref" condition is needed for the agent smoke test to run on pull
+requests, but it also accepts a modified copy of that workflow file pushed to any branch of this repository
+(only people with write access can push). Pinning it to the exact claim
+`job_workflow_ref: Xevos117/mcp-zotero/.github/workflows/claude-agent-smoke.yml@refs/heads/main` closes that
+gap but disables the agent smoke test on PRs (it would then run only on manual runs from `main`).
+
+Other owner settings:
+
+- The Zotero test account needs a collection named `__mzt_disposable__`.
+- Repository settings: "Allow auto-merge", and "Allow GitHub Actions to create and approve pull requests"
+  (the dependency workflow opens its PR with `GITHUB_TOKEN`). Keep the ruleset at **0 required approvals**:
+  auto-merge of the dependency PR relies on it, and it is also what makes the second setting acceptable. That
+  setting is a conscious trade-off: it lets workflows open PRs (needed) and approve them (not used by any
+  workflow here); if approvals are ever required, it would let a workflow approve its own PR, so revisit it
+  together with any approval requirement.
+- No GitHub App is used by any workflow (the agents authenticate to Anthropic with Workload Identity
+  Federation and use only `GITHUB_TOKEN` on GitHub, read-only for the agents). If the Claude GitHub App is
+  installed on this repository, uninstall it.
+- Set a monthly spend limit on the Anthropic workspace used by the federation rules: it is the real cap on
+  agent costs.
+- Residual risk: the agent smoke job that holds the OIDC token also runs the MCP server built from the PR's
+  code (that is what it tests). It runs only for same-repository PRs by the owner or a bot, the token is
+  bound to the `zotero-live` environment and the workspace spend limit caps any misuse.
+- Required checks after the stack merges: `test (node 22)`, `test (node 24)`, `test (node 26)`,
+  `live-tests`, `agent-smoke`.
+
+### Releasing
+
+1. Update `CHANGELOG.md` (move `Unreleased` to the new version) and `version` in `package.json`.
+2. Make sure CI, live tests and the agent smoke test are green on `main`.
+3. Run the manual [Word checklist](test/WORD_CHECKLIST.md) on a document injected by the release candidate
+   and record the results in its log.
+4. Publish the GitHub release: the [release workflow](.github/workflows/release.yml) runs the tests, publishes
+   to npm and attaches the skill zips.
+
 ### Debug with MCP Inspector
 
 ```bash

package/build/citation-injector/injector.js

@@ -1,6 +1,7 @@
 import JSZip from "jszip";
 import { readFile, writeFile } from "node:fs/promises";
 import { format, parse } from "node:path";
+import { isZoteroApiError } from "../types/zotero-types.js";
 import { generateZoteroFieldCode, generateBibliographyFieldCode } from "./field-codes.js";
 import { formatCitationText } from "./citation-formatter.js";
 import { regexEscape, unescapeXml } from "./xml-utils.js";
@@ -39,10 +40,19 @@ function parseZciteMatches(documentXml) {
 async function fetchCslData(keys, zoteroApi, libraryType, userId) {
     const cslData = new Map();
     for (const key of keys) {
-        const response = await zoteroApi
-            .library(libraryType, userId)
-            .items(key)
-            .get();
+        let response;
+        try {
+            response = await zoteroApi
+                .library(libraryType, userId)
+                .items(key)
+                .get();
+        }
+        catch (err) {
+            // Unknown keys are collected and reported together by the caller; any other failure aborts at once
+            if (isZoteroApiError(err) && err.response?.status === 404)
+                continue;
+            throw err;
+        }
         const zoteroItem = response.getData();
         cslData.set(key, zoteroItemToCsl(zoteroItem));
     }
@@ -123,8 +133,20 @@ export async function injectCitations(filePath, zoteroApi, libraryType, userId,
     }
     // Collect all unique item keys
     const uniqueKeys = new Set(matches.flatMap((m) => m.keys));
+    // Keys from the document go into API URL paths (one GET per key): only letters and digits, so a crafted
+    // <zcite> cannot point the request at another endpoint ("../", "?", "&"). The skill's inject.js applies the same check
+    const invalid = [...uniqueKeys].filter((k) => !/^[A-Za-z0-9]{1,32}$/.test(k));
+    if (invalid.length > 0) {
+        throw new Error(`Invalid Zotero item key(s) in <zcite>: ${invalid.join(", ")} (letters and digits only)`);
+    }
     // Fetch CSL data from Zotero
     const cslData = await fetchCslData(uniqueKeys, zoteroApi, libraryType, userId);
+    // No placeholder citations in the user's document: a citation of a nonexistent item fails the injection,
+    // like the skill's inject.js with a key missing from metadata.json
+    const missingKeys = [...uniqueKeys].filter((k) => !cslData.has(k));
+    if (missingKeys.length > 0) {
+        throw new Error(`${missingKeys.length} cited key(s) not found in the library: ${missingKeys.join(", ")}`);
+    }
     // Replace each zcite tag with a field code
     let injected = 0;
     for (const match of matches) {

package/build/server.js

@@ -8,6 +8,7 @@ import { registerAllTools } from "./tools/index.js";
 import { logger } from "./utils/logger.js";
 import { parseUnsafeOperations } from "./utils/unsafe-operations.js";
 import { getDefaultLibrary } from "./utils/library-context.js";
+import { withRequestTimeout } from "./utils/timeouts.js";
 // Report the package version in the MCP handshake (package.json sits one level above both src/ and build/).
 const { version: SERVER_VERSION } = createRequire(import.meta.url)("../package.json");
 // Re-export for backward compatibility with existing tests
@@ -54,7 +55,8 @@ class ZoteroServer {
             // global fetch; the old lib/main-node.cjs (cross-fetch polyfill) no longer exists.
             const require = createRequire(import.meta.url);
             const { default: zoteroApiFactory } = require("zotero-api-client");
-            this.zoteroApi = zoteroApiFactory(apiKey);
+            // every request carries its own AbortSignal.timeout (TIMEOUTS.zoteroApiMs)
+            this.zoteroApi = withRequestTimeout(zoteroApiFactory(apiKey));
         }
     }
     setupHandlers() {

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

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

package/build/tools/add-items.js

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

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

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

package/build/tools/create-collection.js

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

package/build/tools/delete-collection.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { canDeleteCollections } from "../utils/unsafe-operations.js";
@@ -7,9 +8,7 @@ export const toolConfig = {
     name: "delete_collection",
     description: "Delete a collection (folder) from your Zotero library. Items inside the collection are NOT deleted — they remain in your library. Requires UNSAFE_OPERATIONS environment variable set to 'all'.",
     inputSchema: {
-        collection_key: z
-            .string()
-            .min(1)
+        collection_key: zoteroKey()
             .describe("Zotero collection key to delete. Get this from get_collections."),
         ...libraryArgsSchema,
     },

package/build/tools/delete-items.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { canDeleteItems } from "../utils/unsafe-operations.js";
@@ -9,7 +10,7 @@ export const toolConfig = {
     description: "Delete one or more items from your Zotero library: they are permanently deleted (not moved to the Zotero trash). Accepts up to 50 item keys per call. Requires UNSAFE_OPERATIONS environment variable set to 'items' or 'all'.",
     inputSchema: {
         item_keys: z
-            .array(z.string())
+            .array(zoteroKey())
             .min(1)
             .max(50)
             .describe('Array of Zotero item keys to delete (e.g. ["EUHUT5K3", "F9UQM7N2"]). Max 50 per call.'),
@@ -44,7 +45,8 @@ export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "no
                 item_keys,
             });
         }
-        const keysToDelete = [...foundKeys];
+        // only keys the caller asked for, whatever the API returned
+        const keysToDelete = item_keys.filter((k) => foundKeys.has(k));
         await zoteroApi
             .library(libraryType, libraryId)
             .items()

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse, formatEmptyResult, errorMessage, logToolError } from "../utils/error-formatter.js";
 import { attachOpenAccessPdfs } from "../utils/oa-pdf.js";
 import { fetchAllPages, fetchItemsByKeys } from "../utils/pagination.js";
@@ -8,11 +9,10 @@ export const toolConfig = {
     description: "For each Zotero item, check Unpaywall for open access PDFs and attach them. Items must have a DOI. Uses the same source as Zotero Desktop's 'Find Available PDFs'.",
     inputSchema: {
         item_keys: z
-            .array(z.string())
+            .array(zoteroKey())
             .optional()
             .describe("Array of Zotero item keys to process (mutually exclusive with collection_key)"),
-        collection_key: z
-            .string()
+        collection_key: zoteroKey()
             .optional()
             .describe("Process all items in this collection (mutually exclusive with item_keys)"),
         skip_if_attachment_exists: z

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatJsonResult, formatErrorResponse, formatEmptyResult } from "../utils/error-formatter.js";
 import { formatCreators, formatTags } from "../utils/item-formatter.js";
@@ -8,7 +9,7 @@ export const toolConfig = {
     name: "get_collection_items",
     description: "Get all items in a specific Zotero collection. Returns item keys, titles, authors, and dates. Use the collectionKey from get_collections. Use the returned item keys with get_items_details, get_item_fulltext, or inject_citations.",
     inputSchema: {
-        collectionKey: z.string().describe("The collection key/ID"),
+        collectionKey: zoteroKey().describe("The collection key/ID"),
         excludeAttachments: z
             .boolean()
             .default(true)

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

@@ -1,13 +1,16 @@
+import { InvalidJsonResponseError, readJsonObject } from "../utils/json-response.js";
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
-import { findPdfAttachment, isPdfAttachment } from "../utils/attachments.js";
+import { findPdfAttachments, isLinkedUrl, isPdfAttachment } from "../utils/attachments.js";
+import { fetchWithTimeout, isTimeoutAbort, timeoutError, TIMEOUTS } from "../utils/timeouts.js";
 export const toolConfig = {
     name: "get_item_fulltext",
     description: "Get the full text content of a Zotero item's PDF attachment via Zotero's fulltext index. Zotero desktop automatically indexes PDFs when synced. Use this to read the full content of papers instead of relying on abstracts.",
     inputSchema: {
-        item_key: z.string().describe("The Zotero item key (parent item or attachment key)"),
+        item_key: zoteroKey().describe("The Zotero item key (parent item or attachment key)"),
         max_characters: z
             .number()
             .optional()
@@ -31,11 +34,20 @@ export async function handleGetItemFulltext(zoteroApi, userId, args) {
             .items(item_key)
             .get();
         const itemData = itemResponse.getData();
-        // If the item itself is a PDF attachment, use it directly
+        // If the item itself is a PDF attachment, use it directly (a web link has no stored file)
         if (isPdfAttachment(itemData)) {
+            if (isLinkedUrl(itemData)) {
+                return formatErrorResponse("This attachment is a link to a PDF on the web (linked URL): Zotero stores no file or full text for it. Fetch the URL directly.", { item_key, url: itemData.url || undefined });
+            }
             return fetchFulltext(item_key, item_key, libraryType, libraryId, apiKey, max_characters);
         }
-        const pdfAttachment = await findPdfAttachment(zoteroApi, { type: libraryType, id: libraryId }, item_key);
+        // Stored PDFs first: linked URLs never have server-side full text, even when listed first
+        const pdfs = await findPdfAttachments(zoteroApi, { type: libraryType, id: libraryId }, item_key);
+        const pdfAttachment = pdfs.find((p) => !isLinkedUrl(p));
+        const linkedPdf = pdfs.find(isLinkedUrl);
+        if (!pdfAttachment?.key && linkedPdf) {
+            return formatErrorResponse("No stored PDF attachment found. This item only links to a PDF on the web (linked URL attachment), which Zotero does not index — fetch the linked URL directly.", { item_key, attachment_key: linkedPdf.key, url: linkedPdf.url || undefined });
+        }
         if (!pdfAttachment?.key) {
             // Provide context-aware error messages
             if (itemData.itemType === "webpage" || itemData.itemType === "blogPost") {
@@ -59,16 +71,28 @@ export async function handleGetItemFulltext(zoteroApi, userId, args) {
 }
 async function fetchFulltext(itemKey, attachmentKey, libraryType, userId, apiKey, maxCharacters) {
     const url = `https://api.zotero.org/${libraryType}s/${userId}/items/${attachmentKey}/fulltext`;
-    const response = await fetch(url, {
-        headers: { "Zotero-API-Key": apiKey },
-    });
+    const response = await fetchWithTimeout(url, { headers: { "Zotero-API-Key": apiKey } }, TIMEOUTS.zoteroApiMs, "Zotero fulltext request");
     if (response.status === 404) {
         return formatErrorResponse("Full text not indexed for this item. Open the PDF in Zotero desktop to trigger indexing, then sync.", { item_key: itemKey, attachment_key: attachmentKey });
     }
     if (!response.ok) {
         return formatErrorResponse(`Zotero fulltext API returned status ${response.status}`, { item_key: itemKey, attachment_key: attachmentKey });
     }
-    const data = (await response.json());
+    let data;
+    try {
+        data = await readJsonObject(response);
+    }
+    catch (err) {
+        if (err instanceof InvalidJsonResponseError) {
+            return formatErrorResponse(`Zotero fulltext API: ${err.message}`, { item_key: itemKey, attachment_key: attachmentKey });
+        }
+        if (!isTimeoutAbort(err))
+            throw err;
+        return formatErrorResponse(timeoutError("Zotero fulltext request", url, TIMEOUTS.zoteroApiMs).message, {
+            item_key: itemKey,
+            attachment_key: attachmentKey,
+        });
+    }
     let text = data.content;
     let truncated = false;
     if (maxCharacters > 0 && text.length > maxCharacters) {

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

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

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse, errorMessage, logToolError } from "../utils/error-formatter.js";
 import { downloadAndUploadPdf } from "../utils/pdf-uploader.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
@@ -19,13 +20,12 @@ export const toolConfig = {
             .string()
             .optional()
             .default("application/pdf")
-            .describe('MIME type of the file (default: "application/pdf")'),
-        parent_item: z
-            .string()
+            .describe('MIME type recorded on the attachment (default: "application/pdf"). This tool imports PDFs only: the downloaded file must start with %PDF- or the import is rejected, whatever this value says. Full text is extracted only for "application/pdf".'),
+        parent_item: zoteroKey()
             .optional()
             .describe("Item key of the parent item. If provided, the attachment becomes a child of that item."),
         collections: z
-            .array(z.string())
+            .array(zoteroKey())
             .optional()
             .describe("Collection keys (only used for standalone attachments, ignored when parent_item is set)"),
         tags: z
@@ -80,10 +80,12 @@ export async function handleImportPdfToZotero(zoteroApi, userId, args) {
                 case "auth_failed":
                     return formatErrorResponse("Upload authorization failed", {
                         status: result.error.status,
+                        details: result.error.networkDetail, // e.g. the timeout or connection error
                     });
                 case "upload_failed":
                     return formatErrorResponse("File upload failed", {
                         status: result.error.status,
+                        details: result.error.networkDetail, // e.g. the timeout or connection error
                     });
                 case "not_pdf":
                     return formatErrorResponse("Downloaded file is not a valid PDF", {
@@ -94,6 +96,7 @@ export async function handleImportPdfToZotero(zoteroApi, userId, args) {
                 case "registration_failed":
                     return formatErrorResponse("Upload registration failed", {
                         status: result.error.status,
+                        details: result.error.networkDetail, // e.g. the timeout or connection error
                     });
                 case "item_creation_failed":
                     return formatErrorResponse("import_pdf_to_zotero failed", {

package/build/tools/inject-citations.js

@@ -27,7 +27,7 @@ Supported attributes (any order):
   - 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.
+A new .docx file (original filename with _cited suffix) with Zotero field codes and a ZOTERO_BIBL bibliography at the end. A cited key that is not in the library, or that is not letters and digits only, is an error and no file is written.
 
 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: {

package/build/utils/attachments.js

@@ -2,8 +2,19 @@ import { asArray } from "./pagination.js";
 export function isPdfAttachment(item) {
     return item.itemType === "attachment" && item.contentType === "application/pdf";
 }
+/**
+ * A link to a PDF on the web (linkMode "linked_url"): Zotero stores no file for it, so it has no
+ * full text on the server and cannot be opened or indexed in Zotero desktop.
+ */
+export function isLinkedUrl(item) {
+    return item.linkMode === "linked_url";
+}
+/** All PDF attachments (stored files and links) among the children of an item. */
+export async function findPdfAttachments(zoteroApi, library, itemKey) {
+    const response = await zoteroApi.library(library.type, library.id).items(itemKey).children().get();
+    return asArray(response.getData()).filter(isPdfAttachment);
+}
 /** First PDF attachment among the children of an item, if any. */
 export async function findPdfAttachment(zoteroApi, library, itemKey) {
-    const response = await zoteroApi.library(library.type, library.id).items(itemKey).children().get();
-    return asArray(response.getData()).find(isPdfAttachment);
+    return (await findPdfAttachments(zoteroApi, library, itemKey))[0];
 }

package/build/utils/doi-resolver.js

@@ -1,17 +1,26 @@
 import { mapWithConcurrency } from "./concurrency.js";
 import { fetchWithRetry } from "./fetch-retry.js";
 import { errorMessage } from "./error-formatter.js";
+import { InvalidJsonResponseError, readJsonObject } from "./json-response.js";
 export async function resolveDoi(doi) {
     const response = await fetchWithRetry(`https://doi.org/${encodeURIComponent(doi)}`, {
         headers: {
             Accept: "application/vnd.citationstyles.csl+json",
         },
         redirect: "follow",
-    });
+    }, { label: "DOI resolution" });
     if (!response.ok) {
         throw new Error(`DOI resolution failed for ${doi}: ${response.status} ${response.statusText}`);
     }
-    return (await response.json());
+    try {
+        return await readJsonObject(response);
+    }
+    catch (err) {
+        // doi.org answers some unresolvable DOIs with an HTML page and status 200
+        if (err instanceof InvalidJsonResponseError)
+            throw new Error(`DOI not found or not resolvable: ${doi} (${err.message})`);
+        throw err;
+    }
 }
 export async function resolveDois(dois, concurrency) {
     const settled = await mapWithConcurrency(dois, (doi) => resolveDoi(doi), concurrency);

package/build/utils/fetch-retry.js

@@ -1,3 +1,4 @@
+import { fetchWithTimeout, TIMEOUTS } from "./timeouts.js";
 const DEFAULT_MAX_RETRIES = 3;
 const DEFAULT_BASE_DELAY_MS = 1000;
 const DEFAULT_RETRYABLE_STATUSES = [429, 503];
@@ -21,7 +22,7 @@ export async function fetchWithRetry(url, init, options) {
     const retryableStatuses = options?.retryableStatuses ?? DEFAULT_RETRYABLE_STATUSES;
     let lastResponse;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        const response = await fetch(url, init);
+        const response = await fetchWithTimeout(url, init ?? {}, options?.timeoutMs ?? TIMEOUTS.metadataMs, options?.label ?? "Request");
         lastResponse = response;
         if (!retryableStatuses.includes(response.status) || attempt === maxRetries) {
             return response;

package/build/utils/item-formatter.js

@@ -1,6 +1,7 @@
 export function formatCreators(creators) {
     return (creators
-        ?.map((c) => `${c.firstName || ""} ${c.lastName || ""}`.trim())
+        // single-field names (institutions, consortia) are stored in `name`
+        ?.map((c) => (c.name?.trim() || `${c.firstName || ""} ${c.lastName || ""}`.trim()))
         .filter(Boolean)
         .join(", ") || "No authors listed");
 }

package/build/utils/json-response.js

@@ -0,0 +1,29 @@
+/**
+ * A response body that is not the JSON object the API documents: an HTML error or landing page (doi.org answers
+ * an unresolvable DOI with HTML), an empty body, or a bare value. The message names the status and content type,
+ * never the raw JSON.parse error.
+ */
+export class InvalidJsonResponseError extends Error {
+    status;
+    constructor(response) {
+        const type = response.headers?.get?.("content-type")?.split(";")[0].trim();
+        super(`response is not a JSON object (HTTP ${response.status}${type ? `, ${type}` : ""})`);
+        this.name = "InvalidJsonResponseError";
+        this.status = response.status;
+    }
+}
+/** Body of `response` as a JSON object; InvalidJsonResponseError otherwise. Timeouts while reading propagate. */
+export async function readJsonObject(response) {
+    let data;
+    try {
+        data = await response.json();
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            throw new InvalidJsonResponseError(response);
+        throw err;
+    }
+    if (data === null || typeof data !== "object" || Array.isArray(data))
+        throw new InvalidJsonResponseError(response);
+    return data;
+}

package/build/utils/pagination.js

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

package/build/utils/pdf-uploader.js

@@ -1,9 +1,11 @@
+import { InvalidJsonResponseError, readJsonObject } from "./json-response.js";
 import { createHash } from "node:crypto";
 import { logger } from "./logger.js";
 import { extractPdfText } from "./pdf-text-extractor.js";
 import { putFulltext } from "./zotero-fulltext.js";
 import { formatWriteErrors } from "./write-results.js";
 import { errorMessage } from "./error-formatter.js";
+import { fetchWithTimeout, isTimeoutAbort, timeoutError, RequestTimeoutError, TIMEOUTS } from "./timeouts.js";
 const MAX_FILE_SIZE = 100 * 1024 * 1024; // 100 MB
 function safeBasename(name) {
     return (name.split(/[\\/]/).pop() ?? "").replace(/[\x00-\x1f"]/g, "").trim();
@@ -53,11 +55,7 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
     // 1. Download the file
     let downloadResponse;
     try {
-        downloadResponse = await fetch(options.url, {
-            headers: {
-                "User-Agent": "mcp-zotero/1.0 (Open Access PDF retrieval)",
-            },
-        });
+        downloadResponse = await fetchWithTimeout(options.url, { headers: { "User-Agent": "mcp-zotero/1.0 (Open Access PDF retrieval)" } }, TIMEOUTS.pdfTransferMs, "PDF download");
     }
     catch (err) {
         const detail = errorMessage(err);
@@ -87,8 +85,18 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
             contentType: responseContentType,
         });
     }
-    const arrayBuffer = await downloadResponse.arrayBuffer();
-    const buffer = Buffer.from(arrayBuffer);
+    let buffer;
+    try {
+        buffer = Buffer.from(await downloadResponse.arrayBuffer());
+    }
+    catch (err) {
+        // the download bound also covers the body: a server that stalls mid-file ends here
+        const detail = isTimeoutAbort(err) ? timeoutError("PDF download", options.url, TIMEOUTS.pdfTransferMs).message : errorMessage(err);
+        return {
+            success: false,
+            error: { code: "network_error", message: `Network error downloading file: ${detail}.`, networkDetail: detail },
+        };
+    }
     const filename = options.filename ??
         resolvePdfFilename(options.url, downloadResponse.headers.get("content-disposition"), options.doi);
     const title = options.title ?? filename;
@@ -179,7 +187,7 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
     });
     let authResponse;
     try {
-        authResponse = await fetch(authUrl, {
+        authResponse = await fetchWithTimeout(authUrl, {
             method: "POST",
             headers: {
                 "Zotero-API-Key": apiKey,
@@ -187,7 +195,7 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
                 "If-None-Match": "*",
             },
             body: authBody.toString(),
-        });
+        }, TIMEOUTS.zoteroApiMs, "Upload authorization");
     }
     catch (err) {
         const detail = errorMessage(err);
@@ -223,7 +231,19 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
             },
         };
     }
-    const authData = (await authResponse.json());
+    let authData;
+    try {
+        authData = await readJsonObject(authResponse);
+    }
+    catch (err) {
+        if (!(err instanceof InvalidJsonResponseError))
+            throw err;
+        return {
+            success: false,
+            itemKey,
+            error: { code: "auth_failed", message: `Upload authorization failed: ${err.message}`, status: authResponse.status, networkDetail: err.message },
+        };
+    }
     // 6-7. Upload binary + register (skip if already exists)
     if (!("exists" in authData)) {
         const auth = authData;
@@ -232,11 +252,11 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
         const uploadBody = Buffer.concat([prefix, buffer, suffix]);
         let uploadResponse;
         try {
-            uploadResponse = await fetch(auth.url, {
+            uploadResponse = await fetchWithTimeout(auth.url, {
                 method: "POST",
                 headers: { "Content-Type": auth.contentType },
                 body: uploadBody,
-            });
+            }, TIMEOUTS.pdfTransferMs, "File upload");
         }
         catch (err) {
             const detail = errorMessage(err);
@@ -263,7 +283,7 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
         }
         let registerResponse;
         try {
-            registerResponse = await fetch(authUrl, {
+            registerResponse = await fetchWithTimeout(authUrl, {
                 method: "POST",
                 headers: {
                     "Zotero-API-Key": apiKey,
@@ -271,7 +291,7 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
                     "If-None-Match": "*",
                 },
                 body: `upload=${auth.uploadKey}`,
-            });
+            }, TIMEOUTS.zoteroApiMs, "Upload registration");
         }
         catch (err) {
             const detail = errorMessage(err);
@@ -309,8 +329,11 @@ export async function downloadAndUploadPdf(zoteroApi, libraryType, userId, apiKe
                 ? "Fulltext indexed successfully. Use get_item_fulltext to retrieve content."
                 : `Fulltext PUT failed: ${putResult.error}. Sync with Zotero Desktop to index the PDF.`;
         }
-        catch {
-            fulltextStatus = "PDF text extraction failed. Sync with Zotero Desktop to index the PDF.";
+        catch (err) {
+            fulltextStatus =
+                err instanceof RequestTimeoutError
+                    ? `Fulltext indexing failed: ${err.message}. Sync with Zotero Desktop to index the PDF.`
+                    : "PDF text extraction failed. Sync with Zotero Desktop to index the PDF.";
         }
     }
     else {

package/build/utils/timeouts.js

@@ -0,0 +1,97 @@
+/**
+ * Bounds for every network call the server makes. A remote that accepts the connection and then
+ * never answers would otherwise block a tool until the MCP client gives up, with no useful error.
+ * Values are read at call time, so tests can lower them.
+ */
+export const TIMEOUTS = {
+    /** Zotero Web API: metadata reads/writes, fulltext, upload authorization and registration. */
+    zoteroApiMs: 30_000,
+    /** DOI resolution (doi.org / Crossref) and Unpaywall lookups, per attempt. */
+    metadataMs: 30_000,
+    /**
+     * PDF download and upload to Zotero storage, body included. Files are capped at 100 MB, so this
+     * allows ~0.6 MB/s for the largest file; typical papers (1-10 MB) finish in seconds.
+     */
+    pdfTransferMs: 180_000,
+};
+/** A network call that hit its bound. The message names the operation, host and bound. */
+export class RequestTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RequestTimeoutError";
+    }
+}
+/** True for the abort raised by AbortSignal.timeout (DOMException "TimeoutError"). */
+export function isTimeoutAbort(err) {
+    return typeof err === "object" && err !== null && err.name === "TimeoutError";
+}
+function host(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+}
+function seconds(ms) {
+    return `${ms / 1000} s`;
+}
+export function timeoutError(label, url, timeoutMs) {
+    return new RequestTimeoutError(`${label} timed out after ${seconds(timeoutMs)} (${host(url)})`);
+}
+/** Signal that aborts after `timeoutMs`, combined with the caller's signal when there is one. */
+export function timeoutSignal(timeoutMs, signal) {
+    const bound = AbortSignal.timeout(timeoutMs);
+    return signal ? AbortSignal.any([signal, bound]) : bound;
+}
+/**
+ * fetch() with a bound. The signal stays attached to the response, so reading the body is bounded
+ * too: callers that read it should map isTimeoutAbort() errors with timeoutError().
+ */
+export async function fetchWithTimeout(url, init, timeoutMs, label) {
+    try {
+        return await fetch(url, { ...init, signal: timeoutSignal(timeoutMs, init.signal) });
+    }
+    catch (err) {
+        if (isTimeoutAbort(err))
+            throw timeoutError(label, url, timeoutMs);
+        throw err;
+    }
+}
+const VERB_OPTS_INDEX = { get: 0, post: 1, put: 1, patch: 1, delete: 1 };
+/**
+ * Wraps a zotero-api-client instance so every request carries a fresh AbortSignal.timeout
+ * (the client forwards `signal` to fetch). Chain methods return wrapped chains; terminal verbs get
+ * the signal merged into their options, and a timeout becomes a RequestTimeoutError.
+ */
+export function withRequestTimeout(api, timeoutMs) {
+    return new Proxy(api, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function" || typeof prop !== "string")
+                return value;
+            const optsIndex = VERB_OPTS_INDEX[prop];
+            if (optsIndex === undefined) {
+                return (...args) => {
+                    const result = value.apply(target, args);
+                    return result && typeof result === "object" ? withRequestTimeout(result, timeoutMs) : result;
+                };
+            }
+            return async (...args) => {
+                const bound = timeoutMs ?? TIMEOUTS.zoteroApiMs;
+                const opts = (args[optsIndex] ?? {});
+                const callArgs = [...args];
+                callArgs[optsIndex] = { ...opts, signal: timeoutSignal(bound, opts.signal) };
+                try {
+                    return await value.apply(target, callArgs);
+                }
+                catch (err) {
+                    if (isTimeoutAbort(err)) {
+                        throw new RequestTimeoutError(`Zotero API request (${prop.toUpperCase()}) timed out after ${seconds(bound)} (api.zotero.org)`);
+                    }
+                    throw err;
+                }
+            };
+        },
+    });
+}

package/build/utils/unpaywall.js

@@ -1,3 +1,4 @@
+import { InvalidJsonResponseError, readJsonObject } from "./json-response.js";
 import { fetchWithRetry } from "./fetch-retry.js";
 import { logger } from "./logger.js";
 import { errorMessage } from "./error-formatter.js";
@@ -28,7 +29,7 @@ export async function lookupOaPdfWithFallbacks(doi) {
     const url = `https://api.unpaywall.org/v2/${encodeURIComponent(doi)}?email=${encodeURIComponent(email)}`;
     let response;
     try {
-        response = await fetchWithRetry(url);
+        response = await fetchWithRetry(url, undefined, { label: "Unpaywall lookup" });
     }
     catch (err) {
         const detail = errorMessage(err);
@@ -39,7 +40,16 @@ export async function lookupOaPdfWithFallbacks(doi) {
         logger.error("Unpaywall API error", { doi, status: response.status });
         return { primary: { ...UNAVAILABLE_RESULT }, fallback_urls: [] };
     }
-    const data = (await response.json());
+    let data;
+    try {
+        data = await readJsonObject(response);
+    }
+    catch (err) {
+        if (!(err instanceof InvalidJsonResponseError))
+            throw err;
+        logger.error("Unpaywall API returned an invalid response", { doi, error: err.message });
+        return { primary: { ...UNAVAILABLE_RESULT }, fallback_urls: [] };
+    }
     const locations = data.is_oa
         ? [data.best_oa_location, ...(data.oa_locations ?? [])].filter((l) => l !== null && l !== undefined)
         : [];

package/build/utils/zotero-fulltext.js

@@ -1,6 +1,7 @@
+import { fetchWithTimeout, TIMEOUTS } from "./timeouts.js";
 export async function putFulltext(libraryType, userId, itemKey, apiKey, content, totalPages) {
     const url = `https://api.zotero.org/${libraryType}s/${userId}/items/${itemKey}/fulltext`;
-    const response = await fetch(url, {
+    const response = await fetchWithTimeout(url, {
         method: "PUT",
         headers: {
             "Content-Type": "application/json",
@@ -11,7 +12,7 @@ export async function putFulltext(libraryType, userId, itemKey, apiKey, content,
             indexedPages: totalPages,
             totalPages,
         }),
-    });
+    }, TIMEOUTS.zoteroApiMs, "Zotero fulltext upload");
     if (response.status === 204) {
         return { success: true };
     }

package/build/utils/zotero-keys.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+/** Zotero object keys (items, collections): 8 characters from this alphabet, never 0, 1, O or lowercase. */
+export const ZOTERO_KEY = /^[23456789ABCDEFGHIJKLMNPQRSTUVWXYZ]{8}$/;
+export const INVALID_KEY_MESSAGE = "Invalid Zotero key: expected 8 characters from 23456789ABCDEFGHIJKLMNPQRSTUVWXYZ";
+/**
+ * Schema for every key argument of every tool. Keys end up in API URL paths (zotero-api-client does not
+ * encode path segments, and URL parsing resolves "..") and in itemKey filters (ignored by the API when
+ * no key is well-formed): a malformed key must be rejected before any request.
+ */
+export const zoteroKey = () => z.string().regex(ZOTERO_KEY, INVALID_KEY_MESSAGE);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xevos117/mcp-zotero",
   "type": "module",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Unofficial MCP server for Zotero integration with citation management",
   "repository": {
     "type": "git",
@@ -28,7 +28,9 @@
     "smoke": "node scripts/smoke-stdio.mjs",
     "start": "node build/server.js",
     "prepublishOnly": "npm test && npm run build",
-    "test:e2e": "npm run build && vitest run --config vitest.e2e.config.ts"
+    "test:e2e": "npm run build && vitest run --config vitest.e2e.config.ts",
+    "test:live": "npm run build && vitest run --config vitest.live.config.ts",
+    "test:live:cleanup": "node test/live/cleanup.mjs"
   },
   "keywords": [
     "mcp",
@@ -53,7 +55,10 @@
     "zotero-api-client": "^0.51.0"
   },
   "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.296",
     "@types/node": "^26.6.4",
+    "ajv": "^8.20.0",
+    "citeproc": "^2.4.63",
     "typescript": "^7.0.2",
     "vitest": "^5.0.3"
   }