@xevos117/mcp-zotero 1.0.8 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  import { z } from "zod";
2
- import { isZoteroApiError } from "../types/zotero-types.js";
3
- import { formatErrorResponse } from "../utils/error-formatter.js";
4
- import { logger } from "../utils/logger.js";
2
+ import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
3
+ import { formatWriteErrors } from "../utils/write-results.js";
4
+ import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
5
5
  export const toolConfig = {
6
6
  name: "create_collection",
7
7
  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.",
@@ -11,53 +11,34 @@ export const toolConfig = {
11
11
  .string()
12
12
  .optional()
13
13
  .describe("Zotero collection key of the parent collection. Get this from get_collections."),
14
+ ...libraryArgsSchema,
14
15
  },
15
16
  };
16
17
  const CreateCollectionSchema = z.object(toolConfig.inputSchema);
17
18
  export async function handleCreateCollection(zoteroApi, userId, args) {
18
- const { name, parent_collection } = CreateCollectionSchema.parse(args);
19
+ const { name, parent_collection, library_type, library_id } = CreateCollectionSchema.parse(args);
20
+ const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
19
21
  if (!name?.trim()) {
20
22
  return formatErrorResponse("Collection name is required");
21
23
  }
22
- try {
23
- const collectionData = { name: name.trim() };
24
- if (parent_collection) {
25
- collectionData.parentCollection = parent_collection;
26
- }
27
- const response = await zoteroApi
28
- .library("user", userId)
29
- .collections()
30
- .post([collectionData]);
31
- if (!response.isSuccess()) {
32
- const errors = response.getErrors();
33
- const errorMsg = Object.values(errors).join("; ") || "Unknown error";
34
- return formatErrorResponse("Failed to create collection", {
35
- details: errorMsg,
36
- });
37
- }
38
- const created = response.getData();
39
- const collection = created[0];
40
- return {
41
- content: [
42
- {
43
- type: "text",
44
- text: JSON.stringify({
45
- collection_key: collection.key,
46
- name: collection.name,
47
- }, null, 2),
48
- },
49
- ],
50
- };
24
+ const collectionData = { name: name.trim() };
25
+ if (parent_collection) {
26
+ collectionData.parentCollection = parent_collection;
51
27
  }
52
- catch (err) {
53
- if (isZoteroApiError(err)) {
54
- logger.error("Tool execution failed", {
55
- tool: "create_collection",
56
- status: err.response?.status,
57
- errorMessage: err.message,
58
- url: err.response?.url,
59
- });
60
- }
61
- throw err;
28
+ const response = await zoteroApi
29
+ .library(libraryType, libraryId)
30
+ .collections()
31
+ .post([collectionData]);
32
+ if (!response.isSuccess()) {
33
+ const errorMsg = formatWriteErrors(response.getErrors());
34
+ return formatErrorResponse("Failed to create collection", {
35
+ details: errorMsg,
36
+ });
62
37
  }
38
+ const created = response.getData();
39
+ const collection = created[0];
40
+ return formatJsonResult({
41
+ collection_key: collection.key,
42
+ name: collection.name,
43
+ });
63
44
  }
@@ -1,8 +1,8 @@
1
1
  import { z } from "zod";
2
2
  import { isZoteroApiError } from "../types/zotero-types.js";
3
- import { formatErrorResponse } from "../utils/error-formatter.js";
3
+ import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
4
4
  import { canDeleteCollections } from "../utils/unsafe-operations.js";
5
- import { logger } from "../utils/logger.js";
5
+ import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
6
6
  export const toolConfig = {
7
7
  name: "delete_collection",
8
8
  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'.",
@@ -11,11 +11,13 @@ export const toolConfig = {
11
11
  .string()
12
12
  .min(1)
13
13
  .describe("Zotero collection key to delete. Get this from get_collections."),
14
+ ...libraryArgsSchema,
14
15
  },
15
16
  };
16
17
  const DeleteCollectionSchema = z.object(toolConfig.inputSchema);
17
18
  export async function handleDeleteCollection(zoteroApi, userId, args, unsafeOps = "none") {
18
- const { collection_key } = DeleteCollectionSchema.parse(args);
19
+ const { collection_key, library_type, library_id } = DeleteCollectionSchema.parse(args);
20
+ const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
19
21
  if (!canDeleteCollections(unsafeOps)) {
20
22
  return formatErrorResponse("Deletion of collections is not allowed. Set the UNSAFE_OPERATIONS environment variable to 'all' to enable this operation.", {
21
23
  env_var: "UNSAFE_OPERATIONS",
@@ -25,7 +27,7 @@ export async function handleDeleteCollection(zoteroApi, userId, args, unsafeOps
25
27
  }
26
28
  try {
27
29
  const response = await zoteroApi
28
- .library("user", userId)
30
+ .library(libraryType, libraryId)
29
31
  .collections(collection_key)
30
32
  .get();
31
33
  const collection = response.getData();
@@ -36,22 +38,15 @@ export async function handleDeleteCollection(zoteroApi, userId, args, unsafeOps
36
38
  });
37
39
  }
38
40
  await zoteroApi
39
- .library("user", userId)
41
+ .library(libraryType, libraryId)
40
42
  .collections(collection_key)
41
43
  .version(version)
42
44
  .delete();
43
- return {
44
- content: [
45
- {
46
- type: "text",
47
- text: JSON.stringify({
48
- deleted: true,
49
- collection_key,
50
- name: collection.name || collection_key,
51
- }, null, 2),
52
- },
53
- ],
54
- };
45
+ return formatJsonResult({
46
+ deleted: true,
47
+ collection_key,
48
+ name: collection.name || collection_key,
49
+ });
55
50
  }
56
51
  catch (err) {
57
52
  if (isZoteroApiError(err)) {
@@ -67,12 +62,6 @@ export async function handleDeleteCollection(zoteroApi, userId, args, unsafeOps
67
62
  status: "version_conflict",
68
63
  });
69
64
  }
70
- logger.error("Tool execution failed", {
71
- tool: "delete_collection",
72
- status: err.response.status,
73
- errorMessage: err.message,
74
- url: err.response.url,
75
- });
76
65
  }
77
66
  throw err;
78
67
  }
@@ -1,22 +1,25 @@
1
1
  import { z } from "zod";
2
2
  import { isZoteroApiError } from "../types/zotero-types.js";
3
- import { formatErrorResponse } from "../utils/error-formatter.js";
3
+ import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
4
4
  import { canDeleteItems } from "../utils/unsafe-operations.js";
5
- import { logger } from "../utils/logger.js";
5
+ import { fetchItemsByKeys } from "../utils/pagination.js";
6
+ import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
6
7
  export const toolConfig = {
7
8
  name: "delete_items",
8
- description: "Delete one or more items from your Zotero library permanently (moves to trash). Accepts up to 50 item keys per call. Requires UNSAFE_OPERATIONS environment variable set to 'items' or 'all'.",
9
+ 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'.",
9
10
  inputSchema: {
10
11
  item_keys: z
11
12
  .array(z.string())
12
13
  .min(1)
13
14
  .max(50)
14
15
  .describe('Array of Zotero item keys to delete (e.g. ["EUHUT5K3", "F9UQM7N2"]). Max 50 per call.'),
16
+ ...libraryArgsSchema,
15
17
  },
16
18
  };
17
19
  const DeleteItemsSchema = z.object(toolConfig.inputSchema);
18
20
  export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "none") {
19
- const { item_keys } = DeleteItemsSchema.parse(args);
21
+ const { item_keys, library_type, library_id } = DeleteItemsSchema.parse(args);
22
+ const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
20
23
  if (!canDeleteItems(unsafeOps)) {
21
24
  return formatErrorResponse("Deletion of items is not allowed. Set the UNSAFE_OPERATIONS environment variable to 'items' or 'all' to enable this operation.", {
22
25
  env_var: "UNSAFE_OPERATIONS",
@@ -25,13 +28,8 @@ export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "no
25
28
  });
26
29
  }
27
30
  try {
28
- const response = await zoteroApi
29
- .library("user", userId)
30
- .items()
31
- .get({ itemKey: item_keys.join(",") });
32
- const items = response.getData();
33
- const itemList = Array.isArray(items) ? items : [items];
34
- const foundKeys = new Set(itemList.map((item) => item.key).filter(Boolean));
31
+ const { items, version: libraryVersion } = await fetchItemsByKeys((params) => zoteroApi.library(libraryType, libraryId).items().get(params), item_keys);
32
+ const foundKeys = new Set(items.map((item) => item.key).filter(Boolean));
35
33
  const notFoundKeys = item_keys.filter((k) => !foundKeys.has(k));
36
34
  if (foundKeys.size === 0) {
37
35
  return formatErrorResponse("No items found for the given keys", {
@@ -41,7 +39,6 @@ export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "no
41
39
  }
42
40
  // Use library version from response header (Last-Modified-Version),
43
41
  // not individual item versions — required for multi-object DELETE
44
- const libraryVersion = response.getVersion();
45
42
  if (libraryVersion === null) {
46
43
  return formatErrorResponse("Could not determine library version", {
47
44
  item_keys,
@@ -49,7 +46,7 @@ export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "no
49
46
  }
50
47
  const keysToDelete = [...foundKeys];
51
48
  await zoteroApi
52
- .library("user", userId)
49
+ .library(libraryType, libraryId)
53
50
  .items()
54
51
  .version(libraryVersion)
55
52
  .delete(keysToDelete);
@@ -60,14 +57,7 @@ export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "no
60
57
  if (notFoundKeys.length > 0) {
61
58
  result.not_found = notFoundKeys;
62
59
  }
63
- return {
64
- content: [
65
- {
66
- type: "text",
67
- text: JSON.stringify(result, null, 2),
68
- },
69
- ],
70
- };
60
+ return formatJsonResult(result);
71
61
  }
72
62
  catch (err) {
73
63
  if (isZoteroApiError(err)) {
@@ -77,12 +67,6 @@ export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "no
77
67
  status: "version_conflict",
78
68
  });
79
69
  }
80
- logger.error("Tool execution failed", {
81
- tool: "delete_items",
82
- status: err.response.status,
83
- errorMessage: err.message,
84
- url: err.response.url,
85
- });
86
70
  }
87
71
  throw err;
88
72
  }
@@ -1,11 +1,8 @@
1
1
  import { z } from "zod";
2
- import { isZoteroApiError } from "../types/zotero-types.js";
3
- import { formatErrorResponse } from "../utils/error-formatter.js";
4
- import { logger } from "../utils/logger.js";
5
- import { lookupOaPdfWithFallbacks } from "../utils/unpaywall.js";
6
- import { downloadAndUploadPdf } from "../utils/pdf-uploader.js";
7
- import { mapWithConcurrency } from "../utils/concurrency.js";
8
- import { fetchAllPages } from "../utils/pagination.js";
2
+ import { formatJsonResult, formatErrorResponse, formatEmptyResult, errorMessage, logToolError } from "../utils/error-formatter.js";
3
+ import { attachOpenAccessPdfs } from "../utils/oa-pdf.js";
4
+ import { fetchAllPages, fetchItemsByKeys } from "../utils/pagination.js";
5
+ import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
9
6
  export const toolConfig = {
10
7
  name: "find_and_attach_pdfs",
11
8
  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'.",
@@ -26,11 +23,13 @@ export const toolConfig = {
26
23
  .boolean()
27
24
  .default(false)
28
25
  .describe("Only report which PDFs are available without downloading/attaching"),
26
+ ...libraryArgsSchema,
29
27
  },
30
28
  };
31
29
  const FindAndAttachPdfsSchema = z.object(toolConfig.inputSchema);
32
30
  export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
33
- const { item_keys, collection_key, skip_if_attachment_exists, dry_run } = FindAndAttachPdfsSchema.parse(args);
31
+ const { item_keys, collection_key, skip_if_attachment_exists, dry_run, library_type, library_id } = FindAndAttachPdfsSchema.parse(args);
32
+ const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
34
33
  // Validate: exactly one of item_keys or collection_key
35
34
  if (item_keys && collection_key) {
36
35
  return formatErrorResponse("Provide either item_keys or collection_key, not both");
@@ -46,7 +45,7 @@ export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
46
45
  // 1. Resolve item keys
47
46
  let keys;
48
47
  if (collection_key) {
49
- const { items: collItems } = await fetchAllPages((params) => zoteroApi.library("user", userId).collections(collection_key).items().get(params));
48
+ const { items: collItems } = await fetchAllPages((params) => zoteroApi.library(libraryType, libraryId).collections(collection_key).items().get(params));
50
49
  keys = collItems
51
50
  .filter((item) => item.itemType !== "attachment" && item.itemType !== "note")
52
51
  .map((item) => item.key)
@@ -56,148 +55,77 @@ export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
56
55
  keys = item_keys;
57
56
  }
58
57
  if (keys.length === 0) {
59
- return formatErrorResponse("No items to process");
58
+ return formatEmptyResult("No items to process");
60
59
  }
61
60
  // 2. Batch-fetch item metadata to get DOIs
62
- const metaResponse = await zoteroApi
63
- .library("user", userId)
64
- .items()
65
- .get({ itemKey: keys.join(",") });
66
- const metaItems = metaResponse.getData();
67
- const itemsArray = Array.isArray(metaItems) ? metaItems : [metaItems];
61
+ const { items: metaItems } = await fetchItemsByKeys((params) => zoteroApi.library(libraryType, libraryId).items().get(params), keys);
68
62
  const itemMap = new Map();
69
- for (const item of itemsArray) {
63
+ for (const item of metaItems) {
70
64
  if (item.key) {
71
65
  itemMap.set(item.key, item);
72
66
  }
73
67
  }
74
- // 3. Process each item in parallel
75
- const settled = await mapWithConcurrency(keys, async (key) => {
68
+ // 3. Items without metadata or DOI are reported directly; the others go through the shared pipeline
69
+ const preResults = new Map();
70
+ const targets = [];
71
+ for (const key of keys) {
76
72
  const item = itemMap.get(key);
77
- if (!item) {
78
- return { item_key: key, doi: null, status: "error", reason: "Item not found" };
79
- }
80
- const doi = item.DOI ?? null;
81
- if (!doi) {
82
- return { item_key: key, doi: null, status: "error", reason: "No DOI" };
83
- }
84
- // Check for existing attachments
85
- if (skip_if_attachment_exists) {
86
- const childrenResponse = await zoteroApi
87
- .library("user", userId)
88
- .items(key)
89
- .children()
90
- .get();
91
- const children = childrenResponse.getData();
92
- const childrenArray = Array.isArray(children) ? children : [children];
93
- const hasPdf = childrenArray.some((child) => child.itemType === "attachment" && child.contentType === "application/pdf");
94
- if (hasPdf) {
95
- return { item_key: key, doi, status: "skipped", reason: "PDF attachment already exists" };
96
- }
97
- }
98
- // Lookup OA PDF
99
- const { primary, fallback_urls } = await lookupOaPdfWithFallbacks(doi);
100
- if (!primary.found || !primary.pdf_url) {
101
- let reason;
102
- if (primary.warning) {
103
- reason = primary.warning;
104
- }
105
- else if (primary.landing_url) {
106
- reason = "Open access copy exists at a repository but no direct PDF link is available. If the user needs this PDF, they can download it manually from the landing page and use import_pdf_to_zotero to attach it.";
107
- }
108
- else if (primary.oa_status) {
109
- reason = `OA status: ${primary.oa_status}`;
110
- }
111
- else {
112
- reason = "No open access PDF found";
113
- }
114
- return {
115
- item_key: key,
116
- doi,
117
- status: "not_found",
118
- reason,
119
- ...(primary.landing_url ? { landing_url: primary.landing_url } : {}),
120
- ...(primary.oa_status ? { oa_status: primary.oa_status } : {}),
121
- };
122
- }
123
- if (dry_run) {
124
- return {
125
- item_key: key,
126
- doi,
127
- status: "available",
128
- source: primary.source ?? undefined,
129
- pdf_url: primary.pdf_url,
130
- };
131
- }
132
- // Try primary URL, then fallbacks
133
- const urlsToTry = [primary.pdf_url, ...fallback_urls];
134
- for (const pdfUrl of urlsToTry) {
135
- const uploadResult = await downloadAndUploadPdf(zoteroApi, userId, apiKey, {
136
- url: pdfUrl,
137
- parentItem: key,
138
- });
139
- if (uploadResult.success) {
140
- return {
141
- item_key: key,
142
- doi,
143
- status: "attached",
144
- source: primary.source ?? undefined,
145
- pdf_url: pdfUrl,
146
- };
147
- }
148
- }
149
- return {
150
- item_key: key,
151
- doi,
152
- status: "error",
153
- reason: `Download failed for all ${urlsToTry.length} URL(s)`,
154
- source: primary.source ?? undefined,
155
- };
73
+ if (!item)
74
+ preResults.set(key, { item_key: key, doi: null, status: "error", reason: "Item not found" });
75
+ else if (!item.DOI)
76
+ preResults.set(key, { item_key: key, doi: null, status: "error", reason: "No DOI" });
77
+ else
78
+ targets.push({ itemKey: key, doi: item.DOI });
79
+ }
80
+ const pipelineResults = await attachOpenAccessPdfs(targets, {
81
+ zoteroApi,
82
+ library: { type: libraryType, id: libraryId },
83
+ apiKey,
84
+ skipIfPdfExists: skip_if_attachment_exists,
85
+ dryRun: dry_run,
86
+ });
87
+ const byKey = new Map(pipelineResults.map((r) => [r.item_key, r]));
88
+ const results = keys.flatMap((key) => {
89
+ const r = preResults.get(key) ?? byKey.get(key);
90
+ if (!r)
91
+ return []; // not started: storage quota exhausted
92
+ return [r.url_used ? { ...r, pdf_url: r.url_used } : r];
156
93
  });
157
- const results = settled
158
- .filter((r) => r.status === "fulfilled")
159
- .map((r) => r.value);
160
94
  let attached = 0;
161
95
  let notFound = 0;
162
96
  let skipped = 0;
163
97
  let errors = 0;
98
+ let quotaExceeded = 0;
164
99
  for (const r of results) {
165
100
  if (r.status === "attached")
166
101
  attached++;
167
- else if (r.status === "not_found")
102
+ else if (r.status === "not_found" || r.status === "landing_page_only")
168
103
  notFound++;
169
104
  else if (r.status === "skipped")
170
105
  skipped++;
171
106
  else if (r.status === "error")
172
107
  errors++;
108
+ else if (r.status === "quota_exceeded")
109
+ quotaExceeded++;
173
110
  }
174
- return {
175
- content: [
176
- {
177
- type: "text",
178
- text: JSON.stringify({
179
- processed: keys.length,
180
- attached,
181
- not_found: notFound,
182
- skipped,
183
- errors,
184
- dry_run,
185
- results,
186
- }, null, 2),
187
- },
188
- ],
189
- };
111
+ return formatJsonResult({
112
+ processed: keys.length,
113
+ attached,
114
+ not_found: notFound,
115
+ skipped,
116
+ errors,
117
+ quota_exceeded: quotaExceeded,
118
+ dry_run,
119
+ ...(quotaExceeded > 0
120
+ ? {
121
+ storage_quota_warning: "Zotero storage quota is full. Remaining PDF uploads were skipped. Free up space at https://www.zotero.org/settings/storage or upgrade your plan.",
122
+ }
123
+ : {}),
124
+ results,
125
+ });
190
126
  }
191
127
  catch (err) {
192
- if (isZoteroApiError(err)) {
193
- logger.error("Tool execution failed", {
194
- tool: "find_and_attach_pdfs",
195
- status: err.response?.status,
196
- errorMessage: err.message,
197
- url: err.response?.url,
198
- });
199
- }
200
- const message = err instanceof Error ? err.message : String(err);
201
- return formatErrorResponse("find_and_attach_pdfs failed", { details: message });
128
+ logToolError("find_and_attach_pdfs", err);
129
+ return formatErrorResponse("find_and_attach_pdfs failed", { details: errorMessage(err) });
202
130
  }
203
131
  }
@@ -1,9 +1,9 @@
1
1
  import { z } from "zod";
2
2
  import { isZoteroApiError } from "../types/zotero-types.js";
3
- import { formatErrorResponse } from "../utils/error-formatter.js";
3
+ import { formatJsonResult, formatErrorResponse, formatEmptyResult } from "../utils/error-formatter.js";
4
4
  import { formatCreators, formatTags } from "../utils/item-formatter.js";
5
- import { logger } from "../utils/logger.js";
6
5
  import { fetchAllPages } from "../utils/pagination.js";
6
+ import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
7
7
  export const toolConfig = {
8
8
  name: "get_collection_items",
9
9
  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.",
@@ -13,15 +13,17 @@ export const toolConfig = {
13
13
  .boolean()
14
14
  .default(true)
15
15
  .describe("Exclude attachment and note items (default: true)"),
16
+ ...libraryArgsSchema,
16
17
  },
17
18
  };
18
19
  const CollectionItemsSchema = z.object(toolConfig.inputSchema);
19
20
  export async function handleGetCollectionItems(zoteroApi, userId, args) {
20
- const { collectionKey, excludeAttachments } = CollectionItemsSchema.parse(args);
21
+ const { collectionKey, excludeAttachments, library_type, library_id } = CollectionItemsSchema.parse(args);
22
+ const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
21
23
  try {
22
- const { items: allItems, totalResults } = await fetchAllPages((params) => zoteroApi.library("user", userId).collections(collectionKey).items().get(params));
24
+ const { items: allItems, totalResults } = await fetchAllPages((params) => zoteroApi.library(libraryType, libraryId).collections(collectionKey).items().get(params));
23
25
  if (!allItems || allItems.length === 0) {
24
- return formatErrorResponse("Collection is empty", {
26
+ return formatEmptyResult("Collection is empty", {
25
27
  collectionKey,
26
28
  suggestion: "Add some items to this collection in Zotero",
27
29
  status: "empty",
@@ -45,24 +47,17 @@ export async function handleGetCollectionItems(zoteroApi, userId, args) {
45
47
  publicationTitle: item.publicationTitle || null,
46
48
  }));
47
49
  if (formatted.length === 0) {
48
- return formatErrorResponse("No valid items found in collection", {
50
+ return formatEmptyResult("No valid items found in collection", {
49
51
  collectionKey,
50
52
  suggestion: "Check that items in this collection have the expected metadata",
51
53
  status: "invalid_items",
52
54
  });
53
55
  }
54
- return {
55
- content: [
56
- {
57
- type: "text",
58
- text: JSON.stringify({
59
- total_items: totalResults,
60
- returned_items: formatted.length,
61
- items: formatted,
62
- }, null, 2),
63
- },
64
- ],
65
- };
56
+ return formatJsonResult({
57
+ total_items: totalResults,
58
+ returned_items: formatted.length,
59
+ items: formatted,
60
+ });
66
61
  }
67
62
  catch (err) {
68
63
  if (isZoteroApiError(err)) {
@@ -73,12 +68,6 @@ export async function handleGetCollectionItems(zoteroApi, userId, args) {
73
68
  status: "not_found",
74
69
  });
75
70
  }
76
- logger.error("Tool execution failed", {
77
- tool: "get_collection_items",
78
- status: err.response?.status,
79
- errorMessage: err.message,
80
- url: err.response?.url,
81
- });
82
71
  }
83
72
  throw err;
84
73
  }
@@ -1,8 +1,7 @@
1
1
  import { z } from "zod";
2
- import { isZoteroApiError } from "../types/zotero-types.js";
3
- import { formatErrorResponse } from "../utils/error-formatter.js";
4
- import { logger } from "../utils/logger.js";
2
+ import { formatJsonResult, formatEmptyResult } from "../utils/error-formatter.js";
5
3
  import { fetchAllPages } from "../utils/pagination.js";
4
+ import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
6
5
  export const toolConfig = {
7
6
  name: "get_collections",
8
7
  description: "List all collections (folders) in your Zotero library. Returns collection keys, names, and parent relationships. Use collection keys with get_collection_items or as parent_collection in create_collection. Trashed collections are excluded by default.",
@@ -12,44 +11,29 @@ export const toolConfig = {
12
11
  .optional()
13
12
  .default(false)
14
13
  .describe("Include trashed (deleted) collections. Default false."),
14
+ ...libraryArgsSchema,
15
15
  },
16
16
  };
17
17
  const GetCollectionsSchema = z.object(toolConfig.inputSchema);
18
18
  export async function handleGetCollections(zoteroApi, userId, args) {
19
- const { include_trashed } = GetCollectionsSchema.parse(args);
20
- try {
21
- const { items: allCollections } = await fetchAllPages((params) => zoteroApi.library("user", userId).collections().get(params));
22
- if (!Array.isArray(allCollections) || allCollections.length === 0) {
23
- return formatErrorResponse("No collections found", {
24
- suggestion: "Create a collection in your Zotero library first",
25
- helpUrl: "https://www.zotero.org/support/collections",
26
- });
27
- }
28
- // Zotero API returns deleted collections despite not requesting them —
29
- // filter client-side as a workaround
30
- const collections = include_trashed
31
- ? allCollections
32
- : allCollections.filter((c) => !c.deleted);
33
- if (collections.length === 0) {
34
- return formatErrorResponse("No collections found", {
35
- suggestion: "All collections are in the trash. Use include_trashed=true to see them.",
36
- });
37
- }
38
- return {
39
- content: [
40
- { type: "text", text: JSON.stringify(collections, null, 2) },
41
- ],
42
- };
19
+ const { include_trashed, library_type, library_id } = GetCollectionsSchema.parse(args);
20
+ const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
21
+ const { items: allCollections } = await fetchAllPages((params) => zoteroApi.library(libraryType, libraryId).collections().get(params));
22
+ if (!Array.isArray(allCollections) || allCollections.length === 0) {
23
+ return formatEmptyResult("No collections found", {
24
+ suggestion: "Create a collection in your Zotero library first",
25
+ helpUrl: "https://www.zotero.org/support/collections",
26
+ });
43
27
  }
44
- catch (err) {
45
- if (isZoteroApiError(err)) {
46
- logger.error("Tool execution failed", {
47
- tool: "get_collections",
48
- status: err.response?.status,
49
- errorMessage: err.message,
50
- url: err.response?.url,
51
- });
52
- }
53
- throw err;
28
+ // Zotero API returns deleted collections despite not requesting them —
29
+ // filter client-side as a workaround
30
+ const collections = include_trashed
31
+ ? allCollections
32
+ : allCollections.filter((c) => !c.deleted);
33
+ if (collections.length === 0) {
34
+ return formatEmptyResult("No collections found", {
35
+ suggestion: "All collections are in the trash. Use include_trashed=true to see them.",
36
+ });
54
37
  }
38
+ return formatJsonResult(collections);
55
39
  }