zotero-mcp

# 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

| Tool | Primary Use | Claude Desktop Limit | Claude Code (Agent) |
|------|-------------|---------------------|---------------------|
| `zotero_semantic_search` | Conceptual discovery | limit=10 | No limit, use liberally |
| `zotero_search_items` | Keyword matching | limit=10 | No limit |
| `zotero_advanced_search` | Precise filtering | limit=10 | No limit |
| `zotero_get_tags` | Discover tags | No limit needed | No limit needed |
| `zotero_search_by_tag` | Tag filtering | limit=10 | No limit |
| `zotero_search_notes` | Annotation search | limit=10 | No limit |
| `zotero_get_annotations` | Highlight retrieval | limit=10 | No limit |
| `zotero_get_item_fulltext` | Full-text access | N/A (single item) | N/A (single item) |
| `zotero_get_collections` | Collection discovery | No limit needed | No limit needed |
| `zotero_get_recent` | Recent additions | limit=10 | No limit |
| `zotero_update_search_database` | Update index | N/A | N/A |

---

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