zotero-mcp

Imported from kerim/zotero-mcp-skill (SKILL.md). Install upstream with npx skills add kerim/zotero-mcp-skill. Copyright stays with the author.

Zotero MCP Search Skill

Interface with Zotero's MCP server to search and retrieve bibliographic data using advanced semantic search and multi-strategy approaches.

Designed for plain markdown outline output: This skill generates bibliographies formatted as plain markdown outlines suitable for pasting into Logseq with:

• Outline hierarchy (nested bullets, no markdown headers)
• Compact citation format (Author, Year. Title)
• Side-by-side Chinese-English translations for improved English language search
• Plain text (no bold styling)
• Zotero item links

Context-Aware Skill: This skill automatically adapts its strategy based on the environment:

• Claude Code: Uses autonomous agents for comprehensive multi-step searches
• Claude Desktop: Uses batched manual searches with safety limits

Core Philosophy

Search comprehensively, not narrowly. Never settle for a single search attempt. Always:

• Use semantic search for conceptual discovery
• Try multiple search angles and variations
• Combine different search methods
• Iteratively refine based on results
• Ask clarifying questions when needed
• Format bibliographies for Logseq with proper outline structure

Environment Detection

Detect which environment you're running in:

• Claude Code: Agents available (Task tool), no conversation crash risk
• Claude Desktop: No agents, conversation deletion risk with large responses

How to tell: Check if Task tool is available in your tool list.

PART 1: Claude Desktop Strategy

⚠️ CRITICAL: Avoiding Claude Desktop Crashes ⚠️

KNOWN BUG: Claude Desktop has a critical bug where large MCP responses cause request timeouts that DELETE the entire conversation without warning or recovery.

Safe Search Strategy: Batched Iteration

To get comprehensive results safely, use iterative batched searches:

✅ SAFE: Multiple small searches

• Each search limited to 10-15 results maximum
• Multiple searches with different angles/filters
• Combine results across searches

❌ UNSAFE: Single large search

• limit=50 or higher in one call
• Risks conversation deletion
• No recovery possible

Recommended Approaches for Claude Desktop

Approach 1: Multi-Angle Coverage (Preferred)

Instead of one search with limit=50, do 5 searches with different angles:

1. Semantic search: "main concept" (limit=10)
2. Semantic search: "related concept variation" (limit=10)
3. Keyword search: "specific terms" (limit=10)
4. Tag-based search: relevant tags (limit=10)
5. Notes/annotations search: "concept" (limit=10)

This gives ~50 results from different perspectives, safer than one large call.

Approach 2: Iterative Interactive

For user-guided exploration:

1. First batch: limit=10
2. Present results
3. Ask: "Would you like more results, or shall I search from a different angle?"
4. Next batch based on user feedback

Default Limits for Claude Desktop

Always use these safe defaults:

• limit=10 for initial searches
• limit=15 if user explicitly needs more
• Never exceed limit=20 in a single call
• For comprehensive results: use multiple searches, not larger limits

PART 2: Claude Code Strategy

Agent-First Approach

When running in Claude Code, use autonomous agents for comprehensive searches.

When to Use Agents (Claude Code Only)

Use agents when:

• User needs comprehensive literature searches
• User asks exploratory questions ("What do I have about...")
• User needs multi-angle search coverage
• User wants thorough, curated results
• User's query is conceptual or thematic

Don't use agents when:

• User asks for a single specific paper by exact title
• User just wants to see recent additions
• User is browsing collections interactively

Agent Task Patterns

Pattern 1: Comprehensive Topic Search

User request: "Find me papers about [topic]"

Agent task:

Search my Zotero library comprehensively for papers about [topic].

Use multiple search strategies autonomously:

1. SEMANTIC SEARCHES (5-6 variations)
   - Try natural language phrasings
   - Try different conceptual angles
   - Use synonyms and related terms
   - No limit restrictions - get comprehensive results

2. KEYWORD SEARCHES (3-4 variations)
   - Try exact terms and variations
   - Try broader/narrower terms
   - Try related methodology terms

3. TAG-BASED SEARCHES
   - First use zotero_get_tags to discover relevant tags
   - Then search by multiple relevant tags
   - Try tag combinations

4. FULL-TEXT & ANNOTATIONS
   - Use zotero_search_notes for the concept
   - Use zotero_get_annotations to find highlights
   - Search for related concepts in notes

5. SYNTHESIS
   - Combine all results and deduplicate
   - Identify the 20-30 most relevant papers
   - Group by theme/approach if applicable
   - Provide brief relevance explanations

Return a curated list with:
- Paper metadata (title, authors, year)
- Why each paper is relevant
- Thematic groupings if applicable
- Coverage note (which strategies found what)

Pattern 2: Author-Focused Search

User request: "What do I have by/about [author]?"

Agent task:

Find all items related to [author] in my Zotero library.

Search comprehensively:

1. DIRECT AUTHORSHIP
   - zotero_search_items with author="[author]"
   - zotero_advanced_search with author field

2. CITATIONS & MENTIONS
   - zotero_search_notes: "[author]" (cited in my notes)
   - zotero_get_annotations: "[author]" (mentioned in highlights)
   - zotero_semantic_search: "[author]'s main concepts/theories"

3. RELATED WORK
   - Search for concepts/theories associated with this author
   - Search for methodologies they use
   - Search for co-authors

4. SYNTHESIS
   - Organize by: (1) authored by, (2) cited in my notes, (3) related concepts
   - Include temporal overview if relevant
   - Note any thematic clusters

Return organized results with context about how each item relates to [author].

Pattern 3: Concept in Context

User request: "Research about X in context Y"

Agent task:

Find papers about [X] in the context of [Y].

Multi-angle search strategy:

1. COMBINED SEARCHES
   - Semantic: "X in Y" + variations
   - Semantic: "Y approaches to X"
   - Advanced: keyword=X AND keyword=Y
   - Advanced: keyword=X AND keyword=[Y synonyms]

2. SEPARATE THEN CROSS-REFERENCE
   - Find strong X papers
   - Find strong Y papers
   - Identify overlap and connections
   - Check if X papers mention Y in fulltext
   - Check if Y papers mention X in fulltext

3. TAG ANALYSIS
   - Get tags related to X
   - Get tags related to Y
   - Search items tagged with both domains
   - Find bridging concepts in tags

4. ANNOTATION MINING
   - Search notes for X+Y together
   - Search notes for X and Y separately
   - Check if you've annotated connections

5. SYNTHESIS
   - Papers directly about X in Y context
   - Papers about X that discuss Y
   - Papers about Y that discuss X
   - Papers that bridge both (even if not explicit)

Return results grouped by relevance strength and connection type.

Pattern 4: Exploratory Discovery

User request: "What's related to X?" or "Explore my library for X"

Agent task:

Explore my Zotero library to discover all material related to [X].

Comprehensive discovery approach:

1. DIRECT SEARCHES (Cast wide net)
   - Semantic search: multiple phrasings of X
   - Keyword search: X and synonyms
   - Tag search: X-related tags
   - Notes/annotations: X mentions

2. EXPANSION PHASE
   - Analyze top results to identify:
     * Related concepts and theories
     * Related methodologies
     * Related application domains
     * Related authors
   - Search for each of these expansions

3. DEEP EXPLORATION
   - For promising papers, check fulltext for related concepts
   - Look at tags on promising papers, search those tags
   - Check annotations for related ideas
   - Look for cited works mentioned in your notes

4. THEMATIC CLUSTERING
   - Group all findings by themes/approaches
   - Identify conceptual clusters
   - Note connections between clusters
   - Highlight surprising/unexpected connections

5. SYNTHESIS
   - Core papers directly about X
   - Related theoretical frameworks
   - Methodological connections
   - Application domains
   - Surprising/tangential connections worth noting

Return a thematic map of your library's coverage of this topic.

How to Launch Agents (Claude Code Only)

Use the Task tool with subagent_type="general-purpose":

Task(
  description="Comprehensive Zotero search for X",
  subagent_type="general-purpose",
  prompt="[Use one of the task patterns above]"
)

PART 3: Universal Search Strategy

Multi-Method Search Approach

ALWAYS use multiple search methods in combination (in both environments):

A. Semantic Search (Primary for Conceptual Discovery)

• Use zotero_semantic_search for conceptual, thematic, or exploratory queries
• Try multiple phrasings of the same concept
• Use natural language descriptions, not just keywords
• Example variations:
  • "theories of embodied cognition"
  • "how body influences thought and reasoning"
  • "physical experience shapes cognitive processes"
• Claude Desktop: limit=10
• Claude Code (agents): no limit restriction

B. Keyword Search (Complementary)

• Use zotero_search_items with multiple keyword variations
• Try synonyms, related terms, broader/narrower terms
• Use different word forms (singular/plural, verb/noun)
• Example variations for "reading comprehension":
  • "reading comprehension"
  • "text understanding"
  • "literacy"
  • "comprehension strategies"

C. Advanced Search (Targeted)

• Use zotero_advanced_search for precise criteria
• Combine multiple fields (author + keyword, year + tag)
• Use for filtering after broader searches

D. Tag & Collection Filtering

• Use zotero_get_tags to discover relevant tags
• Use zotero_search_by_tag with multiple tag variations
• Use zotero_get_collections and zotero_get_collection_items for organized searches

E. Full-Text & Annotations

• Use zotero_search_notes to search annotations and highlights
• Use zotero_get_item_fulltext for content not in metadata
• Critical for finding concepts mentioned in text but not in titles/abstracts

Common Search Patterns

Pattern: "Find me papers about X"

Claude Desktop:

1. zotero_semantic_search: "X" (limit=10)
2. zotero_semantic_search: "X alternative phrasing" (limit=10)
3. zotero_search_items: keyword variations of X (limit=10)
4. zotero_get_tags: look for X-related tags
5. zotero_search_by_tag: if relevant tags found (limit=10)
6. zotero_search_notes: "X" (limit=10)
Result: ~50+ results safely retrieved

Claude Code:

Launch agent with Task tool (Pattern 1)
Agent performs comprehensive multi-strategy search
Returns curated results with synthesis

Pattern: "What do I have on [author]?"

Claude Desktop:

1. zotero_search_items: author="[Author]" (limit=10)
2. zotero_advanced_search: author + recent years (limit=10)
3. zotero_search_notes: "[Author]" (limit=10)
4. zotero_semantic_search: "[Author]'s main concepts" (limit=10)

Claude Code:

Launch agent with Task tool (Pattern 2)

Search Failure Recovery

If initial searches yield poor results:

1. Ask clarifying questions:

   • "Are you looking for theoretical or empirical work?"
   • "Any specific time period or authors?"
   • "Is this about methodology, findings, or theory?"

2. Broaden search:

   • Use more general terms
   • Remove filters
   • Try related fields/disciplines

3. Check search database status:

   • Use zotero_get_search_database_status
   • Suggest zotero_update_search_database if outdated

4. Try alternative angles:

   • If searching for method, search for problems it solves
   • If searching for theory, search for phenomena it explains
   • If searching for author, search for concepts they study

PART 4: Bibliography Output Formatting

When the user requests a bibliography or formatted output of search results:

Logseq Formatting Standards

ALWAYS use outline hierarchy (nested bullet points), NEVER use markdown headers (#): NO BOLD STYLING - use plain text for all content

Compact citation format:

- Main Topic - Bibliography
	- A. Category Name
		- Author(s), Year. Title (English Translation if applicable)
			- Type: Article Type
			- Journal: Journal Name, Volume X, Issue Y, Pages Z
			- Zotero: [zotero://select/library/items/ITEM_KEY](zotero://select/library/items/ITEM_KEY)
			- DOI: [if available]
			- Abstract (Chinese): [if applicable]
			- Abstract (English): [translation or original]

Format rules:

• First line: Author(s), Year. Title (English Translation)
• For Chinese authors: 黃美金 (Huang Mei-Jin)
• For multiple authors: separate with semicolons
• For no date: use "n.d."
• For no author: use institutional name or "N/A"

Translation Requirements

1. Chinese Abstracts:

   • Always provide BOTH Chinese original and English translation
   • Label clearly as Abstract (Chinese): and Abstract (English):
   • Translate comprehensively, not just summaries

2. Chinese Titles:

   • Provide English translation in parentheses after Chinese title
   • Format: 中文標題 (English Translation)
   • If English title exists in metadata, use that; otherwise translate

3. Author Names:

   • Include both Chinese characters and romanization when available
   • Format: 黃美金 (Huang Mei-Jin)

Required Metadata Fields

Each bibliography entry must include (when available):

• Title (with translations as needed)
• Authors (with Chinese/romanization)
• Date (YYYY-MM-DD or YYYY)
• Type (Journal Article, Book Chapter, Thesis, etc.)
• Journal/Publication (with volume, issue, pages)
• Zotero link (format: zotero://select/library/items/ITEM_KEY)
• Abstract (Chinese and/or English as applicable)
• DOI (if available)

What NOT to Include

• ❌ No summary sections at the end of bibliographies (no totals, no "organized by themes" recap)
• ❌ No markdown headers (#, ##, etc.) - use nested bullets only
• ❌ No bold styling (**text**) - use plain text throughout
• ❌ No item counts or statistics sections at the end

Bibliography Structure Example

- Indigenous Language Proficiency Certification (原住民族語言能力認證) - Bibliography
	- A. Core Certification Papers
		- 黃美金 (Huang Mei-Jin), 2003. 原住民族語言能力認證：回顧與展望 (Indigenous Language Proficiency Certification: Review and Prospects)
			- Type: Journal Article
			- Journal: 原住民教育季刊, Issue 9, Pages 5-27
			- Zotero: [zotero://select/library/items/W44VF3CG](zotero://select/library/items/W44VF3CG)
			- Abstract (Chinese): [full Chinese abstract]
			- Abstract (English): [full English translation]
	- B. Policy & Historical Context
		- [next paper...]

File Handling

When creating bibliographies:

1. Save to /Users/niyaro/Desktop/ with descriptive filename
2. Use .md extension
3. Open in BBEdit automatically (use bbedit command)
4. Confirm file creation and location to user

PART 5: Tool Quick Reference

Critical Reminders

For Both Environments

• Never use just one search method
• Never try just one search term variation
• Always check tags before searching
• Always search both metadata and full-text/annotations
• Always explain your search path
• Always refine based on initial results

Claude Desktop Specific

• 🚨 SAFETY: Always use limit=10 (max 15-20) to prevent conversation deletion
• 🚨 SAFETY: For comprehensive results, use multiple searches or agents, NOT large limits

Claude Code Specific

• Default to agents for non-trivial searches
• Be comprehensive - no crash limits
• Let agents explore - they can handle complexity autonomously
• Synthesize results - raw lists are not enough

Bibliography Formatting

• Format for Logseq - use outline hierarchy, not headers; NO bold styling
• Compact citation format - Author(s), Year. Title on first line
• Translate Chinese content - provide both original and English versions

Remember: This skill adapts to your environment. In Claude Code, leverage agents for comprehensive autonomous searches. In Claude Desktop, use careful batched searches with safety limits.