zettelkasten-mcp

Instructions

Implementation Reference

• src/zettelkasten_mcp/server/mcp_server.py:548-592 (handler)

  MCP tool handler implementation for zk_find_similar_notes, including decorator registration, input parameters (note_id, threshold, limit), logic to fetch similar notes from zettel_service, apply limit, and format output string.

      name="zk_find_similar_notes",
      description="Discover notes with similar content using semantic similarity analysis.",
      annotations={
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
      },
  )
  def zk_find_similar_notes(
      note_id: str, threshold: float = 0.3, limit: int = 5
  ) -> str:
      """Discover notes with similar content using semantic similarity analysis.
  
      Args:
          note_id: The unique ID of the reference note to compare against
          threshold: Minimum similarity score from 0.0 (unrelated) to 1.0 (identical) (default: 0.3)
          limit: Maximum number of similar notes to return (default: 5)
      """
      try:
          # Get similar notes
          similar_notes = self.zettel_service.find_similar_notes(
              str(note_id), threshold
          )
          # Limit results
          similar_notes = similar_notes[:limit]
          if not similar_notes:
              return f"No similar notes found for {note_id} with threshold {threshold}."
  
          # Format results
          output = f"Found {len(similar_notes)} similar notes for {note_id}:\n\n"
          for i, (note, similarity) in enumerate(similar_notes, 1):
              output += f"{i}. {note.title} (ID: {note.id})\n"
              output += f"   Similarity: {similarity:.2f}\n"
              if note.tags:
                  output += (
                      f"   Tags: {', '.join(tag.name for tag in note.tags)}\n"
                  )
              # Add a snippet of content (first 100 chars)
              content_preview = note.content[:100].replace("\n", " ")
              if len(note.content) > 100:
                  content_preview += "..."
              output += f"   Preview: {content_preview}\n\n"
          return output
      except Exception as e:
          return self.format_error_response(e)

• src/zettelkasten_mcp/services/zettel_service.py:253-315 (helper)

  Core helper method implementing similarity calculation based on tag overlap (40%), shared outgoing links (20%), incoming links to the reference note (20%), and direct outgoing links (20%). Compares against all notes, filters by threshold, sorts by score.

  def find_similar_notes(self, note_id: str, threshold: float = 0.5) -> List[Tuple[Note, float]]:
      """Find notes similar to the given note based on shared tags and links."""
      note = self.repository.get(note_id)
      if not note:
          raise ValueError(f"Note with ID {note_id} not found")
      
      # Get all notes
      all_notes = self.repository.get_all()
      results = []
      
      # Set of this note's tags and links
      note_tags = {tag.name for tag in note.tags}
      note_links = {link.target_id for link in note.links}
      
      # Add notes linked to this note
      incoming_notes = self.repository.find_linked_notes(note_id, "incoming")
      note_incoming = {n.id for n in incoming_notes}
      
      # For each note, calculate similarity
      for other_note in all_notes:
          if other_note.id == note_id:
              continue
          
          # Calculate tag overlap
          other_tags = {tag.name for tag in other_note.tags}
          tag_overlap = len(note_tags.intersection(other_tags))
          
          # Calculate link overlap (outgoing)
          other_links = {link.target_id for link in other_note.links}
          link_overlap = len(note_links.intersection(other_links))
          
          # Check if other note links to this note
          incoming_overlap = 1 if other_note.id in note_incoming else 0
          
          # Check if this note links to other note
          outgoing_overlap = 1 if other_note.id in note_links else 0
          
          # Calculate similarity score
          # Weight: 40% tags, 20% outgoing links, 20% incoming links, 20% direct connections
          total_possible = (
              max(len(note_tags), len(other_tags)) * 0.4 +
              max(len(note_links), len(other_links)) * 0.2 +
              1 * 0.2 +  # Possible incoming link
              1 * 0.2    # Possible outgoing link
          )
          
          # Avoid division by zero
          if total_possible == 0:
              similarity = 0.0
          else:
              similarity = (
                  (tag_overlap * 0.4) +
                  (link_overlap * 0.2) +
                  (incoming_overlap * 0.2) +
                  (outgoing_overlap * 0.2)
              ) / total_possible
          
          if similarity >= threshold:
              results.append((other_note, similarity))
      
      # Sort by similarity (descending)
      results.sort(key=lambda x: x[1], reverse=True)
      return results