@goonnguyen/human-mcp 1.3.0 → 2.0.0

package/README.md

@@ -21,12 +21,39 @@ 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
+- Multiple artistic styles: photorealistic, artistic, cartoon, sketch, digital art
+- Flexible aspect ratios and output formats
+- 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
+- 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
@@ -400,6 +427,70 @@ Or via JSON configuration:
 }
 ```
 
+#### OpenCode
+
+OpenCode is a powerful AI coding agent that supports MCP servers for enhanced capabilities. Use Human MCP to add visual analysis tools to your OpenCode workflow.
+
+**Configuration Location:**
+- **Global**: `~/.config/opencode/opencode.json`
+- **Project**: `./opencode.json` in your project root
+
+**Configuration Example (STDIO - Recommended):**
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "human": {
+      "type": "local",
+      "command": ["npx", "@goonnguyen/human-mcp"],
+      "enabled": true,
+      "environment": {
+        "GOOGLE_GEMINI_API_KEY": "your_gemini_api_key_here",
+        "TRANSPORT_TYPE": "stdio",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+**Alternative Configuration (if globally installed):**
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "human": {
+      "type": "local",
+      "command": ["human-mcp"],
+      "enabled": true,
+      "environment": {
+        "GOOGLE_GEMINI_API_KEY": "your_gemini_api_key_here",
+        "TRANSPORT_TYPE": "stdio"
+      }
+    }
+  }
+}
+```
+
+**Setup Steps:**
+1. Install Human MCP: `npm install -g @goonnguyen/human-mcp`
+2. Create or edit your OpenCode configuration file
+3. Add the Human MCP server configuration (use `npx` version for reliability)
+4. Set your Google Gemini API key in environment variables or the config
+5. Restart OpenCode
+
+**Important Notes:**
+- **STDIO Mode**: Human MCP uses stdio transport by default, which provides the best compatibility with OpenCode
+- **No R2 Uploads**: In stdio mode, all images and videos are processed locally and sent to Gemini using inline base64 - no Cloudflare R2 uploads occur
+- **Security**: Never commit API keys to version control. Use environment variables or secure credential storage
+
+**Verification:**
+- Check OpenCode logs for successful MCP connection
+- Try using `eyes_analyze` tool: "Analyze this screenshot for UI issues"
+- Verify no external network calls to Cloudflare R2 in stdio mode
+
 #### Gemini CLI
 
 While Gemini CLI doesn't directly support MCP, you can use Human MCP as a bridge to access visual analysis capabilities.
@@ -855,7 +946,74 @@ 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"
+}
+```
+
+### 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"]
 }
 ```
 
@@ -886,12 +1044,67 @@ 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"
+}
+```
+
+### 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:
@@ -977,9 +1190,19 @@ 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
+│   ├── Style Customization
+│   ├── Aspect Ratio Control
+│   └── Prompt Engineering
+├── Mouth Tool (Speech Generation)
+│   ├── Text-to-Speech Synthesis
+│   ├── Long-form Narration
+│   ├── Code Explanation
+│   └── Voice Customization
 ├── Debugging Prompts
 └── Documentation Resources
 ```
@@ -992,7 +1215,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
@@ -1001,6 +1224,21 @@ 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.2.2)
+- High-quality image generation using Gemini Imagen API
+- Multiple artistic styles and aspect ratios
+- Advanced prompt engineering with negative prompts
+- Comprehensive validation and error handling
+- 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)
@@ -1019,21 +1257,25 @@ 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.2.2)
+- ✅ Image generation from text descriptions using Imagen API
+- Multiple artistic styles: photorealistic, artistic, cartoon, sketch, digital_art
+- Flexible aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4
+- Advanced prompt engineering with negative prompts
+- Comprehensive error handling and validation
+- Future: Advanced image editing (inpainting, style transfer, enhancement)
+- Future: Video generation up to 30 seconds using Veo3 API
+- Future: Animation creation with motion graphics
 
 ### Target Architecture (End 2025)
 

package/bin/human-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/index.js');