Zotero MCP

Instructions

Implementation Reference

• src/zotero_mcp/server.py:918-1079 (handler)

  The main handler function for the 'zotero_advanced_search' tool. It creates a temporary saved search in Zotero using the provided conditions, executes it, formats the results in markdown, and cleans up the saved search afterward.
  name="zotero_advanced_search", description="Perform an advanced search with multiple criteria." ) def advanced_search( conditions: List[Dict[str, str]], join_mode: Literal["all", "any"] = "all", sort_by: Optional[str] = None, sort_direction: Literal["asc", "desc"] = "asc", limit: Union[int, str] = 50, *, ctx: Context ) -> str: """ Perform an advanced search with multiple criteria. Args: conditions: List of search condition dictionaries, each containing: - field: The field to search (title, creator, date, tag, etc.) - operation: The operation to perform (is, isNot, contains, etc.) - value: The value to search for join_mode: Whether all conditions must match ("all") or any condition can match ("any") sort_by: Field to sort by (dateAdded, dateModified, title, creator, etc.) sort_direction: Direction to sort (asc or desc) limit: Maximum number of results to return ctx: MCP context Returns: Markdown-formatted search results """ try: if not conditions: return "Error: No search conditions provided" ctx.info(f"Performing advanced search with {len(conditions)} conditions") zot = get_zotero_client() # Prepare search parameters params = {} # Add sorting parameters if specified if sort_by: params["sort"] = sort_by params["direction"] = sort_direction if isinstance(limit, str): limit = int(limit) # Add limit parameter params["limit"] = limit # Build search conditions search_conditions = [] for i, condition in enumerate(conditions): if "field" not in condition or "operation" not in condition or "value" not in condition: return f"Error: Condition {i+1} is missing required fields (field, operation, value)" # Map common field names to Zotero API fields if needed field = condition["field"] operation = condition["operation"] value = condition["value"] # Handle special fields if field == "author" or field == "creator": field = "creator" elif field == "year": field = "date" # Convert year to partial date format for matching value = str(value) search_conditions.append({ "condition": field, "operator": operation, "value": value }) # Add join mode condition search_conditions.append({ "condition": "joinMode", "operator": join_mode, "value": "" }) # Create a saved search search_name = f"temp_search_{uuid.uuid4().hex[:8]}" saved_search = zot.saved_search( search_name, search_conditions ) # Extract the search key from the result if not saved_search.get("success"): return f"Error creating saved search: {saved_search.get('failed', 'Unknown error')}" search_key = next(iter(saved_search.get("success", {}).values()), None) # Execute the saved search try: results = zot.collection_items(search_key) finally: # Clean up the temporary saved search try: zot.delete_saved_search([search_key]) except Exception as cleanup_error: ctx.warn(f"Error cleaning up saved search: {str(cleanup_error)}") # Format the results if not results: return "No items found matching the search criteria." output = ["# Advanced Search Results", ""] output.append(f"Found {len(results)} items matching the search criteria:") output.append("") # Add search criteria summary output.append("## Search Criteria") output.append(f"Join mode: {join_mode.upper()}") for i, condition in enumerate(conditions, 1): output.append(f"{i}. {condition['field']} {condition['operation']} \"{condition['value']}\"") output.append("") # Format results output.append("## Results") for i, item in enumerate(results, 1): data = item.get("data", {}) title = data.get("title", "Untitled") item_type = data.get("itemType", "unknown") date = data.get("date", "No date") key = item.get("key", "") # Format creators creators = data.get("creators", []) creators_str = format_creators(creators) # Build the formatted entry output.append(f"### {i}. {title}") output.append(f"**Type:** {item_type}") output.append(f"**Item Key:** {key}") output.append(f"**Date:** {date}") output.append(f"**Authors:** {creators_str}") # Add abstract snippet if present if abstract := data.get("abstractNote"): # Limit abstract length for search results abstract_snippet = abstract[:150] + "..." if len(abstract) > 150 else abstract output.append(f"**Abstract:** {abstract_snippet}") # Add tags if present if tags := data.get("tags"): tag_list = [f"`{tag['tag']}`" for tag in tags] if tag_list: output.append(f"**Tags:** {' '.join(tag_list)}") output.append("") # Empty line between items return "\n".join(output) except Exception as e: ctx.error(f"Error in advanced search: {str(e)}") return f"Error in advanced search: {str(e)}"
• src/zotero_mcp/server.py:918-920 (registration)

  The @mcp.tool decorator registers the advanced_search function as the 'zotero_advanced_search' tool.
  name="zotero_advanced_search", description="Perform an advanced search with multiple criteria." )