@goonnguyen/human-mcp 1.0.2

package/inspector-wrapper.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+// Workaround for eventsource ESM import issues
+import { createRequire } from 'module';
+import { spawn } from 'child_process';
+
+const require = createRequire(import.meta.url);
+
+// Try to fix the eventsource import by patching the module resolution
+const Module = require('module');
+const originalResolveFilename = Module._resolveFilename;
+
+Module._resolveFilename = function (request, parent, isMain, options) {
+  if (request === 'eventsource' && parent?.filename?.includes('@modelcontextprotocol/inspector')) {
+    // Force CommonJS resolution for eventsource
+    return require.resolve('eventsource');
+  }
+  return originalResolveFilename.call(this, request, parent, isMain, options);
+};
+
+// Run the inspector with the command line args
+const args = process.argv.slice(2);
+const child = spawn('npx', ['@modelcontextprotocol/inspector', ...args], {
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    NODE_OPTIONS: '--loader ./inspector-loader.mjs'
+  }
+});
+
+child.on('close', (code) => {
+  process.exit(code);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@goonnguyen/human-mcp",
+  "version": "1.0.2",
+  "description": "Human MCP: Bringing Human Capabilities to Coding Agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "scripts": {
+    "dev": "bun run --watch src/index.ts",
+    "build": "bun build src/index.ts --target=node --outdir=dist",
+    "start": "bun run dist/index.js",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "inspector": "mcp-inspector stdio -- bun run src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.4.0",
+    "zod": "^3.23.0",
+    "@google/generative-ai": "^0.21.0",
+    "sharp": "^0.33.0",
+    "fluent-ffmpeg": "^2.1.3"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/inspector": "^0.2.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.5",
+    "@semantic-release/npm": "^12.0.2",
+    "@types/bun": "latest",
+    "@types/fluent-ffmpeg": "^2.1.26",
+    "semantic-release": "^24.2.7",
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "multimodal",
+    "vision",
+    "debugging"
+  ],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plans/reports/001-from-qa-engineer-to-development-team-test-suite-report.md

@@ -0,0 +1,188 @@
+# Human MCP Test Suite Analysis Report
+
+**Report Generated:** September 8, 2025  
+**Project:** Human MCP - Model Context Protocol Server  
+**Test Framework:** Bun Test  
+**Report By:** QA Engineer
+
+## Executive Summary
+
+The test suite execution reveals **3 failing tests out of 10 total tests** (70% pass rate). While TypeScript compilation passes successfully, there are critical inconsistencies between test expectations and actual implementation that need immediate attention.
+
+## Test Results Overview
+
+- **Total Tests:** 10
+- **Tests Passed:** 7 (70%)
+- **Tests Failed:** 3 (30%)  
+- **Tests Skipped:** 0
+- **Execution Time:** 417ms
+- **TypeScript Compilation:** ✅ PASS
+
+## Detailed Test Failures
+
+### 1. Formatters Test Failure: Accessibility Prompt
+
+**File:** `tests/unit/formatters.test.ts`  
+**Test:** "should create accessibility prompt"  
+**Status:** ❌ FAIL
+
+**Issue:** Test expects "concise analysis" text in accessibility prompt for basic detail level, but the actual implementation uses "Provide a concise analysis focusing on the most important findings." instead.
+
+**Expected:** `"concise analysis"`  
+**Received:** Full prompt text without the expected substring
+
+**Root Cause:** Mismatch between test expectations and the `createPrompt()` function implementation in `src/tools/eyes/utils/formatters.ts`.
+
+### 2. Config Test Failure: Default Model Mismatch
+
+**File:** `tests/unit/config.test.ts`  
+**Test:** "should override defaults with environment variables"  
+**Status:** ❌ FAIL
+
+**Issue:** Test expects `"gemini-2.0-flash-exp"` model but actual implementation returns `"gemini-2.5-flash"`.
+
+**Expected:** `"gemini-2.0-flash-exp"`  
+**Received:** `"gemini-2.5-flash"`
+
+**Root Cause:** The test is setting `process.env.GOOGLE_GEMINI_MODEL = "gemini-2.5-flash"` but expecting a different model name in the assertion.
+
+### 3. Server Integration Test Failure: Type Mismatch
+
+**File:** `tests/integration/server.test.ts`  
+**Test:** "should be properly configured"  
+**Status:** ❌ FAIL
+
+**Issue:** Test expects server to be instance of `Server` class but receives `McpServer` instance.
+
+**Expected:** Instance of `Server` (from `@modelcontextprotocol/sdk/server/index.js`)  
+**Received:** Instance of `McpServer`
+
+**Root Cause:** Incorrect import and type expectation. The `createServer()` function returns `McpServer` instance, not `Server`.
+
+## Coverage Analysis
+
+**Note:** No coverage metrics are currently configured in the project. The package.json does not include coverage scripts.
+
+**Recommendations for Coverage:**
+- Add coverage collection with `bun test --coverage`
+- Target minimum 80% coverage for critical paths
+- Focus on vision analysis tools and configuration validation
+
+## Performance Metrics
+
+- **Test Execution Time:** 417ms (Acceptable)
+- **Slowest Individual Test:** ~1.54ms (Server creation test)
+- **Average Test Time:** ~41.7ms per test
+
+The test performance is excellent with sub-second execution time.
+
+## Critical Issues Requiring Immediate Attention
+
+### High Priority
+1. **Config Test Logic Error:** Test is setting an environment variable to one value but expecting a different value
+2. **Server Type Mismatch:** Import and expectation mismatch for server type
+
+### Medium Priority  
+1. **Formatter Test Expectations:** String matching issues in prompt generation tests
+
+## Detailed Recommendations
+
+### 1. Fix Config Test (HIGH PRIORITY)
+**Location:** `tests/unit/config.test.ts:28`
+
+```typescript
+// Current problematic code:
+process.env.GOOGLE_GEMINI_MODEL = "gemini-2.5-flash";
+expect(config.gemini.model).toBe("gemini-2.0-flash-exp"); // Wrong expectation
+
+// Should be:
+process.env.GOOGLE_GEMINI_MODEL = "gemini-2.0-flash-exp";  
+expect(config.gemini.model).toBe("gemini-2.0-flash-exp");
+```
+
+### 2. Fix Server Type Test (HIGH PRIORITY)
+**Location:** `tests/integration/server.test.ts:22`
+
+```typescript
+// Current problematic code:
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+expect(server).toBeInstanceOf(Server);
+
+// Should be:
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+expect(server).toBeInstanceOf(McpServer);
+```
+
+### 3. Fix Formatter Test (MEDIUM PRIORITY)
+**Location:** `tests/unit/formatters.test.ts:30`
+
+Update test expectation to match actual implementation:
+```typescript
+// Either update the test expectation:
+expect(prompt).toContain("Provide a concise analysis");
+
+// Or update the formatters.ts implementation to include "concise analysis"
+```
+
+### 4. Add Test Coverage (MEDIUM PRIORITY)
+Add to package.json:
+```json
+{
+  "scripts": {
+    "test:coverage": "bun test --coverage",
+    "test:watch": "bun test --watch"
+  }
+}
+```
+
+### 5. Enhance Test Suite (LOW PRIORITY)
+- Add error scenario testing for vision analysis tools  
+- Add integration tests for Google Gemini API calls (with mocking)
+- Add performance benchmarks for image/video processing
+- Add end-to-end tests for MCP protocol compliance
+
+## Test Quality Assessment
+
+### Strengths
+- Good separation between unit and integration tests
+- Proper use of test setup/teardown with `beforeEach`/`afterAll`
+- Environment variable management in tests
+- Structured test organization
+
+### Weaknesses  
+- Missing error scenario coverage
+- No mocking for external dependencies (Google Gemini API)
+- Limited edge case testing
+- Missing performance validation tests
+
+## Security Considerations
+
+- Tests properly manage environment variables for API keys
+- No sensitive data leakage detected in test files
+- Test environment isolation appears adequate
+
+## Next Steps (Prioritized)
+
+1. **IMMEDIATE:** Fix the 3 failing tests by correcting assertions and imports
+2. **SHORT TERM:** Add test coverage collection and reporting  
+3. **MEDIUM TERM:** Expand test suite with error scenarios and edge cases
+4. **LONG TERM:** Add performance benchmarks and comprehensive integration tests
+
+## Build Process Verification
+
+- **TypeScript Compilation:** ✅ PASS - No type errors detected
+- **Dependency Resolution:** ✅ PASS - All imports resolve correctly  
+- **Build Configuration:** ✅ PASS - Project builds successfully
+
+## Files Requiring Attention
+
+1. `/Users/duynguyen/www/human-mcp/tests/unit/config.test.ts` - Fix environment variable test logic
+2. `/Users/duynguyen/www/human-mcp/tests/integration/server.test.ts` - Fix server type expectation  
+3. `/Users/duynguyen/www/human-mcp/tests/unit/formatters.test.ts` - Update string expectations
+4. `/Users/duynguyen/www/human-mcp/package.json` - Add coverage scripts
+
+---
+
+**Quality Gate Status:** ❌ BLOCKED  
+**Reason:** 3 failing tests prevent production deployment  
+**Required Action:** Fix failing tests before proceeding with any releases

package/plans/templates/bug-fix-template.md

@@ -0,0 +1,69 @@
+# [Bug Fix] Implementation Plan
+
+**Date**: YYYY-MM-DD  
+**Type**: Bug Fix  
+**Priority**: [Critical/High/Medium/Low]  
+**Context Tokens**: <150 words
+
+## Executive Summary
+Brief description of the bug and its impact.
+
+## Issue Analysis
+### Symptoms
+- [ ] Symptom 1
+- [ ] Symptom 2
+
+### Root Cause
+Brief explanation of the underlying cause.
+
+### Evidence
+- **Logs**: Reference to log files (don't include full logs)
+- **Error Messages**: Key error patterns
+- **Affected Components**: List of impacted files/modules
+
+## Context Links
+- **Related Issues**: [GitHub issue numbers]
+- **Recent Changes**: [Relevant commits or PRs]
+- **Dependencies**: [Related systems]
+
+## Solution Design
+### Approach
+High-level fix strategy in 2-3 sentences.
+
+### Changes Required
+1. **File 1** (`path/to/file.ts`): Brief change description
+2. **File 2** (`path/to/file.ts`): Brief change description
+
+### Testing Changes
+- [ ] Update existing tests
+- [ ] Add new test cases
+- [ ] Validate fix doesn't break existing functionality
+
+## Implementation Steps
+1. [ ] Step 1 - file: `path/to/file.ts`
+2. [ ] Step 2 - file: `path/to/file.ts`
+3. [ ] Run test suite
+4. [ ] Validate fix in relevant environments
+
+## Verification Plan
+### Test Cases
+- [ ] Test case 1: Expected behavior
+- [ ] Test case 2: Edge case handling
+- [ ] Regression test: Ensure no new issues
+
+### Rollback Plan
+If the fix causes issues:
+1. Revert commit: `git revert <commit-hash>`
+2. Restore previous behavior in files X, Y, Z
+
+## Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Risk 1 | Medium | Mitigation plan |
+
+## TODO Checklist
+- [ ] Implement fix
+- [ ] Update tests
+- [ ] Run full test suite
+- [ ] Code review
+- [ ] Deploy and verify

package/plans/templates/feature-implementation-template.md

@@ -0,0 +1,84 @@
+# [Feature Name] Implementation Plan
+
+**Date**: YYYY-MM-DD  
+**Type**: Feature Implementation  
+**Status**: Planning  
+**Context Tokens**: <200 words
+
+## Executive Summary
+Brief 2-3 sentence description of the feature and its business value.
+
+## Context Links
+- **Related Plans**: [List other plan files - no full content]
+- **Dependencies**: [External systems, APIs, existing features]
+- **Reference Docs**: [Link to docs in ./docs directory]
+
+## Requirements
+### Functional Requirements
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+### Non-Functional Requirements  
+- [ ] Performance target
+- [ ] Security requirement
+- [ ] Scalability requirement
+
+## Architecture Overview
+```mermaid
+[Simple component diagram]
+```
+
+### Key Components
+- **Component 1**: Brief description
+- **Component 2**: Brief description
+
+### Data Models
+- **Model 1**: Key fields
+- **Model 2**: Key fields
+
+## Implementation Phases
+
+### Phase 1: [Name] (Est: X days)
+**Scope**: Specific boundaries
+**Tasks**:
+1. [ ] Task 1 - file: `path/to/file.ts`
+2. [ ] Task 2 - file: `path/to/file.ts`
+
+**Acceptance Criteria**:
+- [ ] Criteria 1
+- [ ] Criteria 2
+
+### Phase 2: [Name] (Est: X days)
+[Repeat structure]
+
+## Testing Strategy
+- **Unit Tests**: Specific test coverage targets
+- **Integration Tests**: Key interaction points
+- **E2E Tests**: Critical user flows
+
+## Security Considerations
+- [ ] Security item 1
+- [ ] Security item 2
+
+## Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Risk 1 | High | Mitigation strategy |
+
+## Quick Reference
+### Key Commands
+```bash
+npm run command
+```
+
+### Configuration Files
+- `config/file.ts`: Purpose
+- `.env.example`: Environment variables
+
+## TODO Checklist
+- [ ] Phase 1 Task 1
+- [ ] Phase 1 Task 2
+- [ ] Phase 2 Task 1
+- [ ] Testing complete
+- [ ] Documentation updated
+- [ ] Code review passed

package/plans/templates/refactor-template.md

@@ -0,0 +1,82 @@
+# [Component/Module] Refactoring Plan
+
+**Date**: YYYY-MM-DD  
+**Type**: Refactoring  
+**Scope**: [Module/Component/System level]  
+**Context Tokens**: <200 words
+
+## Executive Summary
+Brief description of what is being refactored and why.
+
+## Current State Analysis
+### Issues with Current Implementation
+- [ ] Issue 1: Performance bottleneck
+- [ ] Issue 2: Code maintainability
+- [ ] Issue 3: Technical debt
+
+### Metrics (Before)
+- **Performance**: Current benchmarks
+- **Code Quality**: Complexity metrics
+- **Test Coverage**: Current percentage
+
+## Context Links
+- **Affected Modules**: [List without full content]
+- **Dependencies**: [Other systems impacted]
+- **Related Documentation**: [Links to docs]
+
+## Refactoring Strategy
+### Approach
+High-level strategy for the refactoring in 2-3 sentences.
+
+### Architecture Changes
+```mermaid
+[Before/After comparison diagram]
+```
+
+### Key Improvements
+- **Improvement 1**: Brief description
+- **Improvement 2**: Brief description
+
+## Implementation Plan
+
+### Phase 1: Preparation (Est: X days)
+**Scope**: Setup and preparation work
+1. [ ] Create comprehensive tests for current functionality
+2. [ ] Document current behavior
+3. [ ] Identify all dependencies
+
+### Phase 2: Core Refactoring (Est: X days)
+**Scope**: Main refactoring work
+1. [ ] Refactor component A - file: `path/to/file.ts`
+2. [ ] Refactor component B - file: `path/to/file.ts`
+3. [ ] Update integration points
+
+### Phase 3: Integration & Testing (Est: X days)
+**Scope**: Validation and cleanup
+1. [ ] Integration testing
+2. [ ] Performance validation
+3. [ ] Documentation updates
+
+## Backward Compatibility
+- **Breaking Changes**: [List any breaking changes]
+- **Migration Path**: [Steps for users/systems]
+- **Deprecation Timeline**: [If applicable]
+
+## Success Metrics (After)
+- **Performance**: Target improvements
+- **Code Quality**: Target metrics
+- **Test Coverage**: Target percentage
+
+## Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Breaking changes | High | Comprehensive testing |
+| Performance regression | Medium | Benchmarking |
+
+## TODO Checklist
+- [ ] Phase 1: Preparation complete
+- [ ] Phase 2: Core refactoring complete  
+- [ ] Phase 3: Integration complete
+- [ ] Performance benchmarks validated
+- [ ] Documentation updated
+- [ ] Code review passed

package/plans/templates/template-usage-guide.md

@@ -0,0 +1,58 @@
+# Plan Template Usage Guide
+
+## Template Selection
+
+### Feature Implementation Template
+**Use when**: Adding new functionality, endpoints, services, or modules
+**File**: `feature-implementation-template.md`
+**Size**: Medium to large scope changes
+
+### Bug Fix Template  
+**Use when**: Fixing specific issues, errors, or broken functionality
+**File**: `bug-fix-template.md`
+**Size**: Small to medium scope changes
+
+### Refactoring Template
+**Use when**: Improving code structure, performance, or maintainability without changing functionality
+**File**: `refactor-template.md` 
+**Size**: Medium to large scope changes
+
+## Context Management Best Practices
+
+### Keep Plans Focused
+- **Executive Summary**: Max 3 sentences
+- **Context Links**: Reference files, don't include full content
+- **Tasks**: Max 10 per phase
+- **Context Tokens**: Target <200 words for summaries
+
+### Template Adaptation
+1. Copy the appropriate template to `plans/NNN-feature-name-plan.md`
+2. Replace bracketed placeholders with actual content
+3. Remove sections not relevant to your specific use case
+4. Keep the core structure intact for consistency
+
+### Cross-References Instead of Duplication
+- Link to existing documentation in `./docs/`
+- Reference other plans without copying content
+- Use file paths instead of code blocks where possible
+- Focus on "what" and "why", not detailed "how"
+
+## Quality Checklist
+
+Before finalizing any plan:
+- [ ] Executive summary is clear and concise
+- [ ] Tasks are specific and actionable
+- [ ] File paths are included for implementation tasks
+- [ ] Success criteria are measurable
+- [ ] Context links are used instead of full content
+- [ ] TODO checklist is complete and realistic
+
+## Context Refresh Triggers
+
+Use these templates when:
+- Starting a new development phase
+- Switching between different types of work (feature → bugfix)
+- After major context accumulation (>8000 tokens)
+- When agent handoffs occur
+
+This ensures each plan starts with fresh, focused context optimized for the specific task type.

package/src/index.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+
+import { startStdioServer } from "./server.js";
+
+await startStdioServer();