Mnemosyne MCP

Instructions

Implementation Reference

• src/neem/mcp/tools/hocuspocus.py:444-505 (handler)

  The main handler function for the 'move_folder' tool. It authenticates the request, validates inputs, connects to the workspace, verifies the folder exists, updates the folder's parent and order using Y.js WorkspaceWriter, and returns a success result with workspace snapshot.

  async def move_folder_tool(
      graph_id: str,
      folder_id: str,
      new_parent_id: Optional[str] = None,
      new_order: Optional[float] = None,
      context: Context | None = None,
  ) -> dict:
      """Move a folder to a new parent via Y.js."""
      auth = MCPAuthContext.from_context(context)
      auth.require_auth()
  
      if not graph_id or not graph_id.strip():
          raise ValueError("graph_id is required and cannot be empty")
      if not folder_id or not folder_id.strip():
          raise ValueError("folder_id is required and cannot be empty")
  
      try:
          await hp_client.connect_workspace(graph_id.strip())
  
          # Read current folder state from Y.js
          channel = hp_client._workspace_channels.get(graph_id.strip())
          if channel is None:
              raise RuntimeError(f"Workspace not connected: {graph_id}")
  
          reader = WorkspaceReader(channel.doc)
          current = reader.get_folder(folder_id.strip())
  
          if not current:
              raise RuntimeError(f"Folder '{folder_id}' not found in graph '{graph_id}'")
  
          # Update folder with new parent/order via Y.js
          await hp_client.transact_workspace(
              graph_id.strip(),
              lambda doc: WorkspaceWriter(doc).update_folder(
                  folder_id.strip(),
                  parent_id=new_parent_id.strip() if new_parent_id else None,
                  order=new_order,
              ),
          )
  
          snapshot = hp_client.get_workspace_snapshot(graph_id.strip())
  
          result = {
              "success": True,
              "folder_id": folder_id.strip(),
              "graph_id": graph_id.strip(),
              "new_parent_id": new_parent_id.strip() if new_parent_id else None,
              "workspace": snapshot,
          }
          return result
  
      except Exception as e:
          logger.error(
              "Failed to move folder",
              extra_context={
                  "graph_id": graph_id,
                  "folder_id": folder_id,
                  "error": str(e),
              },
          )
          raise RuntimeError(f"Failed to move folder: {e}")

• src/neem/mcp/tools/hocuspocus.py:435-443 (registration)

  The @server.tool decorator registers the 'move_folder' tool with its name, title, and description, which also serves as the schema definition via type hints in the function signature.

  @server.tool(
      name="move_folder",
      title="Move Folder",
      description=(
          "Move a folder to a new parent folder. "
          "Set new_parent_id to null to move to root level. "
          "Optionally update the order for positioning among siblings."
      ),
  )

• src/neem/mcp/tools/hocuspocus.py:435-443 (schema)

  Tool schema defined in the decorator: name, title, description. Input schema inferred from function parameters: graph_id (str), folder_id (str), new_parent_id (Optional[str]), new_order (Optional[float]), context (Optional[Context]). Output: dict.

  @server.tool(
      name="move_folder",
      title="Move Folder",
      description=(
          "Move a folder to a new parent folder. "
          "Set new_parent_id to null to move to root level. "
          "Optionally update the order for positioning among siblings."
      ),
  )