@apresai/gimage-mcp 1.2.63 → 1.2.65

package/bin/CHANGELOG.md

@@ -0,0 +1,374 @@
+# 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).
+
+## [Unreleased]
+
+(empty - ready for next release)
+
+## [1.2.63] - 2025-11-06
+
+### Changed
+
+- **Generate command**: Now accepts positional prompt argument (`gimage generate "sunset"`) in addition to flag-based prompt (`--prompt`) for improved UX
+- **Auth commands**: Refactored into modular structure with new dedicated `auth status` command providing detailed credential information
+- **CLI verbose output**: Improved formatting and consistency across all image processing commands (resize, crop, scale, compress, convert)
+- **Configuration**: Streamlined config management, removing legacy config command in favor of auth commands
+- **Documentation**: Comprehensive overhaul of README.md, COMMANDS.md, CLAUDE.md, and MCP_USAGE.md with clearer examples and better organization
+- **Integration tests**: Updated CLI E2E tests to use new positional prompt syntax
+
+### Removed
+
+- **Batch CLI commands**: Removed `gimage batch` command (batch operations now exclusively through MCP server)
+- **TUI batch menu**: Removed batch processing UI from TUI (use MCP server batch tools instead)
+- **Batch history tracking**: Removed history persistence system (`internal/batch/history.go` and tests)
+- **Documentation files**: Removed 12 planning/implementation docs (DESIGN.md, IMPLEMENTATION_SUMMARY.md, PRODUCTION_QUALITY_FIXES.md, TUI_FEATURE_TOUR.md, TUI_IMPLEMENTATION_SUMMARY.md, TESTING.md, lambda.md, tui.md, npm/README.md, test/integration/README.md, internal/generate/README.md, INTEGRATION_GUIDE.md) - ~14,000 lines total
+- **Config command**: Removed legacy `gimage config` subcommand
+
+
+## [1.2.61] - 2025-11-05
+
+### Changed
+- 
+
+
+## [1.2.60] - 2025-11-05
+
+### Added
+- Imagen 3 models support (`imagen-3.0-generate-001`, `imagen-3.0-generate-002`, `imagen-3.0-fast-generate-001`)
+- Model alias `imagen-3` for latest Imagen 3 model
+- Enhanced MCP end-to-end test coverage with model metadata validation
+
+### Changed
+- Updated model registry with comprehensive Imagen 3 and Imagen 4 model definitions
+- Improved provider auto-detection logic to handle both Imagen 3 and Imagen 4 models
+- Streamlined `models_test.go` using table-driven tests (197 → 151 lines)
+
+### Fixed
+- Resolved logger deadlock in auth commands by deferring stdout restoration
+- Fixed test suite reliability issues in model registry tests
+
+
+## [1.2.58] - 2025-11-05
+
+### Added
+- **Provider System**: New architecture for AI backends with clean abstraction layer for Gemini, Vertex AI, and AWS Bedrock
+- **Model Registry**: Centralized system for model management and auto-detection
+- **Enhanced Auth Commands**: 
+  - `auth list` - Display all configured credentials and their status
+  - `auth setup` - Interactive setup wizard for configuring providers
+  - `auth test` - Validate credentials and test API connectivity
+- **Design Documentation**: Added `DESIGN.md` documenting provider architecture and patterns
+
+### Changed
+- **Major Refactor**: Migrated from monolithic `models.go` (643 lines) to modular `providers.go` (565 lines) with cleaner separation
+- **Auth Command Structure**: Reorganized authentication commands with new subcommands for better UX
+- **Generate Command**: Enhanced with improved provider selection logic and better error handling
+- **MCP Server**: Updated tools and prompts to work with new provider system
+- **Logging**: Improved context and verbosity handling across components
+
+### Removed
+- **Legacy Code**: Removed old model management system (`internal/generate/models.go` and tests)
+- **Test Files**: Cleaned up automated TUI tests (`automated_test.go`, `debug_test.go`)
+
+
+## [1.1.54] - 2025-11-05
+
+### Fixed
+- TUI image generation now works correctly by switching from SDK to REST client for API calls
+- Enhanced TUI generation flow with improved error handling and progress feedback
+
+### Added
+- Comprehensive logging system for debugging TUI operations
+- Automated testing suite for TUI image generation workflows
+- Debug mode support with detailed operation logging
+- Progress indicators and status messages during image generation
+
+### Changed
+- Refactored TUI generation flow to use REST client instead of SDK for better reliability
+- Improved TUI styles and visual feedback during operations
+
+
+## [1.1.52] - 2025-11-05
+
+### Added
+- macOS keyboard shortcuts for improved navigation
+- Settings navigation menu for easier configuration access
+- Editable API keys in settings interface
+
+### Changed
+- Enhanced error handling in generate flow
+- Improved settings menu UI and functionality
+
+
+## [1.1.50] - 2025-11-05
+
+### Changed
+- Updated Go dependencies to resolve test compatibility issues
+
+
+## [1.1.48] - 2025-11-05
+
+### Fixed
+
+- Add context.Context parameter to test function calls for proper context handling in image processing tests
+
+
+## [1.1.46] - 2025-11-05
+
+```markdown
+## [Unreleased]
+
+### Added
+- Interactive TUI (Terminal User Interface) with main menu, batch processing, generation flow, and settings management
+- Batch operation history tracking with persistent storage
+- Progress reporter for real-time operation feedback
+- Production quality test suite with comprehensive integration tests
+- Image compression operation with quality control
+- TUI documentation and feature tour
+- Test fixtures (small_test.png, test_image.png, test_image_512x512.png)
+
+### Changed
+- Simplified CLI command outputs for better TUI integration
+- Improved image processing operations (resize, scale, crop, convert) with enhanced error handling
+- Streamlined documentation: consolidated guides into concise references
+- Reduced project documentation by 56% (removed planning and implementation tracking docs)
+- Updated lambda.md from 1,385 to 272 lines (removed CDK code, kept deployment guide)
+- Updated INTEGRATION_GUIDE.md to focus on crisp examples only
+
+### Removed
+- Project planning documents (RELEASING.md, roadmap.md, HOMEBREW.md)
+- Implementation tracking docs (DEPLOYMENT_CHECKLIST.md, LAMBDA_STATUS.md)
+- Research/analysis docs (MCP_LLM_LEARNING_ANALYSIS.md, AI_TOOL_CALLING_IMPROVEMENTS.md, AWS_BEDROCK_SDK_GUIDE.md, etc.)
+- Redundant documentation (API_REFERENCE.md, SWAGGER_SETUP.md, RELEASE_NOTES.md, etc.)
+```
+
+
+## [1.1.43] - 2025-11-02
+
+### Added
+
+- MCP Prompts feature: New prompt templates for image generation, batch processing, and common workflows
+- MCP server now exposes 13 prompt templates via the prompts/list capability
+- Comprehensive documentation for MCP Prompts design and implementation (MCP_PROMPTS_DESIGN.md, MCP_PROMPTS_IMPLEMENTATION.md)
+- Analysis documentation for LLM learning patterns with MCP (MCP_LLM_LEARNING_ANALYSIS.md)
+
+### Changed
+
+- Enhanced MCP tool descriptions with more actionable guidance for LLM clients
+- Improved MCP handler with prompt list and get capabilities
+- Updated MCP server to register prompt templates on initialization
+
+
+## [1.1.41] - 2025-11-02
+
+### Changed
+- 
+
+
+## [1.1.40] - 2025-11-02
+
+### Changed
+- Build number incremented to 1.1.40 (automatic versioning from git commit count)
+
+
+## [1.1.38] - 2025-11-02
+
+### Changed
+- Upgraded GoReleaser configuration to v2 format for improved build and release automation
+
+
+## [1.1.36] - 2025-11-02
+
+### Changed
+- Build number incremented to 1.1.36 (automatic versioning from git commit count)
+
+
+## [1.1.34] - 2025-11-02
+
+### Changed
+- 
+
+
+## [1.1.33] - 2025-11-02
+
+### Changed
+- Updated .gitignore patterns for improved exclusion rules
+
+
+## [1.1.32] - 2025-11-02
+
+### Added
+
+- AWS Bedrock Nova Canvas integration with dual implementation modes (REST and SDK)
+- AWS Bedrock authentication setup via `gimage auth bedrock` command
+- Nova Canvas model support (`amazon.nova-canvas-v1:0`) with quality presets (standard/premium)
+- Advanced generation controls: negative prompts, CFG scale, seed, and quality settings
+- Comprehensive AWS Bedrock documentation (SDK guide, quickstart, onboarding guide)
+- Testing infrastructure with coverage reporting tools (`cmd/coverage-report`, `cmd/test-report`, `cmd/test-summary`)
+- Extensive test suites for Bedrock REST and SDK clients (382+ and 305+ test cases respectively)
+- MCP tools test coverage (batch, convert, generate operations)
+- End-to-end integration tests for CLI and generation workflows
+- Testing best practices documentation (TESTING.md)
+- Model onboarding guide (MODEL_ONBOARDING.md) for adding new backends
+- Documentation index (DOCUMENTATION_INDEX.md) for centralized reference
+- Coverage report scripts with detailed HTML output
+
+### Changed
+
+- Updated CLAUDE.md with multi-backend architecture guidance and AWS Bedrock sections
+- Enhanced `gimage generate` command with AWS-specific flags (quality, seed, CFG scale, negative prompts)
+- Expanded configuration system to support AWS credentials and region settings
+- Updated README.md with AWS Bedrock usage examples
+- Improved MCP_TOOLS.md with Bedrock integration examples
+- Enhanced Makefile with test coverage and reporting targets
+- Refactored generate models to support backend-specific options
+- Updated auth.go with Bedrock credential management (REST and SDK modes)
+
+### Fixed
+
+- Image scaling operations with improved precision
+- Crop and scale CLI commands with better error handling
+
+
+## [1.1.29] - 2025-11-02
+
+### Changed
+- 
+
+
+## [1.1.28] - 2025-11-02
+
+### Changed
+- 
+
+
+## [1.1.27] - 2025-11-02
+
+### Changed
+- 
+
+
+## [1.1.26] - 2025-11-02
+
+### Removed
+- Removed MCP tool tests (convert_test.go, generate_test.go, models_test.go) that were incompatible with current implementation
+
+
+## [1.1.23] - 2025-11-02
+
+### Added
+- Comprehensive model pricing and announcement system with cost tracking and latest model information
+- Unit tests for generate command with coverage for both Gemini and Vertex AI backends
+- Unit tests for convert operation with format conversion validation
+- Unit tests for resize operation with comprehensive dimension and format testing
+- Unit tests for crop operation with boundary and validation testing
+- Automated changelog update script for release process
+
+### Changed
+- Enhanced generate command with model pricing display and cost estimation
+- Improved MCP server with model information and pricing details
+- Updated RELEASING.md with streamlined release workflow and automation improvements
+- Refactored Makefile with improved test coverage reporting and build targets
+
+
+## [1.1.19] - 2025-11-02
+
+### Changed
+- Build number incremented to 1.1.19 (automatic versioning from git commit count)
+
+
+## [1.1.18] - 2025-11-01
+
+### Changed
+- Build number incremented to 1.1.18 (automatic versioning from git commit count)
+
+
+## [1.1.9] - 2025-11-01
+
+### Added
+- **Automated version synchronization** between CLI and npm package
+- **Build number versioning** using git commit count (format: 1.1.[build])
+- WebP support via nativewebp library (pure Go, zero C dependencies)
+- CLI `convert` command for format conversion
+- Comprehensive integration tests for WebP
+- End-to-end tests for all 10 MCP tools
+- Help text displayed when running `gimage` with no arguments
+- Complete release automation with GoReleaser
+- GitHub Actions workflows for CI and releases
+- npm package for MCP server distribution
+- Homebrew tap for macOS/Linux distribution
+- Comprehensive RELEASING.md guide
+- `make version` and `make sync-version` commands
+
+### Changed
+- **Version numbering scheme** to 1.1.[commit_count] for automatic sync
+- Root command now shows help instead of crashing when run without arguments
+- All MCP tools now support WebP output format
+- Homebrew tap repository renamed to `homebrew-tap` (conventional naming)
+- Documentation updated for new distribution methods
+
+### Fixed
+- Root command exit behavior
+- WebP encoding in all contexts (CLI, MCP server, programmatic usage)
+- Version synchronization between CLI binary and npm package
+
+## [0.1.1] - 2025-11-01
+
+### Added
+- Automatic format conversion based on output file extension
+  - Specify `-o output.jpg` to save as JPEG
+  - Specify `-o output.png` to save as PNG
+  - Specify `-o output.gif` to save as GIF
+  - Specify `-o output.bmp` to save as BMP
+  - Specify `-o output.tiff` to save as TIFF
+- Intelligent transparency handling (converts transparent areas to white when saving to formats that don't support transparency)
+- Format normalization (automatically handles .jpg vs .jpeg, .tif vs .tiff)
+
+### Changed
+- SaveImage now automatically converts image format based on file extension
+
+## [0.1.0] - 2025-11-01
+
+### Added
+- Initial release of gimage CLI tool
+- AI-powered image generation using Google Gemini 2.5 Flash Image
+- AI-powered image generation using Vertex AI Imagen 4
+- Image processing operations:
+  - Resize: Change image dimensions
+  - Scale: Scale by percentage
+  - Crop: Extract specific regions
+  - Compress: Reduce file size
+- Batch processing with concurrent operations
+- MCP server for Claude integration
+- Support for multiple image formats: PNG, JPG, WebP, GIF, TIFF, BMP
+- Pure Go implementation with zero C dependencies
+- Cross-platform support (Linux, macOS, Windows, ARM)
+- Interactive authentication setup:
+  - `gimage auth gemini` - Gemini API key setup
+  - `gimage auth vertex` - Vertex AI setup (Express Mode or Full Mode)
+- Smart credential detection - auto-selects API based on available credentials
+- Configuration system with markdown-based config file (~/.gimage/config.md)
+- Comprehensive CLI with Cobra framework
+
+### Features
+- Text-to-image generation with customizable prompts
+- Multiple generation styles: photorealistic, artistic, anime
+- Configurable image sizes and aspect ratios
+- Negative prompts for image generation
+- Seed support for reproducible results
+- Verbose mode for debugging
+- Model listing and auto-detection
+- Express Mode for Vertex AI (API key authentication)
+- Full Mode for Vertex AI (service account authentication)
+
+### Technical
+- Built with Go 1.22+
+- Uses disintegration/imaging library for image processing
+- Gemini API integration via REST
+- Vertex AI integration via REST (Express Mode) and SDK (Full Mode)
+- Concurrent batch processing with worker pools
+- Comprehensive error handling and validation

package/bin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chad Masso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/README.md

@@ -0,0 +1,825 @@
+# Gimage - AI-Powered Image Generation and Processing
+
+**Gimage** is a powerful tool for generating AI images and processing them with ease. Built with pure Go for maximum portability.
+
+## 🚀 Three Ways to Use Gimage
+
+### 1. Command-Line Tool (CLI)
+A single binary with zero dependencies for local image operations on your computer.
+
+### 2. MCP Server for AI Assistants
+Run as an MCP (Model Context Protocol) server for seamless integration with Claude Desktop and other AI assistants.
+
+### 3. Cloud API (AWS Lambda)
+Production-ready serverless REST API for web applications and remote processing.
+
+## What Can You Do with Gimage?
+
+### 🎨 AI Image Generation
+- Generate stunning images from text prompts using Google Gemini, Vertex AI, or AWS Bedrock
+- Multiple AI models: Gemini 2.5 Flash, Imagen 3, Imagen 4, Nova Canvas
+- Control size, style, quality, and use negative prompts
+- Reproducible results with seed values
+
+### 🛠️ Image Processing
+- **Resize** - Change image dimensions with high-quality resampling
+- **Scale** - Scale images by factor (2x, 0.5x, etc.)
+- **Crop** - Extract specific regions from images
+- **Compress** - Reduce file size while maintaining quality
+- **Convert** - Transform between formats (PNG, JPG, WebP, GIF, TIFF, BMP)
+
+### ⚡ Batch Processing (MCP Server Only)
+- Process multiple images concurrently via MCP server
+- Optimized for AI assistants (Claude Desktop)
+- CLI users: use shell scripts or `find` + `xargs`
+
+### 🔌 Integration Options
+- **Claude Desktop**: Run as MCP server
+- **Web Applications**: REST API via AWS Lambda
+- **Serverless**: AWS Lambda on ARM64/Graviton2
+
+## Quick Start - CLI
+
+### 1. Installation
+
+#### Homebrew (macOS/Linux) - Recommended
+
+```bash
+# Install gimage (tap is added automatically)
+brew install apresai/tap/gimage
+```
+
+#### Upgrade via Homebrew
+
+```bash
+brew upgrade apresai/tap/gimage
+```
+
+#### Manual Installation
+
+Download the latest release for your platform:
+
+```bash
+# macOS (Intel)
+curl -L https://github.com/apresai/gimage/releases/latest/download/gimage-darwin-amd64 -o gimage
+chmod +x gimage
+sudo mv gimage /usr/local/bin/
+
+# macOS (Apple Silicon)
+curl -L https://github.com/apresai/gimage/releases/latest/download/gimage-darwin-arm64 -o gimage
+chmod +x gimage
+sudo mv gimage /usr/local/bin/
+
+# Linux
+curl -L https://github.com/apresai/gimage/releases/latest/download/gimage-linux-amd64 -o gimage
+chmod +x gimage
+sudo mv gimage /usr/local/bin/
+```
+
+### 2. Setup Authentication
+
+**Quick Start** (recommended for most users):
+
+```bash
+# Get a free Gemini API key from https://aistudio.google.com/app/apikey
+# Then run the interactive setup:
+gimage auth setup gemini
+
+# Or use environment variable (more secure):
+export GEMINI_API_KEY="your-api-key-here"
+gimage generate "test sunset"
+```
+
+**Check your configuration:**
+
+```bash
+# Check current authentication status
+gimage auth status
+
+# List all configured providers with pricing
+gimage auth list
+
+# Test your credentials
+gimage auth test gemini
+```
+
+**Get API Keys:**
+- **Gemini API**: https://aistudio.google.com/app/apikey (FREE tier: 1500 requests/day, no credit card)
+- **Vertex AI**: https://cloud.google.com/vertex-ai (3 auth modes: Express Mode/Service Account/Application Default Credentials)
+- **AWS Bedrock**: https://console.aws.amazon.com/bedrock (4 auth modes: Bearer Token/Access Keys/Profile/IAM Role)
+
+### 3. Generate Your First Image
+
+```bash
+gimage generate "a sunset over mountains with vibrant colors"
+```
+
+That's it! Your image will be saved as `generated_<timestamp>.png`
+
+## Examples
+
+### Image Generation
+
+```bash
+# Basic generation (positional prompt - most common)
+gimage generate "futuristic city at night"
+
+# Specify size and style
+gimage generate "abstract art" --size 1024x1024 --style photorealistic
+
+# Use Vertex AI Imagen 4 (auto-detects vertex API)
+gimage generate "beautiful landscape" --model imagen-4
+
+# Use AWS Bedrock Nova Canvas with premium quality
+gimage generate "futuristic robot" --model nova-canvas --quality premium
+
+# Use negative prompts to avoid unwanted elements
+gimage generate "forest scene" --negative "people, buildings"
+
+# Reproducible results with seed
+gimage generate "random pattern" --seed 12345
+
+# Control creativity with CFG scale (Nova Canvas)
+gimage generate "abstract art" --model nova-canvas --cfg-scale 10
+
+# List all available models with pricing
+gimage generate --list-models
+
+# Or use explicit --prompt flag if preferred
+gimage generate --prompt "your prompt here"
+```
+
+### Image Processing
+
+All image processing commands use explicit flags for clarity:
+
+```bash
+# Resize to specific dimensions
+gimage resize --input photo.jpg --width 800 --height 600
+
+# Scale to 50% size
+gimage scale --input photo.jpg --factor 0.5
+
+# Crop a region
+gimage crop --input photo.jpg --x 100 --y 100 --width 800 --height 600
+
+# Compress with custom quality (supports JPG and WebP)
+gimage compress --input photo.jpg --quality 85
+
+# Convert format
+gimage convert --input photo.png --format jpg
+
+# Use --output to specify custom output path
+gimage resize --input photo.jpg --width 800 --height 600 --output resized.jpg
+
+# Add --verbose for detailed progress
+gimage convert --input photo.png --format webp --verbose
+```
+
+### Batch Processing
+
+**Batch operations are available only through the MCP server** for use with AI assistants like Claude.
+
+For CLI users who need batch processing:
+- Use shell scripts with loops
+- Use `find` + `xargs` for parallel processing
+- Example: `find photos/ -name "*.jpg" | xargs -P 4 -I {} gimage resize --input {} --width 800 --height 600`
+
+MCP server batch tools (for AI assistants):
+- `batch_resize` - Concurrent image resizing
+- `batch_compress` - Concurrent compression
+- `batch_convert` - Concurrent format conversion
+
+See [MCP documentation](#mcp-server-for-ai-assistants) for details.
+
+## Configuration
+
+### Authentication Priority (Highest to Lowest)
+1. **Command-line flags** (highest priority)
+2. **Environment variables** (`GEMINI_API_KEY`, `VERTEX_API_KEY`, etc.)
+3. **Config file** (`~/.gimage/config.md`)
+4. **Default values** (lowest priority)
+
+**Recommended**: Use environment variables for sensitive keys. Config file stores keys in **plaintext**.
+
+### Config File
+
+Location: `~/.gimage/config.md` (created automatically by `gimage auth` commands)
+
+**Security Notes**:
+- File permissions: 0600 (only you can read/write)
+- Contains PLAINTEXT API keys
+- **NEVER commit to version control**
+- **PREFER environment variables** over config file
+- Use `gimage auth status` to check for conflicting credentials
+
+Format (markdown with `**key**: value`):
+```markdown
+# Gimage Configuration
+
+⚠️  SECURITY WARNING ⚠️
+This file contains SENSITIVE API KEYS stored in PLAINTEXT.
+
+**gemini_api_key**: your-gemini-key
+**vertex_api_key**: your-vertex-key
+**vertex_project**: your-gcp-project
+**vertex_location**: us-central1
+**vertex_credentials_path**: /path/to/service-account.json
+**aws_access_key_id**: AKIA...
+**aws_secret_access_key**: wJalr...
+**aws_region**: us-east-1
+**aws_profile**: default
+**aws_bedrock_api_key**: bearer-token
+**default_api**: gemini
+**default_model**: gemini-2.5-flash-image
+**default_size**: 1024x1024
+**log_level**: info
+```
+
+### Environment Variables (Recommended)
+
+**Gemini API**:
+```bash
+export GEMINI_API_KEY="your-key"
+```
+
+**Vertex AI** (3 authentication modes):
+```bash
+# Option 1: Express Mode (REST) - Simplest
+export VERTEX_API_KEY="your-key"
+export VERTEX_PROJECT="your-project-id"
+export VERTEX_LOCATION="us-central1"
+
+# Option 2: Service Account - Production
+export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
+export VERTEX_PROJECT="your-project-id"
+
+# Option 3: Application Default Credentials - gcloud SDK
+# No env vars needed - uses gcloud auth
+```
+
+**AWS Bedrock** (4 authentication modes):
+```bash
+# Option 1: REST API with Bearer Token
+export AWS_BEARER_TOKEN_BEDROCK="your-bearer-token"
+export AWS_REGION="us-east-1"
+
+# Option 2: SDK with Access Keys (supports both long-term and short-term credentials)
+export AWS_ACCESS_KEY_ID="AKIA..."           # Long-term access key ID
+export AWS_SECRET_ACCESS_KEY="wJalr..."     # Long-term secret access key
+export AWS_SESSION_TOKEN="FwoGZXIvYXd..."   # Optional: for short-term credentials
+export AWS_REGION="us-east-1"
+
+# Option 3: SDK with Named Profile
+export AWS_PROFILE="your-profile-name"
+export AWS_REGION="us-east-1"
+
+# Option 4: SDK with IAM Role (Lambda/EC2/ECS - no credentials needed)
+# Instance/task role automatically provides credentials
+export AWS_REGION="us-east-1"  # Optional, defaults to instance region
+```
+
+**Check credential conflicts**:
+```bash
+gimage auth status  # Shows which credentials are active and their sources
+```
+
+## Available Models
+
+### Gemini API (Google AI Studio) - FREE Tier
+- **`gemini-2.5-flash-image`** (default, recommended)
+  - FREE: 1500 requests/day, no credit card required
+  - Resolution: up to 1024x1024
+  - Fast generation (~2-3 seconds)
+  - Best for: Quick iterations, development, testing
+
+- **`gemini-2.0-flash-preview-image-generation`**
+  - FREE: 1500 requests/day
+  - Preview model with experimental features
+
+### Vertex AI (Google Cloud) - Paid
+- **`imagen-3.0-generate-002`** (Imagen 3)
+  - Pricing: ~$0.02-0.04/image
+  - Resolution: up to 1536x1536
+  - High quality, production-ready
+
+- **`imagen-4`** (newest, highest quality)
+  - Pricing: ~$0.04/image
+  - Resolution: up to 2048x2048
+  - Best for: Professional work, final production images
+
+### AWS Bedrock - Paid
+- **`amazon.nova-canvas-v1:0`** (Nova Canvas)
+  - Resolution: up to 1408x1408
+  - Standard quality: 50 steps, $0.04/image
+  - Premium quality: 100 steps, $0.08/image
+  - Best for: AWS-integrated applications
+
+**View all models with live pricing:**
+```bash
+gimage generate --list-models
+# or
+gimage auth list  # Shows configured providers
+```
+
+## Image Formats Supported
+
+**Input & Output**: PNG, JPEG, WebP, GIF, TIFF, BMP
+
+All processing operations preserve format by default, or you can specify output format with `--output` flag or use the `convert` command.
+
+## Advanced Features
+
+### Styles (Generation)
+- `photorealistic` - Realistic photos
+- `artistic` - Artistic interpretations
+- `anime` - Anime/manga style
+
+### Quality Settings
+- Compression quality: 1-100 (default: 90)
+- Resampling: Lanczos algorithm (highest quality)
+- Transparency: Preserved for PNG, white background for JPEG
+
+### Batch Processing
+- Default: 4 parallel workers
+- Configurable with `--workers` flag
+- Processes entire directories
+- Preserves directory structure with `--output`
+
+## Use Cases
+
+### For Designers & Artists
+- Rapid prototyping of visual concepts
+- Generate variations of ideas
+- Quick image editing and optimization
+- Batch resize for different platforms
+
+### For Developers
+- Generate placeholder images for apps
+- Automate image processing pipelines
+- Integrate AI generation into workflows
+- Test with reproducible images (seeds)
+
+### For Content Creators
+- Create social media graphics
+- Generate blog post illustrations
+- Batch optimize images for web
+- Convert formats for different platforms
+
+### For AI/ML Engineers
+- Generate training data
+- Create synthetic datasets
+- Automate image augmentation
+- Integrate with Claude via MCP server
+
+## MCP Server for AI Assistants
+
+Gimage can run as an MCP (Model Context Protocol) server, enabling AI assistants like Claude to generate and process images directly. The server communicates over stdio using the MCP protocol and exposes 10 tools for image generation and processing.
+
+### Installation Methods
+
+There are two ways to install gimage for use with Claude Desktop. Choose based on your use case:
+
+#### Method 1: Homebrew (Recommended - macOS/Linux only)
+
+**Use this if:** You want both CLI access AND MCP server functionality from a single installation.
+
+**Step 1: Install gimage via Homebrew**
+```bash
+brew install apresai/tap/gimage
+gimage --version  # Verify installation
+```
+
+**Step 2: Configure Claude Desktop MCP**
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/Claude/claude_desktop_config.json` (Linux):
+
+```json
+{
+  "mcpServers": {
+    "gimage": {
+      "command": "gimage",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+**Why this method?**
+- ✅ Single installation serves both CLI and MCP
+- ✅ Easy updates: `brew upgrade apresai/tap/gimage`
+- ✅ Directly calls the `gimage` binary in your PATH
+- ✅ Smaller total footprint (one binary)
+
+#### Method 2: npm Package (Cross-platform alternative)
+
+**Use this if:** You're on Windows, don't use Homebrew, or only want MCP functionality (no CLI needed).
+
+**Step 1: Install via npm**
+```bash
+npm install -g @apresai/gimage-mcp
+```
+
+**Step 2: Configure Claude Desktop MCP**
+
+Edit your Claude Desktop config file:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "gimage": {
+      "command": "npx",
+      "args": ["-y", "@apresai/gimage-mcp"]
+    }
+  }
+}
+```
+
+**Why this method?**
+- ✅ Works on Windows (Homebrew method doesn't)
+- ✅ npm-based workflow (familiar to Node.js users)
+- ✅ `npx` automatically downloads/runs the correct version
+- ⚠️ Note: npm installs gimage ONLY for MCP use (hidden in npm global directory)
+- ⚠️ If you want CLI access too, you'll need to install via Homebrew separately
+
+**Configuration difference explained:**
+- **Homebrew**: Uses `"command": "gimage"` - directly calls the binary in your PATH
+- **npm**: Uses `"command": "npx"` - npx finds and runs the npm-installed package
+
+### Setup Authentication
+
+Before using the MCP server, configure your API credentials:
+
+```bash
+# Quick start with Gemini (FREE tier)
+gimage auth setup gemini
+
+# Or use environment variable (more secure):
+export GEMINI_API_KEY="your-api-key-here"
+
+# Verify configuration
+gimage auth status
+gimage auth test gemini
+```
+
+The MCP server automatically uses credentials from:
+1. **Environment variables** - `GEMINI_API_KEY`, `VERTEX_API_KEY`, `AWS_ACCESS_KEY_ID`, etc. (RECOMMENDED for security)
+2. **Config file** - `~/.gimage/config.md` (created by `gimage auth setup` commands)
+
+**Best Practice**: Use environment variables for production - they're more secure than storing credentials in config files.
+
+### Start Using with Claude
+
+After installation and authentication, restart Claude Desktop. You can then use natural language:
+
+```
+"Generate an image of a sunset over mountains"
+"Resize photo.jpg to 800x600"
+"Compress all images in the photos directory to 85% quality"
+"Create a 2048x2048 photorealistic image of a wise old wizard"
+```
+
+### Available MCP Tools
+
+The MCP server exposes 10 tools for AI assistants:
+
+| Tool | Purpose |
+|------|---------|
+| `generate_image` | AI image generation from text |
+| `resize_image` | Resize to specific dimensions |
+| `scale_image` | Scale by factor (maintain aspect ratio) |
+| `crop_image` | Crop to specific region |
+| `compress_image` | Reduce file size with quality control |
+| `convert_image` | Convert between formats |
+| `batch_resize` | Resize multiple images concurrently |
+| `batch_compress` | Compress multiple images |
+| `batch_convert` | Convert multiple images to new format |
+| `list_models` | List available AI models |
+
+### Troubleshooting MCP Server
+
+If the MCP server isn't working in Claude Desktop:
+
+1. **Verify gimage is installed and in PATH:**
+   ```bash
+   which gimage
+   gimage --version
+   ```
+
+2. **Test the serve command directly:**
+   ```bash
+   gimage serve --verbose
+   ```
+   This will show detailed logging to stderr. Press Ctrl+C to stop.
+
+3. **Verify API credentials are configured:**
+   ```bash
+   gimage auth status  # Check all configured credentials
+   ```
+
+4. **Test image generation works outside MCP:**
+   ```bash
+   gimage generate "test image"
+   ```
+
+5. **Check Claude Desktop logs** for error messages:
+   - **macOS**: `~/Library/Logs/Claude/`
+   - **Linux**: `~/.config/Claude/logs/`
+
+6. **Ensure config file exists and has correct permissions:**
+   ```bash
+   ls -la ~/.gimage/config.md
+   ```
+   Should be readable (permissions: `-rw-------` or `-rw-r--r--`)
+
+### Environment Variables
+
+The MCP server respects the same environment variables as the CLI. See [Configuration](#configuration) for complete list of supported variables for all authentication modes (Gemini, Vertex AI, AWS Bedrock).
+
+### MCP Documentation
+
+For comprehensive guides and examples:
+
+- **Usage Guide**: [docs/MCP_USAGE.md](docs/MCP_USAGE.md) - Complete setup and usage
+- **Tool Reference**: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) - Detailed tool documentation
+- **Examples**: [docs/MCP_EXAMPLES.md](docs/MCP_EXAMPLES.md) - Real-world workflows
+- **Implementation Plan**: [mcp.md](mcp.md) - Complete MCP architecture and implementation details
+
+## Command Reference
+
+See [COMMANDS.md](COMMANDS.md) for complete command reference and detailed usage examples.
+
+**Available commands**:
+- `generate` - AI image generation from text prompts
+- `resize` - Resize images to specific dimensions
+- `scale` - Scale images by a factor
+- `crop` - Crop images to specific regions
+- `compress` - Compress images to reduce file size (JPG, WebP)
+- `convert` - Convert images between formats
+- `auth` - Configure and manage API credentials (setup, status, list, test)
+- `serve` - Start MCP server for Claude Desktop (includes batch operations)
+- `tui` - Launch interactive terminal UI
+
+**Removed commands** (use alternatives):
+- `batch` - Use MCP server or shell scripts (see [Batch Processing](#batch-processing))
+- `config` - Use `auth` commands for configuration
+
+Run `gimage [command] --help` for detailed usage of any command.
+
+---
+
+## Go SDK
+
+A type-safe Go SDK for programmatic API access.
+
+**Repository**: [github.com/apresai/gimage-go-sdk](https://github.com/apresai/gimage-go-sdk)
+
+### Installation
+
+```bash
+go get github.com/apresai/gimage-go-sdk@latest
+```
+
+### Quick Start
+
+```go
+import gimage "github.com/apresai/gimage-go-sdk"
+
+// Create client with API key authentication
+client, _ := gimage.NewClient(
+    "https://your-api.execute-api.us-east-1.amazonaws.com/production",
+    gimage.WithRequestEditorFn(func(ctx context.Context, req *http.Request) error {
+        req.Header.Set("x-api-key", "your-api-key")
+        return nil
+    }),
+)
+
+// Generate image
+resp, _ := client.GenerateImage(ctx, gimage.GenerateImageJSONRequestBody{
+    Prompt: "sunset over mountains",
+    Model:  stringPtr("gemini-2.5-flash-image"),
+    Size:   stringPtr("1024x1024"),
+})
+```
+
+### Features
+
+- ✅ **Type-safe**: All types generated from OpenAPI spec
+- ✅ **Auto-complete**: Full IDE support with godoc
+- ✅ **API Gateway ready**: Built-in API key authentication support
+- ✅ **Standard Go modules**: Independent versioning with semantic versioning
+
+### Documentation
+
+Complete documentation, examples, and API reference:
+- **SDK Repository**: [github.com/apresai/gimage-go-sdk](https://github.com/apresai/gimage-go-sdk)
+- **GoDoc**: [pkg.go.dev/github.com/apresai/gimage-go-sdk](https://pkg.go.dev/github.com/apresai/gimage-go-sdk)
+- **Examples**: See the SDK repository for working examples
+
+---
+
+## Lambda API Distribution
+
+Deploy Gimage as a serverless REST API on AWS Lambda for web application integration.
+
+### Features
+
+- **Serverless Architecture**: AWS Lambda on ARM64/Graviton2 (provided.al2023 runtime)
+- **Auto-Scaling**: Handles 0 to thousands of requests automatically
+- **Cost-Effective**: Pay only for what you use (~$0.25/month for 10K requests)
+- **S3 Storage**: Automatic S3 bucket for image storage with presigned URLs
+- **Production-Ready**: Full CORS, error handling, monitoring
+- **API Gateway Integration**: Managed API keys, usage plans, rate limiting
+
+### Quick Deploy
+
+**Option 1: Using gimage-deploy tool (Recommended)**
+
+```bash
+# Build Lambda function
+make build-lambda
+make package-lambda
+
+# Deploy using gimage-deploy (from sibling directory)
+cd ../gimage-deploy
+./bin/gimage-deploy deploy \
+  --id production \
+  --stage production \
+  --region us-east-1 \
+  --lambda-code ../gimage/bin/lambda.zip \
+  --memory 512 \
+  --timeout 30
+
+# Create API key
+./bin/gimage-deploy keys create --name prod-key --deployment production
+```
+
+**Option 2: Manual deployment**
+
+See [lambda.md](lambda.md) for manual deployment guide with AWS CLI.
+
+### Deployment Tool
+
+The `gimage-deploy` CLI tool (separate project) provides complete deployment management:
+- One-command deployment to AWS Lambda
+- API Gateway configuration with API keys
+- Monitoring (logs, metrics, health checks)
+- Interactive TUI for management
+- No hardcoded account IDs - works in any AWS account
+
+See the `gimage-deploy` directory for the deployment management tool.
+
+### API Endpoints
+
+All operations available via REST API:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/generate` | POST | AI image generation |
+| `/resize` | POST | Resize to dimensions |
+| `/scale` | POST | Scale by factor |
+| `/crop` | POST | Crop region |
+| `/compress` | POST | Compress with quality |
+| `/convert` | POST | Convert format |
+| `/batch` | POST | Process multiple images |
+| `/health` | GET | Health check |
+| `/docs` | GET | **Interactive Swagger UI documentation** |
+| `/openapi.yaml` | GET | OpenAPI specification |
+
+**Try the API**: After deployment, visit `https://your-api-url/prod/docs` for interactive documentation!
+
+### Integration Examples
+
+**TypeScript/JavaScript:**
+```typescript
+const response = await fetch('https://your-api-url/generate', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    prompt: 'a sunset over mountains',
+    size: '1024x1024',
+    response_format: 's3_url'
+  })
+});
+
+const result = await response.json();
+console.log('Image URL:', result.s3_url);
+```
+
+**Python:**
+```python
+import requests
+
+response = requests.post('https://your-api-url/resize', json={
+    'image': base64_image,
+    'width': 800,
+    'height': 600
+})
+
+result = response.json()
+print(f"Resized: {result['width']}x{result['height']}")
+```
+
+**Go:**
+```go
+client := gimage.NewClient("https://your-api-url", apiKey)
+result, err := client.GenerateImage(gimage.GenerateRequest{
+    Prompt: "beautiful landscape",
+    Size:   "1024x1024",
+})
+```
+
+### Documentation
+
+- **Deployment Guide**: [lambda.md](lambda.md) - Complete deployment and infrastructure setup
+- **Integration Guide**: [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md) - Client SDKs & examples
+- **OpenAPI Spec**: [openapi.yaml](openapi.yaml) - Complete API reference
+
+### Architecture
+
+```
+Client Request → API Gateway → Lambda (Go/ARM64) → {S3, Gemini, Vertex AI}
+                                ↓
+                         Small: base64 response
+                         Large: S3 presigned URL
+```
+
+**Runtime**: AWS Lambda provided.al2023 (Amazon Linux 2023)
+**Architecture**: ARM64 (Graviton2 processors)
+**Package Size**: 17MB compressed, 42MB uncompressed
+**Memory**: 2GB (configurable)
+**Timeout**: 5 minutes max
+
+---
+
+## Building from Source
+
+### CLI Binary
+
+```bash
+git clone https://github.com/apresai/gimage.git
+cd gimage
+make build
+./bin/gimage --version
+```
+
+### Lambda Function
+
+```bash
+# Build for AWS Lambda ARM64
+make build-lambda
+
+# Package as deployment zip
+make package-lambda
+
+# Output: bin/lambda.zip (17MB)
+```
+
+## Requirements
+
+### CLI
+- **None!** Single static binary with zero dependencies
+- Works on: macOS, Linux, Windows (x86_64, ARM64)
+- No Python, no Node.js, no system libraries required
+
+### Lambda API
+- AWS Account
+- AWS CLI configured
+- Node.js 20+ (for CDK deployment)
+- Go 1.22+ (for building)
+
+## Support & Documentation
+
+### CLI
+- **Full Command Reference**: [COMMANDS.md](COMMANDS.md)
+- **Configuration Guide**: See `gimage auth --help`
+
+### Lambda API
+- **OpenAPI Specification**: [openapi.yaml](openapi.yaml)
+- **Integration Guide**: [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md)
+- **Deployment Guide**: [lambda.md](lambda.md)
+- **Implementation Status**: [LAMBDA_STATUS.md](LAMBDA_STATUS.md)
+
+### Community
+- **GitHub Issues**: https://github.com/apresai/gimage/issues
+- **Discussions**: https://github.com/apresai/gimage/discussions
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Credits
+
+Built with:
+- [Cobra](https://github.com/spf13/cobra) - CLI framework
+- [Imaging](https://github.com/disintegration/imaging) - Image processing
+- [Google Gen AI SDK](https://github.com/googleapis/go-genai) - Gemini API
+- [Vertex AI SDK](https://cloud.google.com/go/vertexai) - Vertex AI
+- [AWS SDK for Go](https://github.com/aws/aws-sdk-go-v2) - AWS Bedrock
+
+---
+
+**Made with ❤️ for developers, designers, and AI enthusiasts**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apresai/gimage-mcp",
-  "version": "1.2.63",
+  "version": "1.2.65",
   "description": "MCP server for AI-powered image generation and processing with gimage",
   "keywords": [
     "mcp",

package/bin/gimage-mcp.js

@@ -1,55 +0,0 @@
-#!/usr/bin/env node
-
-const { spawn } = require('child_process');
-const path = require('path');
-const fs = require('fs');
-
-function getBinaryPath() {
-  const platform = process.platform;
-  const ext = platform === 'win32' ? '.exe' : '';
-  const binaryName = `gimage${ext}`;
-
-  // Try package-installed binary first
-  const packagePath = path.join(__dirname, '..', 'bin', binaryName);
-  if (fs.existsSync(packagePath)) {
-    return packagePath;
-  }
-
-  // Fall back to system PATH (if gimage is installed globally via Homebrew, etc.)
-  return 'gimage';
-}
-
-function main() {
-  const binaryPath = getBinaryPath();
-
-  // Spawn gimage serve command
-  const child = spawn(binaryPath, ['serve'], {
-    stdio: 'inherit',
-    env: process.env
-  });
-
-  child.on('error', (error) => {
-    console.error('Failed to start gimage MCP server:', error.message);
-    console.error('\nPlease ensure gimage is installed:');
-    console.error('  npm install -g @apresai/gimage-mcp');
-    console.error('  or');
-    console.error('  brew install gimage');
-    console.error('\nFor manual installation, see: https://github.com/apresai/gimage');
-    process.exit(1);
-  });
-
-  child.on('exit', (code) => {
-    process.exit(code || 0);
-  });
-
-  // Handle signals for graceful shutdown
-  process.on('SIGINT', () => {
-    child.kill('SIGINT');
-  });
-
-  process.on('SIGTERM', () => {
-    child.kill('SIGTERM');
-  });
-}
-
-main();