@vibescope/mcp-server 0.2.0 → 0.2.2

package/src/handlers/organizations.ts

@@ -18,40 +18,103 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
-import { validateRequired, validateUUID } from '../validators.js';
+import { parseArgs, uuidValidator, createEnumValidator, ValidationError } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
 // Valid roles in order of permission level
 const ROLE_ORDER = ['viewer', 'member', 'admin', 'owner'] as const;
+const ASSIGNABLE_ROLES = ['viewer', 'member', 'admin'] as const;
 type Role = (typeof ROLE_ORDER)[number];
+type AssignableRole = (typeof ASSIGNABLE_ROLES)[number];
 
 // Valid share permissions
 const PERMISSION_ORDER = ['read', 'write', 'admin'] as const;
 type Permission = (typeof PERMISSION_ORDER)[number];
 
+// ============================================================================
+// Argument Schemas
+// ============================================================================
+
+const createOrganizationSchema = {
+	name: { type: 'string' as const, required: true as const },
+	description: { type: 'string' as const },
+	slug: { type: 'string' as const },
+};
+
+const updateOrganizationSchema = {
+	organization_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	name: { type: 'string' as const },
+	description: { type: 'string' as const },
+	logo_url: { type: 'string' as const },
+};
+
+const deleteOrganizationSchema = {
+	organization_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const listOrgMembersSchema = {
+	organization_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const inviteMemberSchema = {
+	organization_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	email: { type: 'string' as const, required: true as const },
+	role: { type: 'string' as const, default: 'member', validate: createEnumValidator(ASSIGNABLE_ROLES) },
+};
+
+const updateMemberRoleSchema = {
+	organization_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	user_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	role: { type: 'string' as const, required: true as const, validate: createEnumValidator(ROLE_ORDER) },
+};
+
+const removeMemberSchema = {
+	organization_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	user_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const leaveOrganizationSchema = {
+	organization_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const shareProjectWithOrgSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	organization_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	permission: { type: 'string' as const, default: 'read', validate: createEnumValidator(PERMISSION_ORDER) },
+};
+
+const updateProjectShareSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	organization_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	permission: { type: 'string' as const, required: true as const, validate: createEnumValidator(PERMISSION_ORDER) },
+};
+
+const unshareProjectSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	organization_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const listProjectSharesSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
 // ============================================================================
 // Organization Management
 // ============================================================================
 
-export const listOrganizations: Handler = async (_args, ctx) => {
+export const listOrganizations: Handler = async (_args, _ctx) => {
 	const apiClient = getApiClient();
 	const response = await apiClient.listOrganizations();
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to list organizations');
+		return { result: { error: response.error || 'Failed to list organizations' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
-export const createOrganization: Handler = async (args, ctx) => {
-	const { name, description, slug } = args as {
-		name: string;
-		description?: string;
-		slug?: string;
-	};
-
-	validateRequired(name, 'name');
+export const createOrganization: Handler = async (args, _ctx) => {
+	const { name, description, slug } = parseArgs(args, createOrganizationSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.createOrganization({
@@ -61,53 +124,43 @@ export const createOrganization: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to create organization');
+		return { result: { error: response.error || 'Failed to create organization' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
-export const updateOrganization: Handler = async (args, ctx) => {
-	const { organization_id, name, description, logo_url } = args as {
-		organization_id: string;
-		name?: string;
-		description?: string;
-		logo_url?: string;
-	};
+export const updateOrganization: Handler = async (args, _ctx) => {
+	const { organization_id, name, description, logo_url } = parseArgs(args, updateOrganizationSchema);
 
-	validateRequired(organization_id, 'organization_id');
-	validateUUID(organization_id, 'organization_id');
+	// Check that at least one update is provided
+	if (name === undefined && description === undefined && logo_url === undefined) {
+		throw new ValidationError('No updates provided');
+	}
 
 	const updates: Record<string, unknown> = {};
 	if (name !== undefined) updates.name = name;
 	if (description !== undefined) updates.description = description;
 	if (logo_url !== undefined) updates.logo_url = logo_url;
 
-	if (Object.keys(updates).length === 0) {
-		throw new Error('No updates provided');
-	}
-
 	const apiClient = getApiClient();
 	const response = await apiClient.updateOrganization(organization_id, updates);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to update organization');
+		return { result: { error: response.error || 'Failed to update organization' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
-export const deleteOrganization: Handler = async (args, ctx) => {
-	const { organization_id } = args as { organization_id: string };
-
-	validateRequired(organization_id, 'organization_id');
-	validateUUID(organization_id, 'organization_id');
+export const deleteOrganization: Handler = async (args, _ctx) => {
+	const { organization_id } = parseArgs(args, deleteOrganizationSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.deleteOrganization(organization_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to delete organization');
+		return { result: { error: response.error || 'Failed to delete organization' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -117,110 +170,70 @@ export const deleteOrganization: Handler = async (args, ctx) => {
 // Member Management
 // ============================================================================
 
-export const listOrgMembers: Handler = async (args, ctx) => {
-	const { organization_id } = args as { organization_id: string };
-
-	validateRequired(organization_id, 'organization_id');
-	validateUUID(organization_id, 'organization_id');
+export const listOrgMembers: Handler = async (args, _ctx) => {
+	const { organization_id } = parseArgs(args, listOrgMembersSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.listOrgMembers(organization_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to list members');
+		return { result: { error: response.error || 'Failed to list members' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
-export const inviteMember: Handler = async (args, ctx) => {
-	const { organization_id, email, role = 'member' } = args as {
-		organization_id: string;
-		email: string;
-		role?: 'admin' | 'member' | 'viewer';
-	};
-
-	validateRequired(organization_id, 'organization_id');
-	validateRequired(email, 'email');
-	validateUUID(organization_id, 'organization_id');
-
-	if (!['admin', 'member', 'viewer'].includes(role)) {
-		throw new Error('Invalid role. Must be admin, member, or viewer.');
-	}
+export const inviteMember: Handler = async (args, _ctx) => {
+	const { organization_id, email, role } = parseArgs(args, inviteMemberSchema);
 
 	const apiClient = getApiClient();
-	const response = await apiClient.inviteMember(organization_id, email, role);
+	const response = await apiClient.inviteMember(organization_id, email, role as AssignableRole);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to create invite');
+		return { result: { error: response.error || 'Failed to create invite' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
-export const updateMemberRole: Handler = async (args, ctx) => {
-	const { organization_id, user_id, role } = args as {
-		organization_id: string;
-		user_id: string;
-		role: Role;
-	};
-
-	validateRequired(organization_id, 'organization_id');
-	validateRequired(user_id, 'user_id');
-	validateRequired(role, 'role');
-	validateUUID(organization_id, 'organization_id');
-	validateUUID(user_id, 'user_id');
-
-	if (!ROLE_ORDER.includes(role)) {
-		throw new Error(`Invalid role. Must be one of: ${ROLE_ORDER.join(', ')}`);
-	}
+export const updateMemberRole: Handler = async (args, _ctx) => {
+	const { organization_id, user_id, role } = parseArgs(args, updateMemberRoleSchema);
 
 	if (role === 'owner') {
-		throw new Error('Cannot assign owner role. Use transfer ownership instead.');
+		throw new ValidationError('Cannot assign owner role. Use transfer ownership instead.');
 	}
 
 	const apiClient = getApiClient();
-	const response = await apiClient.updateMemberRole(organization_id, user_id, role);
+	const response = await apiClient.updateMemberRole(organization_id, user_id, role as Role);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to update member role');
+		return { result: { error: response.error || 'Failed to update member role' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
-export const removeMember: Handler = async (args, ctx) => {
-	const { organization_id, user_id } = args as {
-		organization_id: string;
-		user_id: string;
-	};
-
-	validateRequired(organization_id, 'organization_id');
-	validateRequired(user_id, 'user_id');
-	validateUUID(organization_id, 'organization_id');
-	validateUUID(user_id, 'user_id');
+export const removeMember: Handler = async (args, _ctx) => {
+	const { organization_id, user_id } = parseArgs(args, removeMemberSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.removeMember(organization_id, user_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to remove member');
+		return { result: { error: response.error || 'Failed to remove member' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
-export const leaveOrganization: Handler = async (args, ctx) => {
-	const { organization_id } = args as { organization_id: string };
-
-	validateRequired(organization_id, 'organization_id');
-	validateUUID(organization_id, 'organization_id');
+export const leaveOrganization: Handler = async (args, _ctx) => {
+	const { organization_id } = parseArgs(args, leaveOrganizationSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.leaveOrganization(organization_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to leave organization');
+		return { result: { error: response.error || 'Failed to leave organization' }, isError: true };
 	}
 
 	return { result: response.data };
@@ -230,91 +243,53 @@ export const leaveOrganization: Handler = async (args, ctx) => {
 // Project Sharing
 // ============================================================================
 
-export const shareProjectWithOrg: Handler = async (args, ctx) => {
-	const { project_id, organization_id, permission = 'read' } = args as {
-		project_id: string;
-		organization_id: string;
-		permission?: Permission;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateRequired(organization_id, 'organization_id');
-	validateUUID(project_id, 'project_id');
-	validateUUID(organization_id, 'organization_id');
-
-	if (!PERMISSION_ORDER.includes(permission)) {
-		throw new Error(`Invalid permission. Must be one of: ${PERMISSION_ORDER.join(', ')}`);
-	}
+export const shareProjectWithOrg: Handler = async (args, _ctx) => {
+	const { project_id, organization_id, permission } = parseArgs(args, shareProjectWithOrgSchema);
 
 	const apiClient = getApiClient();
-	const response = await apiClient.shareProjectWithOrg(project_id, organization_id, permission);
+	const response = await apiClient.shareProjectWithOrg(project_id, organization_id, permission as Permission);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to share project');
+		return { result: { error: response.error || 'Failed to share project' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
-export const updateProjectShare: Handler = async (args, ctx) => {
-	const { project_id, organization_id, permission } = args as {
-		project_id: string;
-		organization_id: string;
-		permission: Permission;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateRequired(organization_id, 'organization_id');
-	validateRequired(permission, 'permission');
-	validateUUID(project_id, 'project_id');
-	validateUUID(organization_id, 'organization_id');
-
-	if (!PERMISSION_ORDER.includes(permission)) {
-		throw new Error(`Invalid permission. Must be one of: ${PERMISSION_ORDER.join(', ')}`);
-	}
+export const updateProjectShare: Handler = async (args, _ctx) => {
+	const { project_id, organization_id, permission } = parseArgs(args, updateProjectShareSchema);
 
 	const apiClient = getApiClient();
-	const response = await apiClient.updateProjectShare(project_id, organization_id, permission);
+	const response = await apiClient.updateProjectShare(project_id, organization_id, permission as Permission);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to update share');
+		return { result: { error: response.error || 'Failed to update share' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
-export const unshareProject: Handler = async (args, ctx) => {
-	const { project_id, organization_id } = args as {
-		project_id: string;
-		organization_id: string;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateRequired(organization_id, 'organization_id');
-	validateUUID(project_id, 'project_id');
-	validateUUID(organization_id, 'organization_id');
+export const unshareProject: Handler = async (args, _ctx) => {
+	const { project_id, organization_id } = parseArgs(args, unshareProjectSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.unshareProject(project_id, organization_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to unshare project');
+		return { result: { error: response.error || 'Failed to unshare project' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
-export const listProjectShares: Handler = async (args, ctx) => {
-	const { project_id } = args as { project_id: string };
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+export const listProjectShares: Handler = async (args, _ctx) => {
+	const { project_id } = parseArgs(args, listProjectSharesSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.listProjectShares(project_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to list shares');
+		return { result: { error: response.error || 'Failed to list shares' }, isError: true };
 	}
 
 	return { result: response.data };

package/src/handlers/progress.test.ts

@@ -103,19 +103,22 @@ describe('logProgress', () => {
 		expect(mockApiClient.logProgress).toHaveBeenCalled();
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.logProgress.mockResolvedValue({
 			ok: false,
 			error: 'Insert failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			logProgress({
-				project_id: '123e4567-e89b-12d3-a456-426614174000',
-				summary: 'Progress',
-			}, ctx)
-		).rejects.toThrow('Failed to log progress: Insert failed');
+		const result = await logProgress({
+			project_id: '123e4567-e89b-12d3-a456-426614174000',
+			summary: 'Progress',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Insert failed',
+		});
 	});
 
 	it('should throw error for missing project_id', async () => {
@@ -246,18 +249,21 @@ describe('getActivityFeed', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.getActivityFeed.mockResolvedValue({
 			ok: false,
 			error: 'Query failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getActivityFeed(
-				{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
-				ctx
-			)
-		).rejects.toThrow('Failed to fetch activity feed: Query failed');
+		const result = await getActivityFeed(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Query failed',
+		});
 	});
 });

package/src/handlers/progress.ts

@@ -9,20 +9,27 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
-import { validateRequired, validateUUID } from '../validators.js';
+import { parseArgs, uuidValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
-export const logProgress: Handler = async (args, ctx) => {
-	const { project_id, task_id, summary, details } = args as {
-		project_id: string;
-		task_id?: string;
-		summary: string;
-		details?: string;
-	};
+// Argument schemas for type-safe parsing
+const logProgressSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	task_id: { type: 'string' as const, validate: uuidValidator },
+	summary: { type: 'string' as const, required: true as const },
+	details: { type: 'string' as const },
+};
+
+const getActivityFeedSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	limit: { type: 'number' as const, default: 50 },
+	since: { type: 'string' as const },
+	types: { type: 'array' as const },
+	created_by: { type: 'string' as const },
+};
 
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
-	validateRequired(summary, 'summary');
+export const logProgress: Handler = async (args, ctx) => {
+	const { project_id, task_id, summary, details } = parseArgs(args, logProgressSchema);
 
 	const { session } = ctx;
 	const apiClient = getApiClient();
@@ -35,32 +42,27 @@ export const logProgress: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to log progress: ${response.error}`);
+		return { result: { error: response.error || 'Failed to log progress' }, isError: true };
 	}
 
 	return { result: { success: true, progress_id: response.data?.progress_id } };
 };
 
-export const getActivityFeed: Handler = async (args, ctx) => {
-	const { project_id, limit = 50, since } = args as {
-		project_id: string;
-		limit?: number;
-		since?: string;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+export const getActivityFeed: Handler = async (args, _ctx) => {
+	const { project_id, limit, since, types, created_by } = parseArgs(args, getActivityFeedSchema);
 
 	const apiClient = getApiClient();
-	const effectiveLimit = Math.min(limit, 200);
+	const effectiveLimit = Math.min(limit ?? 50, 200);
 
 	const response = await apiClient.getActivityFeed(project_id, {
 		limit: effectiveLimit,
-		since
+		since,
+		types: types as string[] | undefined,
+		created_by
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to fetch activity feed: ${response.error}`);
+		return { result: { error: response.error || 'Failed to fetch activity feed' }, isError: true };
 	}
 
 	return { result: { activities: response.data?.activities || [] } };

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' });
 	});
 });