@vibescope/mcp-server 0.2.0 → 0.2.2

package/src/handlers/ideas.ts

@@ -12,22 +12,55 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
-import { validateRequired, validateUUID, validatePriority, validateEstimatedMinutes } from '../validators.js';
+import {
+	parseArgs,
+	uuidValidator,
+	priorityValidator,
+	minutesValidator,
+	createEnumValidator,
+} from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
-type IdeaStatus = 'raw' | 'exploring' | 'planned' | 'in_development' | 'shipped';
+const VALID_IDEA_STATUSES = ['raw', 'exploring', 'planned', 'in_development', 'shipped'] as const;
+type IdeaStatus = typeof VALID_IDEA_STATUSES[number];
 
-export const addIdea: Handler = async (args, ctx) => {
-	const { project_id, title, description, status } = args as {
-		project_id: string;
-		title: string;
-		description?: string;
-		status?: IdeaStatus;
-	};
+// Argument schemas for type-safe parsing
+const addIdeaSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const, required: true as const },
+	description: { type: 'string' as const },
+	status: { type: 'string' as const, validate: createEnumValidator(VALID_IDEA_STATUSES) },
+};
+
+const updateIdeaSchema = {
+	idea_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const },
+	description: { type: 'string' as const },
+	status: { type: 'string' as const, validate: createEnumValidator(VALID_IDEA_STATUSES) },
+	doc_url: { type: 'string' as const },
+};
 
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
-	validateRequired(title, 'title');
+const getIdeasSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	status: { type: 'string' as const, validate: createEnumValidator(VALID_IDEA_STATUSES) },
+	limit: { type: 'number' as const, default: 50 },
+	offset: { type: 'number' as const, default: 0 },
+	search_query: { type: 'string' as const },
+};
+
+const deleteIdeaSchema = {
+	idea_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const convertIdeaToTaskSchema = {
+	idea_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	priority: { type: 'number' as const, default: 3, validate: priorityValidator },
+	estimated_minutes: { type: 'number' as const, validate: minutesValidator },
+	update_status: { type: 'boolean' as const, default: true },
+};
+
+export const addIdea: Handler = async (args, ctx) => {
+	const { project_id, title, description, status } = parseArgs(args, addIdeaSchema);
 
 	const { session } = ctx;
 	const apiClient = getApiClient();
@@ -35,67 +68,49 @@ export const addIdea: Handler = async (args, ctx) => {
 	const response = await apiClient.addIdea(project_id, {
 		title,
 		description,
-		status
+		status: status as IdeaStatus | undefined
 	}, session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(`Failed to add idea: ${response.error}`);
+		return { result: { error: response.error || 'Failed to add idea' }, isError: true };
 	}
 
 	return { result: { success: true, idea_id: response.data?.idea_id, title } };
 };
 
-export const updateIdea: Handler = async (args, ctx) => {
-	const { idea_id, title, description, status, doc_url } = args as {
-		idea_id: string;
-		title?: string;
-		description?: string;
-		status?: IdeaStatus;
-		doc_url?: string;
-	};
-
-	validateRequired(idea_id, 'idea_id');
-	validateUUID(idea_id, 'idea_id');
+export const updateIdea: Handler = async (args, _ctx) => {
+	const { idea_id, title, description, status, doc_url } = parseArgs(args, updateIdeaSchema);
 
 	const apiClient = getApiClient();
 
 	const response = await apiClient.updateIdea(idea_id, {
 		title,
 		description,
-		status,
+		status: status as IdeaStatus | undefined,
 		doc_url
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to update idea: ${response.error}`);
+		return { result: { error: response.error || 'Failed to update idea' }, isError: true };
 	}
 
 	return { result: { success: true, idea_id } };
 };
 
-export const getIdeas: Handler = async (args, ctx) => {
-	const { project_id, status, limit = 50, offset = 0, search_query } = args as {
-		project_id: string;
-		status?: IdeaStatus;
-		limit?: number;
-		offset?: number;
-		search_query?: string;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+export const getIdeas: Handler = async (args, _ctx) => {
+	const { project_id, status, limit, offset, search_query } = parseArgs(args, getIdeasSchema);
 
 	const apiClient = getApiClient();
 
 	const response = await apiClient.getIdeas(project_id, {
-		status,
+		status: status as IdeaStatus | undefined,
 		limit,
 		offset,
 		search_query
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to fetch ideas: ${response.error}`);
+		return { result: { error: response.error || 'Failed to fetch ideas' }, isError: true };
 	}
 
 	return {
@@ -105,35 +120,22 @@ export const getIdeas: Handler = async (args, ctx) => {
 	};
 };
 
-export const deleteIdea: Handler = async (args, ctx) => {
-	const { idea_id } = args as { idea_id: string };
-
-	validateRequired(idea_id, 'idea_id');
-	validateUUID(idea_id, 'idea_id');
+export const deleteIdea: Handler = async (args, _ctx) => {
+	const { idea_id } = parseArgs(args, deleteIdeaSchema);
 
 	const apiClient = getApiClient();
 
 	const response = await apiClient.deleteIdea(idea_id);
 
 	if (!response.ok) {
-		throw new Error(`Failed to delete idea: ${response.error}`);
+		return { result: { error: response.error || 'Failed to delete idea' }, isError: true };
 	}
 
 	return { result: { success: true } };
 };
 
-export const convertIdeaToTask: Handler = async (args, ctx) => {
-	const { idea_id, priority = 3, estimated_minutes, update_status = true } = args as {
-		idea_id: string;
-		priority?: number;
-		estimated_minutes?: number;
-		update_status?: boolean;
-	};
-
-	validateRequired(idea_id, 'idea_id');
-	validateUUID(idea_id, 'idea_id');
-	validatePriority(priority);
-	validateEstimatedMinutes(estimated_minutes);
+export const convertIdeaToTask: Handler = async (args, _ctx) => {
+	const { idea_id, priority, estimated_minutes, update_status } = parseArgs(args, convertIdeaToTaskSchema);
 
 	const apiClient = getApiClient();
 
@@ -155,7 +157,7 @@ export const convertIdeaToTask: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to convert idea: ${response.error}`);
+		return { result: { error: response.error || 'Failed to convert idea' }, isError: true };
 	}
 
 	return { result: response.data };

package/src/handlers/index.ts

@@ -25,6 +25,9 @@ export * from './organizations.js';
 export * from './cost.js';
 export * from './git-issues.js';
 export * from './sprints.js';
+export * from './file-checkouts.js';
+export * from './roles.js';
+export * from './connectors.js';
 
 import type { HandlerRegistry } from './types.js';
 import { milestoneHandlers } from './milestones.js';
@@ -46,6 +49,9 @@ import { organizationHandlers } from './organizations.js';
 import { costHandlers } from './cost.js';
 import { gitIssueHandlers } from './git-issues.js';
 import { sprintHandlers } from './sprints.js';
+import { fileCheckoutHandlers } from './file-checkouts.js';
+import { roleHandlers } from './roles.js';
+import { connectorHandlers } from './connectors.js';
 
 /**
  * Build the complete handler registry from all modules
@@ -71,5 +77,8 @@ export function buildHandlerRegistry(): HandlerRegistry {
 		...costHandlers,
 		...gitIssueHandlers,
 		...sprintHandlers,
+		...fileCheckoutHandlers,
+		...roleHandlers,
+		...connectorHandlers,
 	};
 }

package/src/handlers/milestones.test.ts

@@ -90,19 +90,20 @@ describe('addMilestone', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.addMilestone.mockResolvedValue({
 			ok: false,
 			error: 'Task not found',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			addMilestone({
-				task_id: '123e4567-e89b-12d3-a456-426614174000',
-				title: 'Milestone 1',
-			}, ctx)
-		).rejects.toThrow('Failed to add milestone: Task not found');
+		const result = await addMilestone({
+			task_id: '123e4567-e89b-12d3-a456-426614174000',
+			title: 'Milestone 1',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Task not found' });
 	});
 });
 
@@ -132,7 +133,7 @@ describe('updateMilestone', () => {
 
 		await expect(
 			updateMilestone({ milestone_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow('At least one field to update is required');
+		).rejects.toThrow(ValidationError);
 	});
 
 	it('should throw error for invalid status', async () => {
@@ -143,7 +144,7 @@ describe('updateMilestone', () => {
 				milestone_id: '123e4567-e89b-12d3-a456-426614174000',
 				status: 'invalid_status',
 			}, ctx)
-		).rejects.toThrow('status must be pending, in_progress, or completed');
+		).rejects.toThrow(ValidationError);
 	});
 
 	it('should update title successfully', async () => {
@@ -192,19 +193,20 @@ describe('updateMilestone', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.updateMilestone.mockResolvedValue({
 			ok: false,
 			error: 'Milestone not found',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			updateMilestone({
-				milestone_id: '123e4567-e89b-12d3-a456-426614174000',
-				title: 'New Title',
-			}, ctx)
-		).rejects.toThrow('Failed to update milestone: Milestone not found');
+		const result = await updateMilestone({
+			milestone_id: '123e4567-e89b-12d3-a456-426614174000',
+			title: 'New Title',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Milestone not found' });
 	});
 });
 
@@ -263,16 +265,17 @@ describe('completeMilestone', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.completeMilestone.mockResolvedValue({
 			ok: false,
 			error: 'Milestone not found',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			completeMilestone({ milestone_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow('Failed to complete milestone: Milestone not found');
+		const result = await completeMilestone({ milestone_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Milestone not found' });
 	});
 });
 
@@ -332,16 +335,17 @@ describe('deleteMilestone', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.deleteMilestone.mockResolvedValue({
 			ok: false,
 			error: 'Milestone not found',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			deleteMilestone({ milestone_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow('Failed to delete milestone: Milestone not found');
+		const result = await deleteMilestone({ milestone_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Milestone not found' });
 	});
 });
 
@@ -456,15 +460,16 @@ describe('getMilestones', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.getMilestones.mockResolvedValue({
 			ok: false,
 			error: 'Task not found',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getMilestones({ task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow('Failed to get milestones: Task not found');
+		const result = await getMilestones({ task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Task not found' });
 	});
 });

package/src/handlers/milestones.ts

@@ -12,20 +12,47 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
-import { ValidationError, validateRequired, validateUUID } from '../validators.js';
+import {
+	parseArgs,
+	uuidValidator,
+	createEnumValidator,
+	ValidationError,
+} from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
-export const addMilestone: Handler = async (args, ctx) => {
-	const { task_id, title, description, order_index } = args as {
-		task_id: string;
-		title: string;
-		description?: string;
-		order_index?: number;
-	};
+const VALID_MILESTONE_STATUSES = ['pending', 'in_progress', 'completed'] as const;
+type MilestoneStatus = typeof VALID_MILESTONE_STATUSES[number];
+
+// Argument schemas for type-safe parsing
+const addMilestoneSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const, required: true as const },
+	description: { type: 'string' as const },
+	order_index: { type: 'number' as const },
+};
+
+const updateMilestoneSchema = {
+	milestone_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const },
+	description: { type: 'string' as const },
+	status: { type: 'string' as const, validate: createEnumValidator(VALID_MILESTONE_STATUSES) },
+	order_index: { type: 'number' as const },
+};
+
+const completeMilestoneSchema = {
+	milestone_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const deleteMilestoneSchema = {
+	milestone_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
 
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
-	validateRequired(title, 'title');
+const getMilestonesSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+export const addMilestone: Handler = async (args, ctx) => {
+	const { task_id, title, description, order_index } = parseArgs(args, addMilestoneSchema);
 
 	const { session } = ctx;
 	const apiClient = getApiClient();
@@ -37,7 +64,7 @@ export const addMilestone: Handler = async (args, ctx) => {
 	}, session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(`Failed to add milestone: ${response.error}`);
+		return { result: { error: response.error || 'Failed to add milestone' }, isError: true };
 	}
 
 	return {
@@ -48,24 +75,8 @@ export const addMilestone: Handler = async (args, ctx) => {
 	};
 };
 
-export const updateMilestone: Handler = async (args, ctx) => {
-	const { milestone_id, title, description, status, order_index } = args as {
-		milestone_id: string;
-		title?: string;
-		description?: string;
-		status?: string;
-		order_index?: number;
-	};
-
-	validateRequired(milestone_id, 'milestone_id');
-	validateUUID(milestone_id, 'milestone_id');
-
-	// Validate status if provided
-	if (status !== undefined) {
-		if (!['pending', 'in_progress', 'completed'].includes(status)) {
-			throw new ValidationError('status must be pending, in_progress, or completed');
-		}
-	}
+export const updateMilestone: Handler = async (args, _ctx) => {
+	const { milestone_id, title, description, status, order_index } = parseArgs(args, updateMilestoneSchema);
 
 	// Check that at least one field is provided
 	if (title === undefined && description === undefined && status === undefined && order_index === undefined) {
@@ -77,12 +88,12 @@ export const updateMilestone: Handler = async (args, ctx) => {
 	const response = await apiClient.updateMilestone(milestone_id, {
 		title,
 		description,
-		status: status as 'pending' | 'in_progress' | 'completed' | undefined,
+		status: status as MilestoneStatus | undefined,
 		order_index
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to update milestone: ${response.error}`);
+		return { result: { error: response.error || 'Failed to update milestone' }, isError: true };
 	}
 
 	return {
@@ -93,18 +104,15 @@ export const updateMilestone: Handler = async (args, ctx) => {
 	};
 };
 
-export const completeMilestone: Handler = async (args, ctx) => {
-	const { milestone_id } = args as { milestone_id: string };
-
-	validateRequired(milestone_id, 'milestone_id');
-	validateUUID(milestone_id, 'milestone_id');
+export const completeMilestone: Handler = async (args, _ctx) => {
+	const { milestone_id } = parseArgs(args, completeMilestoneSchema);
 
 	const apiClient = getApiClient();
 
 	const response = await apiClient.completeMilestone(milestone_id);
 
 	if (!response.ok) {
-		throw new Error(`Failed to complete milestone: ${response.error}`);
+		return { result: { error: response.error || 'Failed to complete milestone' }, isError: true };
 	}
 
 	return {
@@ -115,18 +123,15 @@ export const completeMilestone: Handler = async (args, ctx) => {
 	};
 };
 
-export const deleteMilestone: Handler = async (args, ctx) => {
-	const { milestone_id } = args as { milestone_id: string };
-
-	validateRequired(milestone_id, 'milestone_id');
-	validateUUID(milestone_id, 'milestone_id');
+export const deleteMilestone: Handler = async (args, _ctx) => {
+	const { milestone_id } = parseArgs(args, deleteMilestoneSchema);
 
 	const apiClient = getApiClient();
 
 	const response = await apiClient.deleteMilestone(milestone_id);
 
 	if (!response.ok) {
-		throw new Error(`Failed to delete milestone: ${response.error}`);
+		return { result: { error: response.error || 'Failed to delete milestone' }, isError: true };
 	}
 
 	return {
@@ -137,18 +142,15 @@ export const deleteMilestone: Handler = async (args, ctx) => {
 	};
 };
 
-export const getMilestones: Handler = async (args, ctx) => {
-	const { task_id } = args as { task_id: string };
-
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
+export const getMilestones: Handler = async (args, _ctx) => {
+	const { task_id } = parseArgs(args, getMilestonesSchema);
 
 	const apiClient = getApiClient();
 
 	const response = await apiClient.getMilestones(task_id);
 
 	if (!response.ok) {
-		throw new Error(`Failed to get milestones: ${response.error}`);
+		return { result: { error: response.error || 'Failed to get milestones' }, isError: true };
 	}
 
 	// Stats are calculated server-side now