@vibescope/mcp-server 0.2.1 → 0.2.2

package/src/handlers/sprints.ts

@@ -119,13 +119,13 @@ export const createSprint: Handler = async (args, ctx) => {
 	const startDateObj = new Date(start_date);
 	const endDateObj = new Date(end_date);
 	if (isNaN(startDateObj.getTime())) {
-		throw new Error('Invalid start_date format. Use YYYY-MM-DD');
+		return { result: { error: 'Invalid start_date format. Use YYYY-MM-DD' }, isError: true };
 	}
 	if (isNaN(endDateObj.getTime())) {
-		throw new Error('Invalid end_date format. Use YYYY-MM-DD');
+		return { result: { error: 'Invalid end_date format. Use YYYY-MM-DD' }, isError: true };
 	}
 	if (endDateObj < startDateObj) {
-		throw new Error('end_date must be on or after start_date');
+		return { result: { error: 'end_date must be on or after start_date' }, isError: true };
 	}
 
 	const { session } = ctx;
@@ -151,7 +151,7 @@ export const createSprint: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to create sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to create sprint' }, isError: true };
 	}
 
 	return {
@@ -184,13 +184,13 @@ export const updateSprint: Handler = async (args, ctx) => {
 	if (start_date) {
 		const startDateObj = new Date(start_date);
 		if (isNaN(startDateObj.getTime())) {
-			throw new Error('Invalid start_date format. Use YYYY-MM-DD');
+			return { result: { error: 'Invalid start_date format. Use YYYY-MM-DD' }, isError: true };
 		}
 	}
 	if (end_date) {
 		const endDateObj = new Date(end_date);
 		if (isNaN(endDateObj.getTime())) {
-			throw new Error('Invalid end_date format. Use YYYY-MM-DD');
+			return { result: { error: 'Invalid end_date format. Use YYYY-MM-DD' }, isError: true };
 		}
 	}
 
@@ -208,7 +208,7 @@ export const updateSprint: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to update sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to update sprint' }, isError: true };
 	}
 
 	return { result: { success: true, sprint_id } };
@@ -250,7 +250,7 @@ export const getSprint: Handler = async (args, ctx) => {
 	}>('get_sprint', { sprint_id, summary_only });
 
 	if (!response.ok) {
-		throw new Error(`Failed to get sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to get sprint' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -284,7 +284,7 @@ export const getSprints: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to fetch sprints: ${response.error}`);
+		return { result: { error: response.error || 'Failed to fetch sprints' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -300,7 +300,7 @@ export const deleteSprint: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to delete sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to delete sprint' }, isError: true };
 	}
 
 	return { result: { success: true, message: 'Sprint deleted. Tasks are preserved.' } };
@@ -320,7 +320,7 @@ export const startSprint: Handler = async (args, ctx) => {
 	}>('start_sprint', { sprint_id });
 
 	if (!response.ok) {
-		throw new Error(`Failed to start sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to start sprint' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -346,7 +346,7 @@ export const completeSprint: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to complete sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to complete sprint' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -356,7 +356,7 @@ export const addTaskToSprint: Handler = async (args, ctx) => {
 	const { sprint_id, task_id, story_points, phase } = parseArgs(args, addTaskToSprintSchema);
 
 	if (story_points !== undefined && (story_points < 0 || !Number.isInteger(story_points))) {
-		throw new Error('story_points must be a non-negative integer');
+		return { result: { error: 'story_points must be a non-negative integer' }, isError: true };
 	}
 
 	const apiClient = getApiClient();
@@ -376,7 +376,7 @@ export const addTaskToSprint: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to add task to sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to add task to sprint' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -399,7 +399,7 @@ export const removeTaskFromSprint: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to remove task from sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to remove task from sprint' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -426,7 +426,7 @@ export const getSprintBacklog: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to get sprint backlog: ${response.error}`);
+		return { result: { error: response.error || 'Failed to get sprint backlog' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -453,7 +453,7 @@ export const getSprintVelocity: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to get sprint velocity: ${response.error}`);
+		return { result: { error: response.error || 'Failed to get sprint velocity' }, isError: true };
 	}
 
 	return { result: response.data };

package/src/handlers/tasks.test.ts

@@ -306,6 +306,7 @@ describe('updateTask', () => {
 			{
 				task_id: '123e4567-e89b-12d3-a456-426614174000',
 				status: 'in_progress',
+				git_branch: 'feature/test-branch',
 			},
 			ctx
 		);
@@ -324,6 +325,7 @@ describe('updateTask', () => {
 			{
 				task_id: '123e4567-e89b-12d3-a456-426614174000',
 				status: 'in_progress',
+				git_branch: 'feature/test-branch',
 			},
 			ctx
 		);
@@ -344,6 +346,7 @@ describe('updateTask', () => {
 			{
 				task_id: '123e4567-e89b-12d3-a456-426614174000',
 				status: 'in_progress',
+				git_branch: 'feature/test-branch',
 			},
 			ctx
 		);
@@ -353,7 +356,42 @@ describe('updateTask', () => {
 		});
 	});
 
-	it('should warn when setting in_progress without git_branch', async () => {
+	it('should return error when setting in_progress without git_branch', async () => {
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			error: 'worktree_required',
+			message: expect.stringContaining('git_branch is required'),
+			hint: expect.stringContaining('Create a worktree'),
+		});
+		// Should NOT call the API when worktree requirement fails
+		expect(mockApiClient.updateTask).not.toHaveBeenCalled();
+	});
+
+	it('should return worktree_example in error response', async () => {
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+			},
+			ctx
+		);
+
+		expect(result.result).toHaveProperty('worktree_example');
+		expect(result.result.worktree_example).toHaveProperty('command');
+		expect(result.result.worktree_example).toHaveProperty('then');
+		expect(result.result).toHaveProperty('skip_option');
+	});
+
+	it('should succeed when setting in_progress with git_branch', async () => {
 		mockApiClient.updateTask.mockResolvedValue({
 			ok: true,
 			data: { success: true },
@@ -364,18 +402,17 @@ describe('updateTask', () => {
 			{
 				task_id: '123e4567-e89b-12d3-a456-426614174000',
 				status: 'in_progress',
+				git_branch: 'feature/my-task',
 			},
 			ctx
 		);
 
-		expect(result.result).toMatchObject({
-			success: true,
-			warning: expect.stringContaining('git_branch not set'),
-			hint: expect.stringContaining('update_task again'),
-		});
+		expect(result.result).toMatchObject({ success: true });
+		expect(result.result).not.toHaveProperty('error');
+		expect(mockApiClient.updateTask).toHaveBeenCalled();
 	});
 
-	it('should not warn when setting in_progress with git_branch', async () => {
+	it('should succeed when using skip_worktree_requirement without git_branch', async () => {
 		mockApiClient.updateTask.mockResolvedValue({
 			ok: true,
 			data: { success: true },
@@ -386,16 +423,17 @@ describe('updateTask', () => {
 			{
 				task_id: '123e4567-e89b-12d3-a456-426614174000',
 				status: 'in_progress',
-				git_branch: 'feature/my-task',
+				skip_worktree_requirement: true,
 			},
 			ctx
 		);
 
 		expect(result.result).toMatchObject({ success: true });
-		expect(result.result).not.toHaveProperty('warning');
+		expect(result.result).not.toHaveProperty('error');
+		expect(mockApiClient.updateTask).toHaveBeenCalled();
 	});
 
-	it('should not warn when updating status other than in_progress', async () => {
+	it('should not require git_branch when updating status other than in_progress', async () => {
 		mockApiClient.updateTask.mockResolvedValue({
 			ok: true,
 			data: { success: true },
@@ -411,7 +449,28 @@ describe('updateTask', () => {
 		);
 
 		expect(result.result).toMatchObject({ success: true });
-		expect(result.result).not.toHaveProperty('warning');
+		expect(result.result).not.toHaveProperty('error');
+		expect(mockApiClient.updateTask).toHaveBeenCalled();
+	});
+
+	it('should not require git_branch when updating progress only', async () => {
+		mockApiClient.updateTask.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				progress_percentage: 50,
+				progress_note: 'Halfway done',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+		expect(mockApiClient.updateTask).toHaveBeenCalled();
 	});
 });
 
@@ -480,16 +539,19 @@ describe('completeTask', () => {
 		);
 	});
 
-	it('should throw error when API returns error', async () => {
+	it('should return error when API returns error', async () => {
 		mockApiClient.completeTask.mockResolvedValue({
 			ok: false,
 			error: 'Task not found',
 		});
 
 		const ctx = createMockContext();
-		await expect(
-			completeTask({ task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow('Failed to complete task: Task not found');
+		const result = await completeTask({ task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Task not found',
+		});
 	});
 });
 

package/src/handlers/tasks.ts

@@ -73,7 +73,9 @@ const updateTaskSchema = {
 	progress_note: { type: 'string' as const },
 	estimated_minutes: { type: 'number' as const, validate: minutesValidator },
 	git_branch: { type: 'string' as const },
+	worktree_path: { type: 'string' as const },
 	task_type: { type: 'string' as const, validate: createEnumValidator(VALID_TASK_TYPES) },
+	skip_worktree_requirement: { type: 'boolean' as const, default: false },
 };
 
 const completeTaskSchema = {
@@ -228,7 +230,7 @@ export const getTasks: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to fetch tasks: ${response.error}`);
+		return { result: { error: response.error || 'Failed to fetch tasks' }, isError: true };
 	}
 
 	return {
@@ -247,7 +249,7 @@ export const getNextTask: Handler = async (args, ctx) => {
 	const response = await api.getNextTask(project_id, ctx.session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(`Failed to get next task: ${response.error}`);
+		return { result: { error: response.error || 'Failed to get next task' }, isError: true };
 	}
 
 	const data = response.data;
@@ -299,7 +301,7 @@ export const addTask: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to add task: ${response.error}`);
+		return { result: { error: response.error || 'Failed to add task' }, isError: true };
 	}
 
 	const data = response.data;
@@ -318,8 +320,25 @@ export const addTask: Handler = async (args, ctx) => {
 };
 
 export const updateTask: Handler = async (args, ctx) => {
-	const { task_id, title, description, priority, status, progress_percentage, progress_note, estimated_minutes, git_branch, task_type } = parseArgs(args, updateTaskSchema);
-	const updates = { title, description, priority, status, progress_percentage, estimated_minutes, git_branch, task_type };
+	const { task_id, title, description, priority, status, progress_percentage, progress_note, estimated_minutes, git_branch, worktree_path, task_type, skip_worktree_requirement } = parseArgs(args, updateTaskSchema);
+	const updates = { title, description, priority, status, progress_percentage, estimated_minutes, git_branch, worktree_path, task_type };
+
+	// Enforce worktree creation: require git_branch when marking task as in_progress
+	// This ensures multi-agent collaboration works properly with isolated worktrees
+	if (status === 'in_progress' && !git_branch && !skip_worktree_requirement) {
+		return {
+			result: {
+				error: 'worktree_required',
+				message: 'git_branch is required when marking a task as in_progress. Create a worktree first and provide the branch name.',
+				hint: 'Create a worktree with: git worktree add ../PROJECT-task-TASKID -b feature/TASKID-description BASE_BRANCH, then call update_task with both status and git_branch parameters.',
+				worktree_example: {
+					command: `git worktree add ../worktree-${task_id.substring(0, 8)} -b feature/${task_id.substring(0, 8)}-task develop`,
+					then: `update_task(task_id: "${task_id}", status: "in_progress", git_branch: "feature/${task_id.substring(0, 8)}-task")`,
+				},
+				skip_option: 'If this project does not use git branching (trunk-based or no git workflow), pass skip_worktree_requirement: true',
+			},
+		};
+	}
 
 	const api = getApiClient();
 	const response = await api.updateTask(task_id, {
@@ -364,7 +383,7 @@ export const updateTask: Handler = async (args, ctx) => {
 				},
 			};
 		}
-		throw new Error(`Failed to update task: ${response.error}`);
+		return { result: { error: response.error || 'Failed to update task' }, isError: true };
 	}
 
 	// Build result - include git workflow info when transitioning to in_progress
@@ -381,12 +400,6 @@ export const updateTask: Handler = async (args, ctx) => {
 		result.next_step = data.next_step;
 	}
 
-	// Warn if transitioning to in_progress without git_branch
-	if (updates.status === 'in_progress' && !updates.git_branch) {
-		result.warning = 'git_branch not set. For multi-agent collaboration, set git_branch when marking in_progress to track your worktree.';
-		result.hint = 'Call update_task again with git_branch parameter after creating your worktree.';
-	}
-
 	return { result };
 };
 
@@ -400,12 +413,12 @@ export const completeTask: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to complete task: ${response.error}`);
+		return { result: { error: response.error || 'Failed to complete task' }, isError: true };
 	}
 
 	const data = response.data;
 	if (!data) {
-		throw new Error('No response data from complete task');
+		return { result: { error: 'No response data from complete task' }, isError: true };
 	}
 
 	// Build result matching expected format
@@ -440,7 +453,7 @@ export const deleteTask: Handler = async (args, ctx) => {
 	const response = await api.deleteTask(task_id);
 
 	if (!response.ok) {
-		throw new Error(`Failed to delete task: ${response.error}`);
+		return { result: { error: response.error || 'Failed to delete task' }, isError: true };
 	}
 
 	return { result: { success: true, deleted_id: task_id } };
@@ -456,7 +469,7 @@ export const addTaskReference: Handler = async (args, ctx) => {
 		if (response.error?.includes('already exists')) {
 			return { result: { success: false, error: 'Reference with this URL already exists' } };
 		}
-		throw new Error(`Failed to add reference: ${response.error}`);
+		return { result: { error: response.error || 'Failed to add reference' }, isError: true };
 	}
 
 	return {
@@ -477,7 +490,7 @@ export const removeTaskReference: Handler = async (args, ctx) => {
 		if (response.error?.includes('not found')) {
 			return { result: { success: false, error: 'Reference with this URL not found' } };
 		}
-		throw new Error(`Failed to remove reference: ${response.error}`);
+		return { result: { error: response.error || 'Failed to remove reference' }, isError: true };
 	}
 
 	return { result: { success: true } };
@@ -513,7 +526,7 @@ export const batchUpdateTasks: Handler = async (args, ctx) => {
 	const response = await api.batchUpdateTasks(typedUpdates);
 
 	if (!response.ok) {
-		throw new Error(`Failed to batch update tasks: ${response.error}`);
+		return { result: { error: response.error || 'Failed to batch update tasks' }, isError: true };
 	}
 
 	return {
@@ -553,7 +566,7 @@ export const batchCompleteTasks: Handler = async (args, ctx) => {
 	const response = await api.batchCompleteTasks(typedCompletions);
 
 	if (!response.ok) {
-		throw new Error(`Failed to batch complete tasks: ${response.error}`);
+		return { result: { error: response.error || 'Failed to batch complete tasks' }, isError: true };
 	}
 
 	const data = response.data;
@@ -593,7 +606,7 @@ export const addSubtask: Handler = async (args, ctx) => {
 				},
 			};
 		}
-		throw new Error(`Failed to add subtask: ${response.error}`);
+		return { result: { error: response.error || 'Failed to add subtask' }, isError: true };
 	}
 
 	return {
@@ -612,7 +625,7 @@ export const getSubtasks: Handler = async (args, ctx) => {
 	const response = await api.getSubtasks(parent_task_id, status);
 
 	if (!response.ok) {
-		throw new Error(`Failed to fetch subtasks: ${response.error}`);
+		return { result: { error: response.error || 'Failed to fetch subtasks' }, isError: true };
 	}
 
 	return {
@@ -627,6 +640,59 @@ export const getSubtasks: Handler = async (args, ctx) => {
 	};
 };
 
+// ============================================================================
+// Worktree Cleanup Handlers
+// ============================================================================
+
+const getStaleWorktreesSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const clearWorktreePathSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+export const getStaleWorktrees: Handler = async (args, ctx) => {
+	const { project_id } = parseArgs(args, getStaleWorktreesSchema);
+
+	const api = getApiClient();
+	const response = await api.getStaleWorktrees(project_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get stale worktrees' }, isError: true };
+	}
+
+	const data = response.data;
+	return {
+		result: {
+			project_id: data?.project_id,
+			project_name: data?.project_name,
+			stale_worktrees: data?.stale_worktrees || [],
+			count: data?.count || 0,
+			cleanup_instructions: data?.cleanup_instructions,
+		},
+	};
+};
+
+export const clearWorktreePath: Handler = async (args, ctx) => {
+	const { task_id } = parseArgs(args, clearWorktreePathSchema);
+
+	const api = getApiClient();
+	const response = await api.clearWorktreePath(task_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to clear worktree path' }, isError: true };
+	}
+
+	return {
+		result: {
+			success: true,
+			task_id,
+			message: 'Worktree path cleared. The worktree can now be safely removed if not already done.',
+		},
+	};
+};
+
 /**
  * Task handlers registry
  */
@@ -644,4 +710,7 @@ export const taskHandlers: HandlerRegistry = {
 	// Subtask handlers
 	add_subtask: addSubtask,
 	get_subtasks: getSubtasks,
+	// Worktree cleanup handlers
+	get_stale_worktrees: getStaleWorktrees,
+	clear_worktree_path: clearWorktreePath,
 };

package/src/handlers/tool-categories.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Tests for the documentation generator
+ */
+
+import { describe, it, expect } from 'vitest';
+import { tools } from '../tools.js';
+import { TOOL_CATEGORIES } from './discovery.js';
+
+describe('Documentation Generator Prerequisites', () => {
+	it('should have tools defined', () => {
+		expect(tools).toBeDefined();
+		expect(Array.isArray(tools)).toBe(true);
+		expect(tools.length).toBeGreaterThan(0);
+	});
+
+	it('should have TOOL_CATEGORIES exported', () => {
+		expect(TOOL_CATEGORIES).toBeDefined();
+		expect(typeof TOOL_CATEGORIES).toBe('object');
+	});
+
+	it('should have all tools categorized', () => {
+		const categorizedTools = new Set<string>();
+		for (const category of Object.values(TOOL_CATEGORIES)) {
+			for (const tool of category.tools) {
+				categorizedTools.add(tool.name);
+			}
+		}
+
+		const uncategorized = tools.filter((t) => !categorizedTools.has(t.name)).map((t) => t.name);
+
+		expect(uncategorized).toEqual([]);
+	});
+
+	it('should have valid tool schemas', () => {
+		for (const tool of tools) {
+			expect(tool.name).toBeDefined();
+			expect(typeof tool.name).toBe('string');
+			expect(tool.description).toBeDefined();
+			expect(typeof tool.description).toBe('string');
+			expect(tool.inputSchema).toBeDefined();
+			expect(tool.inputSchema.type).toBe('object');
+		}
+	});
+
+	it('should have category tools that exist in tools array', () => {
+		const toolNames = new Set(tools.map((t) => t.name));
+
+		for (const [categoryName, category] of Object.entries(TOOL_CATEGORIES)) {
+			for (const toolRef of category.tools) {
+				expect(toolNames.has(toolRef.name)).toBe(true);
+			}
+		}
+	});
+
+	it('should have unique tool names', () => {
+		const names = tools.map((t) => t.name);
+		const uniqueNames = new Set(names);
+		expect(names.length).toBe(uniqueNames.size);
+	});
+
+	it('should have unique category names', () => {
+		const names = Object.keys(TOOL_CATEGORIES);
+		const uniqueNames = new Set(names);
+		expect(names.length).toBe(uniqueNames.size);
+	});
+});