@goonnguyen/human-mcp 1.3.0 → 2.0.0

package/bunfig.toml

@@ -1,15 +0,0 @@
-[install]
-auto = "fallback"
-peer = false
-exact = false
-
-[install.cache]
-dir = "~/.bun/install/cache"
-disable = false
-disableManifest = false
-
-[test]
-preload = ["./tests/setup.ts"]
-
-[run]
-bun = true

package/docker-compose.yaml

@@ -1,128 +0,0 @@
-version: '3.8'
-
-services:
-  human-mcp:
-    build:
-      context: .
-      dockerfile: Dockerfile
-    image: human-mcp:latest
-    container_name: human-mcp-server
-    restart: unless-stopped
-    ports:
-      - "3000:3000"
-    environment:
-      # Core Configuration
-      - NODE_ENV=production
-      - GOOGLE_GEMINI_API_KEY=${GOOGLE_GEMINI_API_KEY}
-      - GOOGLE_GEMINI_MODEL=${GOOGLE_GEMINI_MODEL:-gemini-2.5-flash}
-      
-      # Transport Configuration
-      - TRANSPORT_TYPE=http
-      - HTTP_PORT=3000
-      - HTTP_HOST=0.0.0.0
-      - HTTP_SESSION_MODE=${HTTP_SESSION_MODE:-stateful}
-      - HTTP_ENABLE_SSE=${HTTP_ENABLE_SSE:-true}
-      - HTTP_ENABLE_JSON_RESPONSE=${HTTP_ENABLE_JSON_RESPONSE:-true}
-      
-      # Security Configuration
-      - HTTP_CORS_ENABLED=${HTTP_CORS_ENABLED:-true}
-      - HTTP_CORS_ORIGINS=${HTTP_CORS_ORIGINS:-*}
-      - HTTP_DNS_REBINDING_ENABLED=${HTTP_DNS_REBINDING_ENABLED:-true}
-      - HTTP_ALLOWED_HOSTS=${HTTP_ALLOWED_HOSTS:-127.0.0.1,localhost}
-      - HTTP_ENABLE_RATE_LIMITING=${HTTP_ENABLE_RATE_LIMITING:-false}
-      - HTTP_SECRET=${HTTP_SECRET:-}
-      
-      # Server Configuration
-      - MAX_REQUEST_SIZE=${MAX_REQUEST_SIZE:-100MB}
-      - ENABLE_CACHING=${ENABLE_CACHING:-true}
-      - CACHE_TTL=${CACHE_TTL:-3600}
-      - REQUEST_TIMEOUT=${REQUEST_TIMEOUT:-300000}
-      - FETCH_TIMEOUT=${FETCH_TIMEOUT:-60000}
-      
-      # Rate Limiting
-      - RATE_LIMIT_REQUESTS=${RATE_LIMIT_REQUESTS:-100}
-      - RATE_LIMIT_WINDOW=${RATE_LIMIT_WINDOW:-60000}
-      
-      # Logging
-      - LOG_LEVEL=${LOG_LEVEL:-info}
-    
-    volumes:
-      # Optional: Mount a volume for persistent data if needed
-      - ./data:/app/data
-    
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.routers.human-mcp.rule=Host(`${DOMAIN:-localhost}`)"
-      - "traefik.http.routers.human-mcp.entrypoints=websecure"
-      - "traefik.http.routers.human-mcp.tls.certresolver=letsencrypt"
-      - "traefik.http.services.human-mcp.loadbalancer.server.port=3000"
-    
-    networks:
-      - human-mcp-network
-    
-    # Resource limits for production
-    deploy:
-      resources:
-        limits:
-          cpus: '1.0'
-          memory: 1G
-        reservations:
-          cpus: '0.5'
-          memory: 512M
-    
-    # Health check
-    healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 15s
-
-  # Optional: Traefik reverse proxy for production deployment
-  traefik:
-    image: traefik:v3.1
-    container_name: traefik
-    restart: unless-stopped
-    profiles:
-      - proxy
-    ports:
-      - "80:80"
-      - "443:443"
-      - "8080:8080"  # Traefik dashboard (disable in production)
-    environment:
-      - TRAEFIK_API_DASHBOARD=true
-      - TRAEFIK_API_INSECURE=true
-      - TRAEFIK_ENTRYPOINTS_WEB_ADDRESS=:80
-      - TRAEFIK_ENTRYPOINTS_WEBSECURE_ADDRESS=:443
-      - TRAEFIK_PROVIDERS_DOCKER=true
-      - TRAEFIK_PROVIDERS_DOCKER_EXPOSEDBYDEFAULT=false
-      - TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_EMAIL=${ACME_EMAIL:-admin@example.com}
-      - TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_STORAGE=/letsencrypt/acme.json
-      - TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_HTTPCHALLENGE_ENTRYPOINT=web
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock:ro
-      - ./letsencrypt:/letsencrypt
-    networks:
-      - human-mcp-network
-
-  # Optional: Redis for session storage (if needed for scaling)
-  redis:
-    image: redis:7-alpine
-    container_name: human-mcp-redis
-    restart: unless-stopped
-    profiles:
-      - redis
-    ports:
-      - "6379:6379"
-    volumes:
-      - redis-data:/data
-    networks:
-      - human-mcp-network
-    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
-
-volumes:
-  redis-data:
-
-networks:
-  human-mcp-network:
-    driver: bridge

package/docs/README.md

@@ -1,51 +0,0 @@
-# Human MCP Documentation
-
-This directory contains comprehensive documentation for the Human MCP project. Navigate through the documentation using the links below for the most current information about the project's architecture, roadmap, and implementation details.
-
-## Documentation Index
-
-### 📋 Project Overview
-- **[Project Roadmap](project-roadmap.md)** - Complete development roadmap, phases, and vision through 2025
-- **[Project Overview & PDR](project-overview-pdr.md)** - Project overview and product development requirements
-- **[Codebase Summary](codebase-summary.md)** - Comprehensive overview of the current codebase
-
-### 🏗️ Architecture & Development
-- **[Architecture & Code Standards](codebase-structure-architecture-code-standards.md)** - Technical architecture, code organization, and development standards
-
-## Quick Navigation
-
-### For Developers
-If you're looking to contribute to or understand the Human MCP codebase:
-1. Start with **[Codebase Summary](codebase-summary.md)** for a high-level overview
-2. Review **[Architecture & Code Standards](codebase-structure-architecture-code-standards.md)** for technical details
-3. Check the **[Project Roadmap](project-roadmap.md)** to understand future development plans
-
-### For Product Managers
-If you're interested in the product vision and requirements:
-1. Begin with **[Project Overview & PDR](project-overview-pdr.md)** for product requirements
-2. Review **[Project Roadmap](project-roadmap.md)** for development phases and timeline
-3. Reference **[Architecture & Code Standards](codebase-structure-architecture-code-standards.md)** for technical constraints
-
-### For Users & Integrators
-If you're using Human MCP in your projects:
-1. Start with the main **[README.md](../README.md)** for setup instructions
-2. Check **[Project Overview & PDR](project-overview-pdr.md)** for capability details
-3. Refer to **[Project Roadmap](project-roadmap.md)** for upcoming features
-
-## Documentation Standards
-
-All documentation follows these principles:
-- **Accuracy**: Documentation reflects the current state of the codebase
-- **Completeness**: Comprehensive coverage of features and architecture  
-- **Clarity**: Written for both technical and non-technical audiences
-- **Currency**: Regularly updated to match code changes
-- **Cross-referencing**: Linked navigation between related documents
-
-## Last Updated
-
-This documentation structure was established to support the project roadmap and ensure comprehensive coverage of the Human MCP development vision through 2025.
-
----
-
-**Quick Links:**
-- [Main README](../README.md) | [Project Roadmap](project-roadmap.md) | [Architecture](codebase-structure-architecture-code-standards.md) | [Overview](project-overview-pdr.md)

package/docs/codebase-structure-architecture-code-standards.md

@@ -1,428 +0,0 @@
-# Human MCP - Codebase Structure, Architecture & Code Standards
-
-## Project Architecture
-
-### High-Level Architecture
-
-Human MCP follows a modular, event-driven architecture built around the Model Context Protocol (MCP). The system is designed as a server that exposes multimodal analysis capabilities through standardized MCP tools.
-
-#### Current Architecture (Phase 1 - v1.2.1)
-```
-┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
-│   MCP Client    │◄──►│   Human MCP      │◄──►│  Google Gemini  │
-│   (AI Agent)    │    │   Server         │    │   Vision API    │
-└─────────────────┘    └──────────────────┘    └─────────────────┘
-                              │
-                              ▼
-                    ┌──────────────────┐
-                    │  Media Processors │
-                    │ (Image/Video/GIF) │
-                    └──────────────────┘
-                              │
-                              ▼
-                    ┌──────────────────┐
-                    │  System Tools    │
-                    │ (ffmpeg/sharp)   │
-                    └──────────────────┘
-```
-
-#### Target Architecture (Full Roadmap - v2.0.0 by End 2025)
-
-For complete architectural evolution and development phases, see **[Project Roadmap](project-roadmap.md)** - Target Architecture section.
-
-The roadmap extends the current visual analysis foundation to include:
-- **Phase 2**: Document Understanding (Eyes extension for PDFs, Word docs, Excel)
-- **Phase 3**: Audio Processing (Ears - speech-to-text, audio analysis)
-- **Phase 4**: Speech Generation (Mouth - text-to-speech, narration)
-- **Phase 5**: Content Generation (Hands - image/video creation)
-
-### Core Components
-
-1. **MCP Server Layer**: Protocol implementation and tool registration
-2. **Tool Layer**: Visual analysis and comparison tools (`eyes.analyze`, `eyes.compare`)
-3. **Processing Layer**: Media-specific processors for different content types
-4. **Integration Layer**: External service integration (Gemini API)
-5. **Utility Layer**: Configuration, logging, error handling, and validation
-
-## Directory Structure
-
-```
-human-mcp/
-├── .claude/                    # Claude Code agent configurations
-│   ├── agents/                # Specialized agent definitions
-│   ├── commands/              # Custom commands and workflows
-│   └── hooks/                 # Git hooks and automation scripts
-├── .github/
-│   └── workflows/             # GitHub Actions for CI/CD
-├── .serena/                   # Serena MCP tool configuration
-├── docs/                      # Project documentation
-│   ├── project-roadmap.md    # Development roadmap and future vision
-│   ├── project-overview-pdr.md # Project overview and requirements
-│   ├── codebase-summary.md   # Generated codebase overview
-│   └── codebase-structure-architecture-code-standards.md # This file
-├── examples/                  # Usage examples and demonstrations
-│   └── debugging-session.ts
-├── src/                       # Source code
-│   ├── index.ts              # Entry point - starts stdio server
-│   ├── server.ts             # MCP server setup and initialization
-│   ├── tools/                # MCP tools implementation
-│   │   └── eyes/             # Vision analysis tools
-│   │       ├── index.ts      # Tool registration and orchestration
-│   │       ├── schemas.ts    # Zod validation schemas
-│   │       ├── processors/   # Media type processors
-│   │       │   ├── image.ts  # Image processing logic
-│   │       │   ├── video.ts  # Video processing with ffmpeg
-│   │       │   └── gif.ts    # GIF frame extraction
-│   │       └── utils/        # Tool-specific utilities
-│   │           ├── gemini-client.ts  # Google Gemini API client
-│   │           └── formatters.ts     # Output formatting utilities
-│   ├── prompts/              # Pre-built debugging prompts
-│   │   ├── index.ts          # Prompt registration
-│   │   └── debugging-prompts.ts      # Debugging workflow templates
-│   ├── resources/            # MCP resources (documentation)
-│   │   ├── index.ts          # Resource registration
-│   │   └── documentation.ts  # Tool documentation and examples
-│   ├── types/                # TypeScript type definitions
-│   │   └── index.ts          # Shared type definitions
-│   └── utils/                # Core utilities
-│       ├── config.ts         # Environment-based configuration
-│       ├── logger.ts         # Structured logging
-│       └── errors.ts         # Error handling and formatting
-├── tests/                    # Test suites
-│   ├── setup.ts             # Test environment setup
-│   ├── unit/                # Unit tests
-│   │   ├── config.test.ts   # Configuration validation tests
-│   │   └── formatters.test.ts       # Output formatting tests
-│   └── integration/         # Integration tests
-│       └── server.test.ts   # MCP server functionality tests
-├── dist/                    # Built output (generated)
-├── package.json             # Project dependencies and scripts
-├── tsconfig.json           # TypeScript configuration
-├── CLAUDE.md               # Claude Code project instructions
-├── QUICKSTART.md           # Quick setup guide
-└── README.md               # Project overview and setup
-```
-
-## Architectural Patterns
-
-### 1. Model Context Protocol (MCP) Architecture
-
-**Pattern**: Server-Client Protocol Implementation
-- **Server Component**: Human MCP implements MCP server specification
-- **Transport Layer**: Stdio transport for command-line integration
-- **Tool Registration**: Dynamic tool registration with schema validation
-- **Resource Exposure**: Documentation and examples exposed as MCP resources
-
-```typescript
-// MCP Server Setup Pattern
-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;
-}
-```
-
-### 2. Plugin-based Tool Architecture
-
-**Pattern**: Modular Tool Registration
-- **Tool Interface**: Standardized tool registration with schema validation
-- **Processor Strategy**: Different processors for different media types
-- **Configuration Injection**: Environment-based configuration passed to tools
-
-```typescript
-// Tool Registration Pattern
-server.registerTool(
-  "eyes.analyze",
-  {
-    title: "Vision Analysis Tool",
-    description: "Analyze images, videos, and GIFs using AI vision capabilities",
-    inputSchema: EyesInputSchema
-  },
-  async (args) => {
-    return await handleAnalyze(geminiClient, args, config);
-  }
-);
-```
-
-### 3. Strategy Pattern for Media Processing
-
-**Pattern**: Media Type Specific Processing
-- **Image Processor**: Direct processing with Gemini Vision API
-- **Video Processor**: Frame extraction using ffmpeg, then batch analysis
-- **GIF Processor**: Frame extraction using Sharp, animation sequence analysis
-
-```typescript
-// Strategy Pattern Implementation
-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}`);
-}
-```
-
-### 4. Configuration-driven Architecture
-
-**Pattern**: Environment-based Configuration with Validation
-- **Schema Validation**: Zod schemas for runtime configuration validation
-- **Environment Variables**: All configuration via environment variables
-- **Default Values**: Sensible defaults with override capability
-- **Type Safety**: Full TypeScript typing for configuration objects
-
-## Code Standards & Best Practices
-
-### 1. TypeScript Standards
-
-#### Type Safety
-- **Strict Mode**: All TypeScript strict checks enabled
-- **No Implicit Any**: Explicit typing required for all parameters
-- **Runtime Validation**: Zod schemas for external input validation
-- **Path Mapping**: `@/*` aliases for clean imports
-
-```typescript
-// Type-safe configuration pattern
-const ConfigSchema = z.object({
-  gemini: z.object({
-    apiKey: z.string().min(1, "Google Gemini API key is required"),
-    model: z.string().default("gemini-2.5-flash"),
-  }),
-  // ... other config
-});
-
-export type Config = z.infer<typeof ConfigSchema>;
-```
-
-#### Module Organization
-- **ESNext Modules**: Modern ES module syntax throughout
-- **Explicit Extensions**: `.js` extensions for all imports
-- **Barrel Exports**: Index files for clean public APIs
-- **Single Responsibility**: One primary export per file
-
-### 2. Error Handling Patterns
-
-#### Centralized Error Management
-- **Error Utility**: Centralized error handling in `utils/errors.ts`
-- **Structured Errors**: Consistent error format across all tools
-- **MCP Compliance**: Error responses conform to MCP specification
-- **Logging Integration**: All errors logged with context
-
-```typescript
-// Centralized error handling pattern
-export function handleError(error: unknown): McpError {
-  if (error instanceof Error) {
-    return {
-      code: ErrorCode.InternalError,
-      message: error.message
-    };
-  }
-  return {
-    code: ErrorCode.InternalError,
-    message: "An unknown error occurred"
-  };
-}
-```
-
-#### Graceful Degradation
-- **Try-Catch Blocks**: Comprehensive error catching
-- **Fallback Behaviors**: Graceful handling of missing dependencies
-- **User-Friendly Messages**: Clear error messages for end users
-- **Recovery Mechanisms**: Retry logic for transient failures
-
-### 3. Logging Standards
-
-#### Structured Logging
-- **Log Levels**: debug, info, warn, error with configuration
-- **Contextual Information**: Request IDs, tool names, processing steps
-- **Performance Metrics**: Timing information for operations
-- **Privacy Awareness**: No sensitive data in logs
-
-```typescript
-// Structured logging pattern
-logger.info(`Analyzing ${type} with detail level: ${detail_level}`, {
-  toolName: 'eyes.analyze',
-  mediaType: type,
-  detailLevel: detail_level,
-  processingTime: Date.now() - startTime
-});
-```
-
-### 4. Input Validation Standards
-
-#### Schema-driven Validation
-- **Zod Schemas**: Runtime validation for all external inputs
-- **Type Inference**: TypeScript types derived from schemas
-- **Descriptive Errors**: Clear validation error messages
-- **Optional Parameters**: Proper handling of optional inputs
-
-```typescript
-// Schema validation pattern
-export const EyesInputSchema = z.object({
-  source: z.string().describe("URL, file path, or base64 encoded content"),
-  type: z.enum(["image", "video", "gif"]).describe("Type of visual content"),
-  detail_level: z.enum(["quick", "detailed"]).default("detailed"),
-  // ... other fields
-});
-
-export type EyesInput = z.infer<typeof EyesInputSchema>;
-```
-
-### 5. Security Standards
-
-#### API Key Management
-- **Environment Variables**: API keys only via environment variables
-- **No Hardcoding**: Never commit API keys or secrets
-- **Configuration Validation**: Required secrets validated at startup
-- **Secure Defaults**: Security-first configuration defaults
-
-#### Input Sanitization
-- **Path Validation**: Safe file path handling
-- **URL Validation**: Proper URL parsing and validation
-- **Content Limits**: Size limits for uploaded content
-- **Rate Limiting**: Protection against abuse
-
-### 6. Performance Standards
-
-#### Memory Management
-- **Stream Processing**: Large files processed in streams where possible
-- **Cleanup**: Proper cleanup of temporary files and resources
-- **Memory Limits**: Awareness of memory constraints for media processing
-- **Garbage Collection**: Minimal object retention
-
-#### Async/Await Patterns
-- **Promise-based**: All async operations use Promise patterns
-- **Error Propagation**: Proper async error handling
-- **Concurrent Processing**: Parallel processing where beneficial
-- **Timeout Handling**: Configurable timeouts for operations
-
-```typescript
-// Async processing pattern with timeout
-async function processWithTimeout<T>(
-  operation: () => Promise<T>,
-  timeout: number
-): Promise<T> {
-  const timeoutPromise = new Promise<never>((_, reject) => {
-    setTimeout(() => reject(new Error('Operation timeout')), timeout);
-  });
-  
-  return Promise.race([operation(), timeoutPromise]);
-}
-```
-
-### 7. Testing Standards
-
-#### Test Organization
-- **Unit Tests**: Individual function and class testing
-- **Integration Tests**: End-to-end MCP server testing
-- **Test Setup**: Centralized test environment configuration
-- **Mock Usage**: Appropriate mocking of external services
-
-#### Test Coverage
-- **Core Functions**: 100% coverage for utility functions
-- **Error Paths**: Testing of error handling scenarios
-- **Configuration**: Testing of configuration validation
-- **Edge Cases**: Testing of boundary conditions
-
-### 8. Documentation Standards
-
-#### Code Documentation
-- **JSDoc Comments**: Comprehensive function documentation
-- **Type Annotations**: Clear type information
-- **Usage Examples**: Example code in documentation
-- **Architecture Notes**: High-level design documentation
-
-#### API Documentation
-- **Schema Documentation**: Clear description of input/output schemas
-- **Tool Descriptions**: Comprehensive tool functionality descriptions
-- **Integration Guides**: How to use the MCP server
-- **Configuration Reference**: Complete configuration option documentation
-
-## Development Workflow
-
-### 1. Development Commands
-
-```bash
-# Development with hot reload
-bun run dev
-
-# Production build
-bun run build
-
-# Run production build
-bun run start
-
-# Run tests
-bun test
-
-# Type checking
-bun run typecheck
-
-# Interactive tool testing
-bun run inspector
-```
-
-### 2. Code Quality Checks
-
-- **TypeScript Compilation**: No compilation errors allowed
-- **Test Passing**: All tests must pass before commits
-- **Linting**: Code style consistency (relaxed for productivity)
-- **Security Scanning**: Basic security checks on dependencies
-
-### 3. Release Process
-
-- **Semantic Versioning**: Automated version management
-- **GitHub Actions**: Automated testing and release
-- **Changelog**: Automated changelog generation
-- **npm Publishing**: Automated package publishing
-
-## Integration Patterns
-
-### 1. MCP Client Integration
-
-```javascript
-// Example MCP client integration
-const client = new McpClient();
-await client.connect(stdio('bun', ['run', 'src/index.ts']));
-
-const result = await client.callTool('eyes.analyze', {
-  source: '/path/to/screenshot.png',
-  type: 'image',
-  analysis_type: 'ui_debug'
-});
-```
-
-### 2. External Service Integration
-
-```typescript
-// Gemini API integration pattern
-export class GeminiClient {
-  constructor(private config: Config) {
-    this.genAI = new GoogleGenerativeAI(config.gemini.apiKey);
-  }
-
-  getModel(detailLevel: 'quick' | 'detailed'): GenerativeModel {
-    const modelName = detailLevel === 'quick' 
-      ? 'gemini-2.5-flash' 
-      : this.config.gemini.model;
-    return this.genAI.getGenerativeModel({ model: modelName });
-  }
-}
-```
-
-## Conclusion
-
-The Human MCP codebase follows modern TypeScript best practices with a focus on modularity, type safety, and robust error handling. The architecture enables easy extension with new tools and processors while maintaining clean separation of concerns. The comprehensive configuration system and error handling patterns ensure reliable operation across different environments and use cases.