@goonnguyen/human-mcp 1.4.0 → 2.1.0

package/README.md

@@ -21,12 +21,44 @@ Human MCP is a Model Context Protocol server that provides AI coding agents with
 - **Performance**: Loading states, visual performance indicators
 - **Layout**: Responsive design, positioning, visual hierarchy
 
+🎨 **Content Generation**
+- Generate high-quality images from text descriptions using Imagen API
+- Create professional videos from text prompts using Veo 3.0 API
+- Image-to-video generation combining Imagen and Veo 3.0
+- Multiple artistic styles: photorealistic, artistic, cartoon, sketch, digital art (images) and realistic, cinematic, artistic, cartoon, animation (videos)
+- Flexible aspect ratios (1:1, 16:9, 9:16, 4:3, 3:4) and output formats
+- Video duration controls (4s, 8s, 12s) with FPS options (1-60 fps)
+- Camera movement controls: static, pan, zoom, dolly movements
+- Advanced prompt engineering and negative prompts
+
+🗣️ **Speech Generation**
+- Convert text to natural-sounding speech with 30+ voice options
+- Long-form content narration with chapter breaks
+- Technical code explanation with spoken analysis
+- Voice customization and style control
+- Multi-language support (24 languages)
+- Professional audio export in WAV format
+
 🤖 **AI-Powered**
 - Uses Google Gemini 2.5 Flash for fast, accurate analysis
+- Advanced Imagen API for high-quality image generation
+- Cutting-edge Veo 3.0 API for professional video generation
+- Gemini Speech Generation API for natural voice synthesis
 - Detailed technical insights for developers
 - Actionable recommendations for fixing issues
 - Structured output with detected elements and coordinates
 
+### Google Gemini Documentation
+- [Gemini API](https://ai.google.dev/gemini-api/docs?hl=en)
+- [Gemini Models](https://ai.google.dev/gemini-api/docs/models)
+- [Video Understanding](https://ai.google.dev/gemini-api/docs/video-understanding?hl=en)
+- [Image Understanding](https://ai.google.dev/gemini-api/docs/image-understanding)
+- [Document Understanding](https://ai.google.dev/gemini-api/docs/document-processing)
+- [Audio Understanding](https://ai.google.dev/gemini-api/docs/audio)
+- [Speech Generation](https://ai.google.dev/gemini-api/docs/speech-generation)
+- [Image Generation](https://ai.google.dev/gemini-api/docs/image-generation)
+- [Video Generation](https://ai.google.dev/gemini-api/docs/video)
+
 ## Quick Start
 
 ### Getting Your Google Gemini API Key
@@ -919,7 +951,103 @@ Compare two images to identify visual differences.
 {
   "source1": "/path/to/before.png",
   "source2": "/path/to/after.png",
-  "comparison_type": "structural" 
+  "comparison_type": "structural"
+}
+```
+
+### gemini_gen_image
+
+Generate high-quality images from text descriptions using Gemini Imagen API.
+
+```json
+{
+  "prompt": "A modern minimalist login form with clean typography",
+  "style": "digital_art",
+  "aspect_ratio": "16:9",
+  "negative_prompt": "cluttered, low quality, blurry"
+}
+```
+
+### gemini_gen_video
+
+Generate professional videos from text descriptions using Gemini Veo 3.0 API.
+
+```json
+{
+  "prompt": "A serene mountain landscape at sunrise with gentle camera movement",
+  "duration": "8s",
+  "style": "cinematic",
+  "aspect_ratio": "16:9",
+  "camera_movement": "pan_right",
+  "fps": 30
+}
+```
+
+### gemini_image_to_video
+
+Generate videos from images and text descriptions using Imagen + Veo 3.0 pipeline.
+
+```json
+{
+  "prompt": "Animate this landscape with flowing water and moving clouds",
+  "image_input": "data:image/jpeg;base64,/9j/4AAQ...",
+  "duration": "12s",
+  "style": "realistic",
+  "camera_movement": "zoom_in"
+}
+```
+
+### mouth_speak
+
+Convert text to natural-sounding speech with voice customization.
+
+```json
+{
+  "text": "Welcome to our application. Let me guide you through the interface.",
+  "voice": "Zephyr",
+  "language": "en-US",
+  "style_prompt": "Speak in a friendly, welcoming tone"
+}
+```
+
+### mouth_narrate
+
+Generate narration for long-form content with chapter breaks and style control.
+
+```json
+{
+  "content": "Chapter 1: Introduction to React...",
+  "voice": "Sage",
+  "narration_style": "educational",
+  "chapter_breaks": true,
+  "max_chunk_size": 8000
+}
+```
+
+### mouth_explain
+
+Generate spoken explanations of code with technical analysis.
+
+```json
+{
+  "code": "function factorial(n) { return n <= 1 ? 1 : n * factorial(n-1); }",
+  "programming_language": "javascript",
+  "voice": "Apollo",
+  "explanation_level": "intermediate",
+  "include_examples": true
+}
+```
+
+### mouth_customize
+
+Test different voices and styles to find the best fit for your content.
+
+```json
+{
+  "text": "Hello, this is a voice test sample.",
+  "voice": "Charon",
+  "style_variations": ["professional", "casual", "energetic"],
+  "compare_voices": ["Puck", "Sage", "Apollo"]
 }
 ```
 
@@ -950,12 +1078,92 @@ Compare two images to identify visual differences.
 # Check accessibility compliance
 {
   "source": "page-screenshot.png",
-  "type": "image", 
+  "type": "image",
   "analysis_type": "accessibility",
   "check_accessibility": true
 }
 ```
 
+### Image Generation for Design
+```bash
+# Generate UI mockups and design elements
+{
+  "prompt": "Professional dashboard interface with data visualization charts",
+  "style": "digital_art",
+  "aspect_ratio": "16:9"
+}
+```
+
+### Prototype Creation
+```bash
+# Create visual prototypes for development
+{
+  "prompt": "Mobile app login screen with modern design, dark theme",
+  "style": "photorealistic",
+  "aspect_ratio": "9:16",
+  "negative_prompt": "old-fashioned, bright colors"
+}
+```
+
+### Video Generation for Prototyping
+```bash
+# Create animated prototypes and demonstrations
+{
+  "prompt": "User interface animation showing a smooth login process with form transitions",
+  "duration": "8s",
+  "style": "digital_art",
+  "aspect_ratio": "16:9",
+  "camera_movement": "static",
+  "fps": 30
+}
+```
+
+### Marketing Video Creation
+```bash
+# Generate promotional videos for products
+{
+  "prompt": "Elegant product showcase video with professional lighting and smooth camera movement",
+  "duration": "12s",
+  "style": "cinematic",
+  "aspect_ratio": "16:9",
+  "camera_movement": "dolly_forward"
+}
+```
+
+### Code Explanation Audio
+```bash
+# Generate spoken explanations for code reviews
+{
+  "code": "const useAuth = () => { const [user, setUser] = useState(null); return { user, login: setUser }; }",
+  "programming_language": "javascript",
+  "voice": "Apollo",
+  "explanation_level": "advanced",
+  "include_examples": true
+}
+```
+
+### Documentation Narration
+```bash
+# Convert technical documentation to audio
+{
+  "content": "This API endpoint handles user authentication and returns a JWT token...",
+  "voice": "Sage",
+  "narration_style": "professional",
+  "chapter_breaks": true
+}
+```
+
+### User Interface Voice Feedback
+```bash
+# Generate voice responses for applications
+{
+  "text": "File uploaded successfully. Processing will complete in approximately 30 seconds.",
+  "voice": "Kore",
+  "language": "en-US",
+  "style_prompt": "Speak in a helpful, reassuring tone"
+}
+```
+
 ## Prompts
 
 Human MCP includes pre-built prompts for common debugging scenarios:
@@ -1041,9 +1249,22 @@ HTTP_ENABLE_RATE_LIMITING=false
 Human MCP Server
 ├── Eyes Tool (Vision Understanding)
 │   ├── Image Analysis
-│   ├── Video Processing  
+│   ├── Video Processing
 │   ├── GIF Frame Extraction
 │   └── Visual Comparison
+├── Hands Tool (Content Generation)
+│   ├── Image Generation (Imagen API)
+│   ├── Video Generation (Veo 3.0 API)
+│   ├── Image-to-Video Pipeline
+│   ├── Style Customization
+│   ├── Aspect Ratio & Duration Control
+│   ├── Camera Movement Control
+│   └── Prompt Engineering
+├── Mouth Tool (Speech Generation)
+│   ├── Text-to-Speech Synthesis
+│   ├── Long-form Narration
+│   ├── Code Explanation
+│   └── Voice Customization
 ├── Debugging Prompts
 └── Documentation Resources
 ```
@@ -1056,7 +1277,7 @@ For detailed architecture information and future development plans, see:
 
 **Mission**: Transform AI coding agents with complete human-like sensory capabilities, bridging the gap between artificial and human intelligence through sophisticated multimodal analysis.
 
-### Current Status: Phase 1 Complete ✅
+### Current Status: Phase 1 Complete ✅ | Phase 4 Complete ✅ | Phase 5 Complete ✅
 
 **Eyes (Visual Analysis)** - Production Ready (v1.2.1)
 - Advanced image, video, and GIF analysis capabilities
@@ -1065,6 +1286,25 @@ For detailed architecture information and future development plans, see:
 - Processing 20+ visual formats with 98.5% success rate
 - Sub-30 second response times for detailed analysis
 
+**Hands (Content Generation)** - Production Ready (v1.4.0)
+- High-quality image generation using Gemini Imagen API
+- Professional video generation using Gemini Veo 3.0 API
+- Image-to-video generation pipeline combining Imagen + Veo 3.0
+- Multiple artistic styles and aspect ratios for both images and videos
+- Video duration controls (4s, 8s, 12s) with FPS options (1-60 fps)
+- Camera movement controls: static, pan, zoom, dolly movements
+- Advanced prompt engineering with negative prompts
+- Comprehensive validation and error handling with retry logic
+- Fast generation times with reliable output
+
+**Mouth (Speech Generation)** - Production Ready (v1.3.0)
+- Natural text-to-speech with 30+ voice options
+- Long-form content narration with chapter breaks
+- Technical code explanation with spoken analysis
+- Voice customization and style control
+- Multi-language support (24 languages)
+- Professional audio export in WAV format
+
 ### Upcoming Development Phases
 
 #### Phase 2: Document Understanding (Q4 2025)
@@ -1083,21 +1323,28 @@ For detailed architecture information and future development plans, see:
 - Support for 20+ audio formats (WAV, MP3, AAC, OGG, FLAC)
 - Real-time audio processing capabilities
 
-#### Phase 4: Speech Generation - Mouth (Q4 2025)
-**AI Voice Capabilities**
-- High-quality text-to-speech with customizable voice parameters
-- Code explanation and technical content narration
-- Multi-language speech generation (10+ languages)
-- Long-form content narration with natural pacing
-- Professional-quality audio export in multiple formats
-
-#### Phase 5: Content Generation - Hands (Q4 2025)
-**Creative Content Creation**
-- Image generation from text descriptions using Imagen API
-- Advanced image editing (inpainting, style transfer, enhancement)
-- Video generation up to 30 seconds using Veo3 API
-- Animation creation with motion graphics
-- Batch content generation for workflow automation
+#### Phase 4: Speech Generation - Mouth ✅ COMPLETE
+**AI Voice Capabilities** - Production Ready (v1.3.0)
+- ✅ High-quality text-to-speech with 30+ voice options using Gemini Speech API
+- ✅ Code explanation and technical content narration
+- ✅ Multi-language speech generation (24 languages supported)
+- ✅ Long-form content narration with chapter breaks and natural pacing
+- ✅ Professional-quality audio export in WAV format
+- ✅ Voice customization with style prompts and voice comparison
+
+#### Phase 5: Content Generation - Hands ✅ COMPLETE
+**Creative Content Creation** - Production Ready (v1.4.0)
+- ✅ Image generation from text descriptions using Imagen API
+- ✅ Video generation from text prompts using Veo 3.0 API
+- ✅ Image-to-video generation pipeline combining Imagen + Veo 3.0
+- ✅ Multiple artistic styles for images and videos
+- ✅ Flexible aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4
+- ✅ Video duration controls (4s, 8s, 12s) with FPS options (1-60 fps)
+- ✅ Camera movement controls: static, pan, zoom, dolly movements
+- ✅ Advanced prompt engineering with negative prompts
+- ✅ Comprehensive error handling and validation with retry logic
+- Future: Advanced image editing (inpainting, style transfer, enhancement)
+- Future: Animation creation with motion graphics
 
 ### Target Architecture (End 2025)
 
@@ -1121,8 +1368,8 @@ The evolution from single-capability visual analysis to comprehensive human-like
                        │  • Narration         │
                        │                      │
                        │  ✋ Hands (Creation) │
-                       │  • Image Generation  │
-                       │  • Video Generation  │
+                       │  • Image Generation ✅│
+                       │  • Video Generation ✅│
                        └──────────────────────┘
 ```
 
@@ -1145,15 +1392,16 @@ The evolution from single-capability visual analysis to comprehensive human-like
 ### Success Metrics & Timeline
 
 - **Phase 2 (Document Understanding)**: January - March 2025
-- **Phase 3 (Audio Processing)**: April - June 2025  
-- **Phase 4 (Speech Generation)**: September - October 2025
-- **Phase 5 (Content Generation)**: October - December 2025
+- **Phase 3 (Audio Processing)**: April - June 2025
+- **Phase 4 (Speech Generation)**: ✅ Completed September 2025
+- **Phase 5 (Content Generation)**: ✅ Completed September 2025
 
 **Target Goals:**
 - Support 50+ file formats across all modalities
-- 99%+ success rate with sub-60 second processing times
+- 99%+ success rate with optimized processing times (images <30s, videos <5min)
 - 1000+ MCP client integrations and 100K+ monthly API calls
 - Comprehensive documentation with real-world examples
+- Professional-grade content generation capabilities
 
 ### Getting Involved
 
@@ -1165,10 +1413,17 @@ Human MCP is built for the developer community. Whether you're integrating with
 
 ## Supported Formats
 
-**Images**: PNG, JPEG, WebP, GIF (static)  
-**Videos**: MP4, WebM, MOV, AVI
-**GIFs**: Animated GIF with frame extraction  
-**Sources**: File paths, URLs, base64 data URLs
+**Analysis Formats**:
+- **Images**: PNG, JPEG, WebP, GIF (static)
+- **Videos**: MP4, WebM, MOV, AVI
+- **GIFs**: Animated GIF with frame extraction
+- **Sources**: File paths, URLs, base64 data URLs
+
+**Generation Formats**:
+- **Images**: PNG, JPEG (Base64 output)
+- **Videos**: MP4 (Base64 output)
+- **Durations**: 4s, 8s, 12s video lengths
+- **Quality**: Professional-grade output with customizable FPS (1-60)
 
 ## Contributing