zettelkasten-mcp

Instructions

Implementation Reference

• src/zettelkasten_mcp/server/mcp_server.py:207-252 (handler)

  The main handler function for the zk_update_note MCP tool. It handles input validation, note retrieval, type/tag conversion, calls the ZettelService for update, and formats the response.

  def zk_update_note(
      note_id: str,
      title: str | None = None,
      content: str | None = None,
      note_type: str | None = None,
      tags: str | None = None,
  ) -> str:
      """Update the title, content, type, or tags of an existing note.
  
      Args:
          note_id: The unique ID of the note to update
          title: New title for the note (optional)
          content: New markdown content for the note (optional)
          note_type: New note type - one of: fleeting, literature, permanent, structure, hub (optional)
          tags: New comma-separated list of tags, or empty string to clear tags (optional)
      """
      try:
          # Get the note
          note = self.zettel_service.get_note(str(note_id))
          if not note:
              return f"Note not found: {note_id}"
  
          # Convert note_type string to enum if provided
          note_type_enum = None
          if note_type:
              try:
                  note_type_enum = NoteType(note_type.lower())
              except ValueError:
                  return f"Invalid note type: {note_type}. Valid types are: {', '.join(t.value for t in NoteType)}"
  
          # Convert tags string to list if provided
          tag_list = None
          if tags is not None:  # Allow empty string to clear tags
              tag_list = [t.strip() for t in tags.split(",") if t.strip()]
  
          # Update the note
          updated_note = self.zettel_service.update_note(
              note_id=note_id,
              title=title,
              content=content,
              note_type=note_type_enum,
              tags=tag_list,
          )
          return f"Note updated successfully: {updated_note.id}"
      except Exception as e:
          return self.format_error_response(e)

• src/zettelkasten_mcp/server/mcp_server.py:198-206 (registration)

  Registration of the zk_update_note tool in the MCP server using the @mcp.tool decorator, specifying name, description, and operational hints.

  @self.mcp.tool(
      name="zk_update_note",
      description="Update the title, content, type, or tags of an existing note.",
      annotations={
          "readOnlyHint": False,
          "destructiveHint": False,
          "idempotentHint": True,
      },
  )

• src/zettelkasten_mcp/services/zettel_service.py:60-89 (helper)

  Supporting ZettelService.update_note method that implements the core update logic: retrieves note, conditionally updates fields, sets timestamp, and persists via repository.

  def update_note(
      self,
      note_id: str,
      title: Optional[str] = None,
      content: Optional[str] = None,
      note_type: Optional[NoteType] = None,
      tags: Optional[List[str]] = None,
      metadata: Optional[Dict[str, Any]] = None
  ) -> Note:
      """Update an existing note."""
      note = self.repository.get(note_id)
      if not note:
          raise ValueError(f"Note with ID {note_id} not found")
      
      # Update fields
      if title is not None:
          note.title = title
      if content is not None:
          note.content = content
      if note_type is not None:
          note.note_type = note_type
      if tags is not None:
          note.tags = [Tag(name=tag) for tag in tags]
      if metadata is not None:
          note.metadata = metadata
      
      note.updated_at = datetime.datetime.now()
      
      # Save to repository
      return self.repository.update(note)