@goonnguyen/human-mcp 1.3.0 → 2.0.0

package/src/resources/documentation.ts

@@ -1,316 +0,0 @@
-export const documentationContent = `# Human MCP API Documentation
-
-## Overview
-
-Human MCP brings human-like visual capabilities to AI coding agents, enabling them to understand and debug visual content like screenshots, recordings, and UI elements.
-
-## Available Tools
-
-### eyes.analyze
-
-Comprehensive visual analysis tool for images, videos, and GIFs.
-
-**Parameters:**
-- \`source\` (string, required): URL, file path, or base64 encoded content
-- \`type\` (enum, required): "image" | "video" | "gif"  
-- \`analysis_type\` (enum, optional): "general" | "ui_debug" | "error_detection" | "accessibility" | "performance" | "layout"
-- \`detail_level\` (enum, optional): "basic" | "detailed" | "extreme"
-- \`specific_focus\` (string, optional): Areas to focus analysis on
-- \`extract_text\` (boolean, optional): Extract text from image (default: true)
-- \`detect_ui_elements\` (boolean, optional): Detect UI elements (default: true)
-- \`analyze_colors\` (boolean, optional): Analyze color scheme (default: false)
-- \`check_accessibility\` (boolean, optional): Check accessibility (default: false)
-
-**Example:**
-\`\`\`json
-{
-  "source": "/path/to/screenshot.png",
-  "type": "image",
-  "analysis_type": "ui_debug",
-  "detail_level": "detailed",
-  "specific_focus": "login form validation errors"
-}
-\`\`\`
-
-### eyes.compare
-
-Compare two images to identify visual differences.
-
-**Parameters:**
-- \`source1\` (string, required): First image to compare
-- \`source2\` (string, required): Second image to compare  
-- \`comparison_type\` (enum, optional): "pixel" | "structural" | "semantic"
-
-**Example:**
-\`\`\`json
-{
-  "source1": "/path/to/before.png",
-  "source2": "/path/to/after.png", 
-  "comparison_type": "structural"
-}
-\`\`\`
-
-## Analysis Types
-
-### ui_debug
-Focus on layout issues, rendering problems, misalignments, and visual bugs.
-
-### error_detection  
-Look for visible error messages, error states, and system failures.
-
-### accessibility
-Analyze color contrast, readability, and WCAG compliance issues.
-
-### performance
-Identify performance indicators, loading states, and optimization opportunities.
-
-### layout
-Examine responsive design, positioning, and visual hierarchy.
-
-## Detail Levels
-
-### basic
-Concise analysis focusing on most important findings.
-
-### detailed  
-Thorough analysis with specific details about each finding.
-
-### extreme
-Exhaustive analysis with pixel-level precision and comprehensive technical details.
-
-## Common Use Cases
-
-### Debugging UI Issues
-\`\`\`json
-{
-  "source": "screenshot.png",
-  "type": "image", 
-  "analysis_type": "ui_debug",
-  "detail_level": "detailed"
-}
-\`\`\`
-
-### Analyzing Error States
-\`\`\`json
-{
-  "source": "error-recording.mp4",
-  "type": "video",
-  "analysis_type": "error_detection", 
-  "specific_focus": "form submission errors"
-}
-\`\`\`
-
-### Accessibility Audits
-\`\`\`json
-{
-  "source": "page.png",
-  "type": "image",
-  "analysis_type": "accessibility",
-  "check_accessibility": true
-}
-\`\`\`
-
-### Performance Analysis
-\`\`\`json
-{
-  "source": "loading-screen.gif",
-  "type": "gif",
-  "analysis_type": "performance"
-}
-\`\`\`
-
-## Response Format
-
-All tools return structured analysis including:
-
-- **analysis**: Detailed text analysis
-- **detected_elements**: Array of UI elements with locations
-- **debugging_insights**: Technical insights for developers  
-- **recommendations**: Actionable suggestions
-- **metadata**: Processing information and timing
-
-## Best Practices
-
-1. Use appropriate analysis types for your specific needs
-2. Provide context in \`specific_focus\` for better results
-3. Use "detailed" level for most debugging tasks
-4. Compare images when analyzing changes or regressions
-5. Include error descriptions when analyzing failures
-
-## Error Handling
-
-The server provides detailed error messages for:
-- Invalid image formats
-- Network failures when fetching URLs
-- API key issues with Gemini
-- Processing timeouts
-- Unsupported file types
-
-For support and issues: https://github.com/human-mcp/human-mcp/issues
-`;
-
-export const examplesContent = `# Human MCP Debugging Examples
-
-## Example 1: Debugging a Broken Login Form
-
-**Scenario**: Users report login button not working
-
-**Analysis Request**:
-\`\`\`json
-{
-  "source": "/screenshots/broken-login.png",
-  "type": "image",
-  "analysis_type": "ui_debug", 
-  "detail_level": "detailed",
-  "specific_focus": "login button and form validation"
-}
-\`\`\`
-
-**Key Findings**:
-- Login button appears disabled (grayed out)
-- Email field shows red border indicating validation error
-- No error message visible to user
-- Password field missing required indicator
-
-**Recommendations**:
-- Add clear error messages for validation failures
-- Ensure button state reflects form validity
-- Improve visual feedback for required fields
-
-## Example 2: Performance Issue Investigation
-
-**Scenario**: Page feels slow and unresponsive
-
-**Analysis Request**:
-\`\`\`json
-{
-  "source": "/recordings/slow-loading.mp4",
-  "type": "video",
-  "analysis_type": "performance",
-  "detail_level": "detailed"
-}
-\`\`\`
-
-**Key Findings**:
-- 3-second blank screen before content appears
-- Images loading progressively causing layout shifts
-- Spinner shows for extended periods
-- No loading state for dynamic content
-
-**Recommendations**:
-- Implement skeleton loading states
-- Optimize image loading strategy
-- Add progressive enhancement
-- Consider lazy loading for below-fold content
-
-## Example 3: Accessibility Audit
-
-**Scenario**: Ensuring WCAG compliance
-
-**Analysis Request**:
-\`\`\`json
-{
-  "source": "/screenshots/dashboard.png", 
-  "type": "image",
-  "analysis_type": "accessibility",
-  "check_accessibility": true,
-  "detail_level": "detailed"
-}
-\`\`\`
-
-**Key Findings**:
-- Color contrast ratio below 4.5:1 for secondary text
-- No visible focus indicators on interactive elements
-- Important actions only indicated by color
-- Text size appears below 16px on mobile
-
-**Recommendations**:
-- Increase contrast for all text elements
-- Add visible focus outlines
-- Use icons or text alongside color coding
-- Ensure minimum text size for readability
-
-## Example 4: Cross-Browser Layout Issues
-
-**Scenario**: Layout appears different across browsers
-
-**Comparison Request**:
-\`\`\`json
-{
-  "source1": "/screenshots/chrome-layout.png",
-  "source2": "/screenshots/firefox-layout.png",
-  "comparison_type": "structural"
-}
-\`\`\`
-
-**Key Differences**:
-- Firefox shows additional spacing in navigation
-- Button heights vary between browsers  
-- Font rendering differs affecting line heights
-- CSS Grid behavior inconsistent
-
-**Recommendations**:
-- Add CSS reset/normalize stylesheet
-- Use explicit sizing for interactive elements
-- Test with consistent font loading strategies
-- Implement browser-specific CSS if needed
-
-## Example 5: Error State Analysis
-
-**Scenario**: Application crashes under certain conditions
-
-**Analysis Request**:
-\`\`\`json
-{
-  "source": "/recordings/crash-reproduction.mp4",
-  "type": "video", 
-  "analysis_type": "error_detection",
-  "detail_level": "extreme",
-  "specific_focus": "sequence leading to white screen"
-}
-\`\`\`
-
-**Key Findings**:
-- Error occurs after clicking "Submit" on complex form
-- Brief loading state followed by blank page
-- No user feedback about what went wrong
-- Previous data appears lost
-
-**Recommendations**:
-- Implement proper error boundaries
-- Add comprehensive form validation
-- Preserve user data during errors
-- Show helpful error messages instead of blank screens
-
-## Integration Patterns
-
-### With Testing Frameworks
-\`\`\`typescript
-// Example: Automated visual regression testing
-async function visualRegressionTest(testName: string) {
-  const screenshot = await takeScreenshot();
-  
-  const analysis = await humanMcp.analyze({
-    source: screenshot,
-    type: "image",
-    analysis_type: "ui_debug",
-    detail_level: "detailed"
-  });
-  
-  if (analysis.debugging_insights.length > 0) {
-    throw new Error(\`Visual issues found: \${analysis.debugging_insights.join(', ')}\`);
-  }
-}
-\`\`\`
-
-### With CI/CD Pipelines
-\`\`\`yaml
-# Example: GitHub Actions integration
-- name: Visual Quality Check
-  run: |
-    npm run screenshot
-    human-mcp analyze screenshot.png --type=image --analysis=ui_debug
-\`\`\`
-
-These examples demonstrate the practical application of Human MCP for common debugging scenarios in web development.
-`;

package/src/resources/index.ts

@@ -1,49 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { documentationContent, examplesContent } from "./documentation.js";
-import { logger } from "@/utils/logger.js";
-
-export async function registerResources(server: McpServer) {
-  // Register API documentation resource
-  server.registerResource(
-    "api-docs",
-    "humanmcp://docs/api",
-    {
-      title: "Human MCP API Documentation",
-      description: "Complete API reference for all Human MCP tools",
-      mimeType: "text/markdown"
-    },
-    async (uri) => {
-      logger.debug(`Reading resource: ${uri.href}`);
-      
-      return {
-        contents: [{
-          uri: uri.href,
-          mimeType: "text/markdown",
-          text: documentationContent
-        }]
-      };
-    }
-  );
-
-  // Register debugging examples resource  
-  server.registerResource(
-    "debugging-examples",
-    "humanmcp://examples/debugging",
-    {
-      title: "Debugging Examples",
-      description: "Real-world examples of using Human MCP for debugging",
-      mimeType: "text/markdown"
-    },
-    async (uri) => {
-      logger.debug(`Reading resource: ${uri.href}`);
-      
-      return {
-        contents: [{
-          uri: uri.href,
-          mimeType: "text/markdown", 
-          text: examplesContent
-        }]
-      };
-    }
-  );
-}

package/src/server.ts

@@ -1,36 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { registerEyesTool } from "./tools/eyes/index.js";
-import { registerPrompts } from "./prompts/index.js";
-import { registerResources } from "./resources/index.js";
-import { logger } from "./utils/logger.js";
-import { loadConfig } from "./utils/config.js";
-
-export async function createServer() {
-  const config = loadConfig();
-  
-  const server = new McpServer({
-    name: "human-mcp",
-    version: "1.0.0",
-  });
-
-  await registerEyesTool(server, config);
-  await registerPrompts(server);
-  await registerResources(server);
-
-
-  return server;
-}
-
-export async function startStdioServer() {
-  try {
-    const server = await createServer();
-    const transport = new StdioServerTransport();
-    
-    await server.connect(transport);
-    logger.info("Human MCP Server started successfully (stdio transport)");
-  } catch (error) {
-    logger.error("Failed to start server:", error);
-    process.exit(1);
-  }
-}

package/src/tools/eyes/index.ts

@@ -1,225 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { processImage } from "./processors/image.js";
-import { processVideo } from "./processors/video.js";
-import { processGif } from "./processors/gif.js";
-import { GeminiClient } from "./utils/gemini-client.js";
-import { 
-  EyesInputSchema, 
-  CompareInputSchema,
-  type EyesInput,
-  type CompareInput
-} from "./schemas.js";
-import { logger } from "@/utils/logger.js";
-import { handleError } from "@/utils/errors.js";
-import type { Config } from "@/utils/config.js";
-
-export async function registerEyesTool(server: McpServer, config: Config) {
-  const geminiClient = new GeminiClient(config);
-  
-  // Register eyes_analyze tool
-  server.registerTool(
-    "eyes_analyze",
-    {
-      title: "Vision Analysis Tool",
-      description: "Analyze images, videos, and GIFs using AI vision capabilities",
-      inputSchema: {
-        source: z.string().describe("Path, URL, or base64 data URI of the media to analyze"),
-        type: z.enum(["image", "video", "gif"]).describe("Type of media to analyze"),
-        detail_level: z.enum(["quick", "detailed"]).optional().default("detailed").describe("Level of detail in analysis"),
-        prompt: z.string().optional().describe("Custom prompt for analysis"),
-        max_frames: z.number().optional().describe("Maximum number of frames to analyze for videos/GIFs")
-      }
-    },
-    async (args) => {
-      try {
-        return await handleAnalyze(geminiClient, args, config);
-      } catch (error) {
-        const mcpError = handleError(error);
-        logger.error(`Tool eyes_analyze error:`, mcpError);
-        
-        return {
-          content: [{
-            type: "text" as const,
-            text: `Error: ${mcpError.message}`
-          }],
-          isError: true
-        };
-      }
-    }
-  );
-
-  // Register eyes_compare tool
-  server.registerTool(
-    "eyes_compare",
-    {
-      title: "Image Comparison Tool", 
-      description: "Compare two images and identify differences",
-      inputSchema: {
-        source1: z.string().describe("Path, URL, or base64 data URI of the first image"),
-        source2: z.string().describe("Path, URL, or base64 data URI of the second image"),
-        comparison_type: z.enum(["pixel", "structural", "semantic"]).optional().default("semantic").describe("Type of comparison to perform")
-      }
-    },
-    async (args) => {
-      try {
-        return await handleCompare(geminiClient, args);
-      } catch (error) {
-        const mcpError = handleError(error);
-        logger.error(`Tool eyes_compare error:`, mcpError);
-        
-        return {
-          content: [{
-            type: "text" as const, 
-            text: `Error: ${mcpError.message}`
-          }],
-          isError: true
-        };
-      }
-    }
-  );
-}
-
-async function handleAnalyze(
-  geminiClient: GeminiClient, 
-  args: unknown,
-  config: Config
-) {
-  const input = EyesInputSchema.parse(args) as EyesInput;
-  const { source, type, detail_level } = input;
-  
-  logger.info(`Analyzing ${type} with detail level: ${detail_level}`);
-  
-  const model = geminiClient.getModel(detail_level || "detailed");
-  const options = {
-    ...input,
-    fetchTimeout: config.server.fetchTimeout
-  };
-  let result;
-  
-  switch (type) {
-    case "image":
-      result = await processImage(model, source, options);
-      break;
-    case "video":
-      result = await processVideo(model, source, options);
-      break;
-    case "gif":
-      result = await processGif(model, source, options);
-      break;
-    default:
-      throw new Error(`Unsupported media type: ${type}`);
-  }
-  
-  return {
-    content: [
-      {
-        type: "text" as const,
-        text: result.analysis
-      }
-    ],
-    isError: false
-  };
-}
-
-async function handleCompare(
-  geminiClient: GeminiClient,
-  args: unknown
-) {
-  const input = CompareInputSchema.parse(args) as CompareInput;
-  const { source1, source2, comparison_type } = input;
-  
-  logger.info(`Comparing images with type: ${comparison_type}`);
-  
-  const model = geminiClient.getModel("detailed");
-  
-  const prompt = `Compare these two images and identify the differences. Focus on:
-  
-${comparison_type === "pixel" ? 
-  "- Exact pixel-level differences\n- Color value changes\n- Any visual artifacts or rendering differences" :
-  comparison_type === "structural" ?
-  "- Layout changes\n- Element positioning differences\n- Size and proportion changes\n- Structural modifications" :
-  "- Semantic meaning differences\n- Content changes\n- Functional differences\n- User experience impact"
-}
-
-Please provide:
-1. SUMMARY: Brief overview of main differences
-2. SPECIFIC DIFFERENCES: Detailed list of changes found
-3. IMPACT ASSESSMENT: How these differences might affect users
-4. RECOMMENDATIONS: Suggested actions based on the differences
-
-Be precise with locations and measurements where possible.`;
-  
-  try {
-    const [image1Data, image2Data] = await Promise.all([
-      loadImageForComparison(source1),
-      loadImageForComparison(source2)
-    ]);
-    
-    const response = await model.generateContent([
-      { text: prompt },
-      {
-        inlineData: {
-          mimeType: image1Data.mimeType,
-          data: image1Data.data
-        }
-      },
-      { text: "Image 1 (above) vs Image 2 (below):" },
-      {
-        inlineData: {
-          mimeType: image2Data.mimeType,
-          data: image2Data.data
-        }
-      }
-    ]);
-    
-    const result = response.response;
-    const comparisonText = result.text();
-    
-    return {
-      content: [
-        {
-          type: "text" as const,
-          text: comparisonText || "No differences detected or analysis failed"
-        }
-      ],
-      isError: false
-    };
-    
-  } catch (error) {
-    throw new Error(`Failed to compare images: ${error instanceof Error ? error.message : 'Unknown error'}`);
-  }
-}
-
-async function loadImageForComparison(source: string): Promise<{ data: string; mimeType: string }> {
-  if (source.startsWith('data:image/')) {
-    const [header, data] = source.split(',');
-    if (!header || !data) {
-      throw new Error("Invalid base64 image format");
-    }
-    const mimeMatch = header.match(/data:(image\/[^;]+)/);
-    if (!mimeMatch || !mimeMatch[1]) {
-      throw new Error("Invalid base64 image format");
-    }
-    return { data, mimeType: mimeMatch[1] };
-  }
-  
-  if (source.startsWith('http://') || source.startsWith('https://')) {
-    const response = await fetch(source);
-    if (!response.ok) {
-      throw new Error(`Failed to fetch image: ${response.statusText}`);
-    }
-    const buffer = await response.arrayBuffer();
-    return {
-      data: Buffer.from(buffer).toString('base64'),
-      mimeType: response.headers.get('content-type') || 'image/jpeg'
-    };
-  }
-  
-  const fs = await import('fs/promises');
-  const buffer = await fs.readFile(source);
-  return {
-    data: buffer.toString('base64'),
-    mimeType: 'image/jpeg'
-  };
-}