psforge 0.2.0__py3-none-any.whl

psforge/registry.py

@@ -0,0 +1,121 @@
+"""Tool and resource registration system for MCP server."""
+
+import importlib
+import pkgutil
+from pathlib import Path
+from typing import Callable
+
+from loguru import logger
+from mcp.server.fastmcp import FastMCP
+
+
+def register_tool(mcp: FastMCP, func: Callable, name: str | None = None) -> str:
+    """Register a single tool function with the MCP server.
+
+    Args:
+        mcp: MCP server instance.
+        func: Tool function to register.
+        name: Optional tool name override (defaults to function name).
+
+    Returns:
+        The registered tool name.
+    """
+    tool_name = name or func.__name__
+    description = func.__doc__ or f"Tool: {tool_name}"
+
+    mcp.tool(name=tool_name, description=description.strip())(func)
+
+    logger.debug(f"Registered tool: {tool_name}")
+    return tool_name
+
+
+def discover_and_register_tools(mcp: FastMCP) -> list[str]:
+    """Automatically discover and register all tools from the tools package.
+
+    Args:
+        mcp: MCP server instance.
+
+    Returns:
+        List of registered tool names.
+    """
+    registered_tools = []
+
+    # Import tools package
+    try:
+        import psforge.tools as tools_pkg
+    except ImportError as e:
+        logger.error(f"Failed to import tools package: {e}")
+        return registered_tools
+
+    # Get tools package path
+    tools_path = Path(tools_pkg.__file__).parent
+
+    # Iterate through all Python modules in tools/
+    for module_info in pkgutil.iter_modules([str(tools_path)]):
+        if module_info.name.startswith("_"):
+            continue
+
+        module_name = f"psforge.tools.{module_info.name}"
+
+        try:
+            module = importlib.import_module(module_name)
+
+            # Look for register() function
+            if hasattr(module, "register"):
+                logger.info(f"Registering tools from: {module_name}")
+                tool_names = module.register(mcp)
+                registered_tools.extend(tool_names)
+            else:
+                logger.warning(f"Module {module_name} has no register() function")
+
+        except Exception as e:
+            logger.error(f"Failed to register tools from {module_name}: {e}")
+
+    logger.info(f"Total tools registered: {len(registered_tools)}")
+    return registered_tools
+
+
+def discover_and_register_resources(mcp: FastMCP) -> list[str]:
+    """Automatically discover and register all resources from the resources package.
+
+    Args:
+        mcp: MCP server instance.
+
+    Returns:
+        List of registered resource URIs.
+    """
+    registered_resources = []
+
+    # Import resources package
+    try:
+        import psforge.resources as resources_pkg
+    except ImportError as e:
+        logger.error(f"Failed to import resources package: {e}")
+        return registered_resources
+
+    # Get resources package path
+    resources_path = Path(resources_pkg.__file__).parent
+
+    # Iterate through all Python modules in resources/
+    for module_info in pkgutil.iter_modules([str(resources_path)]):
+        if module_info.name.startswith("_"):
+            continue
+
+        module_name = f"psforge.resources.{module_info.name}"
+
+        try:
+            module = importlib.import_module(module_name)
+
+            # Look for register() function
+            if hasattr(module, "register"):
+                logger.info(f"Registering resources from: {module_name}")
+                resource_uris = module.register(mcp)
+                registered_resources.extend(resource_uris)
+            else:
+                logger.warning(f"Module {module_name} has no register() function")
+
+        except Exception as e:
+            logger.error(f"Failed to register resources from {module_name}: {e}")
+
+    logger.info(f"Total resources registered: {len(registered_resources)}")
+    return registered_resources

psforge/resources/__init__.py

@@ -0,0 +1,3 @@
+"""MCP resources for Photoshop state exposure."""
+
+__all__ = []

psforge/resources/registry.py

@@ -0,0 +1,3 @@
+"""Resource registration utilities."""
+
+__all__ = []

psforge/server.py

@@ -0,0 +1,79 @@
+"""PSForge MCP Server - Main entry point."""
+
+import sys
+
+from loguru import logger
+from mcp.server.fastmcp import FastMCP
+
+from psforge.app import __app_name__, __version__
+from psforge.registry import discover_and_register_resources, discover_and_register_tools
+
+
+def setup_logging():
+    """Configure logging with loguru."""
+    logger.remove()  # Remove default handler
+
+    # Add stderr handler for general logging
+    logger.add(
+        sys.stderr,
+        level="INFO",
+        format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <level>{message}</level>",
+    )
+
+    # Add file handler for detailed debug logs
+    logger.add(
+        "psforge_debug.log",
+        level="DEBUG",
+        format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}",
+        rotation="10 MB",
+        retention="7 days",
+    )
+
+
+def run():
+    """Entry point for the CLI command."""
+    setup_logging()
+
+    logger.info(f"Starting {__app_name__} v{__version__}")
+    logger.info("Photoshop MCP Server - AI-Powered Automation")
+
+    # Create MCP server using FastMCP
+    mcp = FastMCP(__app_name__)
+
+    # Discover and register all tools
+    logger.info("Discovering and registering tools...")
+    tool_names = discover_and_register_tools(mcp)
+
+    if tool_names:
+        logger.info(f"Registered {len(tool_names)} tools:")
+        for name in sorted(tool_names):
+            logger.info(f"  - {name}")
+    else:
+        logger.warning("No tools were registered!")
+
+    # Discover and register all resources
+    logger.info("Discovering and registering resources...")
+    resource_uris = discover_and_register_resources(mcp)
+
+    if resource_uris:
+        logger.info(f"Registered {len(resource_uris)} resources:")
+        for uri in sorted(resource_uris):
+            logger.info(f"  - {uri}")
+    else:
+        logger.info("No resources registered (this is OK)")
+
+    # Run the server
+    logger.info("PSForge MCP Server is ready")
+    logger.info("Waiting for connections...")
+
+    try:
+        mcp.run(transport="stdio")
+    except KeyboardInterrupt:
+        logger.info("Server stopped by user")
+    except Exception as e:
+        logger.error(f"Server error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run()

psforge/tools/__init__.py

@@ -0,0 +1,3 @@
+"""MCP tools for Photoshop automation."""
+
+__all__ = []

psforge/tools/action_tools.py

@@ -0,0 +1,149 @@
+"""Action and script execution tools - play actions, run custom scripts."""
+
+from typing import Any
+
+from loguru import logger
+
+from psforge.decorators import debug_tool, log_tool_call
+from psforge.ps_adapter.application import PhotoshopApp
+from psforge.ps_adapter.utils import js_escape_string
+from psforge.registry import register_tool
+
+
+def register(mcp) -> list[str]:
+    """Register all action tools with MCP server.
+
+    Args:
+        mcp: MCP server instance.
+
+    Returns:
+        List of registered tool names.
+    """
+    registered_tools = []
+
+    @debug_tool
+    @log_tool_call
+    def play_action(action_name: str, action_set: str) -> dict[str, Any]:
+        """Execute a Photoshop action from an action set.
+
+        Args:
+            action_name: Name of the action to execute.
+            action_set: Name of the action set containing the action.
+
+        Returns:
+            dict: Operation result and context.
+        """
+        ps_app = PhotoshopApp()
+        doc = ps_app.get_active_document()
+
+        if not doc:
+            return {
+                "success": False,
+                "error": "No active document. Some actions require an open document.",
+            }
+
+        try:
+            # Escape strings for JavaScript
+            action_name_escaped = js_escape_string(action_name)
+            action_set_escaped = js_escape_string(action_set)
+
+            # Execute action via JavaScript
+            action_script = f"""
+            (function() {{
+                try {{
+                    app.doAction("{action_name_escaped}", "{action_set_escaped}");
+                    return "Action executed successfully";
+                }} catch(e) {{
+                    return "Error: " + e.toString();
+                }}
+            }})();
+            """
+
+            result = ps_app.execute_javascript(action_script)
+
+            if isinstance(result, str) and result.startswith("Error:"):
+                return {
+                    "success": False,
+                    "error": result,
+                    "action_name": action_name,
+                    "action_set": action_set,
+                }
+
+            return {
+                "success": True,
+                "message": f"Executed action '{action_name}' from set '{action_set}'",
+                "action_name": action_name,
+                "action_set": action_set,
+                "result": result,
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to execute action: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+                "action_name": action_name,
+                "action_set": action_set,
+            }
+
+    @debug_tool
+    @log_tool_call
+    def execute_script(script: str) -> dict[str, Any]:
+        """Execute arbitrary ExtendScript/JavaScript code in Photoshop.
+
+        This is a powerful tool that allows executing any valid Photoshop ExtendScript.
+        Use with caution - invalid scripts can cause errors or unexpected behavior.
+
+        Args:
+            script: JavaScript/ExtendScript code to execute in Photoshop.
+
+        Returns:
+            dict: Execution result and context.
+
+        Examples:
+            - Simple operation: "app.activeDocument.activeLayer.opacity = 50;"
+            - Get info: "app.activeDocument.layers.length"
+            - Complex: "(function() { var layer = app.activeDocument.activeLayer; layer.rotate(45); return 'Rotated'; })()"
+        """
+        ps_app = PhotoshopApp()
+
+        if not script or not script.strip():
+            return {
+                "success": False,
+                "error": "Script cannot be empty",
+            }
+
+        try:
+            logger.info(f"Executing custom script (length: {len(script)} chars)")
+            logger.debug(f"Script content:\n{script}")
+
+            # Execute the script
+            result = ps_app.execute_javascript(script)
+
+            # Convert result to string if it's not already
+            result_str = str(result) if result is not None else "undefined"
+
+            return {
+                "success": True,
+                "message": "Script executed successfully",
+                "result": result_str,
+                "script_length": len(script),
+            }
+
+        except Exception as e:
+            logger.error(f"Script execution failed: {e}")
+
+            # Try to extract useful error info
+            error_msg = str(e)
+
+            return {
+                "success": False,
+                "error": error_msg,
+                "script_preview": script[:200] + ("..." if len(script) > 200 else ""),
+            }
+
+    # Register all tools
+    registered_tools.append(register_tool(mcp, play_action, "play_action"))
+    registered_tools.append(register_tool(mcp, execute_script, "execute_script"))
+
+    return registered_tools

psforge/tools/adjustment_tools.py

@@ -0,0 +1,316 @@
+"""Adjustment tools - brightness/contrast, hue/saturation, auto-levels, auto-contrast, desaturate, invert."""
+
+from typing import Any
+
+from loguru import logger
+
+from psforge.decorators import debug_tool, log_tool_call
+from psforge.ps_adapter.application import PhotoshopApp
+from psforge.ps_adapter.utils import validate_numeric_range
+from psforge.registry import register_tool
+
+
+def register(mcp) -> list[str]:
+    """Register all adjustment tools with MCP server.
+
+    Args:
+        mcp: MCP server instance.
+
+    Returns:
+        List of registered tool names.
+    """
+    registered_tools = []
+
+    @debug_tool
+    @log_tool_call
+    def adjust_brightness_contrast(brightness: int, contrast: int) -> dict[str, Any]:
+        """Adjust brightness and contrast of the currently active layer.
+
+        Args:
+            brightness: Brightness adjustment (-150 to 150, 0 = no change).
+            contrast: Contrast adjustment (-50 to 100, 0 = no change).
+
+        Returns:
+            dict: Operation result and context.
+        """
+        validate_numeric_range(brightness, -150, 150, "brightness")
+        validate_numeric_range(contrast, -50, 100, "contrast")
+
+        ps_app = PhotoshopApp()
+        doc = ps_app.get_active_document()
+
+        if not doc:
+            return {
+                "success": False,
+                "error": "No active document",
+            }
+
+        try:
+            adjust_script = f"""
+            var layer = app.activeDocument.activeLayer;
+            var layerName = layer.name;
+
+            // Apply Brightness/Contrast
+            layer.adjustBrightnessContrast({brightness}, {contrast});
+
+            layerName;
+            """
+
+            layer_name = ps_app.execute_javascript(adjust_script)
+
+            return {
+                "success": True,
+                "message": f"Adjusted brightness ({brightness:+d}) and contrast ({contrast:+d}) on layer '{layer_name}'",
+                "layer_name": layer_name,
+                "brightness": brightness,
+                "contrast": contrast,
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to adjust brightness/contrast: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+            }
+
+    @debug_tool
+    @log_tool_call
+    def adjust_hue_saturation(hue: int, saturation: int, lightness: int) -> dict[str, Any]:
+        """Adjust hue, saturation, and lightness of the currently active layer.
+
+        Args:
+            hue: Hue shift in degrees (-180 to 180, 0 = no change).
+            saturation: Saturation adjustment (-100 to 100, 0 = no change).
+            lightness: Lightness adjustment (-100 to 100, 0 = no change).
+
+        Returns:
+            dict: Operation result and context.
+        """
+        validate_numeric_range(hue, -180, 180, "hue")
+        validate_numeric_range(saturation, -100, 100, "saturation")
+        validate_numeric_range(lightness, -100, 100, "lightness")
+
+        ps_app = PhotoshopApp()
+        doc = ps_app.get_active_document()
+
+        if not doc:
+            return {
+                "success": False,
+                "error": "No active document",
+            }
+
+        try:
+            adjust_script = f"""
+            var layer = app.activeDocument.activeLayer;
+            var layerName = layer.name;
+
+            // Apply Hue/Saturation
+            layer.adjustColorBalance([0, 0, 0], [0, 0, 0], [0, 0, 0], true);
+            layer.adjustHueSaturation({hue}, {saturation}, {lightness});
+
+            layerName;
+            """
+
+            layer_name = ps_app.execute_javascript(adjust_script)
+
+            return {
+                "success": True,
+                "message": f"Adjusted hue/saturation/lightness on layer '{layer_name}'",
+                "layer_name": layer_name,
+                "hue": hue,
+                "saturation": saturation,
+                "lightness": lightness,
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to adjust hue/saturation: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+            }
+
+    @debug_tool
+    @log_tool_call
+    def auto_levels() -> dict[str, Any]:
+        """Apply Auto Levels adjustment to the currently active layer.
+
+        Returns:
+            dict: Operation result and context.
+        """
+        ps_app = PhotoshopApp()
+        doc = ps_app.get_active_document()
+
+        if not doc:
+            return {
+                "success": False,
+                "error": "No active document",
+            }
+
+        try:
+            auto_levels_script = """
+            var layer = app.activeDocument.activeLayer;
+            var layerName = layer.name;
+
+            // Apply Auto Levels
+            layer.autoLevels();
+
+            layerName;
+            """
+
+            layer_name = ps_app.execute_javascript(auto_levels_script)
+
+            return {
+                "success": True,
+                "message": f"Applied Auto Levels to layer '{layer_name}'",
+                "layer_name": layer_name,
+                "adjustment": "Auto Levels",
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to apply Auto Levels: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+            }
+
+    @debug_tool
+    @log_tool_call
+    def auto_contrast() -> dict[str, Any]:
+        """Apply Auto Contrast adjustment to the currently active layer.
+
+        Returns:
+            dict: Operation result and context.
+        """
+        ps_app = PhotoshopApp()
+        doc = ps_app.get_active_document()
+
+        if not doc:
+            return {
+                "success": False,
+                "error": "No active document",
+            }
+
+        try:
+            auto_contrast_script = """
+            var layer = app.activeDocument.activeLayer;
+            var layerName = layer.name;
+
+            // Apply Auto Contrast
+            layer.autoContrast();
+
+            layerName;
+            """
+
+            layer_name = ps_app.execute_javascript(auto_contrast_script)
+
+            return {
+                "success": True,
+                "message": f"Applied Auto Contrast to layer '{layer_name}'",
+                "layer_name": layer_name,
+                "adjustment": "Auto Contrast",
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to apply Auto Contrast: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+            }
+
+    @debug_tool
+    @log_tool_call
+    def desaturate() -> dict[str, Any]:
+        """Desaturate (convert to grayscale) the currently active layer.
+
+        Returns:
+            dict: Operation result and context.
+        """
+        ps_app = PhotoshopApp()
+        doc = ps_app.get_active_document()
+
+        if not doc:
+            return {
+                "success": False,
+                "error": "No active document",
+            }
+
+        try:
+            desaturate_script = """
+            var layer = app.activeDocument.activeLayer;
+            var layerName = layer.name;
+
+            // Desaturate
+            layer.desaturate();
+
+            layerName;
+            """
+
+            layer_name = ps_app.execute_javascript(desaturate_script)
+
+            return {
+                "success": True,
+                "message": f"Desaturated layer '{layer_name}'",
+                "layer_name": layer_name,
+                "adjustment": "Desaturate",
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to desaturate: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+            }
+
+    @debug_tool
+    @log_tool_call
+    def invert() -> dict[str, Any]:
+        """Invert colors of the currently active layer.
+
+        Returns:
+            dict: Operation result and context.
+        """
+        ps_app = PhotoshopApp()
+        doc = ps_app.get_active_document()
+
+        if not doc:
+            return {
+                "success": False,
+                "error": "No active document",
+            }
+
+        try:
+            invert_script = """
+            var layer = app.activeDocument.activeLayer;
+            var layerName = layer.name;
+
+            // Invert
+            layer.invert();
+
+            layerName;
+            """
+
+            layer_name = ps_app.execute_javascript(invert_script)
+
+            return {
+                "success": True,
+                "message": f"Inverted colors of layer '{layer_name}'",
+                "layer_name": layer_name,
+                "adjustment": "Invert",
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to invert: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+            }
+
+    # Register all tools
+    registered_tools.append(register_tool(mcp, adjust_brightness_contrast, "adjust_brightness_contrast"))
+    registered_tools.append(register_tool(mcp, adjust_hue_saturation, "adjust_hue_saturation"))
+    registered_tools.append(register_tool(mcp, auto_levels, "auto_levels"))
+    registered_tools.append(register_tool(mcp, auto_contrast, "auto_contrast"))
+    registered_tools.append(register_tool(mcp, desaturate, "desaturate"))
+    registered_tools.append(register_tool(mcp, invert, "invert"))
+
+    return registered_tools