list_collection_items

Retrieve metadata for items stored in a Zotero collection to browse research papers and manage library content.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`collection_key`	Yes
`limit`	No

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

zoty