Mnemosyne MCP

Instructions

Implementation Reference

• src/neem/mcp/tools/hocuspocus.py:1153-1224 (handler)

  The MCP tool handler for 'delete_block', including the @server.tool decorator that registers it. Handles authentication, input validation, document connection, transaction-based deletion via helper, and structured response.

  @server.tool(
      name="delete_block",
      title="Delete Block",
      description=(
          "Delete a block by its ID. Use cascade=true to also delete all subsequent blocks "
          "with higher indent (indent-based children). Returns the list of deleted block IDs."
      ),
  )
  async def delete_block_tool(
      graph_id: str,
      document_id: str,
      block_id: str,
      cascade: bool = False,
      context: Context | None = None,
  ) -> dict:
      """Delete a block and optionally its indent-children.
  
      Args:
          graph_id: The graph containing the document
          document_id: The document containing the block
          block_id: The block to delete
          cascade: If True, also delete indent-children
      """
      auth = MCPAuthContext.from_context(context)
      auth.require_auth()
  
      if not graph_id or not graph_id.strip():
          raise ValueError("graph_id is required")
      if not document_id or not document_id.strip():
          raise ValueError("document_id is required")
      if not block_id or not block_id.strip():
          raise ValueError("block_id is required")
  
      try:
          await hp_client.connect_document(graph_id.strip(), document_id.strip())
  
          deleted_ids: list[str] = []
  
          def perform_delete(doc: Any) -> None:
              nonlocal deleted_ids
              writer = DocumentWriter(doc)
              deleted_ids = writer.delete_block_by_id(
                  block_id.strip(), cascade_children=cascade
              )
  
          await hp_client.transact_document(
              graph_id.strip(),
              document_id.strip(),
              perform_delete,
          )
  
          result = {
              "success": True,
              "graph_id": graph_id.strip(),
              "document_id": document_id.strip(),
              "deleted_block_ids": deleted_ids,
              "cascade": cascade,
          }
          return result
  
      except Exception as e:
          logger.error(
              "Failed to delete block",
              extra_context={
                  "graph_id": graph_id,
                  "document_id": document_id,
                  "block_id": block_id,
                  "error": str(e),
              },
          )
          raise RuntimeError(f"Failed to delete block: {e}")

• src/neem/hocuspocus/document.py:674-736 (helper)

  Core implementation of block deletion in DocumentWriter class, supporting optional cascade deletion of subsequent higher-indent child blocks. Called by the tool handler.

  def delete_block_by_id(self, block_id: str, cascade_children: bool = False) -> list[str]:
      """Delete a block by its ID, optionally cascading to indent-children.
  
      Args:
          block_id: The block ID to delete
          cascade_children: If True, also delete all subsequent blocks with
                           higher indent (indent-based children)
  
      Returns:
          List of deleted block IDs.
  
      Raises:
          ValueError: If block not found.
      """
      result = self.find_block_by_id(block_id)
      if result is None:
          raise ValueError(f"Block not found: {block_id}")
  
      index, elem = result
      deleted_ids = [block_id]
  
      fragment = self.get_content_fragment()
  
      with self._doc.transaction():
          if cascade_children:
              # Find children by indent
              parent_indent = _get_attr_safe(elem.attributes, "indent", 0)
              if isinstance(parent_indent, str):
                  try:
                      parent_indent = int(parent_indent)
                  except ValueError:
                      parent_indent = 0
  
              children = list(fragment.children)
              # Collect indices to delete (in reverse order to maintain positions)
              indices_to_delete = [index]
  
              for i in range(index + 1, len(children)):
                  child = children[i]
                  if not hasattr(child, "attributes"):
                      break
                  child_indent = _get_attr_safe(child.attributes, "indent", 0)
                  if isinstance(child_indent, str):
                      try:
                          child_indent = int(child_indent)
                      except ValueError:
                          child_indent = 0
  
                  if child_indent <= parent_indent:
                      break  # No longer a child
  
                  indices_to_delete.append(i)
                  child_id = _get_attr_safe(child.attributes, "data-block-id", None)
                  if child_id:
                      deleted_ids.append(child_id)
  
              # Delete in reverse order to maintain indices
              for idx in reversed(indices_to_delete):
                  del fragment.children[idx]
          else:
              del fragment.children[index]
  
      return deleted_ids

• src/neem/mcp/tools/hocuspocus.py:1153-1225 (registration)

  The @server.tool decorator registers the delete_block tool with the MCP server, defining its name, title, description (input/output schema), and handler function.

  @server.tool(
      name="delete_block",
      title="Delete Block",
      description=(
          "Delete a block by its ID. Use cascade=true to also delete all subsequent blocks "
          "with higher indent (indent-based children). Returns the list of deleted block IDs."
      ),
  )
  async def delete_block_tool(
      graph_id: str,
      document_id: str,
      block_id: str,
      cascade: bool = False,
      context: Context | None = None,
  ) -> dict:
      """Delete a block and optionally its indent-children.
  
      Args:
          graph_id: The graph containing the document
          document_id: The document containing the block
          block_id: The block to delete
          cascade: If True, also delete indent-children
      """
      auth = MCPAuthContext.from_context(context)
      auth.require_auth()
  
      if not graph_id or not graph_id.strip():
          raise ValueError("graph_id is required")
      if not document_id or not document_id.strip():
          raise ValueError("document_id is required")
      if not block_id or not block_id.strip():
          raise ValueError("block_id is required")
  
      try:
          await hp_client.connect_document(graph_id.strip(), document_id.strip())
  
          deleted_ids: list[str] = []
  
          def perform_delete(doc: Any) -> None:
              nonlocal deleted_ids
              writer = DocumentWriter(doc)
              deleted_ids = writer.delete_block_by_id(
                  block_id.strip(), cascade_children=cascade
              )
  
          await hp_client.transact_document(
              graph_id.strip(),
              document_id.strip(),
              perform_delete,
          )
  
          result = {
              "success": True,
              "graph_id": graph_id.strip(),
              "document_id": document_id.strip(),
              "deleted_block_ids": deleted_ids,
              "cascade": cascade,
          }
          return result
  
      except Exception as e:
          logger.error(
              "Failed to delete block",
              extra_context={
                  "graph_id": graph_id,
                  "document_id": document_id,
                  "block_id": block_id,
                  "error": str(e),
              },
          )
          raise RuntimeError(f"Failed to delete block: {e}")
  
  # -------------------------------------------------------------------------