@vibescope/mcp-server 0.2.1 → 0.2.3

package/src/handlers/file-checkouts.ts

@@ -6,6 +6,7 @@
  * - checkin_file: Check in a file after editing
  * - get_file_checkouts: Get active checkouts for a project
  * - abandon_checkout: Force release a checkout
+ * - is_file_available: Check if a file is available for checkout
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
@@ -41,6 +42,11 @@ const abandonCheckoutSchema = {
 	file_path: { type: 'string' as const },
 };
 
+const isFileAvailableSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	file_path: { type: 'string' as const, required: true as const },
+};
+
 export const checkoutFile: Handler = async (args, ctx) => {
 	const { project_id, file_path, reason } = parseArgs(args, checkoutFileSchema);
 
@@ -48,7 +54,7 @@ export const checkoutFile: Handler = async (args, ctx) => {
 	const response = await apiClient.checkoutFile(project_id, file_path, reason, ctx.session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to checkout file');
+		return { result: { error: response.error || 'Failed to checkout file' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -59,7 +65,7 @@ export const checkinFile: Handler = async (args, ctx) => {
 
 	// Validate that either checkout_id or both project_id and file_path are provided
 	if (!checkout_id && (!project_id || !file_path)) {
-		throw new Error('Either checkout_id or both project_id and file_path are required');
+		return { result: { error: 'Either checkout_id or both project_id and file_path are required' }, isError: true };
 	}
 
 	const apiClient = getApiClient();
@@ -71,7 +77,7 @@ export const checkinFile: Handler = async (args, ctx) => {
 	}, ctx.session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to checkin file');
+		return { result: { error: response.error || 'Failed to checkin file' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -88,7 +94,7 @@ export const getFileCheckouts: Handler = async (args, _ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to get file checkouts');
+		return { result: { error: response.error || 'Failed to get file checkouts' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -99,7 +105,7 @@ export const abandonCheckout: Handler = async (args, _ctx) => {
 
 	// Validate that either checkout_id or both project_id and file_path are provided
 	if (!checkout_id && (!project_id || !file_path)) {
-		throw new Error('Either checkout_id or both project_id and file_path are required');
+		return { result: { error: 'Either checkout_id or both project_id and file_path are required' }, isError: true };
 	}
 
 	const apiClient = getApiClient();
@@ -110,12 +116,43 @@ export const abandonCheckout: Handler = async (args, _ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to abandon checkout');
+		return { result: { error: response.error || 'Failed to abandon checkout' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
+export const isFileAvailable: Handler = async (args, _ctx) => {
+	const { project_id, file_path } = parseArgs(args, isFileAvailableSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getFileCheckouts(project_id, {
+		status: 'checked_out',
+		file_path,
+		limit: 1
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to check file availability' }, isError: true };
+	}
+
+	const checkouts = response.data?.checkouts || [];
+	const activeCheckout = checkouts.length > 0 ? checkouts[0] : null;
+
+	return {
+		result: {
+			available: !activeCheckout,
+			file_path,
+			checked_out_by: activeCheckout ? {
+				checkout_id: activeCheckout.id,
+				checked_out_by: activeCheckout.checked_out_by,
+				checked_out_at: activeCheckout.checked_out_at,
+				reason: activeCheckout.checkout_reason
+			} : null
+		}
+	};
+};
+
 /**
  * File Checkouts handlers registry
  */
@@ -124,4 +161,5 @@ export const fileCheckoutHandlers: HandlerRegistry = {
 	checkin_file: checkinFile,
 	get_file_checkouts: getFileCheckouts,
 	abandon_checkout: abandonCheckout,
+	is_file_available: isFileAvailable,
 };

package/src/handlers/findings.test.ts

@@ -106,16 +106,17 @@ describe('addFinding', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.addFinding.mockResolvedValue({
 			ok: false,
 			error: 'Insert failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			addFinding({ project_id: VALID_UUID, title: 'Test' }, ctx)
-		).rejects.toThrow('Insert failed');
+		const result = await addFinding({ project_id: VALID_UUID, title: 'Test' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Insert failed' });
 	});
 });
 
@@ -259,16 +260,17 @@ describe('getFindings', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.getFindings.mockResolvedValue({
 			ok: false,
 			error: 'Query failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getFindings({ project_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Query failed');
+		const result = await getFindings({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Query failed' });
 	});
 });
 
@@ -339,16 +341,17 @@ describe('updateFinding', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.updateFinding.mockResolvedValue({
 			ok: false,
 			error: 'Update failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			updateFinding({ finding_id: VALID_UUID, title: 'Test' }, ctx)
-		).rejects.toThrow('Update failed');
+		const result = await updateFinding({ finding_id: VALID_UUID, title: 'Test' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Update failed' });
 	});
 });
 
@@ -397,16 +400,17 @@ describe('deleteFinding', () => {
 		expect(mockApiClient.deleteFinding).toHaveBeenCalledWith(VALID_UUID);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.deleteFinding.mockResolvedValue({
 			ok: false,
 			error: 'Delete failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			deleteFinding({ finding_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Delete failed');
+		const result = await deleteFinding({ finding_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Delete failed' });
 	});
 });
 
@@ -461,16 +465,17 @@ describe('getFindingsStats', () => {
 		expect(mockApiClient.getFindingsStats).toHaveBeenCalledWith(VALID_UUID);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.getFindingsStats.mockResolvedValue({
 			ok: false,
 			error: 'Query failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getFindingsStats({ project_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Query failed');
+		const result = await getFindingsStats({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Query failed' });
 	});
 });
 
@@ -495,6 +500,14 @@ describe('queryKnowledgeBase', () => {
 		).rejects.toThrow(ValidationError);
 	});
 
+	it('should throw error for invalid scope value', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			queryKnowledgeBase({ project_id: VALID_UUID, scope: 'invalid_scope' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
 	it('should query with default parameters', async () => {
 		mockApiClient.queryKnowledgeBase.mockResolvedValue({
 			ok: true,
@@ -605,15 +618,16 @@ describe('queryKnowledgeBase', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.queryKnowledgeBase.mockResolvedValue({
 			ok: false,
 			error: 'Query failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			queryKnowledgeBase({ project_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Query failed');
+		const result = await queryKnowledgeBase({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Query failed' });
 	});
 });

package/src/handlers/findings.ts

@@ -10,6 +10,7 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
+import { success, error } from './types.js';
 import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
@@ -86,10 +87,10 @@ export const addFinding: Handler = async (args, ctx) => {
 	}, ctx.session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to add finding');
+		return error(response.error || 'Failed to add finding');
 	}
 
-	return { result: response.data };
+	return success(response.data);
 };
 
 export const getFindings: Handler = async (args, _ctx) => {
@@ -107,10 +108,10 @@ export const getFindings: Handler = async (args, _ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to get findings');
+		return error(response.error || 'Failed to get findings');
 	}
 
-	return { result: response.data };
+	return success(response.data);
 };
 
 /**
@@ -125,10 +126,10 @@ export const getFindingsStats: Handler = async (args, _ctx) => {
 	const response = await apiClient.getFindingsStats(project_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to get findings stats');
+		return error(response.error || 'Failed to get findings stats');
 	}
 
-	return { result: response.data };
+	return success(response.data);
 };
 
 export const updateFinding: Handler = async (args, _ctx) => {
@@ -144,10 +145,10 @@ export const updateFinding: Handler = async (args, _ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to update finding');
+		return error(response.error || 'Failed to update finding');
 	}
 
-	return { result: response.data };
+	return success(response.data);
 };
 
 export const deleteFinding: Handler = async (args, _ctx) => {
@@ -157,10 +158,10 @@ export const deleteFinding: Handler = async (args, _ctx) => {
 	const response = await apiClient.deleteFinding(finding_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to delete finding');
+		return error(response.error || 'Failed to delete finding');
 	}
 
-	return { result: response.data };
+	return success(response.data);
 };
 
 /**
@@ -183,10 +184,10 @@ export const queryKnowledgeBase: Handler = async (args, _ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to query knowledge base');
+		return error(response.error || 'Failed to query knowledge base');
 	}
 
-	return { result: response.data };
+	return success(response.data);
 };
 
 /**

package/src/handlers/git-issues.test.ts

@@ -60,7 +60,7 @@ describe('addGitIssue', () => {
 				issue_type: 'invalid_type',
 				branch: 'feature/test',
 			}, ctx)
-		).rejects.toThrow('Invalid issue_type');
+		).rejects.toThrow(ValidationError);
 	});
 
 	it('should throw error for invalid task_id UUID', async () => {
@@ -180,35 +180,37 @@ describe('addGitIssue', () => {
 		}
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.addGitIssue.mockResolvedValue({
 			ok: false,
 			error: 'Insert failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			addGitIssue({
-				project_id: VALID_PROJECT_ID,
-				issue_type: 'merge_conflict',
-				branch: 'feature/test',
-			}, ctx)
-		).rejects.toThrow('Insert failed');
+		const result = await addGitIssue({
+			project_id: VALID_PROJECT_ID,
+			issue_type: 'merge_conflict',
+			branch: 'feature/test',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Insert failed' });
 	});
 
-	it('should throw default error message when API fails without error', async () => {
+	it('should return default error message when API fails without error', async () => {
 		mockApiClient.addGitIssue.mockResolvedValue({
 			ok: false,
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			addGitIssue({
-				project_id: VALID_PROJECT_ID,
-				issue_type: 'merge_conflict',
-				branch: 'feature/test',
-			}, ctx)
-		).rejects.toThrow('Failed to add git issue');
+		const result = await addGitIssue({
+			project_id: VALID_PROJECT_ID,
+			issue_type: 'merge_conflict',
+			branch: 'feature/test',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to add git issue' });
 	});
 });
 
@@ -314,27 +316,29 @@ describe('resolveGitIssue', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.resolveGitIssue.mockResolvedValue({
 			ok: false,
 			error: 'Update failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			resolveGitIssue({ git_issue_id: VALID_GIT_ISSUE_ID }, ctx)
-		).rejects.toThrow('Update failed');
+		const result = await resolveGitIssue({ git_issue_id: VALID_GIT_ISSUE_ID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Update failed' });
 	});
 
-	it('should throw default error message when API fails without error', async () => {
+	it('should return default error message when API fails without error', async () => {
 		mockApiClient.resolveGitIssue.mockResolvedValue({
 			ok: false,
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			resolveGitIssue({ git_issue_id: VALID_GIT_ISSUE_ID }, ctx)
-		).rejects.toThrow('Failed to resolve git issue');
+		const result = await resolveGitIssue({ git_issue_id: VALID_GIT_ISSUE_ID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to resolve git issue' });
 	});
 });
 
@@ -364,7 +368,7 @@ describe('getGitIssues', () => {
 
 		await expect(
 			getGitIssues({ project_id: VALID_PROJECT_ID, status: 'invalid_status' }, ctx)
-		).rejects.toThrow('Invalid status');
+		).rejects.toThrow(ValidationError);
 	});
 
 	it('should throw error for invalid issue_type filter', async () => {
@@ -372,7 +376,7 @@ describe('getGitIssues', () => {
 
 		await expect(
 			getGitIssues({ project_id: VALID_PROJECT_ID, issue_type: 'invalid_type' }, ctx)
-		).rejects.toThrow('Invalid issue_type');
+		).rejects.toThrow(ValidationError);
 	});
 
 	it('should return empty list when no git issues', async () => {
@@ -519,27 +523,29 @@ describe('getGitIssues', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.getGitIssues.mockResolvedValue({
 			ok: false,
 			error: 'Query failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getGitIssues({ project_id: VALID_PROJECT_ID }, ctx)
-		).rejects.toThrow('Query failed');
+		const result = await getGitIssues({ project_id: VALID_PROJECT_ID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Query failed' });
 	});
 
-	it('should throw default error message when API fails without error', async () => {
+	it('should return default error message when API fails without error', async () => {
 		mockApiClient.getGitIssues.mockResolvedValue({
 			ok: false,
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getGitIssues({ project_id: VALID_PROJECT_ID }, ctx)
-		).rejects.toThrow('Failed to fetch git issues');
+		const result = await getGitIssues({ project_id: VALID_PROJECT_ID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to fetch git issues' });
 	});
 });
 
@@ -598,26 +604,28 @@ describe('deleteGitIssue', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.deleteGitIssue.mockResolvedValue({
 			ok: false,
 			error: 'Delete failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			deleteGitIssue({ git_issue_id: VALID_GIT_ISSUE_ID }, ctx)
-		).rejects.toThrow('Delete failed');
+		const result = await deleteGitIssue({ git_issue_id: VALID_GIT_ISSUE_ID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Delete failed' });
 	});
 
-	it('should throw default error message when API fails without error', async () => {
+	it('should return default error message when API fails without error', async () => {
 		mockApiClient.deleteGitIssue.mockResolvedValue({
 			ok: false,
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			deleteGitIssue({ git_issue_id: VALID_GIT_ISSUE_ID }, ctx)
-		).rejects.toThrow('Failed to delete git issue');
+		const result = await deleteGitIssue({ git_issue_id: VALID_GIT_ISSUE_ID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to delete git issue' });
 	});
 });

package/src/handlers/git-issues.ts

@@ -70,7 +70,7 @@ export const addGitIssue: Handler = async (args, ctx) => {
 	}, ctx.session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to add git issue');
+		return { result: { error: response.error || 'Failed to add git issue' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -86,7 +86,7 @@ export const resolveGitIssue: Handler = async (args, ctx) => {
 	}, ctx.session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to resolve git issue');
+		return { result: { error: response.error || 'Failed to resolve git issue' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -104,7 +104,7 @@ export const getGitIssues: Handler = async (args, _ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to fetch git issues');
+		return { result: { error: response.error || 'Failed to fetch git issues' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -117,7 +117,7 @@ export const deleteGitIssue: Handler = async (args, _ctx) => {
 	const response = await apiClient.deleteGitIssue(git_issue_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to delete git issue');
+		return { result: { error: response.error || 'Failed to delete git issue' }, isError: true };
 	}
 
 	return { result: response.data };