awslabs.nova-canvas-mcp-server 0.1.10233__py3-none-any.whl

awslabs/__init__.py

@@ -0,0 +1,2 @@
+# This file is part of the awslabs namespace.
+# It is intentionally minimal to support PEP 420 namespace packages.

awslabs/nova_canvas_mcp_server/__init__.py

@@ -0,0 +1,3 @@
+"""awslabs.nova-canvas-mcp-server"""
+
+__version__ = '0.1.6'

awslabs/nova_canvas_mcp_server/consts.py

@@ -0,0 +1,61 @@
+# Constants
+NOVA_CANVAS_MODEL_ID = 'amazon.nova-canvas-v1:0'
+DEFAULT_WIDTH = 1024
+DEFAULT_HEIGHT = 1024
+DEFAULT_QUALITY = 'standard'
+DEFAULT_CFG_SCALE = 6.5
+DEFAULT_NUMBER_OF_IMAGES = 1
+DEFAULT_OUTPUT_DIR = 'output'  # Default directory inside workspace_dir
+
+
+# Nova Canvas Prompt Best Practices
+PROMPT_INSTRUCTIONS = """
+# Amazon Nova Canvas Prompting Best Practices
+
+## General Guidelines
+
+- Prompts must be no longer than 1024 characters. For very long prompts, place the least important details near the end.
+- Do not use negation words like "no", "not", "without" in your prompt. The model doesn't understand negation and will result in the opposite of what you intend.
+- Use negative prompts (via the `negative_prompt` parameter) to specify objects or characteristics to exclude from the image.
+- Omit negation words from your negative prompts as well.
+
+## Effective Prompt Structure
+
+An effective prompt often includes short descriptions of:
+
+1. The subject
+2. The environment
+3. (optional) The position or pose of the subject
+4. (optional) Lighting description
+5. (optional) Camera position/framing
+6. (optional) The visual style or medium ("photo", "illustration", "painting", etc.)
+
+## Refining Results
+
+When the output is close to what you want but not perfect:
+
+1. Use a consistent `seed` value and make small changes to your prompt or negative prompt.
+2. Once the prompt is refined, generate more variations using the same prompt but different `seed` values.
+
+## Examples
+
+### Example 1: Stock Photo
+**Prompt:** "realistic editorial photo of female teacher standing at a blackboard with a warm smile"
+**Negative Prompt:** "crossed arms"
+
+### Example 2: Story Illustration
+**Prompt:** "whimsical and ethereal soft-shaded story illustration: A woman in a large hat stands at the ship's railing looking out across the ocean"
+**Negative Prompt:** "clouds, waves"
+
+### Example 3: Pre-visualization for TV/Film
+**Prompt:** "drone view of a dark river winding through a stark Iceland landscape, cinematic quality"
+
+### Example 4: Fashion/Editorial Content
+**Prompt:** "A cool looking stylish man in an orange jacket, dark skin, wearing reflective glasses. Shot from slightly low angle, face and chest in view, aqua blue sleek building shapes in background."
+
+## Using Negative Prompts
+
+Negative prompts can be surprisingly useful. Use them to exclude objects or style characteristics that might otherwise naturally occur as a result of your main prompt.
+
+For example, adding "waves, clouds" as a negative prompt to a ship scene will result in a cleaner, more minimal composition.
+"""

awslabs/nova_canvas_mcp_server/models.py

@@ -0,0 +1,287 @@
+"""Pydantic models for Amazon Nova Canvas image generation."""
+
+import random
+import re
+from enum import Enum
+from pydantic import BaseModel, Field, field_validator, model_validator
+from typing import Any, Dict, List, Literal, Optional
+
+
+class Quality(str, Enum):
+    """Quality options for image generation.
+
+    Attributes:
+        STANDARD: Standard quality image generation.
+        PREMIUM: Premium quality image generation with enhanced details.
+    """
+
+    STANDARD = 'standard'
+    PREMIUM = 'premium'
+
+
+class TaskType(str, Enum):
+    """Task types for image generation.
+
+    Attributes:
+        TEXT_IMAGE: Generate an image from text description.
+        COLOR_GUIDED_GENERATION: Generate an image guided by both text and color palette.
+    """
+
+    TEXT_IMAGE = 'TEXT_IMAGE'
+    COLOR_GUIDED_GENERATION = 'COLOR_GUIDED_GENERATION'
+
+
+class ImageGenerationConfig(BaseModel):
+    """Configuration for image generation.
+
+    This model defines the parameters that control the image generation process,
+    including dimensions, quality, and generation settings.
+
+    Attributes:
+        width: Width of the generated image (320-4096, must be divisible by 16).
+        height: Height of the generated image (320-4096, must be divisible by 16).
+        quality: Quality level of the generated image (standard or premium).
+        cfgScale: How strongly the image adheres to the prompt (1.1-10.0).
+        seed: Seed for reproducible generation (0-858993459).
+        numberOfImages: Number of images to generate (1-5).
+    """
+
+    width: int = Field(default=1024, ge=320, le=4096)
+    height: int = Field(default=1024, ge=320, le=4096)
+    quality: Quality = Quality.STANDARD
+    cfgScale: float = Field(default=6.5, ge=1.1, le=10.0)
+    seed: int = Field(default_factory=lambda: random.randint(0, 858993459), ge=0, le=858993459)
+    numberOfImages: int = Field(default=1, ge=1, le=5)
+
+    @field_validator('width', 'height')
+    @classmethod
+    def must_be_divisible_by_16(cls, v: int) -> int:
+        """Validate that width and height are divisible by 16.
+
+        Args:
+            v: The width or height value to validate.
+
+        Returns:
+            The validated value if it passes.
+
+        Raises:
+            ValueError: If the value is not divisible by 16.
+        """
+        if v % 16 != 0:
+            raise ValueError('Value must be divisible by 16')
+        return v
+
+    @model_validator(mode='after')
+    def validate_aspect_ratio_and_total_pixels(self):
+        """Validate aspect ratio and total pixel count.
+
+        Ensures that:
+        1. The aspect ratio is between 1:4 and 4:1
+        2. The total pixel count is less than 4,194,304
+
+        Returns:
+            The validated model if it passes.
+
+        Raises:
+            ValueError: If the aspect ratio or total pixel count is invalid.
+        """
+        width = self.width
+        height = self.height
+
+        # Check aspect ratio between 1:4 and 4:1
+        aspect_ratio = width / height
+        if aspect_ratio < 0.25 or aspect_ratio > 4.0:
+            raise ValueError('Aspect ratio must be between 1:4 and 4:1')
+
+        # Check total pixel count
+        total_pixels = width * height
+        if total_pixels >= 4194304:
+            raise ValueError('Total pixel count must be less than 4,194,304')
+
+        return self
+
+
+class TextToImageParams(BaseModel):
+    """Parameters for text-to-image generation.
+
+    This model defines the text prompts used to generate images.
+
+    Attributes:
+        text: The text description of the image to generate (1-1024 characters).
+        negativeText: Optional text to define what not to include in the image (1-1024 characters).
+    """
+
+    text: str = Field(..., min_length=1, max_length=1024)
+    negativeText: Optional[str] = Field(default=None, min_length=1, max_length=1024)
+
+
+class ColorGuidedGenerationParams(BaseModel):
+    """Parameters for color-guided generation.
+
+    This model defines the text prompts and color palette used to generate images.
+
+    Attributes:
+        colors: List of hexadecimal color values (e.g., "#FF9800") to guide the image generation.
+        text: The text description of the image to generate (1-1024 characters).
+        negativeText: Optional text to define what not to include in the image (1-1024 characters).
+    """
+
+    colors: List[str] = Field(..., max_length=10)
+    text: str = Field(..., min_length=1, max_length=1024)
+    negativeText: Optional[str] = Field(default=None, min_length=1, max_length=1024)
+
+    @field_validator('colors')
+    @classmethod
+    def validate_hex_colors(cls, v: List[str]) -> List[str]:
+        """Validate that colors are in the correct hexadecimal format.
+
+        Args:
+            v: List of color strings to validate.
+
+        Returns:
+            The validated list if all colors pass.
+
+        Raises:
+            ValueError: If any color is not a valid hexadecimal color in the format '#RRGGBB'.
+        """
+        hex_pattern = re.compile(r'^#[0-9A-Fa-f]{6}$')
+        for color in v:
+            if not hex_pattern.match(color):
+                raise ValueError(
+                    f"Color '{color}' is not a valid hexadecimal color in the format '#RRGGBB'"
+                )
+        return v
+
+
+class TextImageRequest(BaseModel):
+    """Request model for text-to-image generation.
+
+    This model combines the task type, text parameters, and generation configuration
+    for a complete text-to-image request.
+
+    Attributes:
+        taskType: The type of task (TEXT_IMAGE).
+        textToImageParams: Parameters for text-to-image generation.
+        imageGenerationConfig: Configuration for image generation.
+    """
+
+    taskType: Literal[TaskType.TEXT_IMAGE] = TaskType.TEXT_IMAGE
+    textToImageParams: TextToImageParams
+    imageGenerationConfig: Optional[ImageGenerationConfig] = Field(
+        default_factory=ImageGenerationConfig
+    )
+
+    # instead of overriding model_dump, we add a post-model_dump extension method
+    def to_api_dict(self) -> Dict[str, Any]:
+        """Convert model to dictionary suitable for API requests.
+
+        Returns:
+            A dictionary representation of the model suitable for API requests.
+        """
+        text_to_image_params = self.textToImageParams.model_dump()
+        # Remove negativeText if it's None
+        if text_to_image_params.get('negativeText') is None:
+            text_to_image_params.pop('negativeText', None)
+
+        return {
+            'taskType': self.taskType,
+            'textToImageParams': text_to_image_params,
+            'imageGenerationConfig': self.imageGenerationConfig.model_dump()
+            if self.imageGenerationConfig
+            else None,
+        }
+
+
+class ColorGuidedRequest(BaseModel):
+    """Request model for color-guided generation.
+
+    This model combines the task type, color-guided parameters, and generation configuration
+    for a complete color-guided generation request.
+
+    Attributes:
+        taskType: The type of task (COLOR_GUIDED_GENERATION).
+        colorGuidedGenerationParams: Parameters for color-guided generation.
+        imageGenerationConfig: Configuration for image generation.
+    """
+
+    taskType: Literal[TaskType.COLOR_GUIDED_GENERATION] = TaskType.COLOR_GUIDED_GENERATION
+    colorGuidedGenerationParams: ColorGuidedGenerationParams
+    imageGenerationConfig: Optional[ImageGenerationConfig] = Field(
+        default_factory=ImageGenerationConfig
+    )
+
+    # instead of overriding model_dump, we add a post-model_dump extension method
+    def to_api_dict(self) -> Dict[str, Any]:
+        """Convert model to dictionary suitable for API requests.
+
+        Returns:
+            A dictionary representation of the model suitable for API requests.
+        """
+        color_guided_params = self.colorGuidedGenerationParams.model_dump()
+        # Remove negativeText if it's None
+        if color_guided_params.get('negativeText') is None:
+            color_guided_params.pop('negativeText', None)
+
+        return {
+            'taskType': self.taskType,
+            'colorGuidedGenerationParams': color_guided_params,
+            'imageGenerationConfig': self.imageGenerationConfig.model_dump()
+            if self.imageGenerationConfig
+            else None,
+        }
+
+
+class McpImageGenerationResponse(BaseModel):
+    """Response from image generation API.
+
+    This model represents the response from the Amazon Nova Canvas API
+    for both text-to-image and color-guided image generation.
+    """
+
+    status: str
+    paths: List[str]
+
+
+class ImageGenerationResponse(BaseModel):
+    """Response from image generation API.
+
+    This model represents the response from the Amazon Nova Canvas API
+    for both text-to-image and color-guided image generation.
+
+    Attributes:
+        status: Status of the image generation request ('success' or 'error').
+        message: Message describing the result or error.
+        paths: List of paths to the generated image files.
+        images: List of PIL Image objects.
+        prompt: The text prompt used to generate the images.
+        negative_prompt: The negative prompt used to generate the images, if any.
+        colors: The colors used to guide the image generation, if any.
+    """
+
+    status: str
+    message: str
+    paths: List[str]
+    prompt: str
+    negative_prompt: Optional[str] = None
+    colors: Optional[List[str]] = None
+
+    class Config:
+        """Pydantic configuration."""
+
+        arbitrary_types_allowed = True  # Allow PIL.Image.Image type
+
+    def __getitem__(self, key: str) -> Any:
+        """Support dictionary-style access for backward compatibility.
+
+        Args:
+            key: The attribute name to access.
+
+        Returns:
+            The value of the attribute.
+
+        Raises:
+            KeyError: If the attribute does not exist.
+        """
+        if hasattr(self, key):
+            return getattr(self, key)
+        raise KeyError(f"'{key}' not found in ImageGenerationResponse")

awslabs/nova_canvas_mcp_server/novacanvas.py

@@ -0,0 +1,396 @@
+"""Amazon Nova Canvas API interaction module.
+
+This module provides functions for generating images using Amazon Nova Canvas
+through the AWS Bedrock service. It handles the API requests, response processing,
+and image saving functionality.
+"""
+
+import base64
+import json
+import os
+import random
+from .models import (
+    ColorGuidedGenerationParams,
+    ColorGuidedRequest,
+    ImageGenerationConfig,
+    ImageGenerationResponse,
+    Quality,
+    TextImageRequest,
+    TextToImageParams,
+)
+from awslabs.nova_canvas_mcp_server.consts import (
+    DEFAULT_CFG_SCALE,
+    DEFAULT_HEIGHT,
+    DEFAULT_NUMBER_OF_IMAGES,
+    DEFAULT_OUTPUT_DIR,
+    DEFAULT_QUALITY,
+    DEFAULT_WIDTH,
+    NOVA_CANVAS_MODEL_ID,
+)
+from loguru import logger
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+
+if TYPE_CHECKING:
+    from mypy_boto3_bedrock_runtime import BedrockRuntimeClient
+else:
+    BedrockRuntimeClient = object
+
+
+def save_generated_images(
+    base64_images: List[str],
+    filename: Optional[str] = None,
+    number_of_images: int = DEFAULT_NUMBER_OF_IMAGES,
+    prefix: str = 'nova_canvas',
+    workspace_dir: Optional[str] = None,
+) -> Dict[str, List]:
+    """Save base64-encoded images to files.
+
+    Args:
+        base64_images: List of base64-encoded image data.
+        filename: Base filename to use (without extension). If None, a random name is generated.
+        number_of_images: Number of images being saved.
+        prefix: Prefix to use for randomly generated filenames.
+        workspace_dir: Directory where the images should be saved. If None, uses current directory.
+
+    Returns:
+        Dictionary with lists of paths to the saved image files and PIL Image objects.
+    """
+    logger.debug(f'Saving {len(base64_images)} images')
+    # Determine the output directory
+    if workspace_dir:
+        output_dir = os.path.join(workspace_dir, DEFAULT_OUTPUT_DIR)
+    else:
+        output_dir = DEFAULT_OUTPUT_DIR
+
+    # Create output directory if it doesn't exist
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    # Save the generated images
+    saved_paths: List[str] = []
+    for i, base64_image_data in enumerate(base64_images):
+        # Generate filename if not provided
+        if filename:
+            image_filename = (
+                f'{filename}_{i + 1}.png' if number_of_images > 1 else f'{filename}.png'
+            )
+        else:
+            # Generate a random filename
+            random_id = ''.join(random.choices('abcdefghijklmnopqrstuvwxyz0123456789', k=8))
+            image_filename = f'{prefix}_{random_id}_{i + 1}.png'
+
+        # Decode the base64 image data
+        image_data = base64.b64decode(base64_image_data)
+
+        # Save the image
+        image_path = os.path.join(output_dir, image_filename)
+        with open(image_path, 'wb') as file:
+            file.write(image_data)
+        # Convert to absolute path
+        abs_image_path = os.path.abspath(image_path)
+        saved_paths.append(abs_image_path)
+
+    return {'paths': saved_paths}
+
+
+async def invoke_nova_canvas(
+    request_model_dict: Dict[str, Any],
+    bedrock_runtime_client: BedrockRuntimeClient,
+) -> Dict[str, Any]:
+    """Invoke the Nova Canvas API with the given request.
+
+    Args:
+        request_model_dict: Dictionary representation of the request model.
+        bedrock_runtime_client: BedrockRuntimeClient object.
+
+    Returns:
+        Dictionary containing the API response.
+
+    Raises:
+        Exception: If the API call fails.
+    """
+    logger.debug('Invoking Nova Canvas API')
+
+    # Convert the request payload to JSON
+    request = json.dumps(request_model_dict)
+
+    try:
+        # Invoke the model
+        logger.info(f'Sending request to Nova Canvas model: {NOVA_CANVAS_MODEL_ID}')
+        response = bedrock_runtime_client.invoke_model(modelId=NOVA_CANVAS_MODEL_ID, body=request)
+
+        # Decode the response body
+        result = json.loads(response['body'].read())
+        logger.info('Nova Canvas API call successful')
+        return result
+    except Exception as e:
+        logger.error(f'Nova Canvas API call failed: {str(e)}')
+        raise
+
+
+async def generate_image_with_text(
+    prompt: str,
+    bedrock_runtime_client: BedrockRuntimeClient,
+    negative_prompt: Optional[str] = None,
+    filename: Optional[str] = None,
+    width: int = DEFAULT_WIDTH,
+    height: int = DEFAULT_HEIGHT,
+    quality: str = DEFAULT_QUALITY,
+    cfg_scale: float = DEFAULT_CFG_SCALE,
+    seed: Optional[int] = None,
+    number_of_images: int = DEFAULT_NUMBER_OF_IMAGES,
+    workspace_dir: Optional[str] = None,
+) -> ImageGenerationResponse:
+    """Generate an image using Amazon Nova Canvas with text prompt.
+
+    This function uses Amazon Nova Canvas to generate images based on a text prompt.
+    The generated image will be saved to a file and the path will be returned.
+
+    Args:
+        prompt: The text description of the image to generate (1-1024 characters).
+        bedrock_runtime_client: BedrockRuntimeClient object.
+        negative_prompt: Text to define what not to include in the image (1-1024 characters).
+        filename: The name of the file to save the image to (without extension).
+            If not provided, a random name will be generated.
+        width: The width of the generated image (320-4096, divisible by 16).
+        height: The height of the generated image (320-4096, divisible by 16).
+        quality: The quality of the generated image ("standard" or "premium").
+        cfg_scale: How strongly the image adheres to the prompt (1.1-10.0).
+        seed: Seed for generation (0-858,993,459). Random if not provided.
+        number_of_images: The number of images to generate (1-5).
+        workspace_dir: Directory where the images should be saved. If None, uses current directory.
+
+    Returns:
+        ImageGenerationResponse: An object containing the paths to the generated images,
+        PIL Image objects, and status information.
+    """
+    logger.debug(f"Generating text-to-image with prompt: '{prompt[:30]}...' ({width}x{height})")
+
+    try:
+        # Validate input parameters using Pydantic
+        try:
+            logger.debug('Validating parameters and creating request model')
+
+            # Create image generation config
+            config = ImageGenerationConfig(
+                width=width,
+                height=height,
+                quality=Quality.STANDARD if quality == DEFAULT_QUALITY else Quality.PREMIUM,
+                cfgScale=cfg_scale,
+                seed=seed if seed is not None else random.randint(0, 858993459),
+                numberOfImages=number_of_images,
+            )
+
+            # Create text-to-image params
+            # The Nova Canvas API doesn't accept null for negativeText
+            if negative_prompt is not None:
+                text_params = TextToImageParams(text=prompt, negativeText=negative_prompt)
+            else:
+                text_params = TextToImageParams(text=prompt)
+
+            # Create the full request
+            request_model = TextImageRequest(
+                textToImageParams=text_params, imageGenerationConfig=config
+            )
+
+            # Convert model to dictionary
+            request_model_dict = request_model.to_api_dict()
+            logger.info('Request validation successful')
+
+        except Exception as e:
+            logger.error(f'Parameter validation failed: {str(e)}')
+            return ImageGenerationResponse(
+                status='error',
+                message=f'Validation error: {str(e)}',
+                paths=[],
+                prompt=prompt,
+                negative_prompt=negative_prompt,
+            )
+
+        try:
+            # Invoke the Nova Canvas API
+            logger.debug('Sending request to Nova Canvas API')
+            model_response = await invoke_nova_canvas(request_model_dict, bedrock_runtime_client)
+
+            # Extract the image data
+            base64_images = model_response['images']
+            logger.info(f'Received {len(base64_images)} images from Nova Canvas API')
+
+            # Save the generated images
+            result = save_generated_images(
+                base64_images,
+                filename,
+                number_of_images,
+                prefix='nova_canvas',
+                workspace_dir=workspace_dir,
+            )
+
+            logger.info(f'Successfully generated {len(result["paths"])} image(s)')
+            return ImageGenerationResponse(
+                status='success',
+                message=f'Generated {len(result["paths"])} image(s)',
+                paths=result['paths'],
+                prompt=prompt,
+                negative_prompt=negative_prompt,
+            )
+        except Exception as e:
+            logger.error(f'Image generation failed: {str(e)}')
+            return ImageGenerationResponse(
+                status='error',
+                message=str(e),
+                paths=[],
+                prompt=prompt,
+                negative_prompt=negative_prompt,
+            )
+
+    except Exception as e:
+        logger.error(f'Unexpected error in generate_image_with_text: {str(e)}')
+        return ImageGenerationResponse(
+            status='error',
+            message=str(e),
+            paths=[],
+            prompt=prompt,
+            negative_prompt=negative_prompt,
+        )
+
+
+async def generate_image_with_colors(
+    prompt: str,
+    colors: List[str],
+    bedrock_runtime_client: BedrockRuntimeClient,
+    negative_prompt: Optional[str] = None,
+    filename: Optional[str] = None,
+    width: int = DEFAULT_WIDTH,
+    height: int = DEFAULT_HEIGHT,
+    quality: str = DEFAULT_QUALITY,
+    cfg_scale: float = DEFAULT_CFG_SCALE,
+    seed: Optional[int] = None,
+    number_of_images: int = DEFAULT_NUMBER_OF_IMAGES,
+    workspace_dir: Optional[str] = None,
+) -> ImageGenerationResponse:
+    """Generate an image using Amazon Nova Canvas with color guidance.
+
+    This function uses Amazon Nova Canvas to generate images based on a text prompt and color palette.
+    The generated image will be saved to a file and the path will be returned.
+
+    Args:
+        prompt: The text description of the image to generate (1-1024 characters).
+        colors: List of up to 10 hexadecimal color values (e.g., "#FF9800").
+        bedrock_runtime_client: BedrockRuntimeClient object.
+        negative_prompt: Text to define what not to include in the image (1-1024 characters).
+        filename: The name of the file to save the image to (without extension).
+            If not provided, a random name will be generated.
+        width: The width of the generated image (320-4096, divisible by 16).
+        height: The height of the generated image (320-4096, divisible by 16).
+        quality: The quality of the generated image ("standard" or "premium").
+        cfg_scale: How strongly the image adheres to the prompt (1.1-10.0).
+        seed: Seed for generation (0-858,993,459). Random if not provided.
+        number_of_images: The number of images to generate (1-5).
+        workspace_dir: Directory where the images should be saved. If None, uses current directory.
+
+    Returns:
+        ImageGenerationResponse: An object containing the paths to the generated images,
+        PIL Image objects, and status information.
+    """
+    logger.debug(
+        f"Generating color-guided image with prompt: '{prompt[:30]}...' and {len(colors)} colors"
+    )
+
+    try:
+        # Validate input parameters using Pydantic
+        try:
+            logger.debug('Validating parameters and creating color-guided request model')
+
+            # Create image generation config
+            config = ImageGenerationConfig(
+                width=width,
+                height=height,
+                quality=Quality.STANDARD if quality == DEFAULT_QUALITY else Quality.PREMIUM,
+                cfgScale=cfg_scale,
+                seed=seed if seed is not None else random.randint(0, 858993459),
+                numberOfImages=number_of_images,
+            )
+
+            # Create color-guided params
+            # The Nova Canvas API doesn't accept null for negativeText
+            if negative_prompt is not None:
+                color_params = ColorGuidedGenerationParams(
+                    colors=colors,
+                    text=prompt,
+                    negativeText=negative_prompt,
+                )
+            else:
+                color_params = ColorGuidedGenerationParams(
+                    colors=colors,
+                    text=prompt,
+                )
+
+            # Create the full request
+            request_model = ColorGuidedRequest(
+                colorGuidedGenerationParams=color_params, imageGenerationConfig=config
+            )
+
+            # Convert model to dictionary
+            request_model_dict = request_model.to_api_dict()
+            logger.info('Color-guided request validation successful')
+
+        except Exception as e:
+            logger.error(f'Color-guided parameter validation failed: {str(e)}')
+            return ImageGenerationResponse(
+                status='error',
+                message=f'Validation error: {str(e)}',
+                paths=[],
+                prompt=prompt,
+                negative_prompt=negative_prompt,
+                colors=colors,
+            )
+
+        try:
+            # Invoke the Nova Canvas API
+            logger.debug('Sending color-guided request to Nova Canvas API')
+            model_response = await invoke_nova_canvas(request_model_dict, bedrock_runtime_client)
+
+            # Extract the image data
+            base64_images = model_response['images']
+            logger.info(f'Received {len(base64_images)} images from Nova Canvas API')
+
+            # Save the generated images
+            result = save_generated_images(
+                base64_images,
+                filename,
+                number_of_images,
+                prefix='nova_canvas_color',
+                workspace_dir=workspace_dir,
+            )
+
+            logger.info(f'Successfully generated {len(result["paths"])} color-guided image(s)')
+            return ImageGenerationResponse(
+                status='success',
+                message=f'Generated {len(result["paths"])} image(s)',
+                paths=result['paths'],
+                prompt=prompt,
+                negative_prompt=negative_prompt,
+                colors=colors,
+            )
+        except Exception as e:
+            logger.error(f'Color-guided image generation failed: {str(e)}')
+            return ImageGenerationResponse(
+                status='error',
+                message=str(e),
+                paths=[],
+                prompt=prompt,
+                negative_prompt=negative_prompt,
+                colors=colors,
+            )
+
+    except Exception as e:
+        logger.error(f'Unexpected error in generate_image_with_colors: {str(e)}')
+        return ImageGenerationResponse(
+            status='error',
+            message=str(e),
+            paths=[],
+            prompt=prompt,
+            negative_prompt=negative_prompt,
+            colors=colors,
+        )

awslabs/nova_canvas_mcp_server/server.py

@@ -0,0 +1,324 @@
+"""Nova Canvas MCP Server implementation."""
+
+import argparse
+import boto3
+import os
+import sys
+from awslabs.nova_canvas_mcp_server.consts import (
+    DEFAULT_CFG_SCALE,
+    DEFAULT_HEIGHT,
+    DEFAULT_NUMBER_OF_IMAGES,
+    DEFAULT_QUALITY,
+    DEFAULT_WIDTH,
+    PROMPT_INSTRUCTIONS,
+)
+from awslabs.nova_canvas_mcp_server.models import McpImageGenerationResponse
+from awslabs.nova_canvas_mcp_server.novacanvas import (
+    generate_image_with_colors,
+    generate_image_with_text,
+)
+from loguru import logger
+from mcp.server.fastmcp import Context, FastMCP
+from pydantic import Field
+from typing import TYPE_CHECKING, List, Optional
+
+
+# Logging
+logger.remove()
+logger.add(sys.stderr, level=os.getenv('FASTMCP_LOG_LEVEL', 'WARNING'))
+
+# Bedrock Runtime Client typing
+if TYPE_CHECKING:
+    from mypy_boto3_bedrock_runtime import BedrockRuntimeClient
+else:
+    BedrockRuntimeClient = object
+
+
+# Bedrock Runtime Client
+bedrock_runtime_client: BedrockRuntimeClient
+aws_region: str = os.environ.get('AWS_REGION', 'us-east-1')
+
+try:
+    if aws_profile := os.environ.get('AWS_PROFILE'):
+        bedrock_runtime_client = boto3.Session(
+            profile_name=aws_profile, region_name=aws_region
+        ).client('bedrock-runtime')
+    else:
+        bedrock_runtime_client = boto3.Session(region_name=aws_region).client('bedrock-runtime')
+except Exception as e:
+    logger.error(f'Error creating bedrock runtime client: {str(e)}')
+    raise
+
+
+# Create the MCP server Pwith detailed instructions
+mcp = FastMCP(
+    'awslabs-nova-canvas-mcp-server',
+    instructions=f"""
+# Amazon Nova Canvas Image Generation
+
+This MCP server provides tools for generating images using Amazon Nova Canvas through Amazon Bedrock.
+
+## Available Tools
+
+### generate_image
+Generate an image from a text prompt using Amazon Nova Canvas.
+
+### generate_image_with_colors
+Generate an image from a text prompt and color palette using Amazon Nova Canvas.
+
+## Prompt Best Practices
+
+{PROMPT_INSTRUCTIONS}
+""",
+    dependencies=[
+        'pydantic',
+        'boto3',
+    ],
+)
+
+
+@mcp.tool(name='generate_image')
+async def mcp_generate_image(
+    ctx: Context,
+    prompt: str = Field(
+        description='The text description of the image to generate (1-1024 characters)'
+    ),
+    negative_prompt: Optional[str] = Field(
+        default=None,
+        description='Text to define what not to include in the image (1-1024 characters)',
+    ),
+    filename: Optional[str] = Field(
+        default=None, description='The name of the file to save the image to (without extension)'
+    ),
+    width: int = Field(
+        default=DEFAULT_WIDTH,
+        description='The width of the generated image (320-4096, divisible by 16)',
+    ),
+    height: int = Field(
+        default=DEFAULT_HEIGHT,
+        description='The height of the generated image (320-4096, divisible by 16)',
+    ),
+    quality: str = Field(
+        default=DEFAULT_QUALITY,
+        description='The quality of the generated image ("standard" or "premium")',
+    ),
+    cfg_scale: float = Field(
+        default=DEFAULT_CFG_SCALE,
+        description='How strongly the image adheres to the prompt (1.1-10.0)',
+    ),
+    seed: Optional[int] = Field(default=None, description='Seed for generation (0-858,993,459)'),
+    number_of_images: int = Field(
+        default=DEFAULT_NUMBER_OF_IMAGES, description='The number of images to generate (1-5)'
+    ),
+    workspace_dir: Optional[str] = Field(
+        default=None,
+        description="""The current workspace directory where the image should be saved.
+        CRITICAL: Assistant must always provide the current IDE workspace directory parameter to save images to the user's current project.""",
+    ),
+) -> McpImageGenerationResponse:
+    """Generate an image using Amazon Nova Canvas with text prompt.
+
+    This tool uses Amazon Nova Canvas to generate images based on a text prompt.
+    The generated image will be saved to a file and the path will be returned.
+
+    IMPORTANT FOR ASSISTANT: Always send the current workspace directory when calling this tool!
+    The workspace_dir parameter should be set to the directory where the user is currently working
+    so that images are saved to a location accessible to the user.
+
+    ## Prompt Best Practices
+
+    An effective prompt often includes short descriptions of:
+    1. The subject
+    2. The environment
+    3. (optional) The position or pose of the subject
+    4. (optional) Lighting description
+    5. (optional) Camera position/framing
+    6. (optional) The visual style or medium ("photo", "illustration", "painting", etc.)
+
+    Do not use negation words like "no", "not", "without" in your prompt. Instead, use the
+    negative_prompt parameter to specify what you don't want in the image.
+
+    You should always include "people, anatomy, hands, low quality, low resolution, low detail" in your negative_prompt
+
+    ## Example Prompts
+
+    - "realistic editorial photo of female teacher standing at a blackboard with a warm smile"
+    - "whimsical and ethereal soft-shaded story illustration: A woman in a large hat stands at the ship's railing looking out across the ocean"
+    - "drone view of a dark river winding through a stark Iceland landscape, cinematic quality"
+
+    Returns:
+        McpImageGenerationResponse: A response containing the generated image paths.
+    """
+    logger.debug(
+        f"MCP tool generate_image called with prompt: '{prompt[:30]}...', dims: {width}x{height}"
+    )
+
+    try:
+        logger.info(
+            f'Generating image with text prompt, quality: {quality}, cfg_scale: {cfg_scale}'
+        )
+        response = await generate_image_with_text(
+            prompt=prompt,
+            bedrock_runtime_client=bedrock_runtime_client,
+            negative_prompt=negative_prompt,
+            filename=filename,
+            width=width,
+            height=height,
+            quality=quality,
+            cfg_scale=cfg_scale,
+            seed=seed,
+            number_of_images=number_of_images,
+            workspace_dir=workspace_dir,
+        )
+
+        if response.status == 'success':
+            # return response.paths
+            return McpImageGenerationResponse(
+                status='success',
+                paths=[f'file://{path}' for path in response.paths],
+            )
+        else:
+            logger.error(f'Image generation returned error status: {response.message}')
+            await ctx.error(f'Failed to generate image: {response.message}')  # type: ignore
+            # Return empty image or raise exception based on requirements
+            raise Exception(f'Failed to generate image: {response.message}')
+    except Exception as e:
+        logger.error(f'Error in mcp_generate_image: {str(e)}')
+        await ctx.error(f'Error generating image: {str(e)}')  # type: ignore
+        raise
+
+
+@mcp.tool(name='generate_image_with_colors')
+async def mcp_generate_image_with_colors(
+    ctx: Context,
+    prompt: str = Field(
+        description='The text description of the image to generate (1-1024 characters)'
+    ),
+    colors: List[str] = Field(
+        description='List of up to 10 hexadecimal color values (e.g., "#FF9800")'
+    ),
+    negative_prompt: Optional[str] = Field(
+        default=None,
+        description='Text to define what not to include in the image (1-1024 characters)',
+    ),
+    filename: Optional[str] = Field(
+        default=None, description='The name of the file to save the image to (without extension)'
+    ),
+    width: int = Field(
+        default=1024, description='The width of the generated image (320-4096, divisible by 16)'
+    ),
+    height: int = Field(
+        default=1024, description='The height of the generated image (320-4096, divisible by 16)'
+    ),
+    quality: str = Field(
+        default='standard',
+        description='The quality of the generated image ("standard" or "premium")',
+    ),
+    cfg_scale: float = Field(
+        default=6.5, description='How strongly the image adheres to the prompt (1.1-10.0)'
+    ),
+    seed: Optional[int] = Field(default=None, description='Seed for generation (0-858,993,459)'),
+    number_of_images: int = Field(default=1, description='The number of images to generate (1-5)'),
+    workspace_dir: Optional[str] = Field(
+        default=None,
+        description="The current workspace directory where the image should be saved. CRITICAL: Assistant must always provide this parameter to save images to the user's current project.",
+    ),
+) -> McpImageGenerationResponse:
+    """Generate an image using Amazon Nova Canvas with color guidance.
+
+    This tool uses Amazon Nova Canvas to generate images based on a text prompt and color palette.
+    The generated image will be saved to a file and the path will be returned.
+
+    IMPORTANT FOR Assistant: Always send the current workspace directory when calling this tool!
+    The workspace_dir parameter should be set to the directory where the user is currently working
+    so that images are saved to a location accessible to the user.
+
+    ## Prompt Best Practices
+
+    An effective prompt often includes short descriptions of:
+    1. The subject
+    2. The environment
+    3. (optional) The position or pose of the subject
+    4. (optional) Lighting description
+    5. (optional) Camera position/framing
+    6. (optional) The visual style or medium ("photo", "illustration", "painting", etc.)
+
+    Do not use negation words like "no", "not", "without" in your prompt. Instead, use the
+    negative_prompt parameter to specify what you don't want in the image.
+
+    ## Example Colors
+
+    - ["#FF5733", "#33FF57", "#3357FF"] - A vibrant color scheme with red, green, and blue
+    - ["#000000", "#FFFFFF"] - A high contrast black and white scheme
+    - ["#FFD700", "#B87333"] - A gold and bronze color scheme
+
+    Returns:
+        McpImageGenerationResponse: A response containing the generated image paths.
+    """
+    logger.debug(
+        f"MCP tool generate_image_with_colors called with prompt: '{prompt[:30]}...', {len(colors)} colors"
+    )
+
+    try:
+        color_hex_list = ', '.join(colors[:3]) + (', ...' if len(colors) > 3 else '')
+        logger.info(
+            f'Generating color-guided image with colors: [{color_hex_list}], quality: {quality}'
+        )
+
+        response = await generate_image_with_colors(
+            prompt=prompt,
+            colors=colors,
+            bedrock_runtime_client=bedrock_runtime_client,
+            negative_prompt=negative_prompt,
+            filename=filename,
+            width=width,
+            height=height,
+            quality=quality,
+            cfg_scale=cfg_scale,
+            seed=seed,
+            number_of_images=number_of_images,
+            workspace_dir=workspace_dir,
+        )
+
+        if response.status == 'success':
+            return McpImageGenerationResponse(
+                status='success',
+                paths=[f'file://{path}' for path in response.paths],
+            )
+        else:
+            logger.error(
+                f'Color-guided image generation returned error status: {response.message}'
+            )
+            await ctx.error(f'Failed to generate color-guided image: {response.message}')
+            raise Exception(f'Failed to generate color-guided image: {response.message}')
+    except Exception as e:
+        logger.error(f'Error in mcp_generate_image_with_colors: {str(e)}')
+        await ctx.error(f'Error generating color-guided image: {str(e)}')
+        raise
+
+
+def main():
+    """Run the MCP server with CLI argument support."""
+    logger.info('Starting nova-canvas-mcp-server MCP server')
+
+    parser = argparse.ArgumentParser(
+        description='MCP server for generating images using Amazon Nova Canvas'
+    )
+    parser.add_argument('--sse', action='store_true', help='Use SSE transport')
+    parser.add_argument('--port', type=int, default=8888, help='Port to run the server on')
+
+    args = parser.parse_args()
+    logger.debug(f'Parsed arguments: sse={args.sse}, port={args.port}')
+
+    # Run server with appropriate transport
+    if args.sse:
+        logger.info(f'Using SSE transport on port {args.port}')
+        mcp.settings.port = args.port
+        mcp.run(transport='sse')
+    else:
+        logger.info('Using standard stdio transport')
+        mcp.run()
+
+
+if __name__ == '__main__':
+    main()

awslabs_nova_canvas_mcp_server-0.1.10233.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: awslabs.nova-canvas-mcp-server
+Version: 0.1.10233
+Summary: An AWS Labs Model Context Protocol (MCP) server for Amazon Nova Canvas
+Requires-Python: >=3.13
+Requires-Dist: boto3>=1.37.24
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: mcp[cli]>=1.6.0
+Requires-Dist: pydantic>=2.11.1
+Description-Content-Type: text/markdown
+
+# awslabs MCP Nova Canvas Server
+
+MCP server for generating images using Amazon Nova Canvas
+
+## Features
+
+- **Text-based image generation** - Create images from text prompts with `generate_image`
+  - Customizable dimensions (320-4096px), quality options, and negative prompting
+  - Supports multiple image generation (1-5) in single request
+  - Adjustable parameters like cfg_scale (1.1-10.0) and seeded generation
+
+- **Color-guided image generation** - Generate images with specific color palettes using `generate_image_with_colors`
+  - Define up to 10 hex color values to influence the image style and mood
+  - Same customization options as text-based generation
+
+- **Workspace integration** - Images saved to user-specified workspace directories with automatic folder creation
+
+- **AWS authentication** - Uses AWS profiles for secure access to Amazon Nova Canvas services
+
+## Prerequisites
+
+1. Install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/) or the [GitHub README](https://github.com/astral-sh/uv#installation)
+2. Install Python using `uv python install 3.13`
+3. Set up AWS credentials with access to Amazon Bedrock and Nova Canvas
+   - You need an AWS account with Amazon Bedrock and Amazon Nova Canvas enabled
+   - Configure AWS credentials with `aws configure` or environment variables
+   - Ensure your IAM role/user has permissions to use Amazon Bedrock and Nova Canvas
+
+## Installation
+
+Install the MCP server:
+
+Add the server to your MCP client config (e.g. for Amazon Q CLI MCP, `~/.aws/amazonq/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "awslabs.nova-canvas-mcp-server": {
+      "command": "uvx",
+      "args": ["awslabs.nova-canvas-mcp-server@latest"],
+      "env": {
+        "AWS_PROFILE": "your-aws-profile",  // Optional: specify AWS profile
+        "AWS_REGION": "us-east-1"           // Required: region where Bedrock is available
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+### AWS Authentication
+
+The MCP server uses the AWS profile specified in the `AWS_PROFILE` environment variable. If not provided, it defaults to the "default" profile in your AWS configuration file.
+
+```json
+"env": {
+  "AWS_PROFILE": "your-aws-profile",  // Specify which AWS profile to use
+  "AWS_REGION": "us-east-1"           // Region where Bedrock is available
+}
+```
+
+Make sure the AWS profile has permissions to access Amazon Bedrock and Amazon Nova Canvas. The MCP server creates a boto3 session using the specified profile to authenticate with AWS services. Your AWS IAM credentials remain on your local machine and are strictly used for using the Amazon Bedrock model APIs.

awslabs_nova_canvas_mcp_server-0.1.10233.dist-info/RECORD

@@ -0,0 +1,10 @@
+awslabs/__init__.py,sha256=4zfFn3N0BkvQmMTAIvV_QAbKp6GWzrwaUN17YeRoChM,115
+awslabs/nova_canvas_mcp_server/__init__.py,sha256=D1JLDjoqRWgJm28RaKjBtIzAsuc31Ilg8r5-hv8I0ZU,60
+awslabs/nova_canvas_mcp_server/consts.py,sha256=1qnIsWXKsg7R8JpWalgns0vPmBAHu6f9oI8hylhBuuo,2590
+awslabs/nova_canvas_mcp_server/models.py,sha256=tYJeeTKhU_6OJxKJBvKyAzgC46-Dexx_o5up539jqi4,9935
+awslabs/nova_canvas_mcp_server/novacanvas.py,sha256=ltHqnH5slEfq52jF69xE59pam1pEXmIRaGYnWFtfC04,15017
+awslabs/nova_canvas_mcp_server/server.py,sha256=pZBwGwOU_3CoSfi9PHnfBmqI7g6cYqRGCTeF3Fg-sIk,12272
+awslabs_nova_canvas_mcp_server-0.1.10233.dist-info/METADATA,sha256=QsFHmvWwYAiuaPC3UNzBKI_6nJ0C0cjNT50KgDHmB-4,2989
+awslabs_nova_canvas_mcp_server-0.1.10233.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+awslabs_nova_canvas_mcp_server-0.1.10233.dist-info/entry_points.txt,sha256=v8V4vn8YuugOSL7w_sUxz-M0EDZNZU2_ydJZDd31pGI,94
+awslabs_nova_canvas_mcp_server-0.1.10233.dist-info/RECORD,,

awslabs_nova_canvas_mcp_server-0.1.10233.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

awslabs_nova_canvas_mcp_server-0.1.10233.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+awslabs.nova-canvas-mcp-server = awslabs.nova_canvas_mcp_server.server:main