zotero-mcp 1.3.0

data/lib/zotero/mcp/fulltext.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        DEFAULT_MAX_CHARS = 20_000
+        MAX_MAX_CHARS = 200_000
+
+        def self.clamp_max_chars(max_chars)
+            unless max_chars.is_a?(Integer) && max_chars >= 1
+                return DEFAULT_MAX_CHARS
+            end
+
+            max_chars.clamp(1, MAX_MAX_CHARS)
+        end
+
+        # Full text lives on the attachment, not its parent, but callers often
+        # only have the parent's key. Falling back to the children (PDFs first)
+        # means either key works for zotero_get_item_fulltext.
+        def self.fulltext_with_fallback(client, item_key)
+            { body: client.fulltext(item_key), item_key: item_key }
+        # rubocop:disable Naming/RescuedExceptionsVariableName -- names the error re-raised below
+        rescue NotFoundError => original
+            # rubocop:enable Naming/RescuedExceptionsVariableName
+            begin
+                kids = client.children(item_key)
+            rescue NotFoundError, APIError
+                # Not a parent item (Zotero refuses /children on an
+                # attachment or a note): the original 404 is the answer.
+                raise original
+            end
+            fulltext_from_children(client, item_key, kids) ||
+                (raise NotFoundError,
+                       "No indexed full text for this item or its attachments.")
+        end
+
+        def self.fulltext_from_children(client, parent_key, children)
+            candidate_attachments(children).each do |child|
+                key = child["key"]
+                begin
+                    return { body: client.fulltext(key), item_key: key,
+                             parent_key: parent_key }
+                rescue NotFoundError
+                    next
+                end
+            end
+            nil
+        end
+
+        def self.candidate_attachments(children)
+            attachments = children.select do |child|
+                child.dig("data", "itemType") == "attachment"
+            end
+            pdfs, others = attachments.partition do |child|
+                child.dig("data", "contentType") == "application/pdf"
+            end
+            pdfs + others
+        end
+
+        def self.paginate_fulltext(resolved, offset, max_chars)
+            content = resolved[:body]["content"].to_s
+            start = clamp_start(offset)
+            slice = content[start, clamp_max_chars(max_chars)] || ""
+            result = fulltext_slice_result(resolved, content, start, slice)
+            copy_fulltext_meta(result, resolved[:body])
+        end
+
+        def self.fulltext_slice_result(resolved, content, start, slice)
+            result = {
+                item_key: resolved[:item_key], content: slice, offset: start,
+                returned_chars: slice.length, total_chars: content.length
+            }
+            result[:parent_key] = resolved[:parent_key] if resolved[:parent_key]
+            next_offset = start + slice.length
+            result[:next_offset] = next_offset if next_offset < content.length
+            result
+        end
+
+        def self.copy_fulltext_meta(result, body)
+            %w[indexedPages totalPages indexedChars totalChars].each do |field|
+                result[field.to_sym] = body[field] if body.key?(field)
+            end
+            result
+        end
+    end
+end

data/lib/zotero/mcp/helpers.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        # ----------------------------------------------------------------- #
+        # Small helpers
+        # ----------------------------------------------------------------- #
+
+        def self.truthy?(value)
+            %w[1 true yes on].include?(value.to_s.downcase)
+        end
+
+        def self.presence(value)
+            stripped = value.to_s.strip
+            stripped.empty? ? nil : stripped
+        end
+
+        def self.clamp_limit(limit)
+            return DEFAULT_LIMIT unless limit.is_a?(Integer) && limit.positive?
+
+            [limit, MAX_LIMIT].min
+        end
+
+        def self.clamp_start(start)
+            start.is_a?(Integer) && start.positive? ? start : 0
+        end
+
+        # Zotero keys are short alphanumeric strings. Rejecting anything else
+        # keeps bad input out of URL paths and fails with a clear message.
+        def self.validate_key!(key)
+            return key if KEY_PATTERN.match?(key.to_s)
+
+            raise Error, "Invalid Zotero key: #{key.inspect}."
+        end
+
+        def self.compact(hash)
+            hash.reject { |_key, value| value.nil? || value == "" }
+        end
+
+        def self.batch_error(keys)
+            return "Provide at least one item key." if keys.empty?
+            return nil if keys.length <= MAX_WRITE_BATCH
+
+            "At most #{MAX_WRITE_BATCH} items per call."
+        end
+
+        def self.nonempty(value) = value.nil? || value.empty? ? nil : value
+    end
+end

data/lib/zotero/mcp/read_api.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        # ----------------------------------------------------------------- #
+        # Read-side endpoints
+        # ----------------------------------------------------------------- #
+
+        module ReadAPI
+            def search_items(query:, qmode:, item_type:, tag:, top_only:, # rubocop:disable Metrics/ParameterLists -- mirrors the input_schema
+                             sort:, direction:, limit:, start:)
+                path = "#{prefix}/items#{"/top" if top_only}"
+                params = Zotero::MCP.compact(
+                    q: query, qmode: (query ? qmode : nil), itemType: item_type,
+                    tag: tag, sort: sort, direction: direction,
+                    limit: Zotero::MCP.clamp_limit(limit),
+                    start: Zotero::MCP.clamp_start(start)
+                )
+                get_page(path, params)
+            end
+
+            def item(key)
+                get_json("#{prefix}/items/#{Zotero::MCP.validate_key!(key)}")
+            end
+
+            def children(key)
+                key = Zotero::MCP.validate_key!(key)
+                get_json("#{prefix}/items/#{key}/children")
+            end
+
+            def collections(top_only:, limit:, start:)
+                path = "#{prefix}/collections#{"/top" if top_only}"
+                get_page(path, limit_params(limit, start))
+            end
+
+            def collection_items(key:, top_only:, item_type:, tag:, limit:, # rubocop:disable Metrics/ParameterLists -- mirrors the input_schema
+                                 start:)
+                key = Zotero::MCP.validate_key!(key)
+                suffix = top_only ? "/top" : ""
+                path = "#{prefix}/collections/#{key}/items#{suffix}"
+                params = Zotero::MCP.compact(
+                    itemType: item_type, tag: tag,
+                    limit: Zotero::MCP.clamp_limit(limit),
+                    start: Zotero::MCP.clamp_start(start)
+                )
+                get_page(path, params)
+            end
+
+            def tags(query:, limit:, start:)
+                params = Zotero::MCP.compact(
+                    q: query, limit: Zotero::MCP.clamp_limit(limit),
+                    start: Zotero::MCP.clamp_start(start)
+                )
+                get_page("#{prefix}/tags", params)
+            end
+
+            def fulltext(key)
+                key = Zotero::MCP.validate_key!(key)
+                get_json("#{prefix}/items/#{key}/fulltext")
+            end
+
+            def item_types = get_json("/itemTypes")
+
+            def item_template(item_type)
+                get_json("/items/new", itemType: item_type)
+            end
+
+            def creator_types(item_type)
+                get_json("/itemTypeCreatorTypes", itemType: item_type)
+            end
+
+            def bibliography(item_keys:, collection_key:, style:, mode:,
+                             start: 0)
+                include = mode == "citation" ? "citation" : "bib"
+                start = Zotero::MCP.clamp_start(start)
+                params = { include: include, style: style, limit: MAX_LIMIT,
+                           start: start }
+                response = bib_response(item_keys, collection_key, params)
+                bibliography_result(response, include, start)
+            end
+
+            private
+
+            def bibliography_result(response, include, start)
+                body = parse_json(response.body)
+                {
+                    entries: body.map { |entry| entry[include] }.compact,
+                    total: response["Total-Results"]&.to_i,
+                    start: start, returned: body.length
+                }
+            end
+
+            # /top so child notes and attachments contributed by a collection
+            # produce no bibliography entries of their own.
+            def bib_response(item_keys, collection_key, params)
+                if collection_key
+                    key = Zotero::MCP.validate_key!(collection_key)
+                    path = "#{prefix}/collections/#{key}/items/top"
+                else
+                    keys = item_keys.map { |key| Zotero::MCP.validate_key!(key) }
+                    path = "#{prefix}/items"
+                    params = params.merge(itemKey: keys.join(","))
+                end
+                request(:get, path, params: params)
+            end
+
+            def limit_params(limit, start)
+                {
+                    limit: Zotero::MCP.clamp_limit(limit),
+                    start: Zotero::MCP.clamp_start(start)
+                }
+            end
+        end
+    end
+end

data/lib/zotero/mcp/response_handling.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        # HTTP status-code interpretation for Client: dispatches a response to
+        # the matching domain error (or the retryable rate-limit path) and
+        # builds the error message text. Included into Client.
+        module ResponseHandling
+            private
+
+            def handle(response)
+                status = response.code.to_i
+                return response if (200..299).cover?(status)
+
+                raise_for_status(status, response)
+            end
+
+            def raise_for_status(status, response)
+                case status
+                in 403 then raise NotAuthorisedError, forbidden_text(response)
+                in 404 then raise NotFoundError, not_found_text(response)
+                in 412 then raise ConflictError, conflict_text(response)
+                in 429 then raise_rate_limited(response)
+                in 503 then raise_service_unavailable(response)
+                else raise APIError, api_error_text(status, response)
+                end
+            end
+
+            def forbidden_text(response)
+                "#{forbidden_message}#{body_suffix(response)}"
+            end
+
+            def not_found_text(response)
+                "Not found (404). Check the key.#{body_suffix(response)}"
+            end
+
+            def conflict_text(response)
+                "#{conflict_message}#{body_suffix(response)}"
+            end
+
+            def api_error_text(status, response)
+                "Zotero API error #{status}.#{body_suffix(response)}"
+            end
+
+            def raise_rate_limited(response)
+                header = response["Retry-After"] || response["Backoff"]
+                seconds = Zotero::MCP.presence(header)&.to_i
+                raise RateLimitedError.new(
+                    "Rate limited (429). Retry in #{seconds || "a few"} " \
+                    "seconds.#{body_suffix(response)}",
+                    retry_after: seconds
+                )
+            end
+
+            def raise_service_unavailable(response)
+                header = retry_header(response)
+                return unavailable_without_retry(response) unless header
+
+                raise RateLimitedError.new(service_unavailable_text(header,
+                                                                    response),
+                                           retry_after: header.to_i)
+            end
+
+            def retry_header(response)
+                Zotero::MCP.presence(
+                    response["Retry-After"] || response["Backoff"]
+                )
+            end
+
+            def unavailable_without_retry(response)
+                raise APIError, "Zotero API error 503.#{body_suffix(response)}"
+            end
+
+            def service_unavailable_text(header, response)
+                "Service unavailable (503). Retry in #{header.to_i} " \
+                    "seconds.#{body_suffix(response)}"
+            end
+
+            def forbidden_message
+                "Permission denied (403). The API key is missing, invalid, " \
+                    "or lacks the access needed (write keys need write " \
+                    "permission)."
+            end
+
+            def conflict_message
+                "Version conflict (412). The object changed on the server; " \
+                    "re-fetch it and retry."
+            end
+
+            # Non-2xx responses often carry a plain-text explanation;
+            # surfacing it (bounded, so a huge body can't blow up an error
+            # message) helps diagnose failures that the generic status
+            # message cannot.
+            def body_suffix(response)
+                body = Zotero::MCP.presence(response.body)
+                return "" unless body
+
+                snippet = body.length > 500 ? "#{body[0, 500]}…" : body
+                " Server said: #{snippet}"
+            end
+        end
+    end
+end

data/lib/zotero/mcp/tools/add_to_collection.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class AddToCollection < ::MCP::Tool
+            tool_name "zotero_add_to_collection"
+            description <<~DESC
+                Add existing items to a collection, leaving other memberships
+                intact. Returns which keys were added and any failures.
+            DESC
+            input_schema(
+                properties: {
+                    collection_key: { type: "string",
+                                      description: "Target collection key." },
+                    item_keys: { type: "array", items: { type: "string" },
+                                 description: "Keys of items to add." }
+                },
+                required: %w[collection_key item_keys]
+            )
+            annotations(title: "Add items to a collection",
+                        read_only_hint: false, destructive_hint: false,
+                        idempotent_hint: true, open_world_hint: true)
+
+            def self.call(collection_key:, item_keys:)
+                Zotero::MCP.guard do
+                    error = Zotero::MCP.batch_error(item_keys)
+                    next Zotero::MCP.error_text(error) if error
+
+                    Zotero::MCP.text(
+                        Zotero::MCP.client.add_to_collection(
+                            collection_key: collection_key, keys: item_keys
+                        )
+                    )
+                end
+            end
+        end
+    end
+end

data/lib/zotero/mcp/tools/create_collection.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class CreateCollection < ::MCP::Tool
+            tool_name "zotero_create_collection"
+            description <<~DESC
+                Create a new collection, optionally nested under a parent. Returns
+                the created collection key.
+            DESC
+
+            parent_collection_key_desc = "Parent collection to nest under " \
+                                         "(optional)."
+
+            input_schema(
+                properties: {
+                    name: { type: "string",
+                            description: "Name of the new collection." },
+                    parent_collection_key: { type: "string",
+                                             description:
+                                                 parent_collection_key_desc }
+                },
+                required: ["name"]
+            )
+            annotations(title: "Create a collection", read_only_hint: false,
+                        destructive_hint: false, idempotent_hint: false,
+                        open_world_hint: true)
+
+            def self.call(name:, parent_collection_key: nil)
+                Zotero::MCP.guard do
+                    payload = { "name" => name }
+                    if parent_collection_key
+                        payload["parentCollection"] = parent_collection_key
+                    end
+                    Zotero::MCP.text(
+                        Zotero::MCP.client.create_collections([payload])
+                    )
+                end
+            end
+        end
+    end
+end

data/lib/zotero/mcp/tools/create_item.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class CreateItem < ::MCP::Tool
+            tool_name "zotero_create_item"
+            description <<~DESC
+                Create a single item in the library. Builds a valid payload from
+                the item type's template, applies the given
+                fields/creators/tags/collections, and submits it. Returns the
+                created item key(s) or per-item failure details.
+            DESC
+
+            fields_desc = "Field -> value map, e.g. " \
+                          "{'title': '...', 'date': '2023'}."
+            creators_desc = "Creators, e.g. {'creatorType': 'author', " \
+                            "'firstName': 'Ada', 'lastName': 'Lovelace'}."
+
+            input_schema(
+                properties: {
+                    item_type: { type: "string",
+                                 description: "Type, e.g. 'journalArticle', " \
+                                              "'book'." },
+                    fields: { type: "object", description: fields_desc },
+                    creators: { type: "array", items: { type: "object" },
+                                description: creators_desc },
+                    tags: { type: "array", items: { type: "string" },
+                            description: "Tag strings." },
+                    collection_keys: { type: "array",
+                                       items: { type: "string" },
+                                       description: "Collections the item " \
+                                                    "belongs to." }
+                },
+                required: ["item_type"]
+            )
+            annotations(title: "Create a Zotero item", read_only_hint: false,
+                        destructive_hint: false, idempotent_hint: false,
+                        open_world_hint: true)
+
+            def self.call(item_type:, fields: {}, creators: nil, tags: nil,
+                          collection_keys: nil)
+                Zotero::MCP.guard do
+                    client = Zotero::MCP.client
+                    template = client.item_template(item_type)
+                    apply!(template, fields, creators, tags, collection_keys)
+                    Zotero::MCP.text(client.create_items([template]))
+                end
+            end
+
+            def self.apply!(template, fields, creators, tags, collection_keys)
+                (fields || {}).each do |name, value|
+                    template[name.to_s] = value
+                end
+                template["creators"] = creators unless creators.nil?
+                template["tags"] = tags.map { |tag| { "tag" => tag } } if tags
+                return if collection_keys.nil?
+
+                template["collections"] = collection_keys
+            end
+        end
+    end
+end

data/lib/zotero/mcp/tools/create_note.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class CreateNote < ::MCP::Tool
+            tool_name "zotero_create_note"
+            description <<~DESC
+                Create a standalone or child note. If parent_item_key is set, the
+                note is created as a child of that item. Returns the new note key.
+            DESC
+
+            note_html_desc = "Note content as HTML (plain text is fine)."
+            parent_item_key_desc = "Make the note a child of this item."
+            collection_keys_desc = "Collections for a standalone note."
+
+            input_schema(
+                properties: {
+                    note_html: { type: "string",
+                                 description: note_html_desc },
+                    parent_item_key: { type: "string",
+                                       description: parent_item_key_desc },
+                    tags: { type: "array", items: { type: "string" },
+                            description: "Tag strings for the note." },
+                    collection_keys: { type: "array",
+                                       items: { type: "string" },
+                                       description: collection_keys_desc }
+                },
+                required: ["note_html"]
+            )
+            annotations(title: "Create a Zotero note", read_only_hint: false,
+                        destructive_hint: false, idempotent_hint: false,
+                        open_world_hint: true)
+
+            def self.call(note_html:, parent_item_key: nil, tags: nil,
+                          collection_keys: nil)
+                Zotero::MCP.guard do
+                    error = note_conflict_error(parent_item_key,
+                                                collection_keys)
+                    next Zotero::MCP.error_text(error) if error
+
+                    client = Zotero::MCP.client
+                    note = build_note(client, note_html, parent_item_key,
+                                      tags, collection_keys)
+                    Zotero::MCP.text(client.create_items([note]))
+                end
+            end
+
+            def self.note_conflict_error(parent_item_key, collection_keys)
+                return nil unless parent_item_key &&
+                                  Array(collection_keys).any?
+
+                "collection_keys apply only to standalone notes; omit " \
+                    "parent_item_key or collection_keys."
+            end
+
+            def self.build_note(client, note_html, parent_item_key, tags,
+                                collection_keys)
+                note = client.item_template("note")
+                note["note"] = note_html
+                note["tags"] = tags.map { |tag| { "tag" => tag } } if tags
+                note["parentItem"] = parent_item_key if parent_item_key
+                if collection_keys && parent_item_key.nil?
+                    note["collections"] = collection_keys
+                end
+                note
+            end
+        end
+    end
+end

data/lib/zotero/mcp/tools/delete_item.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class DeleteItem < ::MCP::Tool
+            tool_name "zotero_delete_item"
+            description <<~DESC
+                Delete one or more items (moves them to the Zotero trash, so
+                deletions are recoverable). Up to 50 keys per call. Returns the
+                deleted keys and any that could not be deleted.
+            DESC
+            input_schema(
+                properties: {
+                    item_keys: { type: "array", items: { type: "string" },
+                                 description: "Item keys to delete (max 50)." }
+                },
+                required: ["item_keys"]
+            )
+            annotations(title: "Delete Zotero items", read_only_hint: false,
+                        destructive_hint: true, idempotent_hint: false,
+                        open_world_hint: true)
+
+            def self.call(item_keys:)
+                Zotero::MCP.guard do
+                    error = Zotero::MCP.batch_error(item_keys)
+                    next Zotero::MCP.error_text(error) if error
+
+                    Zotero::MCP.text(Zotero::MCP.client.delete_items(item_keys))
+                end
+            end
+        end
+    end
+end