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: