@goonnguyen/human-mcp 2.13.0 → 2.14.0

package/README.md

@@ -6,6 +6,9 @@
 
 Human MCP v2.10.0 is a comprehensive Model Context Protocol server that provides AI coding agents with human-like capabilities including visual analysis, document processing, speech generation, content creation, image editing, browser automation, and advanced reasoning for debugging, understanding, and enhancing multimodal content.
 
+## "Human MCP" is a part of [ClaudeKit](https://claudekit.cc)
+![ClaudeKit.cc](claudekit.png)
+
 ## Features
 
 🎯 **Visual Analysis (Eyes) - ✅ Complete (4 tools)**
@@ -123,6 +126,104 @@ curl -H "Content-Type: application/json" \
      -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=YOUR_API_KEY"
 ```
 
+### Choosing Your Gemini Provider
+
+Human MCP supports two ways to access Google's Gemini models:
+
+#### Option 1: Google AI Studio (Default - Recommended for Getting Started)
+
+**Best for:** Quick start, development, prototyping
+
+**Setup:**
+1. Get your API key from [Google AI Studio](https://aistudio.google.com/)
+2. Set environment variable: `export GOOGLE_GEMINI_API_KEY=your_api_key`
+
+**Pros:**
+- Simple setup (just one API key)
+- No GCP account required
+- Free tier available
+- Perfect for development and testing
+
+#### Option 2: Vertex AI (Recommended for Production)
+
+**Best for:** Production deployments, enterprise use, GCP integration
+
+**Setup:**
+1. Create a GCP project and enable Vertex AI API
+2. Set up authentication:
+   ```bash
+   # Option A: Application Default Credentials (for local dev)
+   gcloud auth application-default login
+
+   # Option B: Service Account (for production)
+   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+   ```
+3. Set environment variables:
+   ```bash
+   export USE_VERTEX=1
+   export VERTEX_PROJECT_ID=your-gcp-project-id
+   export VERTEX_LOCATION=us-central1  # optional, defaults to us-central1
+   ```
+
+**Pros:**
+- Enterprise-grade quotas and SLAs
+- Better integration with GCP services
+- Advanced IAM and security controls
+- Usage tracking via Cloud Console
+- Better for production workloads
+
+**Configuration Example (Claude Desktop):**
+
+```json
+{
+  "mcpServers": {
+    "human-mcp-vertex": {
+      "command": "npx",
+      "args": ["@goonnguyen/human-mcp"],
+      "env": {
+        "USE_VERTEX": "1",
+        "VERTEX_PROJECT_ID": "your-gcp-project-id",
+        "VERTEX_LOCATION": "us-central1"
+      }
+    }
+  }
+}
+```
+
+**Note:** With Vertex AI, you don't need `GOOGLE_GEMINI_API_KEY` - authentication is handled by GCP credentials.
+
+#### Vertex AI Authentication Methods
+
+**1. Application Default Credentials (ADC)** - Best for local development
+```bash
+gcloud auth application-default login
+```
+
+**2. Service Account** - Best for production
+```bash
+# Download service account JSON from GCP Console
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+```
+
+**3. Workload Identity** - Best for GKE deployments
+- Automatically configured when running on GKE
+- No credentials file needed
+- Recommended for Kubernetes deployments
+
+**Troubleshooting Vertex AI:**
+
+If you encounter authentication errors:
+1. Verify your GCP project ID: `gcloud config get-value project`
+2. Check ADC status: `gcloud auth application-default print-access-token`
+3. Ensure Vertex AI API is enabled: Visit [Vertex AI Console](https://console.cloud.google.com/vertex-ai)
+4. Verify IAM permissions: Your account needs `Vertex AI User` role
+
+**Cost Considerations:**
+
+Both Google AI Studio and Vertex AI use the same Gemini models and pricing, but:
+- Google AI Studio: Generous free tier for testing
+- Vertex AI: Production-grade quotas, better for high-volume usage
+
 #### Alternative Methods for API Key
 
 **Using Google Cloud Console:**
@@ -156,36 +257,8 @@ echo $GOOGLE_GEMINI_API_KEY
 
 ### Prerequisites
 
-- Node.js v18+ or [Bun](https://bun.sh) v1.2+
-- Google Gemini API key (configured as shown above)
-
-### Installation
-
-Install Human MCP as an npm package:
-
-```bash
-# Using npm
-npm install -g @goonnguyen/human-mcp
-
-# Using bun (recommended)
-bun install -g @goonnguyen/human-mcp
-
-# Using pnpm
-pnpm install -g @goonnguyen/human-mcp
-```
-
-### Environment Setup
-
-Configure your Google Gemini API key:
-
-```bash
-# Option 1: Environment variable (recommended)
-export GOOGLE_GEMINI_API_KEY="your_api_key_here"
-
-# Option 2: Add to your shell profile
-echo 'export GOOGLE_GEMINI_API_KEY="your_api_key_here"' >> ~/.zshrc
-source ~/.zshrc
-```
+- Node.js v22+ or [Bun](https://bun.sh) v1.2+
+- Google [Gemini API key](http://aistudio.google.com/) (configured as shown above)
 
 ### Development (For Contributors)
 
@@ -247,55 +320,15 @@ Claude Desktop is a desktop application that provides a user-friendly interface
 }
 ```
 
-**Alternative Configuration (if globally installed):**
-
-```json
-{
-  "mcpServers": {
-    "human-mcp": {
-      "command": "human-mcp",
-      "env": {
-        "GOOGLE_GEMINI_API_KEY": "your_gemini_api_key_here"
-      }
-    }
-  }
-}
-```
-
-**Setup Steps:**
-1. Install Human MCP globally: `npm install -g @goonnguyen/human-mcp`
-2. Create or edit the Claude Desktop configuration file
-3. Add the Human MCP server configuration (use the first example with `npx` for reliability)
-4. Set your Google Gemini API key in environment variables or the config
-5. Restart Claude Desktop
-
-**Verification:**
-- Look for the connection indicator in Claude Desktop
-- Try using the `eyes_analyze` tool with a test image
-
 #### Claude Code (CLI)
 
 Claude Code is the official CLI for Claude that supports MCP servers for enhanced coding workflows.
 
 **Prerequisites:**
-- Node.js v18+ or Bun v1.2+
+- Node.js v22+ or Bun v1.2+
 - Google Gemini API key
 - Claude Code CLI installed
 
-**Installation:**
-
-```bash
-# Install Claude Code CLI
-npm install -g @anthropic-ai/claude-code
-
-# Install Human MCP server
-npm install -g @goonnguyen/human-mcp
-
-# Verify installations
-claude --version
-human-mcp --version  # or: npx @goonnguyen/human-mcp --version
-```
-
 **Configuration Methods:**
 
 Claude Code offers multiple ways to configure MCP servers. Choose the method that best fits your workflow:
@@ -306,8 +339,8 @@ Claude Code offers multiple ways to configure MCP servers. Choose the method tha
 # Add Human MCP server with automatic configuration
 claude mcp add --scope user human-mcp npx @goonnguyen/human-mcp --env GOOGLE_GEMINI_API_KEY=your_api_key_here
 
-# Alternative: Add globally installed version
-claude mcp add --scope user human-mcp human-mcp --env GOOGLE_GEMINI_API_KEY=your_api_key_here
+# Alternative: Add locally installed version
+claude mcp add --scope project human-mcp npx @goonnguyen/human-mcp --env GOOGLE_GEMINI_API_KEY=your_api_key_here
 
 # List configured MCP servers
 claude mcp list
@@ -339,23 +372,6 @@ claude mcp remove human-mcp
 }
 ```
 
-**Alternative Configuration (if globally installed):**
-
-```json
-{
-  "mcpServers": {
-    "human-mcp": {
-      "command": "human-mcp",
-      "env": {
-        "GOOGLE_GEMINI_API_KEY": "your_gemini_api_key_here",
-        "LOG_LEVEL": "info",
-        "MCP_TIMEOUT": "30000"
-      }
-    }
-  }
-}
-```
-
 **Configuration Scopes:**
 
 Claude Code supports different configuration scopes:
@@ -374,10 +390,9 @@ claude mcp add --scope local human-mcp npx @goonnguyen/human-mcp --env GOOGLE_GE
 
 **Setup Steps:**
 1. Install Claude Code CLI: `npm install -g @anthropic-ai/claude-code`
-2. Install Human MCP: `npm install -g @goonnguyen/human-mcp`
-3. Configure your Google Gemini API key (see Environment Setup section)
-4. Add Human MCP server using CLI or manual configuration
-5. Verify configuration: `claude mcp list`
+2. Configure your Google Gemini API key (see Environment Setup section)
+3. Add Human MCP server using CLI or manual configuration
+4. Verify configuration: `claude mcp list`
 
 **Verification:**
 ```bash
@@ -462,31 +477,10 @@ OpenCode is a powerful AI coding agent that supports MCP servers for enhanced ca
 }
 ```
 
-**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
+1. Configure your Google Gemini API key (see Environment Setup section)
+2. Add Human MCP server using CLI or manual configuration
+3. Verify configuration: `claude mcp list`
 
 **Important Notes:**
 - **STDIO Mode**: Human MCP uses stdio transport by default, which provides the best compatibility with OpenCode
@@ -502,16 +496,6 @@ OpenCode is a powerful AI coding agent that supports MCP servers for enhanced ca
 
 While Gemini CLI doesn't directly support MCP, you can use Human MCP as a bridge to access visual analysis capabilities.
 
-**Direct Usage:**
-
-```bash
-# Run Human MCP server directly (if globally installed)
-human-mcp
-
-# Or using npx (no global installation needed)
-npx @goonnguyen/human-mcp
-```
-
 **Integration Example:**
 ```bash
 # Create a wrapper script for Gemini CLI integration
@@ -552,28 +536,14 @@ These IDE extensions support MCP servers for enhanced AI-assisted coding with vi
 }
 ```
 
-**Alternative Configuration (if globally installed):**
-
-```json
-{
-  "cline.mcpServers": {
-    "human-mcp": {
-      "command": "human-mcp",
-      "env": {
-        "GOOGLE_GEMINI_API_KEY": "your_gemini_api_key_here"
-      }
-    }
-  }
-}
-```
-
 **Setup Steps:**
-1. Install Cline extension from VS Code Marketplace
-2. Install Human MCP: `npm install -g @goonnguyen/human-mcp`
-3. Open VS Code in your project directory
-4. Add Human MCP configuration to workspace settings (use `npx` version for reliability)
-5. Restart VS Code or reload the window
-6. Open Cline panel and verify MCP connection
+1. Configure your Google Gemini API key (see Environment Setup section)
+2. Add Human MCP server using CLI or manual configuration
+3. Verify configuration: `claude mcp list`
+
+**Verification:**
+- Check Cline logs for successful MCP connection
+- Try using `eyes_analyze` tool: "Analyze this screenshot for UI issues"
 
 ##### Cursor
 
@@ -597,25 +567,10 @@ These IDE extensions support MCP servers for enhanced AI-assisted coding with vi
 }
 ```
 
-**Alternative Configuration (if globally installed):**
-
-```json
-{
-  "mcp.servers": {
-    "human-mcp": {
-      "command": "human-mcp",
-      "env": {
-        "GOOGLE_GEMINI_API_KEY": "your_gemini_api_key_here"
-      }
-    }
-  }
-}
-```
-
 **Setup Steps:**
 1. Install latest version of Cursor
-2. Install Human MCP: `npm install -g @goonnguyen/human-mcp`
-3. Open your project in Cursor
+2. Configure your Google Gemini API key (see Environment Setup section)
+3. Add Human MCP server using CLI or manual configuration
 4. Configure MCP servers in settings (use `npx` version for reliability)
 5. Enable MCP integration in Cursor preferences
 6. Test visual analysis features
@@ -643,29 +598,12 @@ These IDE extensions support MCP servers for enhanced AI-assisted coding with vi
 }
 ```
 
-**Alternative Configuration (if globally installed):**
-
-```json
-{
-  "servers": {
-    "human-mcp": {
-      "command": "human-mcp",
-      "env": {
-        "GOOGLE_GEMINI_API_KEY": "your_gemini_api_key_here"
-      },
-      "timeout": 30000
-    }
-  }
-}
-```
-
 **Setup Steps:**
 1. Install Windsurf IDE
-2. Install Human MCP: `npm install -g @goonnguyen/human-mcp`
-3. Create MCP server configuration file
-4. Add Human MCP server configuration (use `npx` version for reliability)
-5. Restart Windsurf
-6. Verify connection in MCP panel
+2. Configure your Google Gemini API key (see Environment Setup section)
+3. Add Human MCP server using CLI or manual configuration
+4. Restart Windsurf
+5. Verify connection in MCP panel
 
 ### Environment Variable Setup
 
@@ -696,12 +634,6 @@ echo "source ~/.env" >> ~/.zshrc
 
 **Test Human MCP Server:**
 ```bash
-# Test the server directly (if globally installed)
-human-mcp
-
-# Or using npx (no installation needed)
-npx @goonnguyen/human-mcp
-
 # For development/testing, use the MCP inspector from source
 # (only if you have cloned the repository for development)
 cd /path/to/human-mcp && bun run inspector
@@ -719,47 +651,24 @@ cd /path/to/human-mcp && bun run inspector
 
 1. **Connection Failed**
    - Verify Node.js/npm or Bun is installed and accessible
-   - Ensure `@goonnguyen/human-mcp` package is installed
+   - Ensure `@goonnguyen/human-mcp` package is installed in the client configuration
    - Check Google Gemini API key is valid and properly configured
 
-2. **Package Not Found**
-   - Install Human MCP globally: `npm install -g @goonnguyen/human-mcp`
-   - Or use `npx @goonnguyen/human-mcp` without global installation
-   - Verify package installation: `npm list -g @goonnguyen/human-mcp`
-
-3. **Tool Not Found**
+2. **Tool Not Found**
    - Restart the MCP client after configuration changes
    - Check Human MCP server logs for errors
    - Verify the server starts: `npx @goonnguyen/human-mcp`
 
-4. **API Errors**
+3. **API Errors**
    - Validate Google Gemini API key
    - Check API quota and usage limits
    - Review network connectivity and firewall settings
 
-5. **Permission Errors**
+4. **Permission Errors**
    - Check npm global installation permissions
    - Use `npx` instead of global installation if needed
    - Verify API key has necessary permissions
 
-**Debug Steps:**
-```bash
-# Enable debug logging
-export LOG_LEVEL=debug
-
-# Run Human MCP with verbose output
-npx @goonnguyen/human-mcp --verbose
-
-# Check package installation
-npm list -g @goonnguyen/human-mcp
-
-# Test direct execution
-human-mcp --version  # if globally installed
-
-# Check MCP client logs
-# (Location varies by client - check client documentation)
-```
-
 **Getting Help:**
 - Check [Human MCP Issues](https://github.com/human-mcp/human-mcp/issues) 
 - Review client-specific MCP documentation