zotero-mcp

Instructions

Implementation Reference

• src/zotero_mcp/client.py:202-252 (handler)

  The core logic for creating an item from a DOI, utilizing the Zotero translator service or CrossRef API.

  def create_item_from_doi(
      self,
      doi: str,
      collections: list[str] | None = None,
      tags: list[str] | None = None,
  ) -> dict:
      """Create item from DOI using Zotero translator. Returns {key, title}."""
      import json
      import urllib.request
  
      metadata = None
      # Try Zotero translator first
      try:
          req = urllib.request.Request(
              "https://translate.zotero.org/search",
              data=doi.encode(),
              headers={"Content-Type": "text/plain"},
          )
          with urllib.request.urlopen(req, timeout=10) as resp:
              items = json.loads(resp.read())
              if items:
                  metadata = items[0]
      except Exception as e:
          logger.warning(f"Zotero translator failed: {e}, trying CrossRef")
  
      # Fallback to CrossRef
      if not metadata:
          try:
              cr_url = f"https://api.crossref.org/works/{doi}"
              req = urllib.request.Request(cr_url, headers={"User-Agent": "ZoteroMCP/0.1"})
              with urllib.request.urlopen(req, timeout=10) as resp:
                  data = json.loads(resp.read())["message"]
                  metadata = self._crossref_to_zotero(data)
          except Exception as e:
              raise RuntimeError(f"Could not resolve DOI {doi}: {e}")
  
      if not metadata:
          raise RuntimeError(f"No metadata found for DOI {doi}")
  
      if collections:
          metadata["collections"] = collections
      if tags:
          metadata["tags"] = [{"tag": t} for t in tags]
  
      resp = self.zot.create_items([metadata])
      created = resp.get("successful", resp.get("success", {}))
      if created:
          val = list(created.values())[0] if isinstance(created, dict) else created[0]
          key = val.get("key", val.get("data", {}).get("key", "")) if isinstance(val, dict) else str(val)
          return {"key": key, "title": metadata.get("title", "")}
      raise RuntimeError(f"Failed to create item: {resp.get('failed', resp)}")

• src/zotero_mcp/server.py:134-142 (registration)

  The MCP tool registration and invocation call to the Zotero client for creating an item from a DOI.

  @mcp.tool(description="Create a Zotero item from a DOI (auto-fills metadata)")
  def create_item_from_doi(
      doi: str,
      collections: list[str] | None = None,
      tags: list[str] | None = None,
  ) -> str:
      """Look up DOI metadata and create item automatically."""
      result = _get_client().create_item_from_doi(doi, collections, tags)
      return json.dumps(result, ensure_ascii=False)