zoty

Instructions

Implementation Reference

• src/zoty/server.py:48-59 (handler)

  MCP tool handler decorated with @mcp_server.tool() that registers 'list_collection_items' as a tool. Accepts collection_key and limit parameters, validates inputs via type hints, and delegates to db.list_collection_items for execution.

  @mcp_server.tool()
  def list_collection_items(collection_key: str, limit: int = 50) -> str:
      """List items in a specific Zotero collection.
  
      Args:
          collection_key: The Zotero collection key (from list_collections)
          limit: Maximum items to return (default: 50)
  
      Returns:
          JSON with item metadata for each item in the collection.
      """
      return db.list_collection_items(collection_key, limit=limit)

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

  Core implementation that fetches items from a Zotero collection using pyzotero client. Filters out attachments and notes, formats each item using _item_to_dict, and returns JSON with items list and total count.

  def list_collection_items(collection_key: str, limit: int = 50) -> str:
      """Return items in a specific collection."""
      limit = max(1, limit)
      try:
          zot = _get_zot()
          items = zot.collection_items(collection_key, limit=limit)
      except Exception as e:
          return json.dumps({"error": f"Failed to fetch collection items: {e}"})
  
      result = []
      for item in items:
          data = item.get("data", {})
          if data.get("itemType") in ("attachment", "note"):
              continue
          result.append(_item_to_dict(item, truncate_abstract=500))
  
      return json.dumps({"items": result, "total": len(result)})

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

  Helper function that defines the output schema by converting pyzotero item dicts to a standardized format with key, itemType, title, creators, date, DOI, url, tags, collections, and abstract fields. Supports abstract truncation for list views.

  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,
      }