zotero-mcp-code

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.

Quality

50%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skill/SKILL.md

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:

Fetches large datasets (50-100+ items per strategy)
Filters and ranks in code execution environment
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:

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"

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"

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?"

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'"

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?"

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"

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

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

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

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:

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):

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

For thorough searches (more comprehensive):

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):

Semantic Search (if enabled):
- Searches "embodied cognition" (hybrid mode) → 50 items
- Searches "embodied cognition" (vector mode) → 50 items
Keyword Search (if enabled):
- Searches with qmode="everything" → 50 items
- Searches with qmode="titleCreatorYear" → 50 items
Tag Search (if enabled):
- Extracts words from query
- Finds matching tags in library
- Searches by matching tags → 50 items
Processing:
- Combines all results (~250 items)
- Deduplicates using item keys (~120 unique)
- Ranks by relevance score
- Returns top 20
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):

# 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):

# 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:

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

Task	Code
Basic search	`orchestrator.comprehensive_search(query, max_results=20)`
Filter by type	`orchestrator.filter_by_criteria(items, item_types=["journalArticle"])`
Filter by date	`orchestrator.filter_by_criteria(items, date_range=(2020, 2025))`
Search author	`library.search_items(author, qmode="titleCreatorYear", limit=50)`
Search by tag	`library.search_by_tag([tags], limit=50)`
Recent items	`library.get_recent(limit=20)`
Format output	`format_results(items, include_abstracts=True)`

💡 Tips

Start simple: Use comprehensive_search() for most queries
Adjust depth: Use search_limit_per_strategy to control thoroughness
Filter after: Fetch broadly, filter in code
Custom logic: Use Python for complex filtering
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:

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

New pattern:

# 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/.

Repository: kerim/zotero-code-execution
Commit: 9d521ef

Last updated: 3 months ago
Created: 3 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.