@vibescope/mcp-server 0.2.9 → 0.3.1

package/src/index.test.ts

@@ -0,0 +1,674 @@
+/**
+ * Tests for MCP Server Entry Point (index.ts)
+ *
+ * Tests covering:
+ * 1. Server lifecycle (startup, shutdown, signal handling)
+ * 2. Tool routing and handler selection
+ * 3. Error handling and recovery
+ * 4. Rate limiting behavior
+ * 5. Token usage tracking
+ * 6. Request/response formatting
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach, beforeAll, afterAll } from 'vitest';
+
+// =============================================================================
+// Mock Setup - MUST be before any imports that use these modules
+// =============================================================================
+
+// Store original env
+const originalEnv = process.env.VIBESCOPE_API_KEY;
+
+// Mock the MCP SDK
+const mockServerConnect = vi.fn().mockResolvedValue(undefined);
+const mockSetRequestHandler = vi.fn();
+const mockServer = {
+	connect: mockServerConnect,
+	setRequestHandler: mockSetRequestHandler,
+};
+vi.mock('@modelcontextprotocol/sdk/server/index.js', () => ({
+	Server: vi.fn(() => mockServer),
+}));
+
+const mockTransport = {};
+vi.mock('@modelcontextprotocol/sdk/server/stdio.js', () => ({
+	StdioServerTransport: vi.fn(() => mockTransport),
+}));
+
+// Mock the API client
+const mockValidateAuth = vi.fn();
+const mockSyncSession = vi.fn().mockResolvedValue(undefined);
+const mockApiClient = {
+	validateAuth: mockValidateAuth,
+	syncSession: mockSyncSession,
+};
+vi.mock('./api-client.js', () => ({
+	initApiClient: vi.fn(),
+	getApiClient: vi.fn(() => mockApiClient),
+}));
+
+// Mock handlers registry
+const mockHandlerResult = { result: { success: true }, user_updates: null };
+const mockHandler = vi.fn().mockResolvedValue(mockHandlerResult);
+const mockHandlerRegistry: Record<string, typeof mockHandler> = {
+	get_next_task: mockHandler,
+	complete_task: mockHandler,
+	update_task: mockHandler,
+	add_task: mockHandler,
+	start_work_session: mockHandler,
+	get_help: mockHandler,
+};
+vi.mock('./handlers/index.js', () => ({
+	buildHandlerRegistry: vi.fn(() => mockHandlerRegistry),
+}));
+
+// Mock token tracking
+const mockTokenUsage = {
+	totalInputTokens: 0,
+	totalOutputTokens: 0,
+	callCount: 0,
+	toolCounts: new Map(),
+};
+vi.mock('./token-tracking.js', () => ({
+	createTokenUsage: vi.fn(() => mockTokenUsage),
+	trackTokenUsage: vi.fn(),
+	setCurrentModel: vi.fn(),
+}));
+
+// Mock tools
+vi.mock('./tools.js', () => ({
+	tools: [
+		{ name: 'get_next_task', description: 'Get next task', inputSchema: { type: 'object' } },
+		{ name: 'complete_task', description: 'Complete task', inputSchema: { type: 'object' } },
+	],
+}));
+
+// Mock utils
+vi.mock('./utils.js', () => ({
+	AGENT_PERSONAS: ['Thor', 'Loki', 'Odin'],
+	FALLBACK_ACTIVITIES: ['code_review', 'security_review'],
+	getRandomFallbackActivity: vi.fn(() => 'code_review'),
+	selectPersona: vi.fn(() => 'Thor'),
+	RateLimiter: class MockRateLimiter {
+		check = vi.fn().mockReturnValue({ allowed: true, remaining: 50, resetIn: 60000 });
+		cleanup = vi.fn();
+	},
+	extractProjectNameFromGitUrl: vi.fn((url: string) => 'test-project'),
+	isValidStatusTransition: vi.fn(() => true),
+}));
+
+// Mock validators
+vi.mock('./validators.js', () => ({
+	ValidationError: class ValidationError extends Error {
+		constructor(
+			public field: string,
+			message: string,
+			public expected?: string
+		) {
+			super(message);
+			this.name = 'ValidationError';
+		}
+		toJSON() {
+			return { error: 'validation_error', field: this.field, message: this.message };
+		}
+	},
+	validateRequired: vi.fn(),
+	validateUUID: vi.fn(),
+	validateTaskStatus: vi.fn(),
+	validateProjectStatus: vi.fn(),
+	validatePriority: vi.fn(),
+	validateProgressPercentage: vi.fn(),
+	validateEstimatedMinutes: vi.fn(),
+	validateEnvironment: vi.fn(),
+	VALID_TASK_STATUSES: ['pending', 'in_progress', 'completed'],
+	VALID_PROJECT_STATUSES: ['active', 'paused', 'completed'],
+	VALID_BLOCKER_STATUSES: ['open', 'resolved'],
+	VALID_DEPLOYMENT_STATUSES: ['pending', 'deploying', 'completed'],
+	VALID_ENVIRONMENTS: ['development', 'staging', 'production'],
+}));
+
+// =============================================================================
+// Test Suites
+// =============================================================================
+
+describe('MCP Server Entry Point', () => {
+	beforeAll(() => {
+		// Set required env var
+		process.env.VIBESCOPE_API_KEY = 'test-api-key-12345';
+	});
+
+	afterAll(() => {
+		// Restore original env
+		if (originalEnv !== undefined) {
+			process.env.VIBESCOPE_API_KEY = originalEnv;
+		} else {
+			delete process.env.VIBESCOPE_API_KEY;
+		}
+	});
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		// Default: valid auth
+		mockValidateAuth.mockResolvedValue({
+			ok: true,
+			data: { valid: true, user_id: 'user-123', api_key_id: 'key-123' },
+		});
+	});
+
+	// =========================================================================
+	// Knowledge Base Tests
+	// =========================================================================
+	describe('Knowledge Base', () => {
+		it('should have getting_started topic', async () => {
+			mockHandlerRegistry['get_help'] = vi.fn().mockImplementation(async (args) => {
+				if (args.topic === 'getting_started') {
+					return {
+						result: {
+							topic: 'getting_started',
+							content: 'Call start_work_session to initialize',
+						},
+					};
+				}
+				return { result: { error: 'Topic not found' } };
+			});
+
+			const handler = mockHandlerRegistry['get_help'];
+			const result = await handler({ topic: 'getting_started' }, {} as never);
+
+			expect(result.result).toHaveProperty('topic', 'getting_started');
+		});
+
+		it('should have topics listing available help', async () => {
+			mockHandlerRegistry['get_help'] = vi.fn().mockImplementation(async (args) => {
+				if (args.topic === 'topics') {
+					return {
+						result: {
+							topic: 'topics',
+							content: 'Available: getting_started, tasks, validation, deployment, git, blockers',
+						},
+					};
+				}
+				return { result: { error: 'Topic not found' } };
+			});
+
+			const handler = mockHandlerRegistry['get_help'];
+			const result = await handler({ topic: 'topics' }, {} as never);
+
+			expect(result.result).toHaveProperty('topic', 'topics');
+			expect(result.result.content).toContain('getting_started');
+		});
+	});
+
+	// =========================================================================
+	// Handler Routing Tests
+	// =========================================================================
+	describe('Tool Handler Routing', () => {
+		it('should route to registered handler', async () => {
+			const handler = mockHandlerRegistry['get_next_task'];
+			const result = await handler({ project_id: 'proj-1' }, {} as never);
+
+			expect(result).toEqual(mockHandlerResult);
+			expect(mockHandler).toHaveBeenCalledWith({ project_id: 'proj-1' }, expect.anything());
+		});
+
+		it('should call handler with correct context structure', async () => {
+			const testArgs = { project_id: 'proj-123', limit: 10 };
+			await mockHandlerRegistry['get_next_task'](testArgs, {} as never);
+
+			expect(mockHandler).toHaveBeenCalledWith(testArgs, expect.anything());
+		});
+
+		it('should throw for unknown tool', async () => {
+			const unknownToolName = 'nonexistent_tool';
+			expect(mockHandlerRegistry[unknownToolName]).toBeUndefined();
+		});
+
+		it('should support multiple handlers', async () => {
+			const handlers = Object.keys(mockHandlerRegistry);
+			expect(handlers).toContain('get_next_task');
+			expect(handlers).toContain('complete_task');
+			expect(handlers).toContain('update_task');
+			expect(handlers).toContain('add_task');
+		});
+	});
+
+	// =========================================================================
+	// Rate Limiting Tests
+	// =========================================================================
+	describe('Rate Limiting', () => {
+		it('should allow requests when under limit', async () => {
+			const { RateLimiter } = await import('./utils.js');
+			const limiter = new RateLimiter(60, 60000);
+
+			const check = limiter.check('test-key');
+			expect(check.allowed).toBe(true);
+			expect(check.remaining).toBeGreaterThan(0);
+		});
+
+		it('should track remaining requests', async () => {
+			const { RateLimiter } = await import('./utils.js');
+			const limiter = new RateLimiter(60, 60000);
+
+			const check = limiter.check('test-key');
+			expect(check).toHaveProperty('remaining');
+			expect(typeof check.remaining).toBe('number');
+		});
+
+		it('should provide reset time when limited', async () => {
+			const { RateLimiter } = await import('./utils.js');
+			const limiter = new RateLimiter(60, 60000);
+
+			const check = limiter.check('test-key');
+			expect(check).toHaveProperty('resetIn');
+			expect(typeof check.resetIn).toBe('number');
+		});
+	});
+
+	// =========================================================================
+	// Token Tracking Tests
+	// =========================================================================
+	describe('Token Usage Tracking', () => {
+		it('should create token usage object', async () => {
+			const { createTokenUsage } = await import('./token-tracking.js');
+			const usage = createTokenUsage();
+
+			expect(usage).toBeDefined();
+			expect(usage).toHaveProperty('totalInputTokens');
+			expect(usage).toHaveProperty('totalOutputTokens');
+			expect(usage).toHaveProperty('callCount');
+		});
+
+		it('should track usage with trackTokenUsage', async () => {
+			const { trackTokenUsage, createTokenUsage } = await import('./token-tracking.js');
+			const usage = createTokenUsage();
+
+			// trackTokenUsage is mocked, so we just verify it can be called
+			expect(() => trackTokenUsage(usage, 'get_next_task', {}, { success: true })).not.toThrow();
+		});
+	});
+
+	// =========================================================================
+	// Error Handling Tests
+	// =========================================================================
+	describe('Error Handling', () => {
+		it('should handle ValidationError with structured output', async () => {
+			const { ValidationError } = await import('./validators.js');
+			const error = new ValidationError('project_id', 'Required field missing', 'UUID');
+
+			expect(error.toJSON()).toEqual({
+				error: 'validation_error',
+				field: 'project_id',
+				message: 'Required field missing',
+			});
+		});
+
+		it('should handle handler errors gracefully', async () => {
+			const errorHandler = vi.fn().mockRejectedValue(new Error('Database connection failed'));
+			mockHandlerRegistry['failing_tool'] = errorHandler;
+
+			await expect(mockHandlerRegistry['failing_tool']({}, {} as never)).rejects.toThrow(
+				'Database connection failed'
+			);
+		});
+
+		it('should handle foreign key constraint errors', async () => {
+			const dbError = new Error('violates foreign key constraint "tasks_project_id_fkey"');
+			const errorHandler = vi.fn().mockRejectedValue(dbError);
+			mockHandlerRegistry['db_error_tool'] = errorHandler;
+
+			try {
+				await mockHandlerRegistry['db_error_tool']({}, {} as never);
+			} catch (error) {
+				expect((error as Error).message).toContain('foreign key constraint');
+			}
+		});
+
+		it('should handle duplicate key errors', async () => {
+			const dbError = new Error('duplicate key value violates unique constraint');
+			const errorHandler = vi.fn().mockRejectedValue(dbError);
+			mockHandlerRegistry['duplicate_error_tool'] = errorHandler;
+
+			try {
+				await mockHandlerRegistry['duplicate_error_tool']({}, {} as never);
+			} catch (error) {
+				expect((error as Error).message).toContain('duplicate key');
+			}
+		});
+	});
+
+	// =========================================================================
+	// API Client Tests
+	// =========================================================================
+	describe('API Client Integration', () => {
+		it('should validate API key on startup', async () => {
+			mockValidateAuth.mockResolvedValueOnce({
+				ok: true,
+				data: { valid: true, user_id: 'user-1', api_key_id: 'key-1' },
+			});
+
+			const { getApiClient } = await import('./api-client.js');
+			const client = getApiClient();
+			const result = await client.validateAuth();
+
+			expect(result.ok).toBe(true);
+			expect(result.data?.valid).toBe(true);
+		});
+
+		it('should fail with invalid API key', async () => {
+			mockValidateAuth.mockResolvedValueOnce({
+				ok: false,
+				data: null,
+			});
+
+			const { getApiClient } = await import('./api-client.js');
+			const client = getApiClient();
+			const result = await client.validateAuth();
+
+			expect(result.ok).toBe(false);
+		});
+
+		it('should sync session on tool calls', async () => {
+			const { getApiClient } = await import('./api-client.js');
+			const client = getApiClient();
+
+			await client.syncSession('session-123');
+			expect(mockSyncSession).toHaveBeenCalledWith('session-123');
+		});
+	});
+
+	// =========================================================================
+	// Response Formatting Tests
+	// =========================================================================
+	describe('Response Formatting', () => {
+		it('should format success response as JSON', () => {
+			const result = { success: true, task_id: 'task-123' };
+			const formatted = JSON.stringify(result, null, 2);
+
+			expect(formatted).toContain('"success": true');
+			expect(formatted).toContain('"task_id": "task-123"');
+		});
+
+		it('should format error response with message', () => {
+			const error = { error: 'not_found', message: 'Task not found' };
+			const formatted = JSON.stringify(error, null, 2);
+
+			expect(formatted).toContain('"error": "not_found"');
+			expect(formatted).toContain('"message": "Task not found"');
+		});
+
+		it('should include user_updates when present', async () => {
+			const handlerWithUpdates = vi.fn().mockResolvedValue({
+				result: { success: true },
+				user_updates: {
+					tasks: [{ id: 'task-1', title: 'New Task' }],
+					blockers: [],
+					ideas: [],
+				},
+			});
+
+			const response = await handlerWithUpdates({}, {} as never);
+			expect(response.user_updates).toBeDefined();
+			expect(response.user_updates.tasks).toHaveLength(1);
+		});
+	});
+
+	// =========================================================================
+	// Handler Context Tests
+	// =========================================================================
+	describe('Handler Context', () => {
+		it('should include auth in context', async () => {
+			const contextCapture = vi.fn().mockImplementation((args, ctx) => {
+				expect(ctx).toBeDefined();
+				return { result: { success: true } };
+			});
+			mockHandlerRegistry['context_test'] = contextCapture;
+
+			await mockHandlerRegistry['context_test']({}, { auth: { userId: 'user-1' } } as never);
+			expect(contextCapture).toHaveBeenCalled();
+		});
+
+		it('should include session info in context', async () => {
+			const contextCapture = vi.fn().mockImplementation((args, ctx) => {
+				expect(ctx.session || ctx).toBeDefined();
+				return { result: { success: true } };
+			});
+			mockHandlerRegistry['session_test'] = contextCapture;
+
+			await mockHandlerRegistry['session_test'](
+				{},
+				{
+					session: {
+						instanceId: 'inst-1',
+						currentSessionId: 'sess-1',
+						currentPersona: 'Thor',
+						currentRole: 'developer',
+					},
+				} as never
+			);
+			expect(contextCapture).toHaveBeenCalled();
+		});
+	});
+
+	// =========================================================================
+	// Complete Task Reminder Tests
+	// =========================================================================
+	describe('Tool Reminders', () => {
+		it('should have reminder for complete_task', async () => {
+			// Simulate what the server does - complete_task gets a reminder
+			const expectedReminder =
+				'CONTINUE WORKING: Call get_next_task or start the next_task. If awaiting_validation tasks exist, validate them FIRST before new work. If context is large, run /clear then start_work_session to refresh.';
+
+			const reminders: Record<string, string> = {
+				complete_task: expectedReminder,
+				batch_complete_tasks:
+					'CONTINUE WORKING: Call get_next_task. If awaiting_validation tasks exist, validate them FIRST before new work.',
+			};
+
+			expect(reminders['complete_task']).toBeDefined();
+			expect(reminders['complete_task']).toContain('CONTINUE WORKING');
+		});
+
+		it('should not have reminder for most tools', () => {
+			const reminders: Record<string, string> = {
+				complete_task: 'some reminder',
+				batch_complete_tasks: 'another reminder',
+			};
+
+			expect(reminders['get_next_task']).toBeUndefined();
+			expect(reminders['update_task']).toBeUndefined();
+			expect(reminders['add_task']).toBeUndefined();
+		});
+	});
+
+	// =========================================================================
+	// Session Management Tests
+	// =========================================================================
+	describe('Session Management', () => {
+		it('should track session ID after start_work_session', async () => {
+			const startHandler = vi.fn().mockImplementation(async (args, ctx) => {
+				// Simulate setting session ID
+				if (ctx.updateSession) {
+					ctx.updateSession({ currentSessionId: 'new-session-id' });
+				}
+				return {
+					result: {
+						session_id: 'new-session-id',
+						persona: 'Thor',
+						project: { id: 'proj-1', name: 'Test' },
+					},
+				};
+			});
+			mockHandlerRegistry['start_work_session'] = startHandler;
+
+			const mockContext = {
+				auth: { userId: 'user-1' },
+				session: { instanceId: 'inst-1', currentSessionId: null },
+				updateSession: vi.fn(),
+			};
+
+			const result = await mockHandlerRegistry['start_work_session'](
+				{ git_url: 'https://github.com/test/repo' },
+				mockContext as never
+			);
+
+			expect(result.result.session_id).toBe('new-session-id');
+			expect(mockContext.updateSession).toHaveBeenCalledWith({ currentSessionId: 'new-session-id' });
+		});
+
+		it('should track persona assignment', async () => {
+			const startHandler = vi.fn().mockImplementation(async (args, ctx) => {
+				if (ctx.updateSession) {
+					ctx.updateSession({ currentPersona: 'Odin' });
+				}
+				return {
+					result: {
+						session_id: 'sess-1',
+						persona: 'Odin',
+					},
+				};
+			});
+			mockHandlerRegistry['start_work_session'] = startHandler;
+
+			const mockContext = {
+				updateSession: vi.fn(),
+			};
+
+			await mockHandlerRegistry['start_work_session']({}, mockContext as never);
+			expect(mockContext.updateSession).toHaveBeenCalledWith({ currentPersona: 'Odin' });
+		});
+
+		it('should track role assignment', async () => {
+			const startHandler = vi.fn().mockImplementation(async (args, ctx) => {
+				if (ctx.updateSession) {
+					ctx.updateSession({ currentRole: 'validator' });
+				}
+				return {
+					result: {
+						session_id: 'sess-1',
+						role: 'validator',
+					},
+				};
+			});
+			mockHandlerRegistry['start_work_session'] = startHandler;
+
+			const mockContext = {
+				updateSession: vi.fn(),
+			};
+
+			await mockHandlerRegistry['start_work_session']({ role: 'validator' }, mockContext as never);
+			expect(mockContext.updateSession).toHaveBeenCalledWith({ currentRole: 'validator' });
+		});
+	});
+
+	// =========================================================================
+	// Instance ID Tests
+	// =========================================================================
+	describe('Instance Tracking', () => {
+		it('should generate unique instance ID', async () => {
+			// The server generates a UUID for INSTANCE_ID
+			const uuid1 = crypto.randomUUID();
+			const uuid2 = crypto.randomUUID();
+
+			expect(uuid1).not.toBe(uuid2);
+			expect(uuid1).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+		});
+
+		it('should include instance ID in session context', () => {
+			const sessionContext = {
+				instanceId: 'inst-12345',
+				currentSessionId: 'sess-1',
+				currentPersona: 'Thor',
+				currentRole: 'developer',
+			};
+
+			expect(sessionContext.instanceId).toBeDefined();
+			expect(typeof sessionContext.instanceId).toBe('string');
+		});
+	});
+
+	// =========================================================================
+	// Server Configuration Tests
+	// =========================================================================
+	describe('Server Configuration', () => {
+		it('should configure server with correct name and version', async () => {
+			const { Server } = await import('@modelcontextprotocol/sdk/server/index.js');
+
+			// Verify Server was called with correct config
+			expect(Server).toBeDefined();
+		});
+
+		it('should enable tools capability', () => {
+			const serverConfig = {
+				capabilities: {
+					tools: {},
+				},
+			};
+
+			expect(serverConfig.capabilities.tools).toBeDefined();
+		});
+	});
+
+	// =========================================================================
+	// Signal Handling Tests
+	// =========================================================================
+	describe('Signal Handling', () => {
+		it('should have handlers for SIGINT and SIGTERM', () => {
+			// These are set up in the actual module
+			// We can verify the pattern is correct
+			const signals = ['SIGINT', 'SIGTERM'];
+			signals.forEach((signal) => {
+				expect(['SIGINT', 'SIGTERM']).toContain(signal);
+			});
+		});
+
+		it('should cleanup rate limiter on exit', () => {
+			// Verify cleanup can be called without error
+			const mockCleanup = vi.fn();
+			const mockInterval = setInterval(() => {}, 1000);
+			clearInterval(mockInterval);
+
+			expect(mockCleanup).not.toThrow;
+		});
+	});
+
+	// =========================================================================
+	// Tools List Tests
+	// =========================================================================
+	describe('Tools Registration', () => {
+		it('should export tools array', async () => {
+			const { tools } = await import('./tools.js');
+			expect(Array.isArray(tools)).toBe(true);
+		});
+
+		it('should have required tool properties', async () => {
+			const { tools } = await import('./tools.js');
+			tools.forEach((tool) => {
+				expect(tool).toHaveProperty('name');
+				expect(tool).toHaveProperty('description');
+				expect(tool).toHaveProperty('inputSchema');
+			});
+		});
+	});
+});
+
+describe('Environment Variable Handling', () => {
+	const originalEnvKey = process.env.VIBESCOPE_API_KEY;
+
+	beforeAll(() => {
+		process.env.VIBESCOPE_API_KEY = 'test-api-key-12345';
+	});
+
+	afterAll(() => {
+		if (originalEnvKey !== undefined) {
+			process.env.VIBESCOPE_API_KEY = originalEnvKey;
+		} else {
+			delete process.env.VIBESCOPE_API_KEY;
+		}
+	});
+
+	it('should use VIBESCOPE_API_KEY from environment', () => {
+		const apiKey = process.env.VIBESCOPE_API_KEY;
+		expect(apiKey).toBeDefined();
+		expect(apiKey).toBe('test-api-key-12345');
+	});
+});