get_examples
Retrieve example flashcards from Anki to assist in creating new cards, using customizable sampling techniques like recent additions, most reviewed, or best performance, with optional deck filtering.
Instructions
Get example notes from Anki to guide your flashcard making. Limit the number of examples returned and provide a sampling technique:
- random: Randomly sample notes
- recent: Notes added in the last week
- most_reviewed: Notes with more than 10 reviews
- best_performance: Notes with less than 3 lapses
- mature: Notes with interval greater than 21 days
- young: Notes with interval less than 7 days
Args:
deck: Optional[str] - Filter by specific deck (use exact name).
limit: int - Maximum number of examples to return (default 5).
sample: str - Sampling technique (random, recent, most_reviewed, best_performance, mature, young).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| deck | No | ||
| limit | No | ||
| sample | No | Sampling technique: random, recent (added last 7d), most_reviewed (>10 reps), best_performance (<3 lapses), mature (ivl>=21d), young (ivl<=7d) | random |
Input Schema (JSON Schema)
{
"properties": {
"deck": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Deck"
},
"limit": {
"default": 5,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"sample": {
"default": "random",
"description": "Sampling technique: random, recent (added last 7d), most_reviewed (>10 reps), best_performance (<3 lapses), mature (ivl>=21d), young (ivl<=7d)",
"pattern": "^(random|recent|most_reviewed|best_performance|mature|young)$",
"title": "Sample",
"type": "string"
}
},
"title": "get_examplesArguments",
"type": "object"
}
Implementation Reference
- mcp_ankiconnect/server.py:268-268 (registration)Registers the get_examples tool with the FastMCP server instance using the @mcp.tool() decorator.@mcp.tool()
- mcp_ankiconnect/server.py:270-325 (handler)The core handler function implementing the get_examples tool logic: constructs Anki search query, finds and samples notes, retrieves note info, formats examples as JSON, prepends flashcard guidelines, decorated with error handler.async def get_examples( deck: Optional[str] = None, limit: int = Field(default = 5, ge = 1), sample: str = Field( default = "random", description="Sampling technique: random, recent (added last 7d), most_reviewed (>10 reps), best_performance (<3 lapses), mature (ivl>=21d), young (ivl<=7d)", pattern="^(random|recent|most_reviewed|best_performance|mature|young)$" # Keep pattern for validation ), # Close Field() ) -> str: # Close parameters list """Get example notes from Anki to guide your flashcard making. Limit the number of examples returned and provide a sampling technique: - random: Randomly sample notes - recent: Notes added in the last week - most_reviewed: Notes with more than 10 reviews - best_performance: Notes with less than 3 lapses - mature: Notes with interval greater than 21 days - young: Notes with interval less than 7 days Args: deck: Optional[str] - Filter by specific deck (use exact name). limit: int - Maximum number of examples to return (default 5). sample: str - Sampling technique (random, recent, most_reviewed, best_performance, mature, young). """ async with get_anki_client() as anki: # Build the query using the helper function query = _build_example_query(deck, sample) logger.debug(f"Finding example notes with query: {query}") note_ids = await anki.find_notes(query=query) if not note_ids: return f"No example notes found matching criteria (Sample: {sample}, Deck: {deck or 'Any'})." # Apply sampling and limit if sample == "random" and len(note_ids) > limit: sampled_note_ids = random.sample(note_ids, limit) else: # For sorted queries, take the top results up to the limit sampled_note_ids = note_ids[:limit] if not sampled_note_ids: return f"No example notes found after sampling/limiting (Sample: {sample}, Deck: {deck or 'Any'})." logger.debug(f"Fetching info for note IDs: {sampled_note_ids}") notes_info = await anki.notes_info(sampled_note_ids) # Format notes using the helper function formatted_examples = _format_example_notes(notes_info) # Combine guidelines with the JSON examples # Use json.dumps for clean formatting examples_json = json.dumps(formatted_examples, indent=2, ensure_ascii=False) result = f"{flashcard_guidelines}\n\nHere are some examples based on your criteria:\n{examples_json}" return result
- mcp_ankiconnect/server.py:271-277 (schema)Pydantic-based input schema for the tool parameters including validation for limit (>=1) and sample (enum-like pattern).deck: Optional[str] = None, limit: int = Field(default = 5, ge = 1), sample: str = Field( default = "random", description="Sampling technique: random, recent (added last 7d), most_reviewed (>10 reps), best_performance (<3 lapses), mature (ivl>=21d), young (ivl<=7d)", pattern="^(random|recent|most_reviewed|best_performance|mature|young)$" # Keep pattern for validation ), # Close Field()
- mcp_ankiconnect/server.py:107-138 (helper)Helper function that constructs the AnkiConnect 'find_notes' query based on the sample strategy and deck filter, excluding suspended notes and certain strings.def _build_example_query(deck: Optional[str], sample: str) -> str: """Builds the Anki query string for finding example notes.""" query_parts = ["-is:suspended"] query_parts.extend([f"-note:*{ex}*" for ex in EXCLUDE_STRINGS]) if deck: query_parts.append(f'"deck:{deck}"') sort_order = "" match sample: case "recent": query_parts.append("added:7") sort_order = "sort:added rev" case "most_reviewed": query_parts.append("prop:reps>10") sort_order = "sort:reps rev" case "best_performance": query_parts.append("prop:lapses<3 is:review") sort_order = "sort:lapses" case "mature": query_parts.append("prop:ivl>=21 -is:learn") sort_order = "sort:ivl rev" case "young": query_parts.append("is:review prop:ivl<=7 -is:learn") sort_order = "sort:ivl" case "random": query_parts.append("is:review") # Default filter for random query = " ".join(query_parts) if sort_order: query += f" {sort_order}" return query
- mcp_ankiconnect/server.py:141-157 (helper)Helper function to clean and format raw Anki notes_info into LLM-friendly dictionaries, stripping extra HTML wrappers from code blocks.def _format_example_notes(notes_info: List[dict]) -> List[dict]: """Formats note information into simplified dictionaries for examples.""" examples = [] for note in notes_info: processed_fields = {} for name, field_data in note.get("fields", {}).items(): value = field_data.get("value", "") processed_value = value.replace("<pre><code>", "<code>").replace("</code></pre>", "</code>") processed_fields[name] = processed_value example = { "modelName": note.get("modelName", "UnknownModel"), "fields": processed_fields, "tags": note.get("tags", []) } examples.append(example) return examples