@vibescope/mcp-server 0.2.1 → 0.2.2

package/src/handlers/project.test.ts

@@ -120,14 +120,17 @@ describe('getProjectContext', () => {
 		expect(result.result).toHaveProperty('active_tasks');
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.listProjects.mockResolvedValue({
 			ok: false,
 			error: 'Database error',
 		});
 		const ctx = createMockContext();
 
-		await expect(getProjectContext({}, ctx)).rejects.toThrow('Database error');
+		const result = await getProjectContext({}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Database error' });
 	});
 });
 
@@ -237,16 +240,17 @@ describe('getGitWorkflow', () => {
 		expect((result.result as { instructions: string[] }).instructions[0]).toContain('No git workflow configured');
 	});
 
-	it('should throw error when project not found', async () => {
+	it('should return error when project not found', async () => {
 		mockApiClient.getGitWorkflow.mockResolvedValue({
 			ok: false,
 			error: 'Project not found',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getGitWorkflow({ project_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Project not found');
+		const result = await getGitWorkflow({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Project not found' });
 	});
 });
 
@@ -327,16 +331,17 @@ describe('createProject', () => {
 		});
 	});
 
-	it('should throw error when insert fails', async () => {
+	it('should return error when insert fails', async () => {
 		mockApiClient.createProject.mockResolvedValue({
 			ok: false,
-			error: 'Failed to create project: Insert failed',
+			error: 'Failed to create project',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			createProject({ name: 'Test Project' }, ctx)
-		).rejects.toThrow('Failed to create project: Insert failed');
+		const result = await createProject({ name: 'Test Project' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to create project' });
 	});
 
 	it('should throw error when name is missing', async () => {
@@ -445,19 +450,20 @@ describe('updateProject', () => {
 		);
 	});
 
-	it('should throw error when update fails', async () => {
+	it('should return error when update fails', async () => {
 		mockApiClient.updateProject.mockResolvedValue({
 			ok: false,
-			error: 'Failed to update project: Update failed',
+			error: 'Failed to update project',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			updateProject({
-				project_id: VALID_UUID,
-				name: 'Test',
-			}, ctx)
-		).rejects.toThrow('Failed to update project: Update failed');
+		const result = await updateProject({
+			project_id: VALID_UUID,
+			name: 'Test',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to update project' });
 	});
 });
 
@@ -522,18 +528,19 @@ describe('updateProjectReadme', () => {
 		);
 	});
 
-	it('should throw error when update fails', async () => {
+	it('should return error when update fails', async () => {
 		mockApiClient.updateProjectReadme.mockResolvedValue({
 			ok: false,
-			error: 'Failed to update README: Update failed',
+			error: 'Failed to update README',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			updateProjectReadme({
-				project_id: VALID_UUID,
-				readme_content: '# README',
-			}, ctx)
-		).rejects.toThrow('Failed to update README: Update failed');
+		const result = await updateProjectReadme({
+			project_id: VALID_UUID,
+			readme_content: '# README',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to update README' });
 	});
 });

package/src/handlers/project.ts

@@ -72,7 +72,7 @@ export const getProjectContext: Handler = async (args, _ctx) => {
 		const response = await apiClient.listProjects();
 
 		if (!response.ok) {
-			throw new Error(response.error || 'Failed to fetch projects');
+			return { result: { error: response.error || 'Failed to fetch projects' }, isError: true };
 		}
 
 		return { result: { projects: response.data?.projects || [] } };
@@ -82,7 +82,7 @@ export const getProjectContext: Handler = async (args, _ctx) => {
 	const response = await apiClient.getProject(project_id || 'by-git-url', git_url);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to fetch project');
+		return { result: { error: response.error || 'Failed to fetch project' }, isError: true };
 	}
 
 	if (!response.data?.found) {
@@ -104,7 +104,7 @@ export const getGitWorkflow: Handler = async (args, _ctx) => {
 	const response = await apiClient.getGitWorkflow(project_id, task_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to get git workflow');
+		return { result: { error: response.error || 'Failed to get git workflow' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -123,7 +123,7 @@ export const createProject: Handler = async (args, _ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to create project');
+		return { result: { error: response.error || 'Failed to create project' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -163,7 +163,7 @@ export const updateProject: Handler = async (args, _ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to update project');
+		return { result: { error: response.error || 'Failed to update project' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -176,7 +176,7 @@ export const updateProjectReadme: Handler = async (args, _ctx) => {
 	const response = await apiClient.updateProjectReadme(project_id, readme_content);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to update README');
+		return { result: { error: response.error || 'Failed to update README' }, isError: true };
 	}
 
 	return { result: response.data };

package/src/handlers/requests.test.ts

@@ -87,19 +87,22 @@ describe('getPendingRequests', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.getPendingRequests.mockResolvedValue({
 			ok: false,
 			error: 'Query failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getPendingRequests(
-				{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
-				ctx
-			)
-		).rejects.toThrow('Failed to get pending requests: Query failed');
+		const result = await getPendingRequests(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Query failed',
+		});
 	});
 });
 
@@ -159,16 +162,19 @@ describe('acknowledgeRequest', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.acknowledgeRequest.mockResolvedValue({
 			ok: false,
 			error: 'Update failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			acknowledgeRequest({ request_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow('Failed to acknowledge request: Update failed');
+		const result = await acknowledgeRequest({ request_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Update failed',
+		});
 	});
 });
 
@@ -246,18 +252,21 @@ describe('answerQuestion', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.answerQuestion.mockResolvedValue({
 			ok: false,
 			error: 'Update failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			answerQuestion({
-				request_id: '123e4567-e89b-12d3-a456-426614174000',
-				answer: 'Answer',
-			}, ctx)
-		).rejects.toThrow('Failed to answer question: Update failed');
+		const result = await answerQuestion({
+			request_id: '123e4567-e89b-12d3-a456-426614174000',
+			answer: 'Answer',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Update failed',
+		});
 	});
 });

package/src/handlers/requests.ts

@@ -36,7 +36,7 @@ export const getPendingRequests: Handler = async (args, ctx) => {
 	const response = await apiClient.getPendingRequests(project_id, session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(`Failed to get pending requests: ${response.error}`);
+		return { result: { error: response.error || 'Failed to get pending requests' }, isError: true };
 	}
 
 	return {
@@ -56,7 +56,7 @@ export const acknowledgeRequest: Handler = async (args, ctx) => {
 	const response = await apiClient.acknowledgeRequest(request_id, session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(`Failed to acknowledge request: ${response.error}`);
+		return { result: { error: response.error || 'Failed to acknowledge request' }, isError: true };
 	}
 
 	return {
@@ -75,7 +75,7 @@ export const answerQuestion: Handler = async (args, ctx) => {
 	const response = await apiClient.answerQuestion(request_id, answer, session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(`Failed to answer question: ${response.error}`);
+		return { result: { error: response.error || 'Failed to answer question' }, isError: true };
 	}
 
 	return {

package/src/handlers/session.test.ts

@@ -526,4 +526,51 @@ describe('startWorkSession', () => {
 		expect(result.result).toHaveProperty('next_task');
 		expect((result.result as { next_task: { id: string } }).next_task.id).toBe('task-1');
 	});
+
+	it('should include pending_requests when available in full mode', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		const mockRequests = [
+			{ id: 'req-1', request_type: 'question', message: 'What is the status?', created_at: '2026-01-14T10:00:00Z' },
+			{ id: 'req-2', request_type: 'instruction', message: 'Please prioritize task X', created_at: '2026-01-14T11:00:00Z' },
+		];
+		mockApiClient.startSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_started: true,
+				session_id: 'new-session-123',
+				persona: 'Wave',
+				role: 'developer',
+				project: { id: 'project-123', name: 'Test Project' },
+				pending_requests: mockRequests,
+			},
+		});
+
+		const result = await startWorkSession({ project_id: 'project-123', mode: 'full' }, ctx);
+
+		expect(result.result).toHaveProperty('pending_requests');
+		expect(result.result).toHaveProperty('pending_requests_count', 2);
+		const pendingRequests = (result.result as { pending_requests: typeof mockRequests }).pending_requests;
+		expect(pendingRequests.length).toBe(2);
+		expect(pendingRequests[0].request_type).toBe('question');
+	});
+
+	it('should not include pending_requests when empty', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		mockApiClient.startSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_started: true,
+				session_id: 'new-session-123',
+				persona: 'Wave',
+				role: 'developer',
+				project: { id: 'project-123', name: 'Test Project' },
+				pending_requests: [],
+			},
+		});
+
+		const result = await startWorkSession({ project_id: 'project-123', mode: 'full' }, ctx);
+
+		expect(result.result).not.toHaveProperty('pending_requests');
+		expect(result.result).not.toHaveProperty('pending_requests_count');
+	});
 });

package/src/handlers/session.ts

@@ -105,22 +105,40 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		});
 	}
 
-	// Build result with directive at top for visibility
+	// Check for urgent questions - these MUST be handled first
+	const hasUrgentQuestions = data.URGENT_QUESTIONS || (data.pending_requests && data.pending_requests.length > 0);
+
+	// Build result - URGENT_QUESTIONS at absolute top for maximum visibility
 	const result: Record<string, unknown> = {
 		session_started: true,
-		directive: data.directive || 'ACTION_REQUIRED: Start working immediately.',
-		auto_continue: true,
-		session_id: data.session_id,
-		persona: data.persona,
-		role: data.role,
-		project: data.project,
 	};
 
+	// URGENT_QUESTIONS must be the FIRST thing the agent sees
+	if (data.URGENT_QUESTIONS) {
+		result.URGENT_QUESTIONS = data.URGENT_QUESTIONS;
+	}
+
+	// Directive comes right after urgent questions
+	result.directive = data.directive || 'ACTION_REQUIRED: Start working immediately.';
+	result.auto_continue = true;
+
+	// Session info
+	result.session_id = data.session_id;
+	result.persona = data.persona;
+	result.role = data.role;
+	result.project = data.project;
+
 	// Add task data
 	if (data.next_task) {
 		result.next_task = data.next_task;
 	}
 
+	// Add pending requests (questions from user) - these take priority
+	if (data.pending_requests && data.pending_requests.length > 0) {
+		result.pending_requests = data.pending_requests;
+		result.pending_requests_count = data.pending_requests.length;
+	}
+
 	// Add active tasks for full mode
 	if (data.active_tasks) {
 		result.active_tasks = data.active_tasks;
@@ -153,8 +171,13 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		};
 	}
 
-	// Add next action at end
-	if (data.next_task) {
+	// Add next action at end - pending requests take priority over tasks
+	if (hasUrgentQuestions) {
+		const firstQuestion = data.URGENT_QUESTIONS?.requests?.[0] || data.pending_requests?.[0];
+		result.next_action = firstQuestion
+			? `answer_question(request_id: "${firstQuestion.id}", answer: "...")`
+			: 'Check pending_requests and respond using answer_question(request_id, answer)';
+	} else if (data.next_task) {
 		result.next_action = `update_task(task_id: "${data.next_task.id}", status: "in_progress")`;
 	} else if (data.project) {
 		result.next_action = `start_fallback_activity(project_id: "${data.project.id}", activity: "code_review")`;

package/src/handlers/sprints.test.ts

@@ -99,30 +99,36 @@ describe('createSprint', () => {
 		).rejects.toThrow(ValidationError);
 	});
 
-	it('should throw error for invalid start_date format', async () => {
+	it('should return error for invalid start_date format', async () => {
 		const ctx = createMockContext();
 
-		await expect(
-			createSprint({
-				project_id: VALID_UUID,
-				title: 'Sprint 1',
-				start_date: 'invalid',
-				end_date: '2025-01-14'
-			}, ctx)
-		).rejects.toThrow('Invalid start_date format');
+		const result = await createSprint({
+			project_id: VALID_UUID,
+			title: 'Sprint 1',
+			start_date: 'invalid',
+			end_date: '2025-01-14'
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Invalid start_date format. Use YYYY-MM-DD',
+		});
 	});
 
-	it('should throw error when end_date is before start_date', async () => {
+	it('should return error when end_date is before start_date', async () => {
 		const ctx = createMockContext();
 
-		await expect(
-			createSprint({
-				project_id: VALID_UUID,
-				title: 'Sprint 1',
-				start_date: '2025-01-14',
-				end_date: '2025-01-01'
-			}, ctx)
-		).rejects.toThrow('end_date must be on or after start_date');
+		const result = await createSprint({
+			project_id: VALID_UUID,
+			title: 'Sprint 1',
+			start_date: '2025-01-14',
+			end_date: '2025-01-01'
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'end_date must be on or after start_date',
+		});
 	});
 
 	it('should create sprint successfully', async () => {
@@ -180,21 +186,24 @@ describe('createSprint', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.proxy.mockResolvedValue({
 			ok: false,
 			error: 'Database error',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			createSprint({
-				project_id: VALID_UUID,
-				title: 'Sprint 1',
-				start_date: '2025-01-01',
-				end_date: '2025-01-14',
-			}, ctx)
-		).rejects.toThrow('Failed to create sprint: Database error');
+		const result = await createSprint({
+			project_id: VALID_UUID,
+			title: 'Sprint 1',
+			start_date: '2025-01-01',
+			end_date: '2025-01-14',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Database error',
+		});
 	});
 });
 
@@ -238,16 +247,19 @@ describe('updateSprint', () => {
 		});
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.proxy.mockResolvedValue({
 			ok: false,
 			error: 'Sprint not found',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			updateSprint({ sprint_id: VALID_UUID, title: 'Test' }, ctx)
-		).rejects.toThrow('Failed to update sprint: Sprint not found');
+		const result = await updateSprint({ sprint_id: VALID_UUID, title: 'Test' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Sprint not found',
+		});
 	});
 });
 
@@ -417,16 +429,19 @@ describe('startSprint', () => {
 		});
 	});
 
-	it('should throw error when sprint not in planning', async () => {
+	it('should return error when sprint not in planning', async () => {
 		mockApiClient.proxy.mockResolvedValue({
 			ok: false,
 			error: "Cannot start sprint in 'active' status",
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			startSprint({ sprint_id: VALID_UUID }, ctx)
-		).rejects.toThrow("Cannot start sprint in 'active' status");
+		const result = await startSprint({ sprint_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: "Cannot start sprint in 'active' status",
+		});
 	});
 });
 
@@ -514,16 +529,19 @@ describe('addTaskToSprint', () => {
 		).rejects.toThrow(ValidationError);
 	});
 
-	it('should throw error for negative story_points', async () => {
+	it('should return error for negative story_points', async () => {
 		const ctx = createMockContext();
 
-		await expect(
-			addTaskToSprint({
-				sprint_id: VALID_UUID,
-				task_id: VALID_UUID_2,
-				story_points: -1,
-			}, ctx)
-		).rejects.toThrow('story_points must be a non-negative integer');
+		const result = await addTaskToSprint({
+			sprint_id: VALID_UUID,
+			task_id: VALID_UUID_2,
+			story_points: -1,
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'story_points must be a non-negative integer',
+		});
 	});
 
 	it('should add task to sprint with story points', async () => {
@@ -554,19 +572,22 @@ describe('addTaskToSprint', () => {
 		});
 	});
 
-	it('should throw error when sprint not in planning', async () => {
+	it('should return error when sprint not in planning', async () => {
 		mockApiClient.proxy.mockResolvedValue({
 			ok: false,
 			error: "Cannot add tasks to sprint in 'active' status",
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			addTaskToSprint({
-				sprint_id: VALID_UUID,
-				task_id: VALID_UUID_2,
-			}, ctx)
-		).rejects.toThrow("Cannot add tasks to sprint in 'active' status");
+		const result = await addTaskToSprint({
+			sprint_id: VALID_UUID,
+			task_id: VALID_UUID_2,
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: "Cannot add tasks to sprint in 'active' status",
+		});
 	});
 });