nanobanana-mcp-server

# Nano Banana MCP Server - Documentation Index **Version:** 0.1.4 **Status:** Production Ready **Package:** `nanobanana-mcp-server` A production-ready Model Context Protocol (MCP) server for AI-powered image generation using Google's Gemini 2.5 Flash Image model. ## 📋 Quick Navigation ### 🚀 Getting Started - **[README.md](../README.md)** - Installation and client configuration - **[CLAUDE.md](../CLAUDE.md)** - Claude Code development guidance ### 📚 Core Documentation - **[API Specification](API_SPECIFICATION.md)** - Complete API reference - **[System Design](SYSTEM_DESIGN.md)** - Architecture and design patterns - **[Component Design](COMPONENT_DESIGN.md)** - Detailed component documentation ### 🔧 Development - **[Implementation Plan](IMPLEMENTATION_PLAN.md)** - Development roadmap and milestones - **[FastMCP Skeleton](fastmcp-skeleton.md)** - FastMCP integration guide - **[Workflows](workflows.md)** - Development workflows and processes ### 📦 Publishing - **[Publishing Workflow](PUBLISHING_WORKFLOW.md)** - Complete publishing guide - **[PyPI Upload Guide](PYPI_UPLOAD_GUIDE.md)** - PyPI deployment instructions ## 🏗️ Project Structure ### Package Layout ``` nanobanana_mcp_server/ ├── __init__.py # Package entry point (v0.1.4) ├── server.py # Main server implementation ├── config/ # Configuration management │ ├── settings.py # Server and API settings │ └── constants.py # Application constants ├── core/ # Core functionality │ ├── server.py # FastMCP server setup │ ├── exceptions.py # Custom exceptions │ ├── validation.py # Input validation │ └── progress_tracker.py # Progress tracking ├── services/ # Business logic services │ ├── __init__.py # Service registry │ ├── gemini_client.py # Gemini API wrapper │ ├── *_image_service.py # Image processing services │ ├── file_service.py # File management │ └── maintenance_service.py # System maintenance ├── tools/ # MCP tools implementation │ ├── generate_image.py # Image generation tool │ ├── upload_file.py # File upload tool │ ├── output_stats.py # Statistics tool │ └── maintenance.py # Maintenance tool ├── resources/ # MCP resources │ ├── file_metadata.py # File metadata resource │ ├── stored_images.py # Image storage resource │ ├── template_catalog.py # Template catalog │ └── operation_status.py # Operation status ├── prompts/ # Prompt templates │ ├── photography.py # Photography templates │ ├── design.py # Design templates │ └── editing.py # Image editing templates └── utils/ # Utility functions ├── image_utils.py # Image processing utilities ├── logging_utils.py # Logging configuration └── validation_utils.py # Validation helpers ``` ### Configuration Files ``` ├── pyproject.toml # Project configuration and dependencies ├── fastmcp.json # FastMCP CLI configuration ├── ruff.toml # Code linting configuration └── uv.lock # Dependency lock file ``` ### Scripts & Tools ``` scripts/ ├── build.py # Automated build script └── upload.py # PyPI upload script ``` ## 🔌 MCP Integration ### Available Tools | Tool | Description | Status | |------|-------------|---------| | `generate_image` | AI image generation from prompts | ✅ Active | | `upload_file` | File upload to Gemini Files API | ✅ Active | | `output_stats` | Image storage statistics | ✅ Active | | `maintenance` | System maintenance operations | ✅ Active | ### Available Resources | Resource | URI Pattern | Description | |----------|-------------|-------------| | File Metadata | `gemini://files/{name}` | Gemini Files API metadata | | Stored Images | `file://images/{id}` | Generated image access | | Image Thumbnails | `file://images/{id}/thumbnail` | Image thumbnail access | | Template Catalog | `nano-banana://prompt-templates` | Prompt template browser | | Operation Status | `nano-banana://operations` | Server operation status | ### Prompt Templates | Template | Module | Purpose | |----------|---------|---------| | `photorealistic_shot` | photography.py | High-quality photography | | `product_shot` | photography.py | E-commerce product photos | | `logo_text` | design.py | Logo design with text | | `sticker_flat` | design.py | Flat design illustrations | | `iterative_edit_instruction` | editing.py | Precise image editing | | `composition_and_style_transfer` | editing.py | Artistic style transfer | ## 🛠️ Technical Stack ### Core Dependencies - **FastMCP** (≥2.11.0) - MCP server framework - **Google GenAI** (≥0.3.0) - Gemini API integration - **Pillow** (≥10.4.0) - Image processing - **Pydantic** (≥2.0.0) - Data validation - **Python-dotenv** (≥1.0.1) - Environment management ### Development Tools - **uv** - Modern Python package management - **Ruff** - Fast Python linter and formatter - **MyPy** - Static type checking - **Pytest** - Testing framework ### Build System - **Hatchling** - Modern Python build backend - **Twine** - PyPI package uploading - **Build** - PEP 517 build frontend ## 📊 Project Metrics ### Package Information - **Total Python Files:** 40+ - **Package Size:** ~260KB (wheel + source) - **Supported Python:** 3.11+ - **License:** MIT - **Development Status:** Alpha (Production Ready) ### Documentation Coverage | Category | Files | Status | |----------|-------|---------| | API Documentation | 3 | ✅ Complete | | System Design | 2 | ✅ Complete | | User Guides | 2 | ✅ Complete | | Development Guides | 3 | ✅ Complete | | Publishing Guides | 2 | ✅ Complete | ## 🔍 Version History ### v0.1.4 (Latest) - Comprehensive Import Fixes - ✅ Fixed all absolute imports to relative imports - ✅ Restructured to proper package layout - ✅ Added automated PyPI publishing workflow - ✅ Streamlined README with client configurations ### v0.1.3 - Import Fixes - ✅ Fixed service import issues - ✅ Updated resource handlers ### v0.1.2 - Directory Fixes - ✅ Fixed read-only filesystem issues - ✅ Improved default directory handling ### v0.1.1 - Initial Package - ✅ Basic MCP server functionality - ✅ Image generation tools ## 📋 Development Status ### ✅ Completed Features - Production-ready MCP server - Comprehensive image generation capabilities - File management and storage - Template system with 6+ templates - Error handling and logging - PyPI package publishing - Multi-client configuration support ### 🔄 In Progress - Enhanced documentation - Performance optimization - Additional prompt templates ### 📋 Planned Features - Image editing capabilities expansion - Batch processing tools - Advanced template customization - Performance monitoring ## 🆘 Support & Resources - **Issues:** [GitHub Issues](https://github.com/zhongweili/nanobanana-mcp-server/issues) - **Discussions:** [GitHub Discussions](https://github.com/zhongweili/nanobanana-mcp-server/discussions) - **Package:** [PyPI Package](https://pypi.org/project/nanobanana-mcp-server/) --- *Last updated: December 2024 | Version 0.1.4*