@goonnguyen/human-mcp 1.2.0 → 1.3.0

package/tests/utils/test-server-manager.ts

@@ -0,0 +1,172 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { startHttpTransport } from "../../src/transports/http/server.js";
+import type { HttpTransportConfig, HttpServerHandle } from "../../src/transports/types.js";
+
+export class TestServerManager {
+  private servers: Map<number, HttpServerHandle> = new Map();
+  private usedPorts: Set<number> = new Set();
+
+  /**
+   * Get a random available port for testing using OS-level port checking
+   */
+  async getAvailablePort(): Promise<number> {
+    // Try sequential ports starting from a random high port
+    const basePort = 4000 + Math.floor(Math.random() * 1000);
+    const maxAttempts = 50;
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const port = basePort + attempt;
+      
+      if (!this.usedPorts.has(port) && await this.isPortAvailable(port)) {
+        this.usedPorts.add(port);
+        return port;
+      }
+    }
+
+    throw new Error(`Unable to find available port after ${maxAttempts} attempts (tried ${basePort} to ${basePort + maxAttempts - 1})`);
+  }
+
+  /**
+   * Check if a port is available using Node.js net module
+   */
+  private async isPortAvailable(port: number): Promise<boolean> {
+    return new Promise((resolve) => {
+      const net = require('net');
+      const server = net.createServer();
+      
+      server.listen(port, '127.0.0.1', () => {
+        server.close(() => {
+          resolve(true);
+        });
+      });
+      
+      server.on('error', () => {
+        resolve(false);
+      });
+    });
+  }
+
+  /**
+   * Start a test server with the given configuration
+   */
+  async startTestServer(config: Partial<HttpTransportConfig> = {}): Promise<{
+    server: HttpServerHandle;
+    port: number;
+    baseUrl: string;
+  }> {
+    const port = await this.getAvailablePort();
+    
+    // Create a basic MCP server for testing
+    const mcpServer = new McpServer(
+      {
+        name: "test-server",
+        version: "1.0.0"
+      },
+      {
+        capabilities: {
+          tools: {}
+        }
+      }
+    );
+
+    const serverConfig: HttpTransportConfig = {
+      port,
+      host: "127.0.0.1",
+      sessionMode: "stateful",
+      enableSse: true,
+      enableJsonResponse: true,
+      enableSseFallback: true,
+      ssePaths: {
+        stream: "/sse",
+        message: "/messages"
+      },
+      security: {
+        enableCors: true,
+        enableDnsRebindingProtection: true,
+        allowedHosts: ["127.0.0.1", "localhost"]
+      },
+      ...config
+    };
+
+    const server = await startHttpTransport(mcpServer, serverConfig);
+    this.servers.set(port, server);
+
+    // Wait for server to be ready
+    await this.waitForServerReady(port);
+
+    return {
+      server,
+      port,
+      baseUrl: `http://127.0.0.1:${port}`
+    };
+  }
+
+  /**
+   * Wait for server to be ready by checking health endpoint
+   */
+  private async waitForServerReady(port: number, timeout = 15000): Promise<void> {
+    const startTime = Date.now();
+    let lastError: Error | undefined;
+    
+    while (Date.now() - startTime < timeout) {
+      try {
+        const response = await fetch(`http://127.0.0.1:${port}/health`, {
+          signal: AbortSignal.timeout(2000)
+        });
+        
+        if (response.ok) {
+          const health = await response.json() as { status: string };
+          if (health.status === 'healthy') {
+            // Give the server a bit more time to fully initialize
+            await new Promise(resolve => setTimeout(resolve, 200));
+            return;
+          }
+        }
+      } catch (error) {
+        lastError = error as Error;
+        // Server not ready yet, continue waiting
+      }
+      
+      await new Promise(resolve => setTimeout(resolve, 250));
+    }
+    
+    throw new Error(`Server on port ${port} did not become ready within ${timeout}ms. Last error: ${lastError?.message || 'Unknown'}`);
+  }
+
+  /**
+   * Stop a specific server by port
+   */
+  async stopServer(port: number): Promise<void> {
+    const server = this.servers.get(port);
+    if (server) {
+      await server.close();
+      this.servers.delete(port);
+      this.usedPorts.delete(port);
+    }
+  }
+
+  /**
+   * Stop all test servers
+   */
+  async stopAllServers(): Promise<void> {
+    const stopPromises = Array.from(this.servers.keys()).map(port => this.stopServer(port));
+    await Promise.all(stopPromises);
+  }
+
+  /**
+   * Get the number of active servers
+   */
+  getActiveServerCount(): number {
+    return this.servers.size;
+  }
+
+  /**
+   * Check if any servers are still running
+   */
+  hasActiveServers(): boolean {
+    return this.servers.size > 0;
+  }
+}
+
+// Global test server manager instance
+export const testServerManager = new TestServerManager();

package/tsconfig.json

@@ -21,6 +21,6 @@
       "@/*": ["*"]
     }
   },
-  "include": ["src/**/*"],
+  "include": ["src/**/*", "tests/**/*"],
   "exclude": ["node_modules", "dist"]
 }

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

@@ -1,188 +0,0 @@
-# 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