@vibescope/mcp-server 0.2.1 → 0.2.3

package/src/handlers/discovery.ts

@@ -38,8 +38,8 @@ async function getToolDocs(): Promise<Record<string, string>> {
 	return toolInfoCache;
 }
 
-// Tool categories with brief descriptions
-const TOOL_CATEGORIES: Record<string, { description: string; tools: Array<{ name: string; brief: string }> }> = {
+// Tool categories with brief descriptions (exported for documentation generation)
+export const TOOL_CATEGORIES: Record<string, { description: string; tools: Array<{ name: string; brief: string }> }> = {
 	session: {
 		description: 'Session lifecycle and monitoring',
 		tools: [
@@ -124,6 +124,7 @@ const TOOL_CATEGORIES: Record<string, { description: string; tools: Array<{ name
 		tools: [
 			{ name: 'add_finding', brief: 'Record audit finding' },
 			{ name: 'get_findings', brief: 'List findings' },
+			{ name: 'get_findings_stats', brief: 'Get findings statistics' },
 			{ name: 'update_finding', brief: 'Update finding status' },
 			{ name: 'delete_finding', brief: 'Remove finding' },
 		],
@@ -177,6 +178,10 @@ const TOOL_CATEGORIES: Record<string, { description: string; tools: Array<{ name
 			{ name: 'add_task_to_body_of_work', brief: 'Add task to group' },
 			{ name: 'remove_task_from_body_of_work', brief: 'Remove from group' },
 			{ name: 'activate_body_of_work', brief: 'Activate for work' },
+			{ name: 'add_task_dependency', brief: 'Add task dependency' },
+			{ name: 'remove_task_dependency', brief: 'Remove task dependency' },
+			{ name: 'get_task_dependencies', brief: 'List task dependencies' },
+			{ name: 'get_next_body_of_work_task', brief: 'Get next available task' },
 		],
 	},
 	sprints: {
@@ -230,6 +235,8 @@ const TOOL_CATEGORIES: Record<string, { description: string; tools: Array<{ name
 			{ name: 'update_cost_alert', brief: 'Update alert config' },
 			{ name: 'delete_cost_alert', brief: 'Remove alert' },
 			{ name: 'get_task_costs', brief: 'Cost per task' },
+			{ name: 'get_body_of_work_costs', brief: 'Cost per body of work' },
+			{ name: 'get_sprint_costs', brief: 'Cost per sprint' },
 		],
 	},
 	git_issues: {
@@ -247,6 +254,58 @@ const TOOL_CATEGORIES: Record<string, { description: string; tools: Array<{ name
 			{ name: 'query_knowledge_base', brief: 'Aggregated project knowledge in one call' },
 		],
 	},
+	discovery: {
+		description: 'Tool discovery and documentation',
+		tools: [
+			{ name: 'discover_tools', brief: 'List tools by category' },
+			{ name: 'get_tool_info', brief: 'Get detailed tool docs' },
+		],
+	},
+	subtasks: {
+		description: 'Break tasks into smaller pieces',
+		tools: [
+			{ name: 'add_subtask', brief: 'Add subtask to task' },
+			{ name: 'get_subtasks', brief: 'List task subtasks' },
+		],
+	},
+	worktrees: {
+		description: 'Git worktree management',
+		tools: [
+			{ name: 'get_stale_worktrees', brief: 'Find orphaned worktrees' },
+			{ name: 'clear_worktree_path', brief: 'Clear worktree from task' },
+		],
+	},
+	roles: {
+		description: 'Agent role management',
+		tools: [
+			{ name: 'get_role_settings', brief: 'Get project role settings' },
+			{ name: 'update_role_settings', brief: 'Configure role behavior' },
+			{ name: 'set_session_role', brief: 'Set session role' },
+			{ name: 'get_agents_by_role', brief: 'List agents by role' },
+		],
+	},
+	file_locks: {
+		description: 'File checkout/locking for multi-agent',
+		tools: [
+			{ name: 'checkout_file', brief: 'Lock file for editing' },
+			{ name: 'checkin_file', brief: 'Release file lock' },
+			{ name: 'get_file_checkouts', brief: 'List file locks' },
+			{ name: 'abandon_checkout', brief: 'Force-release lock' },
+			{ name: 'is_file_available', brief: 'Check if file is free' },
+		],
+	},
+	connectors: {
+		description: 'External integration connectors',
+		tools: [
+			{ name: 'get_connectors', brief: 'List project connectors' },
+			{ name: 'get_connector', brief: 'Get connector details' },
+			{ name: 'add_connector', brief: 'Create new connector' },
+			{ name: 'update_connector', brief: 'Update connector config' },
+			{ name: 'delete_connector', brief: 'Remove connector' },
+			{ name: 'test_connector', brief: 'Send test event' },
+			{ name: 'get_connector_events', brief: 'Event history' },
+		],
+	},
 };
 
 export const discoverTools: Handler = async (args) => {

package/src/handlers/fallback.test.ts

@@ -48,7 +48,7 @@ describe('startFallbackActivity', () => {
 				project_id: '123e4567-e89b-12d3-a456-426614174000',
 				activity: 'invalid_activity',
 			}, ctx)
-		).rejects.toThrow('Invalid activity');
+		).rejects.toThrow(ValidationError);
 	});
 
 	it('should start fallback activity successfully', async () => {
@@ -131,19 +131,20 @@ describe('startFallbackActivity', () => {
 		}
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.startFallbackActivity.mockResolvedValue({
 			ok: false,
 			error: 'Failed to start activity',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			startFallbackActivity({
-				project_id: '123e4567-e89b-12d3-a456-426614174000',
-				activity: 'code_review',
-			}, ctx)
-		).rejects.toThrow('Failed to start fallback activity');
+		const result = await startFallbackActivity({
+			project_id: '123e4567-e89b-12d3-a456-426614174000',
+			activity: 'code_review',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to start activity' });
 	});
 
 	it('should pass through worktree guidance when API returns it', async () => {
@@ -286,18 +287,19 @@ describe('stopFallbackActivity', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.stopFallbackActivity.mockResolvedValue({
 			ok: false,
 			error: 'Failed to stop activity',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			stopFallbackActivity({
-				project_id: '123e4567-e89b-12d3-a456-426614174000',
-			}, ctx)
-		).rejects.toThrow('Failed to stop fallback activity');
+		const result = await stopFallbackActivity({
+			project_id: '123e4567-e89b-12d3-a456-426614174000',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to stop activity' });
 	});
 });
 
@@ -405,16 +407,17 @@ describe('getActivityHistory', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.proxy.mockResolvedValue({
 			ok: false,
 			error: 'Query failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getActivityHistory({ project_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow('Failed to get activity history');
+		const result = await getActivityHistory({ project_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Query failed' });
 	});
 });
 
@@ -518,15 +521,16 @@ describe('getActivitySchedules', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.proxy.mockResolvedValue({
 			ok: false,
 			error: 'Query failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getActivitySchedules({ project_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow('Failed to get activity schedules');
+		const result = await getActivitySchedules({ project_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Query failed' });
 	});
 });

package/src/handlers/fallback.ts

@@ -26,6 +26,7 @@ const VALID_ACTIVITIES = [
 	'documentation_review',
 	'dependency_audit',
 	'validate_completed_tasks',
+	'worktree_cleanup',
 ] as const;
 
 type FallbackActivity = typeof VALID_ACTIVITIES[number];
@@ -60,7 +61,7 @@ export const startFallbackActivity: Handler = async (args, ctx) => {
 	const response = await apiClient.startFallbackActivity(project_id, activity as FallbackActivity, session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(`Failed to start fallback activity: ${response.error}`);
+		return { result: { error: response.error || 'Failed to start fallback activity' }, isError: true };
 	}
 
 	// Get the activity details for the response
@@ -98,7 +99,7 @@ export const stopFallbackActivity: Handler = async (args, ctx) => {
 	const response = await apiClient.stopFallbackActivity(project_id, summary, session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(`Failed to stop fallback activity: ${response.error}`);
+		return { result: { error: response.error || 'Failed to stop fallback activity' }, isError: true };
 	}
 
 	return {
@@ -131,7 +132,7 @@ export const getActivityHistory: Handler = async (args, _ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to get activity history: ${response.error}`);
+		return { result: { error: response.error || 'Failed to get activity history' }, isError: true };
 	}
 
 	return {
@@ -164,7 +165,7 @@ export const getActivitySchedules: Handler = async (args, _ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to get activity schedules: ${response.error}`);
+		return { result: { error: response.error || 'Failed to get activity schedules' }, isError: true };
 	}
 
 	return {

package/src/handlers/file-checkouts.test.ts

@@ -4,6 +4,7 @@ import {
 	checkinFile,
 	getFileCheckouts,
 	abandonCheckout,
+	isFileAvailable,
 } from './file-checkouts.js';
 import { ValidationError } from '../validators.js';
 import { createMockContext, testUUID } from './__test-utils__.js';
@@ -87,33 +88,35 @@ describe('checkoutFile', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.checkoutFile.mockResolvedValue({
 			ok: false,
 			error: 'File already checked out',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			checkoutFile({
-				project_id: VALID_UUID,
-				file_path: '/src/index.ts',
-			}, ctx)
-		).rejects.toThrow('File already checked out');
+		const result = await checkoutFile({
+			project_id: VALID_UUID,
+			file_path: '/src/index.ts',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'File already checked out' });
 	});
 
-	it('should throw default error when API fails without message', async () => {
+	it('should return default error when API fails without message', async () => {
 		mockApiClient.checkoutFile.mockResolvedValue({
 			ok: false,
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			checkoutFile({
-				project_id: VALID_UUID,
-				file_path: '/src/index.ts',
-			}, ctx)
-		).rejects.toThrow('Failed to checkout file');
+		const result = await checkoutFile({
+			project_id: VALID_UUID,
+			file_path: '/src/index.ts',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to checkout file' });
 	});
 });
 
@@ -124,28 +127,31 @@ describe('checkoutFile', () => {
 describe('checkinFile', () => {
 	beforeEach(() => vi.clearAllMocks());
 
-	it('should throw error when neither checkout_id nor project_id+file_path provided', async () => {
+	it('should return error when neither checkout_id nor project_id+file_path provided', async () => {
 		const ctx = createMockContext();
 
-		await expect(
-			checkinFile({}, ctx)
-		).rejects.toThrow('Either checkout_id or both project_id and file_path are required');
+		const result = await checkinFile({}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Either checkout_id or both project_id and file_path are required' });
 	});
 
-	it('should throw error when only project_id provided without file_path', async () => {
+	it('should return error when only project_id provided without file_path', async () => {
 		const ctx = createMockContext();
 
-		await expect(
-			checkinFile({ project_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Either checkout_id or both project_id and file_path are required');
+		const result = await checkinFile({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Either checkout_id or both project_id and file_path are required' });
 	});
 
-	it('should throw error when only file_path provided without project_id', async () => {
+	it('should return error when only file_path provided without project_id', async () => {
 		const ctx = createMockContext();
 
-		await expect(
-			checkinFile({ file_path: '/src/index.ts' }, ctx)
-		).rejects.toThrow('Either checkout_id or both project_id and file_path are required');
+		const result = await checkinFile({ file_path: '/src/index.ts' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Either checkout_id or both project_id and file_path are required' });
 	});
 
 	it('should throw error for invalid checkout_id UUID', async () => {
@@ -215,16 +221,17 @@ describe('checkinFile', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.checkinFile.mockResolvedValue({
 			ok: false,
 			error: 'Checkout not found',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			checkinFile({ checkout_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Checkout not found');
+		const result = await checkinFile({ checkout_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Checkout not found' });
 	});
 });
 
@@ -353,16 +360,17 @@ describe('getFileCheckouts', () => {
 		expect(mockApiClient.getFileCheckouts).toHaveBeenCalledTimes(3);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.getFileCheckouts.mockResolvedValue({
 			ok: false,
 			error: 'Database error',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getFileCheckouts({ project_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Database error');
+		const result = await getFileCheckouts({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Database error' });
 	});
 });
 
@@ -373,20 +381,22 @@ describe('getFileCheckouts', () => {
 describe('abandonCheckout', () => {
 	beforeEach(() => vi.clearAllMocks());
 
-	it('should throw error when neither checkout_id nor project_id+file_path provided', async () => {
+	it('should return error when neither checkout_id nor project_id+file_path provided', async () => {
 		const ctx = createMockContext();
 
-		await expect(
-			abandonCheckout({}, ctx)
-		).rejects.toThrow('Either checkout_id or both project_id and file_path are required');
+		const result = await abandonCheckout({}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Either checkout_id or both project_id and file_path are required' });
 	});
 
-	it('should throw error when only project_id provided without file_path', async () => {
+	it('should return error when only project_id provided without file_path', async () => {
 		const ctx = createMockContext();
 
-		await expect(
-			abandonCheckout({ project_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Either checkout_id or both project_id and file_path are required');
+		const result = await abandonCheckout({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Either checkout_id or both project_id and file_path are required' });
 	});
 
 	it('should throw error for invalid checkout_id UUID', async () => {
@@ -452,26 +462,209 @@ describe('abandonCheckout', () => {
 		});
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.abandonCheckout.mockResolvedValue({
 			ok: false,
 			error: 'Checkout not found',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			abandonCheckout({ checkout_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Checkout not found');
+		const result = await abandonCheckout({ checkout_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Checkout not found' });
 	});
 
-	it('should throw default error when API fails without message', async () => {
+	it('should return default error when API fails without message', async () => {
 		mockApiClient.abandonCheckout.mockResolvedValue({
 			ok: false,
 		});
 		const ctx = createMockContext();
 
+		const result = await abandonCheckout({ checkout_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to abandon checkout' });
+	});
+});
+
+// ============================================================================
+// isFileAvailable Tests
+// ============================================================================
+
+describe('isFileAvailable', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
 		await expect(
-			abandonCheckout({ checkout_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Failed to abandon checkout');
+			isFileAvailable({ file_path: '/src/index.ts' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid project_id UUID', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			isFileAvailable({ project_id: 'invalid', file_path: '/src/index.ts' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for missing file_path', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			isFileAvailable({ project_id: VALID_UUID }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should return available=true when file has no active checkout', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: { checkouts: [] },
+		});
+		const ctx = createMockContext();
+
+		const result = await isFileAvailable(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			available: true,
+			file_path: '/src/index.ts',
+			checked_out_by: null,
+		});
+	});
+
+	it('should return available=false with checkout info when file is checked out', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: {
+				checkouts: [{
+					id: 'checkout-123',
+					file_path: '/src/index.ts',
+					status: 'checked_out',
+					checked_out_by: 'Apex',
+					checked_out_at: '2026-01-16T10:00:00Z',
+					checkout_reason: 'Working on feature X',
+				}],
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await isFileAvailable(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			available: false,
+			file_path: '/src/index.ts',
+			checked_out_by: {
+				checkout_id: 'checkout-123',
+				checked_out_by: 'Apex',
+				checked_out_at: '2026-01-16T10:00:00Z',
+				reason: 'Working on feature X',
+			},
+		});
+	});
+
+	it('should query API with correct parameters', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: { checkouts: [] },
+		});
+		const ctx = createMockContext();
+
+		await isFileAvailable(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(mockApiClient.getFileCheckouts).toHaveBeenCalledWith(VALID_UUID, {
+			status: 'checked_out',
+			file_path: '/src/index.ts',
+			limit: 1,
+		});
+	});
+
+	it('should return error when API call fails', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: false,
+			error: 'Project not found',
+		});
+		const ctx = createMockContext();
+
+		const result = await isFileAvailable({
+			project_id: VALID_UUID,
+			file_path: '/src/index.ts',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Project not found' });
+	});
+
+	it('should return default error when API fails without message', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: false,
+		});
+		const ctx = createMockContext();
+
+		const result = await isFileAvailable({
+			project_id: VALID_UUID,
+			file_path: '/src/index.ts',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to check file availability' });
+	});
+
+	it('should handle empty checkouts array gracefully', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: { checkouts: [] },
+		});
+		const ctx = createMockContext();
+
+		const result = await isFileAvailable(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(result.result.available).toBe(true);
+		expect(result.result.checked_out_by).toBeNull();
+	});
+
+	it('should handle undefined checkouts gracefully', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: {},
+		});
+		const ctx = createMockContext();
+
+		const result = await isFileAvailable(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(result.result.available).toBe(true);
+		expect(result.result.checked_out_by).toBeNull();
 	});
 });