awslabs.nova-canvas-mcp-server 0.1.10233__tar.gz

awslabs_nova_canvas_mcp_server-0.1.10233/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+
+# Ruff
+.ruff_cache/
+
+# Build
+*.manifest
+*.spec
+.pybuilder/
+target/
+
+# Environments
+.env
+.env.local
+.env.*.local
+
+# PyPI
+.pypirc

awslabs_nova_canvas_mcp_server-0.1.10233/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v3.13.0
+    hooks:
+      - id: commitizen
+      - id: commitizen-branch
+        stages: [push]

awslabs_nova_canvas_mcp_server-0.1.10233/.python-version

@@ -0,0 +1 @@
+3.13

awslabs_nova_canvas_mcp_server-0.1.10233/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v0.1.6 (2025-03-30)
+
+### Fix
+
+- update __version__ format to remove v prefix
+
+## v0.1.5 (2025-03-30)
+
+### Fix
+
+- __version__
+
+## v0.1.4 (2025-03-30)
+
+### Fix
+
+- __version__
+
+## v0.1.3 (2025-03-30)
+
+### Fix
+
+- pyproject.toml
+
+## v0.1.2 (2025-03-30)
+
+### Fix
+
+- uv package
+- release
+
+## v0.1.1 (2025-03-30)
+
+### Fix
+
+- release
+
+## v0.1.0 (2025-03-30)
+
+### Feat
+
+- MCP server for generating images with Amazon Nova Canvas
+- **doc**: material mkdocs (#5)
+- **doc**: initial documentation (#4)
+- **security**: add CODEOWNERS (#2)
+- **cicd**: add github workflows (#1)
+
+### Fix
+
+- pyright errors on  overrides
+- optional fields

awslabs_nova_canvas_mcp_server-0.1.10233/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,63 @@
+# 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/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-0.1.10233/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-0.1.10233/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-0.1.10233/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")