zotero-mcp 1.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f8e280c65713f3051f5c0d200f24dc22b8b4cecaba390696473a99c5d13d68e
+  data.tar.gz: b8fc1a864ca6beda8b72f7bbc383dfa772afa09e054544aa1a390d0803f3ae8f
+SHA512:
+  metadata.gz: 0af867aa2ceaee0e2322e7ca7dded6da05871e031ba9af64249cf7da007ace79f4174a07e4786ff0d5137811cef651db813015e4415de635ee9953218fb687d0
+  data.tar.gz: 563ff449c26f3ba41071010935c7b4c6afbbd011662b5553c3039899c9f882eec7afb1ed189ee09cd60857a7e6d506bd13874c4fe95371399708cc5d83a92f41

data/DESIGN.md

@@ -0,0 +1,112 @@
+# Design
+
+Why the Zotero MCP server is shaped the way it is. How to install and use
+it is in `README.md`.
+
+## Small files, standard library HTTP
+
+`lib/zotero/mcp.rb` loads the parts and assembles the server; each part
+is its own file under `lib/zotero/mcp/` (errors, configuration, the
+HTTP client and its response handling, the read and write endpoints,
+formatting, full text), and each tool is a file under
+`lib/zotero/mcp/tools/`. Files stay short enough for the house style's
+size limits, so a change to one tool reads as a change to one file.
+`lib/zotero/mcp/version.rb` holds only the version, so the gemspec can
+read it without loading the `mcp` gem. One launcher, `exe/zotero-mcp`, calls `Zotero::MCP.run`; the
+gem installs it on the `PATH`, and a checkout runs the same file
+through Bundler. The only dependency is the `mcp` gem; HTTP goes
+through `Net::HTTP`. A REST client gem would save little: the Zotero API
+needs only GET, POST, PATCH and DELETE with a few headers.
+
+The gem is `zotero-mcp` and its code is `Zotero::MCP`, following the
+RubyGems rule that a dash in a name marks a namespace. The price is
+sharing the top-level `Zotero` module with the unrelated `zotero` gem
+(0.2.1), which defines `Zotero::VERSION`, `Zotero::Api` and
+`Zotero::Entities`. Everything here lives under `Zotero::MCP`, so the
+two can load in one process without overwriting each other's constants.
+
+## Layers
+
+`Config` reads the environment once. `Client` is the HTTP core
+(`request`, the status-to-exception mapping, retries). The endpoint
+methods are mixed into it from `ReadAPI` and `WriteAPI`. The `MCP::Tool`
+subclasses are thin: they validate arguments, call one client method
+inside `Zotero::MCP.guard`, and format the result. Because of this split,
+the suite can replace `Client#perform` (the one method that touches the
+network) with a stub, and exercise everything else offline.
+
+## Errors are results, not exceptions
+
+Every failure the server can foresee is a subclass of `Zotero::MCP::Error`.
+`guard` turns any exception into a tool result flagged `isError` and
+carrying an `error` message, so the client always gets an answer it can
+act on, and the stdio transport never sees a Ruby exception. Messages say
+what to do next ("re-fetch it and retry"), because their reader is a
+model deciding on its next call. When Zotero explains a refusal in the
+response body, the first 500 characters of that explanation are
+appended. Nothing is ever written to stdout: that stream carries the
+JSON-RPC protocol.
+
+## Writes are version-safe
+
+An update, a delete, or adding an item to a collection first fetches the
+item's current version. The write then sends that version back in
+`If-Unmodified-Since-Version`. If someone else changed the item in
+between, Zotero rejects the write with a 412, which reaches the caller as
+a conflict instead of silently overwriting their edit. The cost is one
+extra GET per item.
+
+Deletes and collection additions go one item at a time, not as a single
+batch request. That costs one round trip per item, but each key's
+success or failure is reported separately: a batch that fails on one
+item would tell the caller nothing about the others.
+
+A delete moves the item to the trash: it sets the item's `deleted`
+property with the same version-checked PATCH. An HTTP DELETE removes the
+item from Zotero for good (it then appears in the library's `/deleted`
+log and nowhere else), so the server never sends one, and
+`zotero_delete_item` stays recoverable from Zotero's trash.
+
+## Bounded retries
+
+A 429, or a 503 that says when to come back, is retried at most
+`MAX_RETRIES` times, and only when the server says how long to wait
+(`Retry-After` or `Backoff`) and that wait is at most `MAX_BACKOFF`
+seconds. A longer wait goes back to the caller as an error, because an
+MCP tool call that blocks for minutes looks like a hang. A 503 with no
+such header is an ordinary error.
+
+Each create request is one POST carrying a `Zotero-Write-Token`. The
+token is generated once per call and reused on every retry of that call,
+so if the server does act on a request that the client thinks failed,
+the retry cannot create the item a second time.
+
+## Keys are validated before they reach a URL
+
+Every item or collection key passes through `validate_key!`, which
+accepts up to 32 alphanumerics. Keys are interpolated into URL paths;
+rejecting anything else keeps a malformed or hostile argument out of
+the path, and fails with a message that names the bad key.
+
+## Summaries by default
+
+The list and search tools return compact summaries unless asked for
+`json`: key, type, title, creators (first three and a count), date,
+publication, tags. A full Zotero record is mostly empty fields, and the
+caller pays for every byte in its context window. `zotero_get_item`
+returns the full record for one key.
+
+Full text is the extreme case: an indexed book can run to megabytes.
+`zotero_get_item_fulltext` returns at most `max_chars` characters per
+call (20,000 by default) along with the offset to continue from, so the
+caller decides how much to read. It also accepts a parent item's key,
+since that is the key a search returns. When Zotero has no text under
+that key, it tries the item's attachments, PDFs first.
+
+## Local mode is read-only
+
+The Zotero desktop app's local API (`ZOTERO_LOCAL=true`) serves reads
+only. The write tools stay registered in that mode, and refuse with a
+`ReadOnlyError` that says to use the Web API. This keeps the tool list
+the same in both modes, so a client's view of the server does not
+depend on an environment variable.

data/LICENSE

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

data/README.md

@@ -0,0 +1,181 @@
+# Zotero MCP Server (Ruby)
+
+An [MCP](https://modelcontextprotocol.io) server that lets Claude Code (and any
+other MCP client) read from and write to your [Zotero](https://www.zotero.org)
+library through the [Zotero Web API v3](https://www.zotero.org/support/dev/web_api/v3/start).
+It can search and browse items, read full text, generate formatted
+bibliographies, and create, update, and delete items, notes, and collections.
+
+Pure Ruby: the only dependency is the official `mcp` gem. HTTP is handled with
+the standard library.
+
+## Tools
+
+| Tool | What it does | Writes? |
+|---|---|---|
+| `zotero_search_items` | Search or browse items (query, type, tag, sort, paging) | no |
+| `zotero_get_item` | Fetch one item's full data, optionally with its children | no |
+| `zotero_list_collections` | List collections (folders) | no |
+| `zotero_get_collection_items` | List items inside a collection | no |
+| `zotero_list_tags` | List tags, optionally filtered | no |
+| `zotero_get_item_fulltext` | Indexed full text of an attachment (e.g. a PDF), or of its parent item — the attachment is resolved automatically (PDFs first); paged with `offset`/`max_chars` | no |
+| `zotero_generate_bibliography` | Formatted references in a CSL style (APA, IEEE, …), for up to 50 items or a whole collection; a collection comes 100 items at a time, continued with `start` | no |
+| `zotero_get_item_template` | List item types, or get a blank template + creator types | no |
+| `zotero_create_item` | Create an item from a type template | **yes** |
+| `zotero_create_note` | Create a standalone or child note | **yes** |
+| `zotero_update_item` | Update fields, tags, or collections of an item | **yes** |
+| `zotero_delete_item` | Delete items (up to 50; goes to trash, recoverable) | **yes** |
+| `zotero_add_to_collection` | Add existing items to a collection | **yes** |
+| `zotero_create_collection` | Create a collection, optionally nested | **yes** |
+
+## Requirements
+
+- Ruby 3.3 or newer.
+- [Bundler](https://bundler.io) to install the `mcp` gem.
+- A Zotero account and a library to connect to.
+
+## Setup
+
+### 1. Install
+
+Either run it from a checkout:
+
+```bash
+cd zotero-mcp
+bundle install
+```
+
+or build and install the gem, which puts a `zotero-mcp` command on your
+`PATH` and pulls in the `mcp` gem:
+
+```bash
+gem build zotero-mcp.gemspec
+gem install ./zotero-mcp-*.gem
+```
+
+### 2. Get a Zotero API key and library id
+
+1. Sign in and open <https://www.zotero.org/settings/keys>.
+2. Create a new key. Grant **read** access, and **write** access too if you
+   want the create/update/delete tools to work. For a group library, allow the
+   relevant group.
+3. Copy the key. Your numeric **userID** is shown on that same page.
+
+You can also skip the library id — if `ZOTERO_LIBRARY_ID` is unset, the server
+resolves your user id from the key automatically. For a **group** library, set
+`ZOTERO_LIBRARY_TYPE=group` and `ZOTERO_LIBRARY_ID` to the group's id.
+
+### 3. Register with Claude Code
+
+Use **absolute paths** (a relative path is the most common reason a server
+fails to connect). The server is started by `exe/zotero-mcp`.
+
+From a checkout, run it through Bundler so the `mcp` gem is found (`which
+ruby` gives the Ruby to name):
+
+```bash
+claude mcp add zotero --scope user \
+  --env ZOTERO_API_KEY=your-zotero-api-key \
+  --env ZOTERO_LIBRARY_ID=1234567 \
+  --env BUNDLE_GEMFILE=/absolute/path/to/zotero-mcp/Gemfile \
+  -- /absolute/path/to/ruby -rbundler/setup /absolute/path/to/zotero-mcp/exe/zotero-mcp
+```
+
+With the gem installed, register its command instead (absolute path from
+`which zotero-mcp`):
+
+```bash
+claude mcp add zotero --scope user \
+  --env ZOTERO_API_KEY=your-zotero-api-key \
+  -- /absolute/path/to/zotero-mcp
+```
+
+Then check it connected:
+
+```bash
+claude mcp list
+```
+
+Inside a Claude Code session, `/mcp` shows the server and its tools.
+
+Prefer editing config by hand? Copy `mcp.json.example` to `.mcp.json` in your
+project (this shares the server with anyone who has the repo), fill in the
+absolute path and your credentials, and restart Claude Code.
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `ZOTERO_API_KEY` | for the Web API | Key from the Zotero settings page. |
+| `ZOTERO_LIBRARY_ID` | optional | Numeric user or group id. Auto-resolved from the key when omitted (user libraries only). |
+| `ZOTERO_LIBRARY_TYPE` | optional | `user` (default) or `group`. |
+| `ZOTERO_LOCAL` | optional | `true` reads the local Zotero desktop app instead of the web service. |
+
+## Local (desktop) mode
+
+Set `ZOTERO_LOCAL=true` to read from the Zotero desktop app running on the same
+machine (`http://localhost:23119`). First enable it in Zotero under
+**Settings → Advanced → Allow other applications on this computer to
+communicate with Zotero**.
+
+The local API is **read-only**: the write tools return a clear error in this
+mode. No API key is needed for local reads.
+
+## A typical workflow
+
+To add an item, ask for a template first so fields and creator types are valid:
+
+1. `zotero_get_item_template` with `item_type: "journalArticle"` — see the
+   fields and valid creator types.
+2. `zotero_create_item` with `item_type`, a `fields` map, `creators`, and any
+   `tags` — the server fills the template and submits it.
+
+Updates are version-safe: `zotero_update_item` fetches the item's current
+version and sends it back, so a concurrent edit fails loudly (a 412 conflict)
+rather than silently clobbering. Passing `tags` or `collection_keys` to update
+**replaces** those lists.
+
+## Tests
+
+The suite is plain [Minitest](https://github.com/minitest/minitest) and never
+touches the network: a `StubClient` records outgoing requests
+and returns canned responses, so the client, read/write endpoints, formatting,
+and tool `.call` methods are all exercised offline; `test/server_test.rb` also
+drives the assembled server through JSON-RPC (`initialize`, `tools/list`,
+`tools/call`). `bundle install` brings in the `mcp` gem and the development
+tools (Minitest, Rake, RuboCop, pinned in the `Gemfile`):
+
+```bash
+bundle exec rake test           # the whole suite (or: ruby test/all.rb)
+bundle exec ruby test/retry_test.rb   # a single file
+bundle exec rubocop             # the house style, from .rubocop.yml
+```
+
+CI (`.github/workflows/ci.yml`) runs the suite on Ruby 3.3 and 3.4, plus
+RuboCop and a gem build, on every push to `main` and every pull request.
+
+## Notes and safety
+
+- Writes are capped at 50 objects per call, matching the Zotero API.
+- Deletes move items to the Zotero **trash**, so they can be restored.
+- The server logs nothing to stdout, as required for stdio MCP servers (stdout
+  carries the JSON-RPC protocol). Errors come back to the client as tool results
+  flagged `isError`, carrying Zotero's own explanation when it sends one.
+- Give the API key the narrowest access that fits your use. Use a read-only key
+  if you never intend to write.
+
+## Troubleshooting
+
+- **Server won't connect / not listed** — use absolute paths for `ruby` and the
+  script; confirm `ruby -v` is 3.3+; run the `claude mcp add` command again.
+- **"Permission denied (403)"** — the key is missing, invalid, or lacks the
+  needed access; write tools require a write-enabled key.
+- **"Version conflict (412)"** — the item changed on the server; re-fetch it
+  with `zotero_get_item` and retry.
+- **Full text is empty** — pass the attachment's key, or its parent item's
+  key (the attachment is then resolved automatically, PDFs first), and make
+  sure Zotero has indexed that attachment.
+
+## License
+
+MIT; see `LICENSE`.

data/exe/zotero-mcp

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Zotero MCP server over stdio; configuration comes from the environment
+# (see README.md).
+require_relative "../lib/zotero/mcp"
+
+Zotero::MCP.run

data/lib/zotero/mcp/client.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        # ----------------------------------------------------------------- #
+        # HTTP client core
+        # ----------------------------------------------------------------- #
+
+        class Client
+            include ReadAPI
+            include WriteAPI
+            include ResponseHandling
+
+            def initialize(config)
+                @config = config
+            end
+
+            def library_id
+                @library_id ||= @config.library_id ||
+                                (@config.local ? "0" : resolve_library_id)
+            end
+
+            def prefix = "/#{@config.library_type}s/#{library_id}"
+
+            def request(method, path, params: {}, body: nil, headers: {})
+                uri = build_uri(path, params)
+                attempts = 0
+                begin
+                    handle(perform(method, uri, body, headers))
+                rescue RateLimitedError => e
+                    attempts += 1
+                    raise unless retryable?(e, attempts)
+
+                    sleep(e.retry_after)
+                    retry
+                end
+            end
+
+            private
+
+            def build_uri(path, params)
+                uri = URI.parse("#{@config.base_url}#{path}")
+                uri.query = URI.encode_www_form(params) unless params.empty?
+                uri
+            end
+
+            def retryable?(error, attempts)
+                attempts <= MAX_RETRIES && !error.retry_after.nil? &&
+                    error.retry_after <= MAX_BACKOFF
+            end
+
+            def perform(method, uri, body, extra_headers)
+                http = Net::HTTP.new(uri.host, uri.port)
+                http.use_ssl = uri.scheme == "https"
+                http.open_timeout = OPEN_TIMEOUT
+                http.read_timeout = READ_TIMEOUT
+                http.request(build_request(method, uri, body, extra_headers))
+            rescue SystemCallError, SocketError, IOError, Net::OpenTimeout,
+                   Net::ReadTimeout, OpenSSL::SSL::SSLError => e
+                raise ConnectionError, connection_message(e)
+            end
+
+            def connection_message(error)
+                reason = "#{error.class}: #{error.message}"
+                return "Could not reach #{@config.base_url} (#{reason})." unless
+                    @config.local
+
+                "Could not reach the local Zotero API (#{reason}). " \
+                    "Is the Zotero desktop app running?"
+            end
+
+            def build_request(method, uri, body, extra_headers)
+                request = REQUEST_CLASSES.fetch(method).new(uri)
+                default_headers.merge(extra_headers).each do |name, value|
+                    request[name] = value
+                end
+                request.body = body if body
+                request
+            end
+
+            def default_headers
+                { "Zotero-API-Version" => API_VERSION,
+                  "Zotero-API-Key" => @config.api_key }.compact
+            end
+
+            def resolve_library_id
+                check_library_id_resolvable!
+                info = parse_json(request(:get, "/keys/current").body)
+                Zotero::MCP.presence(info["userID"]&.to_s) or
+                    raise ConfigurationError, "Could not resolve library id."
+            end
+
+            def check_library_id_resolvable!
+                if @config.library_type == "group"
+                    raise ConfigurationError,
+                          "Set ZOTERO_LIBRARY_ID for group libraries."
+                end
+                return if @config.api_key
+
+                raise ConfigurationError,
+                      "Set ZOTERO_API_KEY or ZOTERO_LIBRARY_ID."
+            end
+
+            def parse_json(body)
+                JSON.parse(body.to_s)
+            rescue JSON::ParserError
+                raise APIError,
+                      "Zotero returned a response that is not valid JSON."
+            end
+
+            def get_json(path, params = {})
+                parse_json(request(:get, path, params: params).body)
+            end
+
+            def get_page(path, params)
+                response = request(:get, path, params: params)
+                Page.new(
+                    items: parse_json(response.body),
+                    total: response["Total-Results"]&.to_i,
+                    start: params[:start] || 0
+                )
+            end
+
+            def ensure_writable!
+                return if @config.write_allowed?
+
+                raise ReadOnlyError,
+                      "The local Zotero API is read-only; use the Web API " \
+                      "to write."
+            end
+        end
+    end
+end

data/lib/zotero/mcp/config.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        DEFAULT_LIMIT = 25
+        MAX_LIMIT = 100
+        MAX_WRITE_BATCH = 50
+        API_VERSION = "3"
+        WEB_BASE = "https://api.zotero.org"
+        LOCAL_BASE = "http://localhost:23119/api"
+        OPEN_TIMEOUT = 10   # seconds to establish a connection
+        READ_TIMEOUT = 60   # seconds to wait for a response
+        MAX_RETRIES = 2     # extra attempts after a 429 or a 503
+        MAX_BACKOFF = 15    # never sleep longer than this between retries
+        KEY_PATTERN = /\A[A-Za-z0-9]{1,32}\z/
+
+        REQUEST_CLASSES = {
+            get: Net::HTTP::Get,
+            post: Net::HTTP::Post,
+            patch: Net::HTTP::Patch
+        }.freeze
+
+        # ----------------------------------------------------------------- #
+        # Configuration
+        # ----------------------------------------------------------------- #
+
+        Config = Data.define(:api_key, :library_id, :library_type, :local) do
+            def self.from_env
+                type = (ENV["ZOTERO_LIBRARY_TYPE"] || "user").downcase
+                validate_type!(type)
+                new(api_key: env_presence("ZOTERO_API_KEY"),
+                    library_id: env_presence("ZOTERO_LIBRARY_ID"),
+                    library_type: type, local: env_truthy?("ZOTERO_LOCAL"))
+            end
+
+            def self.env_presence(name)
+                Zotero::MCP.presence(ENV.fetch(name, nil))
+            end
+
+            def self.env_truthy?(name)
+                Zotero::MCP.truthy?(ENV.fetch(name, nil))
+            end
+
+            def self.validate_type!(type)
+                return if %w[user group].include?(type)
+
+                raise ConfigurationError,
+                      'ZOTERO_LIBRARY_TYPE must be "user" or "group".'
+            end
+
+            def base_url = local ? LOCAL_BASE : WEB_BASE
+
+            def write_allowed? = !local
+        end
+
+        # ----------------------------------------------------------------- #
+        # Value objects
+        # ----------------------------------------------------------------- #
+
+        Page = Data.define(:items, :total, :start) do
+            def more? = total ? (start + items.length) < total : false
+
+            def next_start = more? ? start + items.length : nil
+        end
+
+        # A minimal stand-in so response handling is uniform and testable.
+        FakeResponse = Data.define(:code, :body, :headers) do
+            def [](key) = headers[key]
+        end
+    end
+end

data/lib/zotero/mcp/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        class Error < StandardError; end
+        class ConfigurationError < Error; end
+        class NotAuthorisedError < Error; end
+        class NotFoundError < Error; end
+        class ConflictError < Error; end
+        class ReadOnlyError < Error; end
+        class APIError < Error; end
+        class ConnectionError < Error; end
+
+        class RateLimitedError < Error
+            attr_reader :retry_after
+
+            def initialize(message, retry_after: nil)
+                super(message)
+                @retry_after = retry_after
+            end
+        end
+    end
+end

data/lib/zotero/mcp/formatting.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Zotero
+    module MCP
+        # ----------------------------------------------------------------- #
+        # Module-level glue: client, formatting, tool responses
+        # ----------------------------------------------------------------- #
+
+        def self.client = @client ||= Client.new(Config.from_env)
+
+        def self.text(object)
+            ::MCP::Tool::Response.new(
+                [{ type: "text", text: JSON.pretty_generate(object) }]
+            )
+        end
+
+        def self.error_text(message)
+            ::MCP::Tool::Response.new(
+                [{ type: "text", text: JSON.pretty_generate(error: message) }],
+                error: true
+            )
+        end
+
+        def self.guard
+            yield
+        rescue Error => e
+            error_text(e.message)
+        rescue StandardError => e
+            error_text("Unexpected #{e.class}: #{e.message}")
+        end
+
+        def self.format_page(page, response_format)
+            items = if response_format == "json"
+                        page.items
+                    else
+                        page.items.map { |item| summarize(item) }
+                    end
+            { pagination: pagination_of(page), items: items }
+        end
+
+        def self.pagination_of(page)
+            {
+                count: page.items.length, start: page.start, total: page.total,
+                has_more: page.more?, next_start: page.next_start
+            }.compact
+        end
+
+        def self.summarize(item)
+            data = item["data"] || {}
+            meta = item["meta"] || {}
+            summary_core(item, data, meta).merge(
+                summary_extra(data, meta)
+            ).compact
+        end
+
+        def self.summary_core(item, data, meta)
+            {
+                key: item["key"], version: item["version"],
+                itemType: data["itemType"], title: title_of(data),
+                creators: creators_of(data, meta),
+                date: data["date"] || meta["parsedDate"]
+            }
+        end
+
+        def self.summary_extra(data, meta)
+            {
+                publication: publication_of(data), DOI: data["DOI"],
+                url: data["url"], tags: tags_of(data),
+                collections: nonempty(data["collections"]),
+                numChildren: meta["numChildren"]
+            }
+        end
+
+        def self.title_of(data)
+            data["title"] || data["caseName"] || data["subject"]
+        end
+
+        def self.publication_of(data)
+            data["publicationTitle"] || data["bookTitle"] ||
+                data["proceedingsTitle"] || data["publisher"]
+        end
+
+        def self.tags_of(data)
+            names = (data["tags"] || []).map { |tag| tag["tag"] }
+            nonempty(names)
+        end
+
+        def self.creators_of(data, meta)
+            names = (data["creators"] || [])
+                    .map { |creator| creator_name(creator) }
+                    .reject(&:empty?)
+            return meta["creatorSummary"] if names.empty?
+
+            summarize_names(names)
+        end
+
+        def self.creator_name(creator)
+            creator["name"] ||
+                [creator["firstName"], creator["lastName"]].compact.join(" ")
+        end
+
+        def self.summarize_names(names)
+            return names.join(", ") if names.length <= 3
+
+            "#{names.first(3).join(", ")} (+#{names.length - 3} more)"
+        end
+    end
+end