fangcloud-mcp 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

fangcloud-mcp/__init__.py

@@ -0,0 +1,10 @@
+"""
+FangCloud MCP - Model Context Protocol (MCP) 服务器实现，提供与 FangCloud 云存储服务的集成
+"""
+
+__version__ = "0.1.1"
+
+from .fangcloud import main
+from .fangcloud_api import FangcloudAPI
+
+__all__ = ["main", "FangcloudAPI"]

fangcloud-mcp/fangcloud.py

@@ -0,0 +1,391 @@
+"""
+#!/usr/bin/env python3
+FangCloud MCP Main Module
+
+This is the main entry point for the FangCloud MCP server.
+"""
+
+import logging
+import argparse
+import asyncio
+import sys
+import os
+from typing import Dict, Any, Optional
+from mcp.server.fastmcp import FastMCP
+from .fangcloud_api import FangcloudAPI
+
+
+# Configure logging
+DEFAULT_LOG_FILE = "fangcloud_mcp.log"
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[
+        logging.FileHandler(DEFAULT_LOG_FILE),
+        logging.StreamHandler()
+    ]
+)
+logger = logging.getLogger("FangCloud.Main")
+
+
+# Initialize MCP server
+mcp = FastMCP("fangcloud")
+api = FangcloudAPI()
+
+@mcp.tool()
+async def get_file_info(file_id: str) -> Dict[str, Any]:
+    """
+    Get file information
+    
+    Args:
+        file_id: File ID
+        
+    Returns:
+        File information (JSON format) or error message
+    """
+    
+    if not file_id:
+        return {"status": "error", "message": "file_id is required"}
+    
+    try:
+        result = await api.get_file_info(file_id)
+        if result:
+            return {"status": "success", "data": result}
+        else:
+            return {"status": "error", "message": f"Failed to get file info for file ID {file_id}"}
+    except Exception as e:
+        error_msg = f"Get file info operation failed - {str(e)}"
+        logger.error(error_msg, exc_info=True)
+        return {"status": "error", "message": error_msg}
+
+@mcp.tool()
+async def get_folder_info(folder_id: str) -> Dict[str, Any]:
+    """
+    Get folder information
+    
+    Args:
+        folder_id: Folder ID
+        
+    Returns:
+        Folder information (JSON format) or error message
+    """
+    if not folder_id:
+        return {"status": "error", "message": "folder_id is required"}
+    
+    try:
+        result = await api.get_folder_info(folder_id)
+        if result:
+            return {"status": "success", "data": result}
+        else:
+            return {"status": "error", "message": f"Failed to get folder info for folder ID {folder_id}"}
+    except Exception as e:
+        error_msg = f"Get folder info operation failed - {str(e)}"
+        logger.error(error_msg, exc_info=True)
+        return {"status": "error", "message": error_msg}
+
+@mcp.tool()
+async def create_folder(name: str, parent_id: str, 
+                        target_space_type: Optional[str] = None, 
+                        target_space_id: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Create a new folder
+    
+    Args:
+        name: Folder name (1-222 characters, cannot contain / ? : * " > <)
+        parent_id: Parent folder ID
+        target_space_type: Space type - "department" or "personal" (optional, effective when parent_id is 0)
+        target_space_id: Space ID (required when target_space_type is "department")
+        
+    Returns:
+        Folder creation result (JSON format) or error message
+    """  
+    if not name:
+        return {"status": "error", "message": "name is required"}
+        
+    if not parent_id:
+        return {"status": "error", "message": "parent_id is required"}
+    
+    try:
+        # Validate folder name length
+        if len(name) < 1 or len(name) > 222:
+            return {"status": "error", "message": "Folder name must be between 1 and 222 characters"}
+            
+        # Check for invalid characters in folder name
+        invalid_chars = ['/', '?', ':', '*', '"', '>', '<']
+        if any(char in name for char in invalid_chars):
+            return {"status": "error", "message": "Folder name contains invalid characters (/ ? : * \" > <)"}
+        
+        # Check if target_space_id is provided when needed
+        if parent_id == "0" or parent_id == 0:
+            if target_space_type == "department" and not target_space_id:
+                return {"status": "error", "message": "target_space_id is required when target_space_type is department"}
+        
+        result = await api.create_folder(
+            name, parent_id, target_space_type, target_space_id
+        )
+        if result:
+            return {"status": "success", "data": result}
+        else:
+            return {"status": "error", "message": f"Failed to create folder '{name}' in parent folder {parent_id}"}
+    except Exception as e:
+        error_msg = f"Create folder operation failed - {str(e)}"
+        logger.error(error_msg, exc_info=True)
+        return {"status": "error", "message": error_msg}
+
+@mcp.tool()
+async def upload_file(parent_folder_id: str, local_file_path: str) -> Dict[str, Any]:
+    """
+    Upload file to FangCloud
+    
+    Args:
+        parent_folder_id: Target folder ID in FangCloud
+        local_file_path: Local file path to upload
+        
+    Returns:
+        Upload result message
+    """
+    if not parent_folder_id:
+        return {"status": "error", "message": "parent_folder_id is required"}
+        
+    if not local_file_path:
+        return {"status": "error", "message": "local_file_path is required"}
+    
+    try:
+        # 获取文件名
+        file_name = os.path.basename(local_file_path)
+        
+        # 获取上传URL
+        upload_url = await api.get_file_upload_url(parent_folder_id, file_name)
+        if not upload_url:
+            return {"status": "error", "message": f"Failed to get upload URL for {file_name}"}
+        
+        # 上传文件
+        result = await api.upload_file(upload_url, local_file_path)
+        
+        if result:
+            return {
+                "status": "success", 
+                "message": f"File uploaded successfully - {local_file_path} -> Folder ID {parent_folder_id}",
+                "file_name": file_name,
+                "parent_folder_id": parent_folder_id
+            }
+        else:
+            return {"status": "error", "message": f"File upload failed - {local_file_path}"}
+    except Exception as e:
+        error_msg = f"Upload operation failed - {str(e)}"
+        logger.error(error_msg, exc_info=True)
+        return {"status": "error", "message": error_msg}
+
+@mcp.tool()
+async def update_file(file_id: str, name: Optional[str] = None, 
+                        description: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Update file name and/or description
+    
+    Args:
+        file_id: File ID
+        name: New file name (optional)
+        description: New file description (optional)
+        
+    Returns:
+        Update result message
+        
+    Note:
+        At least one of name or description must be provided
+    """    
+    if not file_id:
+        return {"status": "error", "message": "file_id is required"}
+        
+    if not name and not description:
+        return {"status": "error", "message": "At least one of name or description must be provided"}
+    
+    try:
+        result = await api.update_file(file_id, name, description)
+        if result:
+            updated_fields = []
+            if name:
+                updated_fields.append("name")
+            if description:
+                updated_fields.append("description")
+                
+            fields_str = " and ".join(updated_fields)
+            return {
+                "status": "success", 
+                "message": f"File {file_id} {fields_str} updated successfully",
+                "file_id": file_id,
+                "updated_fields": updated_fields
+            }
+        else:
+            return {"status": "error", "message": f"Failed to update file ID {file_id}"}
+    except Exception as e:
+        error_msg = f"Update operation failed - {str(e)}"
+        logger.error(error_msg, exc_info=True)
+        return {"status": "error", "message": error_msg}
+
+@mcp.tool()
+async def download_file(file_id: str, local_path: str) -> Dict[str, Any]:
+    """
+    Download file from FangCloud
+    
+    Args:
+        file_id: File ID
+        local_path: Local path to save the file
+        
+    Returns:
+        local file path or error message
+    """
+    if not file_id:
+        return {"status": "error", "message": "file_id is required"}
+    
+    try:
+        # Download file to local path
+        result = await api.download_file_to_local(file_id, local_path)
+        if result:
+            return {
+                "status": "success", 
+                "message": f"File downloaded to {result}",
+                "file_path": result
+            }
+        else:
+            return {"status": "error", "message": f"Failed to download file ID {file_id} to {local_path}"}
+    except Exception as e:
+        error_msg = f"Download operation failed - {str(e)}"
+        logger.error(error_msg, exc_info=True)
+        return {"status": "error", "message": error_msg}
+
+@mcp.tool()
+async def list_folder_contents(folder_id: str, page_id: Optional[int] = 0,
+                                page_capacity: Optional[int] = 20, type_filter: Optional[str] = "all",
+                                sort_by: Optional[str] = "date", 
+                                sort_direction: Optional[str] = "desc") -> Dict[str, Any]:
+    """
+    List folder contents (files and subfolders)
+    
+    Args:
+        folder_id: Folder ID
+        page_id: Page number (optional, default 0)
+        page_capacity: Page capacity (optional, default 20)
+        type_filter: Filter by type - "file", "folder", or "all" (optional, default "all")
+        sort_by: Sort by - "name", "date", or "size" (optional, default "date")
+        sort_direction: Sort direction - "desc" or "asc" (optional, default "desc")
+        
+    Returns:
+        Folder contents (JSON format) or error message
+    """ 
+    if not folder_id:
+        return {"status": "error", "message": "folder_id is required"}
+    
+    try:
+        result = await api.get_folder_children(
+            folder_id, page_id, page_capacity, type_filter, sort_by, sort_direction
+        )
+        if result:
+            return {"status": "success", "data": result}
+        else:
+            return {"status": "error", "message": f"Failed to get contents for folder ID {folder_id}"}
+    except Exception as e:
+        error_msg = f"List folder contents operation failed - {str(e)}"
+        logger.error(error_msg, exc_info=True)
+        return {"status": "error", "message": error_msg}
+
+@mcp.tool()
+async def list_personal_items(page_id: Optional[int] = 0,
+                                page_capacity: Optional[int] = 20, type_filter: Optional[str] = "all",
+                                sort_by: Optional[str] = "date", 
+                                sort_direction: Optional[str] = "desc") -> Dict[str, Any]:
+    """
+    List personal items (files and folders in personal space)
+    
+    Args:
+        page_id: Page number (optional, default 0)
+        page_capacity: Page capacity (optional, default 20)
+        type_filter: Filter by type - "file", "folder", or "all" (optional, default "all")
+        sort_by: Sort by - "name", "date", or "size" (optional, default "date")
+        sort_direction: Sort direction - "desc" or "asc" (optional, default "desc")
+        
+    Returns:
+        Personal items (JSON format) or error message
+    """
+    try:
+        result = await api.get_personal_items(
+            page_id, page_capacity, type_filter, sort_by, sort_direction
+        )
+        if result:
+            return {"status": "success", "data": result}
+        else:
+            return {"status": "error", "message": "Failed to get personal items"}
+    except Exception as e:
+        error_msg = f"List personal items operation failed - {str(e)}"
+        logger.error(error_msg, exc_info=True)
+        return {"status": "error", "message": error_msg}
+
+@mcp.tool()
+async def search_items(query_words: str, search_type: Optional[str] = "all",
+                        page_id: Optional[int] = 0, search_in_folder: Optional[str] = None,
+                        query_filter: Optional[str] = "all", 
+                        updated_time_range: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Search for files and folders
+    
+    Args:
+        query_words: Search keywords (required)
+        search_type: Search type - "file", "folder", or "all" (optional, default "all")
+        page_id: Page number (optional, default 0)
+        search_in_folder: Parent folder ID to search within (optional)
+        query_filter: Search filter - "file_name", "content", "creator", or "all" (optional, default "all")
+        updated_time_range: Updated time range in format "start_timestamp,end_timestamp" (optional)
+                            Both timestamps can be empty, but comma is required
+        
+    Returns:
+        Search results (JSON format) or error message
+    """  
+    if not query_words:
+        return {"status": "error", "message": "query_words is required"}
+    
+    try:
+        result = await api.search_items(
+            query_words, search_type, page_id, search_in_folder, query_filter, updated_time_range
+        )
+        if result:
+            return {"status": "success", "data": result}
+        else:
+            return {"status": "error", "message": f"Failed to search for items with query: {query_words}"}
+    except Exception as e:
+        error_msg = f"Search operation failed - {str(e)}"
+        logger.error(error_msg, exc_info=True)
+        return {"status": "error", "message": error_msg}
+
+
+def main():
+    """Main entry point for the FangCloud MCP server"""
+    try:
+        logger.info("=== Starting FangCloud MCP ===")
+        
+        # Parse command line arguments
+        parser = argparse.ArgumentParser(description='FangCloud MCP')
+        parser.add_argument('--access_token', '-c', type=str, required=True, help='FangCloud API access token is required')
+        args = parser.parse_args()
+        
+        # Validate access_token
+        if not args.access_token:
+            logger.error("Access token is required")
+            sys.exit(1)
+            
+        logger.info(f"access_token: {args.access_token}")
+        
+        # set access_token
+        api.set_access_token(args.access_token)
+        
+        # Run MCP server
+        logger.info("Starting MCP server")
+        mcp.run(transport='stdio')
+        
+    except Exception as e:
+        logger.error(f"Initialization failed: {str(e)}", exc_info=True)
+        sys.exit(1)
+    finally:
+        if 'api' in locals():
+            asyncio.run(api.cleanup())
+
+if __name__ == "__main__":
+    main()

fangcloud-mcp/fangcloud_api.py

@@ -0,0 +1,629 @@
+"""
+FangCloud API Module
+
+This module provides API client functionality for interacting with FangCloud.
+"""
+
+import logging
+import uuid
+import os
+import aiohttp
+from typing import Dict, Any, Optional
+
+# Constants
+TOKEN_EXPIRY_SECONDS = 59
+HTTP_OK = 200
+REQUEST_TIMEOUT = 60
+OPEN_HOST = "https://open.fangcloud.com"
+API_UPLOAD_PATH = "/api/v2/file/upload_by_path"
+API_FILE_UPLOAD_PATH = "/api/v2/file/upload"
+API_FILE_INFO_PATH = "/api/v2/file/{id}/info"
+API_FILE_UPDATE_PATH = "/api/v2/file/{id}/update"
+API_FILE_DOWNLOAD_PATH = "/api/v2/file/{id}/download"
+API_FOLDER_INFO_PATH = "/api/v2/folder/{id}/info"
+API_FOLDER_CHILDREN_PATH = "/api/v2/folder/{id}/children"
+API_PERSONAL_ITEMS_PATH = "/api/v2/folder/personal_items"
+API_SEARCH_PATH = "/api/v2/item/search"
+API_FOLDER_CREATE_PATH = "/api/v2/folder/create"
+OAUTH_TOKEN_PATH = "/oauth/token"
+GRANT_TYPE = "jwt_simple"
+UPLOAD_TYPE = "api"
+
+logger = logging.getLogger("FangCloud.API")
+
+
+class FangcloudAPI:
+    def __init__(self):
+        self.access_token = ""
+        self.open_host = OPEN_HOST
+
+    def set_access_token(self, access_token:str):
+        self.access_token = access_token
+
+    def _validate_file(self, file_path: str) -> bool:
+        logger.info(f"Starting file upload: {file_path}")
+        
+        if not os.path.exists(file_path):
+            logger.error(f"File does not exist: {file_path}")
+            return False
+        
+        file_size = os.path.getsize(file_path)
+        logger.info(f"File size: {file_size} bytes")
+        return True
+
+    async def _send_request(self, url: str, method: str = "POST", headers: Dict[str, str] = None, 
+                           data: Any = None, json_data: Any = None, 
+                           is_json_response: bool = True) -> Optional[Any]:
+        async with aiohttp.ClientSession() as session:
+            try:
+                request_method = getattr(session, method.lower())
+                async with request_method(url, headers=headers, data=data, json=json_data) as response:
+                    if response.status != HTTP_OK:
+                        error_text = await response.text()
+                        logger.error(f"Request failed, status: {response.status}, error: {error_text}")
+                        return None
+                    
+                    if is_json_response:
+                        return await response.json()
+                    else:
+                        return await response.text()
+            except Exception as e:
+                logger.error(f"Request error: {str(e)}", exc_info=True)
+                return None
+    
+    async def _api_request(self, operation_name: str, url: str, method: str = "POST", 
+                          headers: Dict[str, str] = None, data: Any = None, json_data: Any = None,
+                          is_json_response: bool = True, check_token: bool = True,
+                          success_key: str = None, success_msg: str = None, 
+                          error_msg: str = None) -> Optional[Any]:
+        try:
+            # 检查访问令牌（如果需要）
+            if check_token and not self.access_token:
+                logger.error(f"Failed to {operation_name}: access_token is empty")
+                return None
+            
+            # 添加认证头（如果需要且未提供）
+            if check_token and headers is None:
+                headers = {
+                    "Authorization": f"Bearer {self.access_token}",
+                    "Content-Type": "application/json"
+                }
+            elif check_token and "Authorization" not in headers:
+                headers["Authorization"] = f"Bearer {self.access_token}"
+            
+            # 发送请求
+            logger.info(f"Sending {operation_name} request")
+            result = await self._send_request(
+                url=url, 
+                method=method,
+                headers=headers,
+                data=data,
+                json_data=json_data,
+                is_json_response=is_json_response
+            )
+            
+            if not result:
+                return None
+            
+            # 检查成功响应中的关键字段
+            if success_key is not None:
+                if isinstance(result, dict) and success_key in result:
+                    if success_msg:
+                        logger.info(success_msg)
+                    return result[success_key]
+                else:
+                    if error_msg:
+                        logger.error(f"{error_msg}: {result}")
+                    else:
+                        logger.error(f"Failed to {operation_name}, response missing {success_key}: {result}")
+                    return None
+            
+            # 如果没有指定关键字段，直接返回结果
+            if success_msg:
+                logger.info(success_msg)
+            return result
+                
+        except Exception as e:
+            logger.error(f"Error in {operation_name}: {str(e)}", exc_info=True)
+            return None
+    
+    async def get_upload_url_by_path(self, target_folder_path: str, file_name: str) -> Optional[str]:
+        logger.info(f"Getting file upload URL for {file_name}")
+        url = f"{self.open_host}{API_UPLOAD_PATH}"
+        
+        params = {
+            "target_folder_path": target_folder_path,
+            "name": file_name,
+            "upload_type": UPLOAD_TYPE
+        }
+        
+        return await self._api_request(
+            operation_name="get upload URL",
+            url=url,
+            json_data=params,
+            success_key="presign_url",
+            success_msg="Successfully obtained upload URL",
+            error_msg="Failed to get upload URL, response missing presign_url"
+        )
+
+    async def get_file_upload_url(self, parent_id: str, name: str, is_covered: Optional[bool] = None) -> Optional[str]:
+        try:
+            if not self.access_token:
+                logger.error("Failed to get file upload URL: access_token is empty")
+                return None
+                
+            logger.info(f"Getting file upload URL for {name} in folder {parent_id}")
+            url = f"{self.open_host}{API_FILE_UPLOAD_PATH}"
+            
+            # Prepare request body
+            params = {
+                "parent_id": parent_id,
+                "name": name,
+                "upload_type": UPLOAD_TYPE
+            }
+            
+            # Add optional parameters if provided
+            if is_covered is not None:
+                params["is_covered"] = is_covered
+            
+            return await self._api_request(
+                operation_name="get file upload URL",
+                url=url,
+                json_data=params,
+                success_key="presign_url",
+                success_msg="Successfully obtained file upload URL",
+                error_msg="Failed to get file upload URL, response missing presign_url"
+            )
+                
+        except Exception as e:
+            logger.error(f"Error getting file upload URL: {str(e)}", exc_info=True)
+            return None
+    
+    async def upload_file(self, url: str, file_path: str) -> Optional[str]:
+        try:
+            if not url:
+                logger.error("Failed to upload file: upload URL is empty")
+                return None
+                
+            if not file_path:
+                logger.error("Failed to upload file: file_path is empty")
+                return None
+            
+            # 验证文件
+            if not self._validate_file(file_path):
+                return None
+            
+            # 发送文件上传请求
+            try:
+                with open(file_path, 'rb') as f:
+                    form_data = aiohttp.FormData()
+                    form_data.add_field('file', f, filename=os.path.basename(file_path))
+                    
+                    logger.info("Sending file upload request")
+                    result = await self._send_request(
+                        url=url, 
+                        data=form_data, 
+                        is_json_response=False
+                    )
+                    
+                    if result:
+                        logger.info("File upload successful")
+                    return result
+            except FileNotFoundError:
+                logger.error(f"File not found or cannot be opened: {file_path}")
+                return None
+            except PermissionError:
+                logger.error(f"Permission denied when accessing file: {file_path}")
+                return None
+                
+        except Exception as e:
+            logger.error(f"Error uploading file: {str(e)}", exc_info=True)
+            return None
+    
+    async def get_file_info(self, file_id: str) -> Optional[Dict[str, Any]]:
+        try:
+            if not self.access_token:
+                logger.error("Failed to get file info: access_token is empty")
+                return None
+                
+            logger.info(f"Getting file info for file ID {file_id}")
+            url = f"{self.open_host}{API_FILE_INFO_PATH.replace('{id}', file_id)}"
+            
+            headers = {
+                "Authorization": f"Bearer {self.access_token}",
+                "Content-Type": "application/json"
+            }
+            
+            # Send request to get file information
+            result = await self._send_request(url=url, method="GET", headers=headers)
+            if not result:
+                return None
+            
+            logger.info(f"Successfully obtained file info for file ID {file_id}")
+            return result
+                
+        except Exception as e:
+            logger.error(f"Error getting file info: {str(e)}", exc_info=True)
+            return None
+    
+    async def update_file(self, file_id: str, name: Optional[str] = None, 
+                         description: Optional[str] = None) -> Optional[Dict[str, Any]]:
+        try:
+            if not self.access_token:
+                logger.error("Failed to update file: access_token is empty")
+                return None
+                
+            if not name and not description:
+                logger.error("Failed to update file: both name and description are empty")
+                return None
+                
+            logger.info(f"Updating file ID {file_id}")
+            url = f"{self.open_host}{API_FILE_UPDATE_PATH.replace('{id}', file_id)}"
+            
+            headers = {
+                "Authorization": f"Bearer {self.access_token}",
+                "Content-Type": "application/json"
+            }
+            
+            # Prepare request body
+            params = {}
+            if name:
+                params["name"] = name
+            if description:
+                params["description"] = description
+            
+            # Send request to update file
+            result = await self._send_request(url=url, headers=headers, json_data=params)
+            if not result:
+                return None
+            
+            logger.info(f"Successfully updated file ID {file_id}")
+            return result
+                
+        except Exception as e:
+            logger.error(f"Error updating file: {str(e)}", exc_info=True)
+            return None
+    
+    async def get_download_url(self, file_id: str) -> Optional[str]:
+        """
+        Get file download URL
+        
+        Args:
+            file_id: File ID
+        Returns:
+            Download URL or None (if request fails)
+        """
+        try:
+            if not self.access_token:
+                logger.error("Failed to get download URL: access_token is empty")
+                return None
+                
+            logger.info(f"Getting download URL for file ID {file_id}")
+            url = f"{self.open_host}{API_FILE_DOWNLOAD_PATH.replace('{id}', file_id)}"
+            
+            headers = {
+                "Authorization": f"Bearer {self.access_token}",
+                "Content-Type": "application/json"
+            }
+            
+            # Prepare query parameters
+            params = {}
+            # Add query parameters to URL if any
+            if params:
+                query_string = "&".join([f"{k}={v}" for k, v in params.items()])
+                url = f"{url}?{query_string}"
+            
+            # Send request to get download URL
+            result = await self._send_request(url=url, method="GET", headers=headers)
+            if not result:
+                return None
+            
+            if "download_url" in result:
+                logger.info(f"Successfully obtained download URL for file ID {file_id}")
+                return result["download_url"]
+            else:
+                logger.error(f"Failed to get download URL, response missing download_url: {result}")
+                return None
+                
+        except Exception as e:
+            logger.error(f"Error getting download URL: {str(e)}", exc_info=True)
+            return None
+    
+    async def download_file_to_local(self, file_id: str, local_path: str) -> Optional[str]:
+        try:
+            # Get file info
+            file_info = await self.get_file_info(file_id)
+            if not file_info:
+                logger.error(f"Failed to download file: could not get file info for file ID {file_id}")
+                return None
+            file_name = file_info["name"]
+            file_path = os.path.join(local_path, file_name)
+
+            # Get download URL
+            download_url = await self.get_download_url(file_id)
+            if not download_url:
+                logger.error(f"Failed to download file: could not get download URL for file ID {file_id}")
+                return None
+            
+            # Ensure directory exists
+            os.makedirs(os.path.dirname(os.path.abspath(file_path)), exist_ok=True)
+            
+            # Generate temporary file path with UUID
+            temp_dir = os.path.dirname(os.path.abspath(file_path))
+            temp_filename = str(uuid.uuid4())
+            temp_path = os.path.join(temp_dir, temp_filename)
+            
+            # Download file to temporary path first
+            logger.info(f"Downloading file ID {file_id} to temporary file {temp_path}")
+            try:
+                async with aiohttp.ClientSession() as session:
+                    async with session.get(download_url) as response:
+                        if response.status != HTTP_OK:
+                            error_text = await response.text()
+                            logger.error(f"File download failed, status: {response.status}, error: {error_text}")
+                            return None
+                        
+                        # Save file to temporary path
+                        with open(temp_path, 'wb') as f:
+                            while True:
+                                chunk = await response.content.read(8192)  # Read in 8kb chunks
+                                if not chunk:
+                                    break
+                                f.write(chunk)
+                
+                # If download successful, rename to the correct file name
+                os.replace(temp_path, file_path)
+                logger.info(f"File successfully downloaded and moved to {file_path}")
+                return file_path
+                
+            except Exception as e:
+                # If any error occurs during download, delete the temporary file if it exists
+                if os.path.exists(temp_path):
+                    try:
+                        os.remove(temp_path)
+                        logger.info(f"Deleted temporary file {temp_path} after download failure")
+                    except Exception as del_err:
+                        logger.error(f"Failed to delete temporary file {temp_path}: {str(del_err)}")
+                raise  # Re-raise the original exception
+                
+        except Exception as e:
+            logger.error(f"Error downloading file: {str(e)}", exc_info=True)
+            return None
+    
+    async def get_folder_children(self, folder_id: str, page_id: Optional[int] = 0,
+                                 page_capacity: Optional[int] = 20, type_filter: Optional[str] = "all",
+                                 sort_by: Optional[str] = "date", 
+                                 sort_direction: Optional[str] = "desc") -> Optional[Dict[str, Any]]:
+        try:
+            if not self.access_token:
+                logger.error("Failed to get folder children: access_token is empty")
+                return None
+                
+            logger.info(f"Getting children for folder ID {folder_id}")
+            url = f"{self.open_host}{API_FOLDER_CHILDREN_PATH.replace('{id}', folder_id)}"
+            
+            headers = {
+                "Authorization": f"Bearer {self.access_token}",
+                "Content-Type": "application/json"
+            }
+            
+            # Prepare query parameters
+            params = {
+                "page_id": page_id,
+                "page_capacity": page_capacity,
+                "type": type_filter,
+                "sort_by": sort_by,
+                "sort_direction": sort_direction
+            }
+                
+            # Add query parameters to URL
+            query_string = "&".join([f"{k}={v}" for k, v in params.items()])
+            url = f"{url}?{query_string}"
+            
+            # Send request to get folder children
+            result = await self._send_request(url=url, method="GET", headers=headers)
+            if not result:
+                return None
+            
+            logger.info(f"Successfully obtained children for folder ID {folder_id}")
+            return result
+                
+        except Exception as e:
+            logger.error(f"Error getting folder children: {str(e)}", exc_info=True)
+            return None
+    
+    async def get_personal_items(self, page_id: Optional[int] = 0,
+                               page_capacity: Optional[int] = 20, type_filter: Optional[str] = "all",
+                               sort_by: Optional[str] = "date", 
+                               sort_direction: Optional[str] = "desc") -> Optional[Dict[str, Any]]:
+        try:
+            if not self.access_token:
+                logger.error("Failed to get personal items: access_token is empty")
+                return None
+                
+            logger.info("Getting personal items")
+            url = f"{self.open_host}{API_PERSONAL_ITEMS_PATH}"
+            
+            headers = {
+                "Authorization": f"Bearer {self.access_token}",
+                "Content-Type": "application/json"
+            }
+            
+            # Prepare query parameters
+            params = {
+                "page_id": page_id,
+                "page_capacity": page_capacity,
+                "type": type_filter,
+                "sort_by": sort_by,
+                "sort_direction": sort_direction
+            }
+                
+            # Add query parameters to URL
+            query_string = "&".join([f"{k}={v}" for k, v in params.items()])
+            url = f"{url}?{query_string}"
+            
+            # Send request to get personal items
+            result = await self._send_request(url=url, method="GET", headers=headers)
+            if not result:
+                return None
+            
+            logger.info("Successfully obtained personal items")
+            return result
+                
+        except Exception as e:
+            logger.error(f"Error getting personal items: {str(e)}", exc_info=True)
+            return None
+    
+    async def get_folder_info(self, folder_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get folder information
+        
+        Args:
+            folder_id: Folder ID (if 0, represents personal space directory)
+            
+        Returns:
+            Folder information or None (if request fails)
+        """
+        try:
+            if not self.access_token:
+                logger.error("Failed to get folder info: access_token is empty")
+                return None
+                
+            logger.info(f"Getting folder info for folder ID {folder_id}")
+            url = f"{self.open_host}{API_FOLDER_INFO_PATH.replace('{id}', folder_id)}"
+            
+            headers = {
+                "Authorization": f"Bearer {self.access_token}",
+                "Content-Type": "application/json"
+            }
+            
+            # Send request to get folder information
+            result = await self._send_request(url=url, method="GET", headers=headers)
+            if not result:
+                return None
+            
+            logger.info(f"Successfully obtained folder info for folder ID {folder_id}")
+            return result
+                
+        except Exception as e:
+            logger.error(f"Error getting folder info: {str(e)}", exc_info=True)
+            return None
+    
+    async def search_items(self, query_words: str, search_type: Optional[str] = "all",
+                         page_id: Optional[int] = 0, search_in_folder: Optional[str] = None,
+                         query_filter: Optional[str] = "all", 
+                         updated_time_range: Optional[str] = None) -> Optional[Dict[str, Any]]:
+        try:
+            if not self.access_token:
+                logger.error("Failed to search items: access_token is empty")
+                return None
+                
+            if not query_words:
+                logger.error("Failed to search items: query_words is empty")
+                return None
+                
+            logger.info(f"Searching for items with query: {query_words}")
+            url = f"{self.open_host}{API_SEARCH_PATH}"
+            
+            headers = {
+                "Authorization": f"Bearer {self.access_token}",
+                "Content-Type": "application/json"
+            }
+            
+            # Prepare query parameters
+            params = {
+                "query_words": query_words,
+                "type": search_type,
+                "page_id": page_id,
+                "query_filter": query_filter
+            }
+            
+            # Add optional parameters if provided
+            if search_in_folder:
+                params["search_in_folder"] = search_in_folder
+            if updated_time_range:
+                params["updated_time_range"] = updated_time_range
+                
+            # Add query parameters to URL
+            query_string = "&".join([f"{k}={v}" for k, v in params.items()])
+            url = f"{url}?{query_string}"
+            
+            # Send request to search items
+            result = await self._send_request(url=url, method="GET", headers=headers)
+            if not result:
+                return None
+            
+            logger.info(f"Successfully completed search for query: {query_words}, result:{result}")
+            return result
+                
+        except Exception as e:
+            logger.error(f"Error searching items: {str(e)}", exc_info=True)
+            return None
+    
+    async def create_folder(self, name: str, parent_id: str, 
+                           target_space_type: Optional[str] = None, 
+                           target_space_id: Optional[str] = None) -> Optional[Dict[str, Any]]:
+        try:
+            if not self.access_token:
+                logger.error("Failed to create folder: access_token is empty")
+                return None
+                
+            if not name:
+                logger.error("Failed to create folder: name is empty")
+                return None
+                
+            if not parent_id and parent_id != "0":
+                logger.error("Failed to create folder: parent_id is empty")
+                return None
+                
+            # Validate folder name length
+            if len(name) < 1 or len(name) > 222:
+                logger.error(f"Failed to create folder: name length must be between 1 and 222 characters")
+                return None
+                
+            # Check for invalid characters in folder name
+            invalid_chars = ['/', '?', ':', '*', '"', '>', '<']
+            if any(char in name for char in invalid_chars):
+                logger.error(f"Failed to create folder: name contains invalid characters")
+                return None
+                
+            logger.info(f"Creating folder '{name}' in parent folder {parent_id}")
+            url = f"{self.open_host}{API_FOLDER_CREATE_PATH}"
+            
+            # Prepare request body
+            params = {
+                "name": name,
+                "parent_id": parent_id
+            }
+            
+            # Add target_space if parent_id is 0
+            if parent_id == "0" or parent_id == 0:
+                if target_space_type:
+                    target_space = {"type": target_space_type}
+                    
+                    # Add target_space_id if type is department
+                    if target_space_type == "department":
+                        if not target_space_id:
+                            logger.error("Failed to create folder: target_space_id is required when target_space_type is department")
+                            return None
+                        target_space["id"] = target_space_id
+                        
+                    params["target_space"] = target_space
+            
+            # Send request to create folder
+            result = await self._api_request(
+                operation_name="create folder",
+                url=url,
+                json_data=params,
+                success_msg=f"Successfully created folder '{name}' in parent folder {parent_id}"
+            )
+            
+            return result
+                
+        except Exception as e:
+            logger.error(f"Error creating folder: {str(e)}", exc_info=True)
+            return None
+    
+    async def cleanup(self) -> None:
+        logger.info("Cleaning up FangCloud client resources")
+        pass

{fangcloud_mcp-0.1.0.dist-info → fangcloud_mcp-0.1.2.dist-info}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Your Name
+Copyright (c) 2025 FangCloud Developer
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{fangcloud_mcp-0.1.0.dist-info → fangcloud_mcp-0.1.2.dist-info}/METADATA

@@ -1,15 +1,24 @@
 Metadata-Version: 2.1
 Name: fangcloud-mcp
-Version: 0.1.0
+Version: 0.1.2
 Summary: FangCloud MCP 是一个 Model Context Protocol (MCP) 服务器实现，提供与 FangCloud 云存储服务的集成
 Home-page: https://github.com/example/fangcloud-mcp
 Author: FangCloud Developer
 Author-email: dev@example.com
 License: UNKNOWN
+Project-URL: Bug Reports, https://github.com/example/fangcloud-mcp/issues
+Project-URL: Source, https://github.com/example/fangcloud-mcp
+Project-URL: Documentation, https://github.com/example/fangcloud-mcp#readme
+Keywords: fangcloud,mcp,cloud storage,api
 Platform: UNKNOWN
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -47,12 +56,28 @@ FangCloud MCP 提供以下功能：
 
 ## 安装方法
 
+### 从 PyPI 安装（推荐）
+
+```bash
+pip install fangcloud-mcp
+```
+
+### 从源码安装
+
 ```bash
 # 克隆仓库
-git clone <repository-url>
+git clone https://github.com/example/fangcloud-mcp.git
 cd fangcloud-mcp
 
-# 使用pip安装依赖
+# 使用pip安装
+pip install .
+```
+
+### 开发模式安装
+
+```bash
+git clone https://github.com/example/fangcloud-mcp.git
+cd fangcloud-mcp
 pip install -e .
 ```
 

fangcloud_mcp-0.1.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+fangcloud-mcp/__init__.py,sha256=fVFqgXkWSUiK1z-GKbZdCUY0b8zlv-jeQeOYHO5-R80,254
+fangcloud-mcp/fangcloud.py,sha256=L5QPVBmY95QbVD68t_xCSHSkXw7B_5OHi_20jAx5qz0,14661
+fangcloud-mcp/fangcloud_api.py,sha256=QQWB8neT-XKfc854yhhZ9WihyN-aI5D_MbV_RRjf-VM,26579
+fangcloud_mcp-0.1.2.dist-info/LICENSE,sha256=PLXgT5nqTcwqGoalBG1tGoXtGUHFunt4gK0M-GxPl6o,1097
+fangcloud_mcp-0.1.2.dist-info/METADATA,sha256=Op8laGdcgYEFCYv8esvQFta9D0089BGoI7wdzgWHK9w,4793
+fangcloud_mcp-0.1.2.dist-info/WHEEL,sha256=G16H4A3IeoQmnOrYV4ueZGKSjhipXx8zc8nu9FGlvMA,92
+fangcloud_mcp-0.1.2.dist-info/entry_points.txt,sha256=cLC2ygrgh8n0kfch8zaPrk5xvyOOVmOW0CRmnkD7KXw,64
+fangcloud_mcp-0.1.2.dist-info/top_level.txt,sha256=7whH_Yk8uCosRXkTZto2fjFqIqLAoEWwVcfPXaMgAz4,14
+fangcloud_mcp-0.1.2.dist-info/RECORD,,

fangcloud_mcp-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+fangcloud-mcp = fangcloud_mcp.fangcloud:main
+

fangcloud_mcp-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+fangcloud-mcp

fangcloud_mcp-0.1.0.dist-info/RECORD

@@ -1,5 +0,0 @@
-fangcloud_mcp-0.1.0.dist-info/LICENSE,sha256=l6425dmjnidzk4JQwhT01C8SpICmjSBMNREAdPnPA9E,1087
-fangcloud_mcp-0.1.0.dist-info/METADATA,sha256=3uhhtZ28666cOqQ85Y5OjG3w3PXtJta_66rr86BU-YU,4038
-fangcloud_mcp-0.1.0.dist-info/WHEEL,sha256=G16H4A3IeoQmnOrYV4ueZGKSjhipXx8zc8nu9FGlvMA,92
-fangcloud_mcp-0.1.0.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-fangcloud_mcp-0.1.0.dist-info/RECORD,,

fangcloud_mcp-0.1.0.dist-info/top_level.txt

@@ -1 +0,0 @@
-