zettelkasten-mcp

Instructions

Implementation Reference

• src/zettelkasten_mcp/server/mcp_server.py:296-337 (handler)

  The handler function that executes the zk_create_link tool logic. It validates inputs (converting link_type to enum), calls ZettelService.create_link, and handles errors including duplicate links.

  def zk_create_link(
      source_id: str,
      target_id: str,
      link_type: str = "reference",
      description: str | None = None,
      bidirectional: bool = False,
  ) -> str:
      """Create a semantic link between two notes to build knowledge connections.
  
      Args:
          source_id: The unique ID of the source note
          target_id: The unique ID of the target note
          link_type: Type of semantic relationship - one of: reference, extends, refines, contradicts, questions, supports, related (default: reference)
          description: Optional text describing the nature of this specific link
          bidirectional: If true, creates links in both directions (source→target and target→source)
      """
      try:
          # Convert link_type string to enum
          try:
              source_id_str = str(source_id)
              target_id_str = str(target_id)
              link_type_enum = LinkType(link_type.lower())
          except ValueError:
              return f"Invalid link type: {link_type}. Valid types are: {', '.join(t.value for t in LinkType)}"
  
          # Create the link
          source_note, target_note = self.zettel_service.create_link(
              source_id=source_id,
              target_id=target_id,
              link_type=link_type_enum,
              description=description,
              bidirectional=bidirectional,
          )
          if bidirectional:
              return f"Bidirectional link created between {source_id} and {target_id}"
          else:
              return f"Link created from {source_id} to {target_id}"
      except (Exception, sqlalchemy_exc.IntegrityError) as e:
          if "UNIQUE constraint failed" in str(e):
              return f"A link of this type already exists between these notes. Try a different link type."
          return self.format_error_response(e)

• src/zettelkasten_mcp/server/mcp_server.py:287-340 (registration)

  The registration of the zk_create_link tool using the FastMCP @tool decorator, specifying name, description, and hints. Includes function assignment to instance and logging.

  @self.mcp.tool(
      name="zk_create_link",
      description="Create a semantic link between two notes to build knowledge connections.",
      annotations={
          "readOnlyHint": False,
          "destructiveHint": False,
          "idempotentHint": False,
      },
  )
  def zk_create_link(
      source_id: str,
      target_id: str,
      link_type: str = "reference",
      description: str | None = None,
      bidirectional: bool = False,
  ) -> str:
      """Create a semantic link between two notes to build knowledge connections.
  
      Args:
          source_id: The unique ID of the source note
          target_id: The unique ID of the target note
          link_type: Type of semantic relationship - one of: reference, extends, refines, contradicts, questions, supports, related (default: reference)
          description: Optional text describing the nature of this specific link
          bidirectional: If true, creates links in both directions (source→target and target→source)
      """
      try:
          # Convert link_type string to enum
          try:
              source_id_str = str(source_id)
              target_id_str = str(target_id)
              link_type_enum = LinkType(link_type.lower())
          except ValueError:
              return f"Invalid link type: {link_type}. Valid types are: {', '.join(t.value for t in LinkType)}"
  
          # Create the link
          source_note, target_note = self.zettel_service.create_link(
              source_id=source_id,
              target_id=target_id,
              link_type=link_type_enum,
              description=description,
              bidirectional=bidirectional,
          )
          if bidirectional:
              return f"Bidirectional link created between {source_id} and {target_id}"
          else:
              return f"Link created from {source_id} to {target_id}"
      except (Exception, sqlalchemy_exc.IntegrityError) as e:
          if "UNIQUE constraint failed" in str(e):
              return f"A link of this type already exists between these notes. Try a different link type."
          return self.format_error_response(e)
  
  self.zk_create_link = zk_create_link
  
  logger.debug("Tool zk_create_link registered")

• src/zettelkasten_mcp/server/mcp_server.py:296-302 (schema)

  Input schema inferred from function parameters: source_id (str), target_id (str), link_type (str, default 'reference'), description (optional str), bidirectional (bool, default False). Output is str response.

  def zk_create_link(
      source_id: str,
      target_id: str,
      link_type: str = "reference",
      description: str | None = None,
      bidirectional: bool = False,
  ) -> str: