@goonnguyen/human-mcp 1.0.2

package/.claude/statusline.sh

@@ -0,0 +1,143 @@
+#!/bin/bash
+# Generated by cc-statusline (https://www.npmjs.com/package/@chongdashu/cc-statusline)
+# Custom Claude Code statusline - Created: 2025-08-19T05:45:09.773Z
+# Theme: detailed | Colors: true | Features: directory, git, model, usage, session, tokens
+
+input=$(cat)
+
+# ---- color helpers (TTY-aware, respect NO_COLOR) ----
+use_color=1
+[ -t 1 ] || use_color=0
+[ -n "$NO_COLOR" ] && use_color=0
+
+C() { if [ "$use_color" -eq 1 ]; then printf '\033[%sm' "$1"; fi; }
+RST() { if [ "$use_color" -eq 1 ]; then printf '\033[0m'; fi; }
+
+# ---- basic colors ----
+dir_color() { if [ "$use_color" -eq 1 ]; then printf '\033[1;36m'; fi; }    # cyan
+model_color() { if [ "$use_color" -eq 1 ]; then printf '\033[1;35m'; fi; }  # magenta  
+version_color() { if [ "$use_color" -eq 1 ]; then printf '\033[1;33m'; fi; } # yellow
+rst() { if [ "$use_color" -eq 1 ]; then printf '\033[0m'; fi; }
+
+# ---- time helpers ----
+to_epoch() {
+  ts="$1"
+  if command -v gdate >/dev/null 2>&1; then gdate -d "$ts" +%s 2>/dev/null && return; fi
+  date -u -j -f "%Y-%m-%dT%H:%M:%S%z" "${ts/Z/+0000}" +%s 2>/dev/null && return
+  python3 - "$ts" <<'PY' 2>/dev/null
+import sys, datetime
+s=sys.argv[1].replace('Z','+00:00')
+print(int(datetime.datetime.fromisoformat(s).timestamp()))
+PY
+}
+
+fmt_time_hm() {
+  epoch="$1"
+  if date -r 0 +%s >/dev/null 2>&1; then date -r "$epoch" +"%H:%M"; else date -d "@$epoch" +"%H:%M"; fi
+}
+
+progress_bar() {
+  pct="${1:-0}"; width="${2:-10}"
+  [[ "$pct" =~ ^[0-9]+$ ]] || pct=0; ((pct<0))&&pct=0; ((pct>100))&&pct=100
+  filled=$(( pct * width / 100 )); empty=$(( width - filled ))
+  printf '%*s' "$filled" '' | tr ' ' '='
+  printf '%*s' "$empty" '' | tr ' ' '-'
+}
+
+# git utilities
+num_or_zero() { v="$1"; [[ "$v" =~ ^[0-9]+$ ]] && echo "$v" || echo 0; }
+
+# ---- basics ----
+if command -v jq >/dev/null 2>&1; then
+  current_dir=$(echo "$input" | jq -r '.workspace.current_dir // .cwd // "unknown"' 2>/dev/null | sed "s|^$HOME|~|g")
+  model_name=$(echo "$input" | jq -r '.model.display_name // "Claude"' 2>/dev/null)
+  model_version=$(echo "$input" | jq -r '.model.version // ""' 2>/dev/null)
+else
+  current_dir="unknown"
+  model_name="Claude"; model_version=""
+fi
+
+# ---- git colors ----
+git_color() { if [ "$use_color" -eq 1 ]; then printf '\033[1;32m'; fi; }
+rst() { if [ "$use_color" -eq 1 ]; then printf '\033[0m'; fi; }
+
+# ---- git ----
+git_branch=""
+if git rev-parse --git-dir >/dev/null 2>&1; then
+  git_branch=$(git branch --show-current 2>/dev/null || git rev-parse --short HEAD 2>/dev/null)
+fi
+
+# ---- usage colors ----
+usage_color() { if [ "$use_color" -eq 1 ]; then printf '\033[1;35m'; fi; }
+cost_color() { if [ "$use_color" -eq 1 ]; then printf '\033[1;36m'; fi; }
+session_color() { 
+  rem_pct=$(( 100 - session_pct ))
+  if   (( rem_pct <= 10 )); then SCLR='1;31'
+  elif (( rem_pct <= 25 )); then SCLR='1;33'
+  else                          SCLR='1;32'; fi
+  if [ "$use_color" -eq 1 ]; then printf '\033[%sm' "$SCLR"; fi
+}
+
+# ---- ccusage integration ----
+session_txt=""; session_pct=0; session_bar=""
+cost_usd=""; cost_per_hour=""; tpm=""; tot_tokens=""
+
+if command -v jq >/dev/null 2>&1; then
+  blocks_output=$(npx ccusage@latest blocks --json 2>/dev/null || ccusage blocks --json 2>/dev/null)
+  if [ -n "$blocks_output" ]; then
+    active_block=$(echo "$blocks_output" | jq -c '.blocks[] | select(.isActive == true)' 2>/dev/null | head -n1)
+    if [ -n "$active_block" ]; then
+      cost_usd=$(echo "$active_block" | jq -r '.costUSD // empty')
+      cost_per_hour=$(echo "$active_block" | jq -r '.burnRate.costPerHour // empty')
+      tot_tokens=$(echo "$active_block" | jq -r '.totalTokens // empty')
+      
+      # Session time calculation
+      reset_time_str=$(echo "$active_block" | jq -r '.usageLimitResetTime // .endTime // empty')
+      start_time_str=$(echo "$active_block" | jq -r '.startTime // empty')
+      
+      if [ -n "$reset_time_str" ] && [ -n "$start_time_str" ]; then
+        start_sec=$(to_epoch "$start_time_str"); end_sec=$(to_epoch "$reset_time_str"); now_sec=$(date +%s)
+        total=$(( end_sec - start_sec )); (( total<1 )) && total=1
+        elapsed=$(( now_sec - start_sec )); (( elapsed<0 ))&&elapsed=0; (( elapsed>total ))&&elapsed=$total
+        session_pct=$(( elapsed * 100 / total ))
+        remaining=$(( end_sec - now_sec )); (( remaining<0 )) && remaining=0
+        rh=$(( remaining / 3600 )); rm=$(( (remaining % 3600) / 60 ))
+        end_hm=$(fmt_time_hm "$end_sec")
+        session_txt="$(printf '%dh %dm until reset at %s (%d%%)' "$rh" "$rm" "$end_hm" "$session_pct")"
+        session_bar=$(progress_bar "$session_pct" 10)
+      fi
+    fi
+  fi
+fi
+
+# ---- render statusline ----
+printf '📁 %s%s%s' "$(dir_color)" "$current_dir" "$(rst)"
+# git display
+if [ -n "$git_branch" ]; then
+  printf '  🌿 %s%s%s' "$(git_color)" "$git_branch" "$(rst)"
+fi
+printf '  🤖 %s%s%s' "$(model_color)" "$model_name" "$(rst)"
+if [ -n "$model_version" ] && [ "$model_version" != "null" ]; then
+  printf '  🏷️ %s%s%s' "$(version_color)" "$model_version" "$(rst)"
+fi
+# session time
+if [ -n "$session_txt" ]; then
+  printf '  ⌛ %s%s%s' "$(session_color)" "$session_txt" "$(rst)"
+  printf '  %s[%s]%s' "$(session_color)" "$session_bar" "$(rst)"
+fi
+# cost
+if [ -n "$cost_usd" ] && [[ "$cost_usd" =~ ^[0-9.]+$ ]]; then
+  if [ -n "$cost_per_hour" ] && [[ "$cost_per_hour" =~ ^[0-9.]+$ ]]; then
+    printf '  💵 %s$%.2f ($%.2f/h)%s' "$(cost_color)" "$cost_usd" "$cost_per_hour" "$(rst)"
+  else
+    printf '  💵 %s$%.2f%s' "$(cost_color)" "$cost_usd" "$(rst)"
+  fi
+fi
+# tokens
+if [ -n "$tot_tokens" ] && [[ "$tot_tokens" =~ ^[0-9]+$ ]]; then
+  if [ -n "$tpm" ] && [[ "$tpm" =~ ^[0-9.]+$ ]] && false; then
+    printf '  📊 %s%s tok (%.0f tpm)%s' "$(usage_color)" "$tot_tokens" "$tpm" "$(rst)"
+  else
+    printf '  📊 %s%s tok%s' "$(usage_color)" "$tot_tokens" "$(rst)"
+  fi
+fi

package/.env.example

@@ -0,0 +1,17 @@
+# Gemini API Configuration
+GOOGLE_GEMINI_API_KEY=your_api_key_here
+GOOGLE_GEMINI_MODEL=gemini-2.5-flash
+
+# Server Configuration
+PORT=3000
+LOG_LEVEL=info
+MAX_REQUEST_SIZE=50MB
+ENABLE_CACHING=true
+CACHE_TTL=3600
+REQUEST_TIMEOUT=120000
+FETCH_TIMEOUT=30000
+
+# Security
+MCP_SECRET=your_secret_here
+RATE_LIMIT_REQUESTS=100
+RATE_LIMIT_WINDOW=60000

package/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: write
+      issues: write
+      pull-requests: write
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.CI_GITHUB_TOKEN }}
+      
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+      
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+      
+      - name: Run type check
+        run: bun run typecheck
+      
+      - name: Run tests
+        run: bun test
+      
+      - name: Build package
+        run: bun run build
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      
+      - name: Release
+        run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.CI_GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.releaserc.json

@@ -0,0 +1,26 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    [
+      "@semantic-release/npm",
+      {
+        "npmPublish": true,
+        "publishConfig": {
+          "access": "public",
+          "registry": "https://registry.npmjs.org/"
+        }
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["package.json", "CHANGELOG.md"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    "@semantic-release/github"
+  ]
+}

package/.serena/project.yml

@@ -0,0 +1,68 @@
+# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby)
+#  * For C, use cpp
+#  * For JavaScript, use typescript
+# Special requirements:
+#  * csharp: Requires the presence of a .sln file in the project folder.
+language: typescript
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "human-mcp"

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+## [1.0.2](https://github.com/mrgoonie/human-mcp/compare/v1.0.1...v1.0.2) (2025-09-08)
+
+
+### Bug Fixes
+
+* **ci:** configure NPM package for public publishing ([3222450](https://github.com/mrgoonie/human-mcp/commit/3222450edae2f40e86cba29dea5c3dfd35bf4fd1))
+
+## [1.0.1](https://github.com/mrgoonie/human-mcp/compare/v1.0.0...v1.0.1) (2025-09-08)
+
+
+### Bug Fixes
+
+* **config:** update NPM publishing configuration for scoped package ([caa26cd](https://github.com/mrgoonie/human-mcp/commit/caa26cd36d6967a935921b62e7478f4074cac671))
+
+# 1.0.0 (2025-09-08)
+
+
+### Bug Fixes
+
+* resolve timeout issues and improve MCP SDK integration ([ccd7f8d](https://github.com/mrgoonie/human-mcp/commit/ccd7f8d44dc9b8f9e5432092e40fa6dd99759dae))
+* **tests:** resolve type mismatches and schema alignment ([f68308b](https://github.com/mrgoonie/human-mcp/commit/f68308bc476be2e47a35da92d9b766c0c2d02a93))
+
+
+### Features
+
+* add claude agent definitions for code review, database, debugging, docs and git management ([8203456](https://github.com/mrgoonie/human-mcp/commit/8203456615ca498074657a07a25cea99b9d538fb))
+* add semantic-release automation with GitHub Actions ([3733a38](https://github.com/mrgoonie/human-mcp/commit/3733a38b1ab90ef37e44af2726ec0b3cec88932e))

package/CLAUDE.md

@@ -0,0 +1,139 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Human MCP is a Model Context Protocol server that provides AI coding agents with visual analysis capabilities for debugging UI issues, processing screenshots, videos, and GIFs using Google Gemini AI.
+
+## Development Commands
+
+### Core Commands
+- `bun run dev` - Start development server with hot reload
+- `bun run build` - Build for production (outputs to dist/)
+- `bun run start` - Run production build
+- `bun test` - Run test suite
+- `bun run typecheck` - Run TypeScript type checking
+- `bun run inspector` - Launch MCP inspector for testing tools
+
+### Testing with MCP Inspector
+The inspector tool is crucial for testing MCP tools during development:
+```bash
+bun run inspector
+```
+
+## Architecture
+
+### Core Structure
+```
+src/
+├── index.ts          # Entry point, starts stdio server
+├── server.ts         # MCP server setup and initialization  
+├── tools/eyes/       # Vision analysis tools (main functionality)
+├── prompts/          # Pre-built debugging prompts
+├── resources/        # Documentation resources
+└── utils/           # Configuration, logging, error handling
+```
+
+### Key Components
+
+**Vision Analysis (tools/eyes/)**
+- `index.ts` - Registers eyes.analyze and eyes.compare tools
+- `processors/` - Handles image, video, and GIF processing
+- `utils/gemini-client.ts` - Google Gemini API integration
+- `schemas.ts` - Zod validation schemas for tool inputs
+
+**Configuration (utils/config.ts)**
+- Environment-based configuration using Zod validation
+- Required: `GOOGLE_GEMINI_API_KEY`
+- Optional settings for timeouts, caching, rate limits
+
+## MCP Tools
+
+### eyes.analyze
+Primary tool for visual analysis of images, videos, and GIFs:
+- Supports file paths, URLs, and base64 data URIs
+- Configurable detail levels (quick/detailed)
+- Frame extraction for videos and GIFs
+- Custom analysis prompts
+
+### eyes.compare  
+Compares two images to identify visual differences:
+- Three comparison types: pixel, structural, semantic
+- Detailed difference reporting
+- Impact assessment and recommendations
+
+## Important Development Notes
+
+### 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)
+
+### Error Handling
+- All tool operations use centralized error handling via `utils/errors.ts`
+- Errors are logged and returned as structured MCP responses
+- Network timeouts are configurable via environment variables
+
+### Media Processing
+- Images: PNG, JPEG, WebP, GIF (static)
+- Videos: MP4, WebM, MOV, AVI (uses ffmpeg via fluent-ffmpeg)  
+- GIFs: Frame extraction using Sharp library
+- All processors handle file paths, URLs, and base64 data
+
+### TypeScript Configuration
+- Uses ESNext modules with bundler resolution
+- Path mapping: `@/*` maps to `src/*`
+- Strict type checking enabled
+- No emit mode (Bun handles compilation)
+
+### Google Gemini Integration
+- Uses Google Generative AI SDK
+- Model selection based on detail level
+- Configurable via `GOOGLE_GEMINI_MODEL` environment variable
+- Default: `gemini-2.5-flash`
+
+## Testing
+
+Run tests with `bun test`. The project uses Bun's built-in test runner.
+
+For manual testing of MCP tools, use the inspector:
+```bash
+bun run inspector
+```
+
+This launches a web interface for testing tool functionality interactively.
+
+---
+
+## Development Rules
+
+### General
+- Use `pnpm` instead of `npm` or `yarn` for package management
+- Use `context7` mcp tools for exploring latest docs of plugins/packages
+- Use `senera` mcp tools for semantic retrieval and editing capabilities
+
+### Code Quality Guidelines
+- Read and follow codebase structure and code standards in `./docs`
+- Don't be too harsh on code linting, but make sure there are no syntax errors and code are compilable
+- Prioritize functionality and readability over strict style enforcement and code formatting
+- Use reasonable code quality standards that enhance developer productivity
+- Use try catch error handling & cover security standards
+- Use `code-reviewer` agent to review code after every implementation
+
+### Pre-commit/Push Rules
+- Run linting before commit
+- Run tests before push (DO NOT ignore failed tests just to pass the build or github actions)
+- Keep commits focused on the actual code changes
+- **DO NOT** commit and push any confidential information (such as dotenv files, API keys, database credentials, etc.) to git repository!
+- NEVER automatically add AI attribution signatures like:
+  "🤖 Generated with [Claude Code]"
+  "Co-Authored-By: Claude noreply@anthropic.com"
+  Any AI tool attribution or signature
+- Create clean, professional commit messages without AI references. Use conventional commit format.

package/Dockerfile

@@ -0,0 +1,28 @@
+FROM oven/bun:1.2.19-alpine
+
+WORKDIR /app
+
+# Install system dependencies for video processing
+RUN apk add --no-cache ffmpeg
+
+# Copy package files
+COPY package.json bun.lockb* ./
+
+# Install dependencies
+RUN bun install --frozen-lockfile
+
+# Copy source code
+COPY . .
+
+# Build the application
+RUN bun run build
+
+# Expose port
+EXPOSE 3000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD bun run dist/index.js --help || exit 1
+
+# Run the application
+CMD ["bun", "run", "dist/index.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Human MCP
+
+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/QUICKSTART.md

@@ -0,0 +1,97 @@
+# Human MCP Quickstart Guide
+
+Get up and running with Human MCP in less than 5 minutes!
+
+## 🚀 Quick Installation
+
+```bash
+# 1. Clone and install
+git clone https://github.com/human-mcp/human-mcp.git
+cd human-mcp
+bun install
+
+# 2. Set up environment
+cp .env.example .env
+# Edit .env and add your GOOGLE_GEMINI_API_KEY
+
+# 3. Start the server
+bun run dev
+```
+
+## 📱 Configuration for Claude Desktop
+
+Add this to your Claude Desktop config file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "human-mcp": {
+      "command": "bun",
+      "args": ["run", "/path/to/human-mcp/src/index.ts"],
+      "env": {
+        "GOOGLE_GEMINI_API_KEY": "your_actual_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## 🔧 Get Your Gemini API Key
+
+1. Visit [Google AI Studio](https://aistudio.google.com/)
+2. Click "Get API Key"
+3. Create a new project or use existing one
+4. Copy your API key
+
+## ✅ Test Your Installation
+
+Try this in Claude Desktop:
+
+```
+Can you analyze this screenshot for UI bugs?
+[Upload a screenshot]
+```
+
+Human MCP should analyze the image and provide detailed debugging insights!
+
+## 🎯 Common Use Cases
+
+### Debug UI Issues
+```
+Use the eyes.analyze tool with this screenshot:
+- Type: image
+- Analysis type: ui_debug  
+- Detail level: detailed
+```
+
+### Analyze Error Recordings
+```
+Use the eyes.analyze tool with this screen recording:
+- Type: video
+- Analysis type: error_detection
+- Focus on: the error sequence
+```
+
+### Check Accessibility
+```
+Use the eyes.analyze tool:
+- Analysis type: accessibility
+- Check accessibility: true
+```
+
+## 🆘 Troubleshooting
+
+**"Tool not found"** → Restart Claude Desktop after config changes
+**"API key error"** → Check your GOOGLE_GEMINI_API_KEY in .env or config
+**"Permission denied"** → Make sure bun is installed and executable
+
+## 📖 Next Steps
+
+- Read the full [README.md](README.md) for detailed documentation
+- Try the [example debugging session](examples/debugging-session.ts)
+- Check out the [API documentation](src/resources/documentation.ts)
+
+Happy debugging! 🐛✨