<< All versions

Skill v1.0.0

currentAutomated scan100/100
kerim/zotero-code-execution/skill
──Details
PublishedOctober 30, 2026 at 04:28 PM
Content Hashsha256:0b00568118e2dff6...
Git SHA9d521ef71dfd
──Files
Files (1 file, 13.5 KB)
SKILL.md13.5 KBactive
SKILL.md · 505 lines · 13.5 KB

name: zotero-mcp-code description: Search Zotero library using code execution for efficient multi-strategy searches without crash risks. Use this skill when the user needs comprehensive Zotero searches with automatic deduplication and ranking. metadata: version: "1.0.0"

Zotero MCP Code Execution Skill

Search your Zotero library using code execution for safe, efficient, comprehensive searches.

🎯 Core Concept

Instead of calling MCP tools directly (which loads all results into context and risks crashes), write Python code that:

  1. Fetches large datasets (50-100+ items per strategy)
  2. Filters and ranks in code execution environment
  3. Returns only top N results to context

Benefits:

  • ✅ No crash risk (large data stays in code)
  • ✅ Automatic multi-strategy search
  • ✅ Automatic deduplication
  • ✅ Automatic ranking
  • ✅ One function call instead of 5-10

🚀 Basic Usage

For 90% of Zotero searches, use this simple pattern:

python
import sys
sys.path.append('/Users/niyaro/Documents/Code/zotero-code-execution')
import setup_paths
from zotero_lib import SearchOrchestrator, format_results
# Single comprehensive search
orchestrator = SearchOrchestrator()
results = orchestrator.comprehensive_search(
    "user's query here",
    max_results=20  # Return top 20 most relevant
)
# Format and display
print(format_results(results, include_abstracts=True))

This automatically:

  • Performs semantic search (multiple variations)
  • Performs keyword search (multiple variations)
  • Performs tag-based search
  • Fetches 100+ items total
  • Deduplicates results
  • Ranks by relevance
  • Returns only top 20 to context

📋 Common Patterns

Pattern 1: Simple Search (Most Common)

User asks: "Find papers about embodied cognition"

python
import sys
sys.path.append('/Users/niyaro/Documents/Code/zotero-code-execution')
import setup_paths
from zotero_lib import SearchOrchestrator, format_results
orchestrator = SearchOrchestrator()
results = orchestrator.comprehensive_search("embodied cognition", max_results=20)
print(format_results(results))

Pattern 2: Filtered Search

User asks: "Find recent journal articles about machine learning"

python
import sys
sys.path.append('/Users/niyaro/Documents/Code/zotero-code-execution')
import setup_paths
from zotero_lib import ZoteroLibrary, SearchOrchestrator, format_results
library = ZoteroLibrary()
orchestrator = SearchOrchestrator(library)
# Fetch broadly (safe - filtering happens in code)
items = library.search_items("machine learning", limit=100)
# Filter in code
filtered = orchestrator.filter_by_criteria(
    items,
    item_types=["journalArticle"],
    date_range=(2020, 2025)
)
print(format_results(filtered[:15]))

Pattern 3: Author Search

User asks: "What papers do I have by Kahneman?"

python
import sys
sys.path.append('/Users/niyaro/Documents/Code/zotero-code-execution')
import setup_paths
from zotero_lib import ZoteroLibrary, format_results
library = ZoteroLibrary()
results = library.search_items(
    "Kahneman",
    qmode="titleCreatorYear",
    limit=50
)
# Sort by date
sorted_results = sorted(results, key=lambda x: x.date, reverse=True)
print(format_results(sorted_results))

Pattern 4: Tag-Based Search

User asks: "Show me papers tagged with 'learning' and 'cognition'"

python
import sys
sys.path.append('/Users/niyaro/Documents/Code/zotero-code-execution')
import setup_paths
from zotero_lib import ZoteroLibrary, format_results
library = ZoteroLibrary()
results = library.search_by_tag(["learning", "cognition"], limit=50)
print(format_results(results[:20]))

Pattern 5: Recent Papers

User asks: "What did I recently add?"

python
import sys
sys.path.append('/Users/niyaro/Documents/Code/zotero-code-execution')
import setup_paths
from zotero_lib import ZoteroLibrary, format_results
library = ZoteroLibrary()
results = library.get_recent(limit=20)
print(format_results(results))

Pattern 6: Multi-Topic Search

User asks: "Find papers about both cognition and learning"

python
import sys
sys.path.append('/Users/niyaro/Documents/Code/zotero-code-execution')
import setup_paths
from zotero_lib import SearchOrchestrator, format_results
orchestrator = SearchOrchestrator()
# Search both topics
results1 = orchestrator.comprehensive_search("cognition", max_results=30)
results2 = orchestrator.comprehensive_search("learning", max_results=30)
# Find intersection
keys1 = {item.key for item in results1}
keys2 = {item.key for item in results2}
common_keys = keys1 & keys2
if common_keys:
    common_items = [item for item in results1 if item.key in common_keys]
    print("Papers about both topics:")
    print(format_results(common_items))
else:
    print("No papers found on both topics.")
    print("\nCognition results:")
    print(format_results(results1[:10]))
    print("\nLearning results:")
    print(format_results(results2[:10]))

🔧 Advanced Usage

Custom Filtering Logic

python
import sys
sys.path.append('/Users/niyaro/Documents/Code/zotero-code-execution')
import setup_paths
from zotero_lib import ZoteroLibrary, SearchOrchestrator, format_results
library = ZoteroLibrary()
orchestrator = SearchOrchestrator(library)
# Fetch large dataset
items = library.search_items("neural networks", limit=100)
# Custom filtering
recent_with_doi = [
    item for item in items
    if item.doi and item.date and int(item.date[:4]) >= 2020
]
print(format_results(recent_with_doi[:15]))

Multi-Angle Custom Search

python
import sys
sys.path.append('/Users/niyaro/Documents/Code/zotero-code-execution')
import setup_paths
from zotero_lib import ZoteroLibrary, SearchOrchestrator, format_results
library = ZoteroLibrary()
orchestrator = SearchOrchestrator(library)
all_results = set()
# Multiple search angles
queries = [
    "skill transfer",
    "transfer of learning",
    "generalization of skills"
]
for query in queries:
    results = library.search_items(query, limit=30)
    all_results.update(results)
# Rank combined results
ranked = orchestrator._rank_items(list(all_results), "skill transfer")
print(format_results(ranked[:20]))

Iterative Refinement

python
import sys
sys.path.append('/Users/niyaro/Documents/Code/zotero-code-execution')
import setup_paths
from zotero_lib import ZoteroLibrary, SearchOrchestrator, format_results
library = ZoteroLibrary()
orchestrator = SearchOrchestrator(library)
# Initial search
initial = library.search_items("memory", limit=50)
# Analyze tags
tag_freq = {}
for item in initial:
    for tag in item.tags:
        tag_freq[tag] = tag_freq.get(tag, 0) + 1
# Find most common tag
if tag_freq:
    most_common_tag = max(tag_freq, key=tag_freq.get)
    # Refine search
    refined = orchestrator.filter_by_criteria(
        initial,
        required_tags=[most_common_tag]
    )
    print(f"Papers with most common tag '{most_common_tag}':")
    print(format_results(refined))

📚 API Reference

SearchOrchestrator

Main class for automated searching.

comprehensive_search(query, max_results=20, use_semantic=True, use_keyword=True, use_tags=True, search_limit_per_strategy=50)

Performs multi-strategy search with automatic deduplication and ranking.

Parameters:

  • query (str): Search query
  • max_results (int): Maximum results to return (default: 20)
  • use_semantic (bool): Use semantic search (default: True)
  • use_keyword (bool): Use keyword search (default: True)
  • use_tags (bool): Use tag search (default: True)
  • search_limit_per_strategy (int): Items to fetch per strategy (default: 50)

Returns: List of ZoteroItem objects

filter_by_criteria(items, item_types=None, date_range=None, required_tags=None, excluded_tags=None)

Filter items by various criteria.

Parameters:

  • items (list): Items to filter
  • item_types (list): Allowed item types (e.g., ["journalArticle"])
  • date_range (tuple): (min_year, max_year)
  • required_tags (list): Tags that must be present
  • excluded_tags (list): Tags that must not be present

Returns: Filtered list of ZoteroItem objects

ZoteroLibrary

Low-level interface to Zotero.

search_items(query, qmode="titleCreatorYear", item_type="-attachment", limit=100, tag=None)

Basic keyword search.

semantic_search(query, limit=100, search_type="hybrid")

Semantic/vector search.

search_by_tag(tags, item_type="-attachment", limit=100)

Search by tags.

get_recent(limit=50)

Get recently added items.

get_tags()

Get all tags in library.

format_results(items, include_abstracts=True, max_abstract_length=300)

Format items as markdown.

⚙️ Configuration

Default Parameters

Good defaults for most searches:

python
orchestrator.comprehensive_search(
    query,
    max_results=20,              # Top 20 results
    search_limit_per_strategy=50 # Fetch 50 per strategy
)

Adjusting Search Depth

For quick searches (fewer results, faster):

python
results = orchestrator.comprehensive_search(
    query,
    max_results=10,
    search_limit_per_strategy=20
)

For thorough searches (more comprehensive):

python
results = orchestrator.comprehensive_search(
    query,
    max_results=30,
    search_limit_per_strategy=100
)

🔍 How It Works

Behind the Scenes

When you call comprehensive_search("embodied cognition", max_results=20):

  1. Semantic Search (if enabled):
  • Searches "embodied cognition" (hybrid mode) → 50 items
  • Searches "embodied cognition" (vector mode) → 50 items
  1. Keyword Search (if enabled):
  • Searches with qmode="everything" → 50 items
  • Searches with qmode="titleCreatorYear" → 50 items
  1. Tag Search (if enabled):
  • Extracts words from query
  • Finds matching tags in library
  • Searches by matching tags → 50 items
  1. Processing:
  • Combines all results (~250 items)
  • Deduplicates using item keys (~120 unique)
  • Ranks by relevance score
  • Returns top 20
  1. Context:
  • Only the final 20 items go to LLM context
  • All processing happens in code execution environment

Why This Is Better

Old Approach (Direct MCP):

python
# 5+ function calls, all results to context
results1 = zotero_semantic_search("query", limit=10)  # Crash risk if > 15
results2 = zotero_search_items("query", limit=10)
# ... manual deduplication, no ranking
# All items (50+) load into context

New Approach (Code Execution):

python
# 1 function call, only top results to context
results = orchestrator.comprehensive_search("query", max_results=20)
# Fetches 250+ items, processes in code, returns top 20

🛠️ Error Handling

Always handle potential errors:

python
import sys
sys.path.append('/Users/niyaro/Documents/Code/zotero-code-execution')
import setup_paths
from zotero_lib import SearchOrchestrator, format_results
orchestrator = SearchOrchestrator()
try:
    results = orchestrator.comprehensive_search("query", max_results=20)
    if results:
        print(format_results(results))
    else:
        print("No results found. Try a broader search term.")
except Exception as e:
    print(f"Search failed: {e}")
    print("Please check your Zotero MCP configuration.")

📖 Examples

See /Users/niyaro/Documents/Code/zotero-code-execution/examples.py for 8 complete working examples.

🎓 Quick Reference

TaskCode
Basic searchorchestrator.comprehensive_search(query, max_results=20)
Filter by typeorchestrator.filter_by_criteria(items, item_types=["journalArticle"])
Filter by dateorchestrator.filter_by_criteria(items, date_range=(2020, 2025))
Search authorlibrary.search_items(author, qmode="titleCreatorYear", limit=50)
Search by taglibrary.search_by_tag([tags], limit=50)
Recent itemslibrary.get_recent(limit=20)
Format outputformat_results(items, include_abstracts=True)

💡 Tips

  1. Start simple: Use comprehensive_search() for most queries
  2. Adjust depth: Use search_limit_per_strategy to control thoroughness
  3. Filter after: Fetch broadly, filter in code
  4. Custom logic: Use Python for complex filtering
  5. Check errors: Always wrap in try/except

📁 Documentation

  • Quick Start: /Users/niyaro/Documents/Code/zotero-code-execution/QUICK_START.md
  • Full Docs: /Users/niyaro/Documents/Code/zotero-code-execution/README.md
  • Examples: /Users/niyaro/Documents/Code/zotero-code-execution/examples.py
  • Status: /Users/niyaro/Documents/Code/zotero-code-execution/HONEST_STATUS.md

⚠️ Important Notes

  • This uses code execution, not direct MCP calls
  • Large datasets are processed in code, keeping context small
  • Semantic search may not be available (falls back to keyword)
  • Results are automatically deduplicated and ranked
  • Safe to use large limits (100+) because filtering happens in code

🔄 Migration from zotero-mcp

Old pattern:

python
# Multiple manual MCP calls
results1 = zotero_semantic_search("query", limit=10)
results2 = zotero_search_items("query", limit=10)
# Manual deduplication...

New pattern:

python
# One function call with code execution
import sys
sys.path.append('/Users/niyaro/Documents/Code/zotero-code-execution')
import setup_paths
from zotero_lib import SearchOrchestrator, format_results
orchestrator = SearchOrchestrator()
results = orchestrator.comprehensive_search("query", max_results=20)
print(format_results(results))

Remember: This skill uses code execution to safely handle large searches. The implementation is in /Users/niyaro/Documents/Code/zotero-code-execution/.

All versions