zoty

Instructions

Implementation Reference

• src/zoty/server.py:75-85 (handler)

  MCP tool handler registered with @mcp_server.tool() decorator. Defines the get_recent_items function that accepts a limit parameter (default 10) and delegates to db.get_recent_items().

  @mcp_server.tool()
  def get_recent_items(limit: int = 10) -> str:
      """Get recently added items from the Zotero library, sorted by date added.
  
      Args:
          limit: Maximum items to return (default: 10)
  
      Returns:
          JSON with item metadata for recently added items.
      """
      return db.get_recent_items(limit=limit)

• src/zoty/db.py:228-243 (handler)

  Core implementation of get_recent_items. Fetches items from Zotero using pyzotero, sorted by dateAdded descending, filters out attachment/note/annotation types, and returns JSON with item metadata.

  def get_recent_items(limit: int = 10) -> str:
      """Recently added items, sorted by dateAdded descending."""
      limit = max(1, limit)
      try:
          zot = _get_zot()
          items = zot.items(
              limit=limit * 3,  # over-fetch to account for filtered types
              sort="dateAdded",
              direction="desc",
          )
          items = [i for i in items if i.get("data", {}).get("itemType") not in _SKIP_TYPES][:limit]
      except Exception as e:
          return json.dumps({"error": f"Failed to fetch recent items: {e}"})
  
      result = [_item_to_dict(item, truncate_abstract=500) for item in items]
      return json.dumps({"items": result, "total": len(result)})

• src/zoty/db.py:21-26 (helper)

  _get_zot() helper function that creates and returns a shared pyzotero Zotero client instance for local library access.

  def _get_zot() -> zotero.Zotero:
      """Return the shared pyzotero client, creating it on first call."""
      global _zot
      if _zot is None:
          _zot = zotero.Zotero("0", "user", local=True)
      return _zot

• src/zoty/db.py:43-64 (helper)

  _item_to_dict() helper that converts pyzotero item objects to concise dictionaries with title, creators, abstract, DOI, URL, tags, and collections fields.

  def _item_to_dict(item: dict, truncate_abstract: int = 0) -> dict:
      """Convert a pyzotero item to a concise dict for tool output."""
      data = item.get("data", {})
      abstract = data.get("abstractNote", "")
      if truncate_abstract > 0 and len(abstract) > truncate_abstract:
          abstract = abstract[:truncate_abstract] + "..."
  
      collections = data.get("collections", [])
      tags = [t.get("tag", "") for t in data.get("tags", []) if t.get("tag")]
  
      return {
          "key": data.get("key", ""),
          "itemType": data.get("itemType", ""),
          "title": data.get("title", ""),
          "creators": _format_creators(data.get("creators", [])),
          "date": data.get("date", ""),
          "DOI": data.get("DOI", ""),
          "url": data.get("url", ""),
          "tags": tags,
          "collections": collections,
          "abstract": abstract,
      }

• src/zoty/db.py:67-67 (helper)

  _SKIP_TYPES constant defining item types to filter out: attachment, note, and annotation.

  _SKIP_TYPES = {"attachment", "note", "annotation"}