@vibescope/mcp-server 0.5.0 → 0.5.2

package/src/index.test.ts

@@ -1,674 +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/index.js');
-			expect(Array.isArray(tools)).toBe(true);
-		});
-
-		it('should have required tool properties', async () => {
-			const { tools } = await import('./tools/index.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');
-	});
-});
+/**
+ * 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/index.js');
+			expect(Array.isArray(tools)).toBe(true);
+		});
+
+		it('should have required tool properties', async () => {
+			const { tools } = await import('./tools/index.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');
+	});
+});