zettelkasten-mcp

Instructions

Implementation Reference

• src/zettelkasten_mcp/server/mcp_server.py:107-115 (registration)

  MCP tool registration decorator defining the tool name, description, and operational hints.

  @self.mcp.tool(
      name="zk_create_note",
      description="Create a new atomic Zettelkasten note with a unique ID, content, and optional tags.",
      annotations={
          "readOnlyHint": False,
          "destructiveHint": False,
          "idempotentHint": False,
      },
  )

• src/zettelkasten_mcp/server/mcp_server.py:116-152 (handler)

  The primary handler function for the zk_create_note tool. Validates input parameters, converts types, calls ZettelService.create_note, and returns success/error messages.

  def zk_create_note(
      title: str,
      content: str,
      note_type: str = "permanent",
      tags: str | None = None,
  ) -> str:
      """Create a new atomic Zettelkasten note with a unique ID, content, and optional tags.
  
      Args:
          title: The title of the note
          content: The main content of the note in markdown format
          note_type: Type of note - one of: fleeting, literature, permanent, structure, hub (default: permanent)
          tags: Optional comma-separated list of tags for categorization
      """
      try:
          # Convert note_type string to enum
          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
          tag_list = []
          if tags:
              tag_list = [t.strip() for t in tags.split(",") if t.strip()]
  
          # Create the note
          note = self.zettel_service.create_note(
              title=title,
              content=content,
              note_type=note_type_enum,
              tags=tag_list,
          )
          return f"Note created successfully with ID: {note.id}"
      except Exception as e:
          return self.format_error_response(e)

• src/zettelkasten_mcp/services/zettel_service.py:26-51 (helper)

  Helper service method in ZettelService that instantiates a Note model and delegates persistence to the NoteRepository.

  def create_note(
      self,
      title: str,
      content: str,
      note_type: NoteType = NoteType.PERMANENT,
      tags: Optional[List[str]] = None,
      metadata: Optional[Dict[str, Any]] = None
  ) -> Note:
      """Create a new note."""
      if not title:
          raise ValueError("Title is required")
      if not content:
          raise ValueError("Content is required")
      
      # Create note object
      note = Note(
          title=title,
          content=content,
          note_type=note_type,
          tags=[Tag(name=tag) for tag in (tags or [])],
          metadata=metadata or {}
      )
      
      # Save to repository
      return self.repository.create(note)

• src/zettelkasten_mcp/models/schema.py:88-95 (schema)

  Pydantic enum defining valid note types used for input validation in the tool handler.

  class NoteType(str, Enum):
      """Types of notes in a Zettelkasten."""
      FLEETING = "fleeting"    # Quick, temporary notes
      LITERATURE = "literature"  # Notes from reading material
      PERMANENT = "permanent"  # Permanent, well-formulated notes
      STRUCTURE = "structure"  # Structure/index notes that organize other notes
      HUB = "hub"              # Hub notes that serve as entry points

• src/zettelkasten_mcp/models/schema.py:109-133 (schema)

  Pydantic model defining the structure of a Note, used when creating notes via the service layer.

  class Note(BaseModel):
      """A Zettelkasten note."""
      id: str = Field(default_factory=generate_id, description="Unique ID of the note")
      title: str = Field(..., description="Title of the note")
      content: str = Field(..., description="Content of the note")
      note_type: NoteType = Field(default=NoteType.PERMANENT, description="Type of note")
      tags: List[Tag] = Field(default_factory=list, description="Tags for categorization")
      links: List[Link] = Field(default_factory=list, description="Links to other notes")
      created_at: datetime.datetime = Field(
          default_factory=datetime.datetime.now,
          description="When the note was created"
      )
      updated_at: datetime.datetime = Field(
          default_factory=datetime.datetime.now,
          description="When the note was last updated"
      )
      metadata: Dict[str, Any] = Field(
          default_factory=dict, 
          description="Additional metadata for the note"
      )
      
      model_config = {
          "validate_assignment": True,
          "extra": "forbid"
      }