zotero-mcp 1.3.0

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class GenerateBibliography < ::MCP::Tool
+            tool_name "zotero_generate_bibliography"
+            description <<~DESC
+                Produce formatted references for items using a CSL citation style.
+                Give either item_keys or collection_key. Returns JSON with an
+                `entries` list of HTML-formatted strings. A collection is formatted
+                100 items at a time: when more remain, the result has
+                `truncated: true` and a `next_start` to pass back as `start`.
+            DESC
+
+            item_keys_desc = "Item keys to format (or use collection_key)."
+            collection_key_desc = "Format every item in this collection."
+            style_desc = "CSL style: 'apa', 'ieee', " \
+                         "'chicago-note-bibliography', etc. (default 'apa')."
+            mode_desc = "'bibliography' (default) or 'citation'."
+            start_desc = "Offset into the collection (default 0)."
+
+            input_schema(
+                properties: {
+                    item_keys: { type: "array", items: { type: "string" },
+                                 description: item_keys_desc },
+                    collection_key: { type: "string",
+                                      description: collection_key_desc },
+                    style: { type: "string", description: style_desc },
+                    mode: { type: "string",
+                            enum: %w[bibliography citation],
+                            description: mode_desc },
+                    start: { type: "integer", description: start_desc }
+                },
+                required: []
+            )
+            annotations(title: "Generate a bibliography", read_only_hint: true,
+                        destructive_hint: false, idempotent_hint: true,
+                        open_world_hint: true)
+
+            def self.call(item_keys: nil, collection_key: nil, style: "apa",
+                          mode: "bibliography", start: 0)
+                Zotero::MCP.guard do
+                    keys = Array(item_keys)
+                    error = batch_error_for(keys, collection_key)
+                    next Zotero::MCP.error_text(error) if error
+
+                    result = Zotero::MCP.client.bibliography(
+                        item_keys: keys, collection_key: collection_key,
+                        style: style, mode: mode, start: start
+                    )
+                    Zotero::MCP.text(bibliography_payload(style, mode, result))
+                end
+            end
+
+            def self.batch_error_for(keys, collection_key)
+                if keys.empty? && collection_key.nil?
+                    return "Provide item_keys or collection_key."
+                end
+                return nil if keys.length <= MAX_WRITE_BATCH
+
+                "At most #{MAX_WRITE_BATCH} item keys per call."
+            end
+
+            def self.bibliography_payload(style, mode, result)
+                payload = { style: style, mode: mode,
+                            entries: result[:entries] }
+                total = result[:total]
+                return payload unless total
+
+                add_pagination!(payload, total, result)
+                payload
+            end
+
+            def self.add_pagination!(payload, total, result)
+                payload[:total] = total
+                next_start = result[:start] + result[:returned]
+                return unless next_start < total
+
+                payload[:truncated] = true
+                payload[:next_start] = next_start
+            end
+        end
+    end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class GetCollectionItems < ::MCP::Tool
+            tool_name "zotero_get_collection_items"
+            description <<~DESC
+                List the items in a specific collection. Same response shape as
+                zotero_search_items: a `pagination` block and an `items` list
+                (compact summaries by default).
+            DESC
+
+            collection_key_desc = "The collection key to list items from."
+            top_only_desc = "Only top-level items (default true)."
+            item_type_desc = "Filter by item type, e.g. 'book'."
+            tag_desc = "Filter by tag (boolean syntax allowed)."
+            start_desc = "Offset for pagination (default 0)."
+            response_format_desc = "'summary' (default) or 'json'."
+
+            input_schema(
+                properties: {
+                    collection_key: { type: "string",
+                                      description: collection_key_desc },
+                    top_only: { type: "boolean", description: top_only_desc },
+                    item_type: { type: "string", description: item_type_desc },
+                    tag: { type: "string", description: tag_desc },
+                    limit: { type: "integer",
+                             description: "Max items, 1-100 (default 25)." },
+                    start: { type: "integer", description: start_desc },
+                    response_format: { type: "string",
+                                       enum: %w[summary json],
+                                       description: response_format_desc }
+                },
+                required: ["collection_key"]
+            )
+            annotations(title: "Get items in a collection",
+                        read_only_hint: true, destructive_hint: false,
+                        idempotent_hint: true, open_world_hint: true)
+
+            def self.call(collection_key:, top_only: true, item_type: nil, # rubocop:disable Metrics/ParameterLists -- mirrors the input_schema
+                          tag: nil, limit: DEFAULT_LIMIT, start: 0,
+                          response_format: "summary")
+                Zotero::MCP.guard do
+                    page = Zotero::MCP.client.collection_items(
+                        key: collection_key, top_only: top_only,
+                        item_type: item_type, tag: tag, limit: limit,
+                        start: start
+                    )
+                    Zotero::MCP.text(Zotero::MCP.format_page(page,
+                                                             response_format))
+                end
+            end
+        end
+    end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class GetItem < ::MCP::Tool
+            tool_name "zotero_get_item"
+            description <<~DESC
+                Fetch the full data for a single item by its key. Returns the
+                complete item JSON. When include_children is true, an additional
+                `children` array with the item's notes and attachments is added.
+                Children in the trash are left out, although the item's
+                meta.numChildren counts them.
+            DESC
+
+            item_key_desc = "The 8-character item key, e.g. 'ABCD2345'."
+            include_children_desc = "Also fetch child notes/attachments."
+
+            input_schema(
+                properties: {
+                    item_key: { type: "string", description: item_key_desc },
+                    include_children: { type: "boolean",
+                                        description: include_children_desc }
+                },
+                required: ["item_key"]
+            )
+            annotations(title: "Get a Zotero item", read_only_hint: true,
+                        destructive_hint: false, idempotent_hint: true,
+                        open_world_hint: true)
+
+            def self.call(item_key:, include_children: false)
+                Zotero::MCP.guard do
+                    client = Zotero::MCP.client
+                    result = { item: client.item(item_key) }
+                    if include_children
+                        result[:children] = client.children(item_key)
+                    end
+                    Zotero::MCP.text(result)
+                end
+            end
+        end
+    end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class GetItemFulltext < ::MCP::Tool
+            tool_name "zotero_get_item_fulltext"
+            description <<~DESC
+                Return the indexed full-text content of an attachment item (e.g. a
+                stored PDF). Either the attachment's own key or its parent item's
+                key is accepted; given a parent key, the attachment (PDFs first)
+                is resolved automatically. The content is paged: use offset and
+                max_chars, and next_offset in the result, to read more.
+            DESC
+
+            item_key_desc = "Key of an attachment with indexed text, or of " \
+                            "its parent item."
+            max_chars_desc = "Max characters to return, 1-200000 " \
+                             "(default 20000)."
+
+            input_schema(
+                properties: {
+                    item_key: { type: "string", description: item_key_desc },
+                    offset: { type: "integer",
+                              description: "Character offset to start from " \
+                                           "(default 0)." },
+                    max_chars: { type: "integer",
+                                 description: max_chars_desc }
+                },
+                required: ["item_key"]
+            )
+            annotations(title: "Get item full text", read_only_hint: true,
+                        destructive_hint: false, idempotent_hint: true,
+                        open_world_hint: true)
+
+            def self.call(item_key:, offset: 0,
+                          max_chars: Zotero::MCP::DEFAULT_MAX_CHARS)
+                Zotero::MCP.guard do
+                    resolved = Zotero::MCP.fulltext_with_fallback(
+                        Zotero::MCP.client, item_key
+                    )
+                    Zotero::MCP.text(
+                        Zotero::MCP.paginate_fulltext(resolved, offset,
+                                                      max_chars)
+                    )
+                end
+            end
+        end
+    end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class GetItemTemplate < ::MCP::Tool
+            tool_name "zotero_get_item_template"
+            description <<~DESC
+                Get a blank item template, or list all valid item types. With no
+                item_type, returns the list of item types. With an item_type,
+                returns a blank editable template plus valid creator types — use
+                this before zotero_create_item.
+            DESC
+
+            item_type_desc = "Type to template, e.g. 'journalArticle'. " \
+                             "Omit to list all item types."
+
+            input_schema(
+                properties: {
+                    item_type: { type: "string", description: item_type_desc }
+                },
+                required: []
+            )
+            annotations(title: "Get item type template", read_only_hint: true,
+                        destructive_hint: false, idempotent_hint: true,
+                        open_world_hint: true)
+
+            def self.call(item_type: nil)
+                Zotero::MCP.guard do
+                    client = Zotero::MCP.client
+                    next Zotero::MCP.text(itemTypes: client.item_types) unless
+                        item_type
+
+                    Zotero::MCP.text(item_template_payload(client, item_type))
+                end
+            end
+
+            def self.item_template_payload(client, item_type)
+                {
+                    itemType: item_type,
+                    template: client.item_template(item_type),
+                    creatorTypes: client.creator_types(item_type)
+                }
+            end
+        end
+    end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class ListCollections < ::MCP::Tool
+            tool_name "zotero_list_collections"
+            description <<~DESC
+                List collections (folders) in the library. Returns a `pagination`
+                block plus a `collections` list, each with key, name,
+                parentCollection, numItems and numCollections.
+            DESC
+
+            top_only_desc = "Only top-level collections (default false)."
+
+            input_schema(
+                properties: {
+                    top_only: { type: "boolean", description: top_only_desc },
+                    limit: { type: "integer",
+                             description: "Max results, 1-100 (default 25)." },
+                    start: { type: "integer",
+                             description: "Offset for pagination (default 0)." }
+                },
+                required: []
+            )
+            annotations(title: "List Zotero collections", read_only_hint: true,
+                        destructive_hint: false, idempotent_hint: true,
+                        open_world_hint: true)
+
+            def self.call(top_only: false, limit: DEFAULT_LIMIT, start: 0)
+                Zotero::MCP.guard do
+                    page = Zotero::MCP.client.collections(
+                        top_only: top_only, limit: limit, start: start
+                    )
+                    Zotero::MCP.text(collections_payload(page))
+                end
+            end
+
+            def self.collections_payload(page)
+                {
+                    pagination: Zotero::MCP.pagination_of(page),
+                    collections: page.items.map { |col| collection_of(col) }
+                }
+            end
+
+            def self.collection_of(col)
+                data = col["data"] || {}
+                meta = col["meta"] || {}
+                {
+                    key: col["key"], name: data["name"],
+                    parentCollection: data["parentCollection"],
+                    numItems: meta["numItems"],
+                    numCollections: meta["numCollections"]
+                }.compact
+            end
+        end
+    end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class ListTags < ::MCP::Tool
+            tool_name "zotero_list_tags"
+            description <<~DESC
+                List tags used in the library, optionally filtered by text. Returns
+                a `pagination` block and a `tags` list of tag objects.
+            DESC
+            filter_text_desc = "Only tags matching this text."
+
+            input_schema(
+                properties: {
+                    filter_text: { type: "string",
+                                   description: filter_text_desc },
+                    limit: { type: "integer",
+                             description: "Max tags, 1-100 (default 25)." },
+                    start: { type: "integer",
+                             description: "Offset for pagination (default 0)." }
+                },
+                required: []
+            )
+            annotations(title: "List Zotero tags", read_only_hint: true,
+                        destructive_hint: false, idempotent_hint: true,
+                        open_world_hint: true)
+
+            def self.call(filter_text: nil, limit: DEFAULT_LIMIT, start: 0)
+                Zotero::MCP.guard do
+                    page = Zotero::MCP.client.tags(
+                        query: filter_text, limit: limit, start: start
+                    )
+                    Zotero::MCP.text(
+                        pagination: Zotero::MCP.pagination_of(page),
+                        tags: page.items
+                    )
+                end
+            end
+        end
+    end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class SearchItems < ::MCP::Tool
+            tool_name "zotero_search_items"
+            description <<~DESC
+                Search or browse items in the Zotero library. Returns a JSON
+                object with a `pagination` block (count, start, total, has_more,
+                next_start) and an `items` list. In 'summary' format each item has
+                key, itemType, title, creators, date, publication, tags and
+                numChildren; use zotero_get_item with the key for the full record.
+            DESC
+
+            query_desc = "Free-text search; omit to browse all."
+            qmode_desc = "'titleCreatorYear' (default) or 'everything' " \
+                         "(also searches attachment full text)."
+            item_type_desc = "Filter by type, e.g. 'journalArticle', 'book'. " \
+                             "Boolean syntax like '-attachment' works."
+            tag_desc = "Filter by tag; boolean 'a && b' / 'a || b'."
+            top_only_desc = "Only top-level items (default true)."
+            sort_desc = "Sort field, e.g. 'dateModified', 'title'."
+            limit_desc = "Max items, 1-100 (default 25)."
+            start_desc = "Offset for pagination (default 0)."
+            response_format_desc = "'summary' (default) or 'json' for raw " \
+                                   "data."
+
+            input_schema(
+                properties: {
+                    query: { type: "string", description: query_desc },
+                    qmode: { type: "string",
+                             enum: %w[titleCreatorYear everything],
+                             description: qmode_desc },
+                    item_type: { type: "string", description: item_type_desc },
+                    tag: { type: "string", description: tag_desc },
+                    top_only: { type: "boolean", description: top_only_desc },
+                    sort: { type: "string", description: sort_desc },
+                    direction: { type: "string", enum: %w[asc desc],
+                                 description: "'asc' or 'desc'." },
+                    limit: { type: "integer", description: limit_desc },
+                    start: { type: "integer", description: start_desc },
+                    response_format: { type: "string",
+                                       enum: %w[summary json],
+                                       description: response_format_desc }
+                },
+                required: []
+            )
+            annotations(title: "Search Zotero items", read_only_hint: true,
+                        destructive_hint: false, idempotent_hint: true,
+                        open_world_hint: true)
+
+            def self.call(query: nil, qmode: "titleCreatorYear", # rubocop:disable Metrics/ParameterLists -- mirrors the input_schema
+                          item_type: nil, tag: nil, top_only: true, sort: nil,
+                          direction: nil, limit: DEFAULT_LIMIT, start: 0,
+                          response_format: "summary")
+                Zotero::MCP.guard do
+                    page = Zotero::MCP.client.search_items(
+                        query: query, qmode: qmode, item_type: item_type,
+                        tag: tag, top_only: top_only, sort: sort,
+                        direction: direction, limit: limit, start: start
+                    )
+                    Zotero::MCP.text(Zotero::MCP.format_page(page,
+                                                             response_format))
+                end
+            end
+        end
+    end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class UpdateItem < ::MCP::Tool
+            tool_name "zotero_update_item"
+            description <<~DESC
+                Update fields, tags, or collections of an existing item. Fetches
+                the item to obtain its current version for safe concurrent editing,
+                applies changes, and saves. Providing tags or collections REPLACES
+                the existing ones.
+            DESC
+
+            collection_keys_desc = "Replaces the item's collections."
+
+            input_schema(
+                properties: {
+                    item_key: { type: "string",
+                                description: "Key of the item to update." },
+                    fields: { type: "object",
+                              description: "Field -> new value map." },
+                    tags: { type: "array", items: { type: "string" },
+                            description: "Replaces the item's tags." },
+                    collection_keys: { type: "array",
+                                       items: { type: "string" },
+                                       description: collection_keys_desc }
+                },
+                required: ["item_key"]
+            )
+            annotations(title: "Update a Zotero item", read_only_hint: false,
+                        destructive_hint: false, idempotent_hint: false,
+                        open_world_hint: true)
+
+            def self.call(item_key:, fields: nil, tags: nil,
+                          collection_keys: nil)
+                Zotero::MCP.guard do
+                    changes = build_changes(fields, tags, collection_keys)
+                    next update_item_error unless changes.any?
+
+                    Zotero::MCP.text(
+                        Zotero::MCP.client.update_item(
+                            key: item_key, changes: changes
+                        )
+                    )
+                end
+            end
+
+            def self.update_item_error
+                Zotero::MCP.error_text(
+                    "Provide fields, tags, or collection_keys."
+                )
+            end
+
+            def self.build_changes(fields, tags, collection_keys)
+                changes = {}
+                (fields || {}).each { |name, value| changes[name.to_s] = value }
+                changes["tags"] = tags.map { |tag| { "tag" => tag } } if tags
+                unless collection_keys.nil?
+                    changes["collections"] =
+                        collection_keys
+                end
+                changes
+            end
+        end
+    end
+end

data/lib/zotero/mcp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        VERSION = "1.3.0"
+    end
+end

data/lib/zotero/mcp/write_api.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        # ----------------------------------------------------------------- #
+        # Write-side endpoints
+        # ----------------------------------------------------------------- #
+
+        module WriteAPI
+            def create_items(payload)
+                ensure_writable!
+                write_json(:post, "#{prefix}/items", payload)
+            end
+
+            def create_collections(payload)
+                ensure_writable!
+                write_json(:post, "#{prefix}/collections", payload)
+            end
+
+            def update_item(key:, changes:)
+                ensure_writable!
+                current = item(key)
+                patch_item(key, current.fetch("version"), changes)
+                { success: true, key: key, message: "Item updated." }
+            end
+
+            def delete_items(keys)
+                ensure_writable!
+                deleted = []
+                failed = []
+                keys.each { |key| delete_one(key, deleted, failed) }
+                { deleted: deleted, failed: failed }
+            end
+
+            def add_to_collection(collection_key:, keys:)
+                ensure_writable!
+                collection_key = Zotero::MCP.validate_key!(collection_key)
+                added = []
+                failed = []
+                keys.each { |key| add_one(collection_key, key, added, failed) }
+                { collection: collection_key, added: added, failed: failed }
+            end
+
+            private
+
+            # Moves the item to the trash. A DELETE request would remove it
+            # from Zotero for good, past any recovery; the trash is the
+            # item's "deleted" property.
+            def delete_one(key, deleted, failed)
+                current = item(key)
+                patch_item(key, current.fetch("version"), { deleted: 1 })
+                deleted << key
+            rescue Error => e
+                failed << { key: key, reason: e.message }
+            end
+
+            def add_one(collection_key, key, added, failed)
+                current = item(key)
+                merged = (current.dig("data",
+                                      "collections") || []) + [collection_key]
+                patch_item(key, current.fetch("version"),
+                           { collections: merged.uniq })
+                added << key
+            rescue Error => e
+                failed << { key: key, reason: e.message }
+            end
+
+            def patch_item(key, version, changes)
+                request(:patch, "#{prefix}/items/#{key}",
+                        body: JSON.dump(changes),
+                        headers: version_header(version).merge(json_content))
+            end
+
+            def version_header(version)
+                { "If-Unmodified-Since-Version" => version.to_s }
+            end
+
+            def write_json(method, path, payload)
+                headers = write_headers(method)
+                response = request(method, path, body: JSON.dump(payload),
+                                                 headers: headers)
+                normalize_write(parse_json(response.body))
+            end
+
+            def write_headers(method)
+                return json_content unless method == :post
+
+                json_content.merge("Zotero-Write-Token" => SecureRandom.hex(16))
+            end
+
+            def normalize_write(body)
+                failed = body["failed"].to_h
+                result = { success: failed.empty?,
+                           created_keys: created_keys(body) }
+                result[:failed] = failed unless failed.empty?
+                unchanged = body["unchanged"]
+                result[:unchanged] = unchanged if nonempty_unchanged?(unchanged)
+                result
+            end
+
+            def nonempty_unchanged?(unchanged)
+                unchanged.respond_to?(:any?) && unchanged.any?
+            end
+
+            def created_keys(body)
+                from_map = (body["success"] || {}).values.grep(String)
+                successful = (body["successful"] || {}).values
+                from_obj = successful.filter_map do |entry|
+                    entry["key"] if entry.is_a?(Hash)
+                end
+                (from_map + from_obj).uniq
+            end
+
+            def json_content = { "Content-Type" => "application/json" }
+        end
+    end
+end