MCP-AnkiConnect

Instructions

Implementation Reference

• mcp_ankiconnect/server.py:291-348 (handler)

  Primary handler for 'get_examples' tool. Decorated with @mcp.tool() for registration and error handling. Fetches example Anki notes based on deck, limit, and sample criteria, formats them into JSON, prepends guidelines, and returns as string.
  @mcp.tool() @handle_anki_connection_error # Apply decorator 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:106-138 (helper)

  Helper function used by get_examples to construct the Anki search query based on deck filter and sample type (random, recent, etc.). Uses EXCLUDE_STRINGS from config.
  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:140-157 (helper)

  Helper function used by get_examples to clean and format Anki notes_info into output-friendly dictionaries with processed field values.
  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
• mcp_ankiconnect/server_prompts.py:38-52 (helper)

  Prompt guidelines string imported and prepended to the JSON examples in the get_examples tool response.
  flashcard_guidelines = """ 1. Ensure each flashcard focuses on a single, important concept or fact from the excerpt. 2. Use a variety of question types, including Cloze format when appropriate. 3. Make questions clear, concise, and specific. 4. Avoid yes/no questions and overly complex formulations. 5. Include questions about important terminology, concepts, and their applications. 6. When possible, relate the information to real-life contexts or existing knowledge. 7. Consider potential misunderstandings and address them in your questions. 8. Make sure they are tagged appropriately so they can easily be found later. Tag by topic and resource. IMPORTANT: The flashcards format like markdown, so when using numbered lists, ensure you add two line breaks before and after the list to avoid formatting issues. Here are some examples: """
• mcp_ankiconnect/server.py:291-291 (registration)

  MCP tool registration decorator for get_examples.
  @mcp.tool()