jitora 1.1.0__tar.gz

jitora-1.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: jitora
+Version: 1.1.0
+Summary: sample mcp tool
+Keywords: image,management,processing,ai,organization,mcp
+Author: sunshine-kjh
+Author-email: sunshine-kjh <kimjihoon0@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Requires-Dist: fastmcp>=4.0.3
+Requires-Dist: pillow>=12.3.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# jictora
+
+A powerful image management tool designed to work with AI systems for intelligent image organization. This tool enables AI to read, understand, and organize local image files into appropriate folders based on their content and characteristics.
+
+## Project Purpose
+
+This tool is specifically designed to:
+- Allow AI systems to access and analyze local image files
+- Enable AI-driven image categorization and organization
+- Provide a robust interface for AI to manage and process images
+- Support automated image sorting and folder management
+- Facilitate AI-powered image content understanding and classification
+
+## Installation
+
+### Installing uvx
+If uvx is not installed on your system, please refer to the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) to install it according to your environment.
+
+### Installation via MCP (Claude Desktop)
+
+Add the following configuration to your MCP settings file:
+
+```json
+"mcpServers": {
+  "jictora": {
+    "command": "uvx",
+    "args": ["jictora"]
+  }
+}
+```
+
+## MCP API Features
+
+### Directory Management
+- **create_directory**: Creates a new directory at the specified path. Can optionally create parent directories and handle existing directories. Essential for AI-driven folder organization.
+
+### Image File Operations
+- **list_image_files**: Scans a directory and returns a formatted list of all valid image files found, including file count and alphabetical listing. Enables AI to discover and analyze available images.
+- **read_image**: Reads an image file and returns it as an Image object for further processing. Allows AI to access and analyze image content.
+- **copy_image**: Copies an image file to a new location while preserving all metadata. Used by AI to organize images into appropriate categories.
+- **move_image**: Moves an image file to a new location, with options to handle existing files and preserve metadata. Enables AI to reorganize images based on content analysis.
+- **delete_image**: Safely deletes an image file with optional confirmation. Provides AI with the ability to manage unwanted or duplicate images.
+- **create_image**: Generates a new blank image with specified dimensions, color, and format. Useful for AI-generated image processing tasks.
+
+### Supported Image Formats
+The tool supports the following image formats for AI analysis:
+- JPG/JPEG
+- PNG
+- GIF
+- BMP
+- WebP
+- TIFF
+- ICO
+- JFIF
+- SVG
+
+### File Management Features
+- Automatic directory creation for AI-driven organization
+- Overwrite protection with optional override
+- Comprehensive error handling and status reporting
+- File metadata preservation during operations
+- Validation of image files before processing
+- Support for batch operations and automated organization
+
+## AI Integration
+
+This tool is designed to work seamlessly with AI systems, providing:
+- Direct access to local image files for AI analysis
+- Tools for AI-driven image organization
+- Support for automated folder creation and management
+- Metadata preservation during AI-driven reorganization
+- Robust error handling for automated operations
+
+## Error Handling
+All operations include comprehensive error handling and return detailed status information including:
+- Success/failure status
+- Error messages (if any)
+- File metadata
+- Operation details
+
+## License
+
+This project is distributed under the MIT License.

jitora-1.1.0/README.md

@@ -0,0 +1,83 @@
+# jictora
+
+A powerful image management tool designed to work with AI systems for intelligent image organization. This tool enables AI to read, understand, and organize local image files into appropriate folders based on their content and characteristics.
+
+## Project Purpose
+
+This tool is specifically designed to:
+- Allow AI systems to access and analyze local image files
+- Enable AI-driven image categorization and organization
+- Provide a robust interface for AI to manage and process images
+- Support automated image sorting and folder management
+- Facilitate AI-powered image content understanding and classification
+
+## Installation
+
+### Installing uvx
+If uvx is not installed on your system, please refer to the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) to install it according to your environment.
+
+### Installation via MCP (Claude Desktop)
+
+Add the following configuration to your MCP settings file:
+
+```json
+"mcpServers": {
+  "jictora": {
+    "command": "uvx",
+    "args": ["jictora"]
+  }
+}
+```
+
+## MCP API Features
+
+### Directory Management
+- **create_directory**: Creates a new directory at the specified path. Can optionally create parent directories and handle existing directories. Essential for AI-driven folder organization.
+
+### Image File Operations
+- **list_image_files**: Scans a directory and returns a formatted list of all valid image files found, including file count and alphabetical listing. Enables AI to discover and analyze available images.
+- **read_image**: Reads an image file and returns it as an Image object for further processing. Allows AI to access and analyze image content.
+- **copy_image**: Copies an image file to a new location while preserving all metadata. Used by AI to organize images into appropriate categories.
+- **move_image**: Moves an image file to a new location, with options to handle existing files and preserve metadata. Enables AI to reorganize images based on content analysis.
+- **delete_image**: Safely deletes an image file with optional confirmation. Provides AI with the ability to manage unwanted or duplicate images.
+- **create_image**: Generates a new blank image with specified dimensions, color, and format. Useful for AI-generated image processing tasks.
+
+### Supported Image Formats
+The tool supports the following image formats for AI analysis:
+- JPG/JPEG
+- PNG
+- GIF
+- BMP
+- WebP
+- TIFF
+- ICO
+- JFIF
+- SVG
+
+### File Management Features
+- Automatic directory creation for AI-driven organization
+- Overwrite protection with optional override
+- Comprehensive error handling and status reporting
+- File metadata preservation during operations
+- Validation of image files before processing
+- Support for batch operations and automated organization
+
+## AI Integration
+
+This tool is designed to work seamlessly with AI systems, providing:
+- Direct access to local image files for AI analysis
+- Tools for AI-driven image organization
+- Support for automated folder creation and management
+- Metadata preservation during AI-driven reorganization
+- Robust error handling for automated operations
+
+## Error Handling
+All operations include comprehensive error handling and return detailed status information including:
+- Success/failure status
+- Error messages (if any)
+- File metadata
+- Operation details
+
+## License
+
+This project is distributed under the MIT License.

jitora-1.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "jitora"
+version = "1.1.0"
+license = "MIT"
+description = "sample mcp tool"
+readme = "README.md"
+requires-python = ">=3.14"
+keywords = [
+    "image",
+    "management",
+    "processing",
+    "ai",
+    "organization",
+    "mcp",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "fastmcp>=4.0.3",
+    "pillow>=12.3.0",
+]
+
+[[project.authors]]
+name = "sunshine-kjh"
+email = "kimjihoon0@gmail.com"
+
+[project.scripts]
+jitora = "jitora:main"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"

jitora-1.1.0/pyproject.toml.orig

@@ -0,0 +1,31 @@
+[project]
+name = "jitora"
+version = "1.1.0"
+license = "MIT"
+description = "sample mcp tool"
+readme = "README.md"
+requires-python = ">=3.14"
+authors = [
+    { name = "sunshine-kjh", email = "kimjihoon0@gmail.com" }
+]
+keywords = ["image", "management", "processing", "ai", "organization", "mcp"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Operating System :: OS Independent"
+]
+dependencies = [
+    "fastmcp>=4.0.3",
+    "pillow>=12.3.0",
+]
+
+[project.scripts]
+jitora = "jitora:main"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"

jitora-1.1.0/src/jitora/__init__.py

@@ -0,0 +1,355 @@
+from fastmcp import FastMCP
+from fastmcp.utilities.types import Image
+import os
+import shutil
+from PIL import Image as PILImage
+from io import BytesIO
+from typing import Dict, Any
+
+mcp = FastMCP("Jitora")
+
+SUPPORTED_IMAGE_EXTENSIONS = {
+    '.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp',
+    '.tiff', '.tif', '.ico', '.jfif', '.svg'
+}
+
+def is_valid_image(filepath: str) -> bool:
+    """
+    Check if the file is a valid image file.
+
+    Args:
+        filepath (str): File path to check
+
+    Returns:
+        bool: True if the file is an image, False otherwise.
+    """
+    try:
+        _, ext = os.path.splitext(filepath.lower())
+        if ext in SUPPORTED_IMAGE_EXTENSIONS:
+            with PILImage.open(filepath) as _:
+                return True
+    
+    except Exception:
+        pass
+    return False
+
+
+@mcp.tool()
+def create_directory(
+    directory_path: str,
+    exist_ok: bool = True,
+    parents: bool = True
+) -> Dict[str, Any]:
+    """
+    Creates a directory at the specified path. 
+    Creates a new directory if it doesn't exist and handles existing directories according to settings.
+
+    Args:
+        directory_path (str): Path of the directory to create
+        exist_ok (bool): Whether to ignore errors if directory exists (default: True)
+        parents (bool): Whether to create parent directories if needed (default: True)
+
+    Returns:
+    Dict[str, Any]: Directory creation result information
+    """
+
+    try:
+        directory_path = os.path.abspath(directory_path) # 절대경로로 변환. 포맷 동일화
+        already_exists = os.path.exists(directory_path)
+
+        if already_exists:
+            if not os.path.isdir(directory_path): # not directory
+                return {
+                    "success": False,
+                    "error": f"Path exists but is not a directory: {directory_path}"
+                }
+            elif not exist_ok: # exist_ok = False
+                return {
+                    "success": False,
+                    "error": f"Directory already exists: {directory_path}"
+                }
+            else:
+                return {
+                    "success": True,
+                    "message": f"Directory already exists: {directory_path}",
+                    "path": directory_path,
+                    "created": False
+                }
+        if parents:
+            os.makedirs(directory_path)
+        else:
+            try: 
+                os.mkdir(directory_path)
+            except FileNotFoundError:
+                return {
+                    "success": False,
+                    "error": f"Parent path does not exist. Set parents = True: {directory_path}"
+                }
+        return {
+            "success": True,
+            "message": f"Directory created successfully: {directory_path}",
+            "path": directory_path,
+            "created": True
+        }
+
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e)
+        }
+
+@mcp.tool()
+def list_image_files(folder: str) -> str:
+    """
+    Return a text list of image files in the specified folder.
+
+    Args:
+        folder (Str): Folder path to search for image files.
+
+    Returns:
+        str: Text list of image files.
+    """
+
+    try:
+        folder = os.path.abspath(folder)
+
+        if not os.path.exists(folder):
+            return f"Error: Folder dose not exist: {folder}"
+        
+        if not os.path.isdir(folder):
+            return f"Error: Specified path is not a directory: {folder}"
+
+        image_files = []
+        for filename  in os.listdir(folder):
+            filepath = os.path.join(folder, filename)
+            if os.path.isfile(filepath) and is_valid_image:
+                image_files.append(filename)
+
+        if not image_files:
+            return f"No image files found in folder: {folder}"
+        
+        result_lines = [
+            f"Folder: {folder}",
+            f"Number of image files: {len(image_files)}",
+            "---",
+            *[f"{i+1}. {name}" for i, name in enumerate(image_files)]
+        ]
+        
+        return "\n".join(result_lines)
+    
+    except Exception as e:
+        return f"Error occurred: {str(e)}"
+
+@mcp.tool()
+def read_image(image_path: str) -> Image:
+    """
+    Read an image file and return it as an Image odject.
+
+    Args:
+        image_path (str) : Path to the image file
+    
+    Returns:
+        Image: Image object
+    """
+    img = PILImage.open(image_path)
+    buffer = BytesIO()
+    img_format = img.format.lower() if img.format else "png"
+    img.save(buffer, format=img_format)
+    return Image(data=buffer.getvalue(), format=img_format)
+    
+@mcp.tool()
+def copy_image(
+    source_path: str,
+    destination_path: str,
+    overwrite: bool = False
+) -> Dict[str, Any]:
+    """
+    Copy an image file to a new location.
+
+    Args:
+        source_path (str): Source image file path
+        destination_path (str): Destination image file path (including filename)
+        overwrite (bool): Whether to overwrite if destination file exists
+
+    Returns:
+        Dict[str, Any]: Copy result information
+
+
+    """
+    try:
+        source_path = os.path.abspath(source_path)
+        destination_path = os.path.abspath(destination_path)
+
+        if not os.path.exists(source_path):
+            return {
+                "success": False,
+                "error": f"Source file does not exist: {source_path}"
+            }
+
+        if not is_valid_image(source_path):
+            return {
+                "success": False,
+                "error": f"Source file is not a valid image: {source_path}"
+            }
+
+        destination_dir = os.path.dirname(destination_path)
+        if not os.path.exists(destination_dir):
+            os.makedirs(destination_dir)
+
+        shutil.copy2(source_path, destination_path)
+
+        file_size = os.path.getsize(destination_path)
+        with PILImage.open(destination_path) as img:
+            width, height = img.size
+            format_name = img.format
+
+        return {
+            "success": True,
+            "message": "Image file copied successfully.",
+            "source_path": source_path,
+            "destination_path": destination_path,
+            "file_size": file_size,
+            "width": width,
+            "height": height,
+            "format": format_name
+        }
+
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e)
+        }
+
+@mcp.tool()
+def move_image(
+    source_path: str,
+    destination_path: str,
+    overwrite: bool = False
+) -> Dict[str, Any]:
+    """
+    Move an image file. 
+    Can move to the same or different path, with the same or different filename.
+
+    Args:
+        source_path (str): Source image file path
+        destination_path (str): Destination image file path (including filename)
+        overwrite (bool): Whether to overwrite if destination file exists
+
+    Returns:
+        Dict[str, Any]: Move result information
+    """
+
+    try:
+        source_path = os.path.abspath(source_path)
+        destination_path = os.path.abspath(destination_path)
+
+        if not os.path.exists(source_path):
+            return {
+                "success": False,
+                "error": f"Source file does not exists: {source_path}"
+            }
+
+        if not is_valid_image(source_path):
+            return {
+                "success": False,
+                "error": f"Source file is not a valid image: {source_path}"
+            }
+
+        if os.path.exists(destination_path) and not overwrite:
+            return {
+                "success": False,
+                "error": f"Destination file already exists and overwrite is not allowed: {destination_path}"
+            }
+
+        file_name = os.path.basename(source_path)
+        file_size = os.path.getsize(source_path)
+        with PILImage.open(source_path) as img:
+            width, height = img.size
+            format_name = img.format
+        
+        destination_dir = os.path.dirname(destination_path)
+        if not os.path.exists(destination_dir):
+            os.makedirs(destination_dir)
+
+        shutil.move(source_path, destination_path)
+
+        return {
+            "success": True,
+            "message" : "Image file moved successfully.",
+            "source_path": source_path,
+            "destination_path": destination_path,
+            "file_name": file_name,
+            "file_size": file_size,
+            "width": width,
+            "height": height,
+            "format": format_name
+        }
+    
+    except Exception as e:
+        return{
+            "success": False,
+            "error": str(e)
+        }
+
+@mcp.tool()
+def delete_image(
+    image_path: str,
+    confirm: bool = True
+) -> Dict[str, Any]:
+    """
+    Delete an image file:
+
+    Args:
+        image_path (str): Path to the image file to delete
+        confirm (bool): Confirmation for deletion (default: True, prevents accidental deletion)
+
+    Returns:
+        Dict[str, Any]: Deletion result information
+
+    """
+
+    try:
+        image_path = os.path.abspath(image_path)
+
+        if not os.path.exists(image_path):
+            return {
+                "success": False,
+                "error": f"File does not exist: {image_path}"
+            }
+        if not is_valid_image(image_path):
+            return {
+                "succcess": False,
+                "error": f"File is not a valid image: {image_path}"
+            }
+
+        if not confirm:
+            return {
+                "success": False,
+                "error": "File deletion not confirmed. Set conform=True to conform deletion."
+            }
+
+        file_size = os.path.getsize(image_path)
+        file_name = os.path.basename(image_path)
+
+        os.remove(image_path)
+
+        return {
+            "success": True,
+            "message": "Image file deleted successfully.",
+            "deleted_path": image_path,
+            "file_name": file_name,
+            "file_size": file_size
+        }
+
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e)
+        }
+
+def main():
+    mcp.run(transport="stdio")
+
+
+
+# 23차시

jitora-1.1.0/src/jitora/__main__.py

@@ -0,0 +1,6 @@
+import sys
+from . import main
+
+sys.exit(main())
+
+# https://pypi.org/