@vibescope/mcp-server 0.2.0 → 0.2.2

package/src/handlers/discovery.ts

@@ -10,6 +10,16 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
+import { parseArgs } from '../validators.js';
+
+// Argument schemas for type-safe parsing
+const discoverToolsSchema = {
+	category: { type: 'string' as const },
+};
+
+const getToolInfoSchema = {
+	tool_name: { type: 'string' as const, required: true as const },
+};
 
 // Lazy-loaded tool documentation cache
 let toolInfoCache: Record<string, string> | null = null;
@@ -28,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: [
@@ -114,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' },
 		],
@@ -167,6 +178,26 @@ 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: {
+		description: 'Time-bounded sprints with velocity tracking',
+		tools: [
+			{ name: 'create_sprint', brief: 'Create new sprint' },
+			{ name: 'update_sprint', brief: 'Update sprint details' },
+			{ name: 'get_sprint', brief: 'Get sprint with tasks' },
+			{ name: 'get_sprints', brief: 'List project sprints' },
+			{ name: 'delete_sprint', brief: 'Delete sprint' },
+			{ name: 'start_sprint', brief: 'Start sprint' },
+			{ name: 'complete_sprint', brief: 'Complete sprint' },
+			{ name: 'add_task_to_sprint', brief: 'Add task to sprint' },
+			{ name: 'remove_task_from_sprint', brief: 'Remove from sprint' },
+			{ name: 'get_sprint_backlog', brief: 'Get available tasks' },
+			{ name: 'get_sprint_velocity', brief: 'Velocity metrics' },
 		],
 	},
 	requests: {
@@ -204,6 +235,17 @@ 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: {
+		description: 'Git conflict and issue tracking',
+		tools: [
+			{ name: 'add_git_issue', brief: 'Record git issue' },
+			{ name: 'resolve_git_issue', brief: 'Mark resolved' },
+			{ name: 'get_git_issues', brief: 'List git issues' },
+			{ name: 'delete_git_issue', brief: 'Delete git issue' },
 		],
 	},
 	knowledge: {
@@ -212,10 +254,62 @@ 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) => {
-	const { category } = args as { category?: string };
+	const { category } = parseArgs(args, discoverToolsSchema);
 
 	if (category) {
 		// Return tools in specific category
@@ -254,11 +348,7 @@ export const discoverTools: Handler = async (args) => {
 };
 
 export const getToolInfo: Handler = async (args) => {
-	const { tool_name } = args as { tool_name: string };
-
-	if (!tool_name) {
-		return { result: { error: 'tool_name is required' } };
-	}
+	const { tool_name } = parseArgs(args, getToolInfoSchema);
 
 	// Lazy-load tool documentation
 	const toolDocs = await getToolDocs();

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

@@ -11,7 +11,7 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
-import { validateRequired, validateUUID } from '../validators.js';
+import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
 import { FALLBACK_ACTIVITIES } from '../utils.js';
 import { getApiClient } from '../api-client.js';
 
@@ -26,26 +26,42 @@ const VALID_ACTIVITIES = [
 	'documentation_review',
 	'dependency_audit',
 	'validate_completed_tasks',
-];
+	'worktree_cleanup',
+] as const;
 
-export const startFallbackActivity: Handler = async (args, ctx) => {
-	const { project_id, activity } = args as { project_id: string; activity: string };
+type FallbackActivity = typeof VALID_ACTIVITIES[number];
 
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
-	validateRequired(activity, 'activity');
+// Argument schemas for type-safe parsing
+const startFallbackActivitySchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	activity: { type: 'string' as const, required: true as const, validate: createEnumValidator(VALID_ACTIVITIES) },
+};
 
-	if (!VALID_ACTIVITIES.includes(activity)) {
-		throw new Error(`Invalid activity. Must be one of: ${VALID_ACTIVITIES.join(', ')}`);
-	}
+const stopFallbackActivitySchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	summary: { type: 'string' as const },
+};
+
+const getActivityHistorySchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	activity_type: { type: 'string' as const },
+	limit: { type: 'number' as const, default: 50 },
+};
+
+const getActivitySchedulesSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+export const startFallbackActivity: Handler = async (args, ctx) => {
+	const { project_id, activity } = parseArgs(args, startFallbackActivitySchema);
 
 	const { session } = ctx;
 	const apiClient = getApiClient();
 
-	const response = await apiClient.startFallbackActivity(project_id, activity, session.currentSessionId || undefined);
+	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
@@ -75,10 +91,7 @@ export const startFallbackActivity: Handler = async (args, ctx) => {
 };
 
 export const stopFallbackActivity: Handler = async (args, ctx) => {
-	const { project_id, summary } = args as { project_id: string; summary?: string };
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+	const { project_id, summary } = parseArgs(args, stopFallbackActivitySchema);
 
 	const { session } = ctx;
 	const apiClient = getApiClient();
@@ -86,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 {
@@ -97,15 +110,8 @@ export const stopFallbackActivity: Handler = async (args, ctx) => {
 	};
 };
 
-export const getActivityHistory: Handler = async (args, ctx) => {
-	const { project_id, activity_type, limit = 50 } = args as {
-		project_id: string;
-		activity_type?: string;
-		limit?: number;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+export const getActivityHistory: Handler = async (args, _ctx) => {
+	const { project_id, activity_type, limit } = parseArgs(args, getActivityHistorySchema);
 
 	const apiClient = getApiClient();
 
@@ -126,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 {
@@ -138,11 +144,8 @@ export const getActivityHistory: Handler = async (args, ctx) => {
 	};
 };
 
-export const getActivitySchedules: Handler = async (args, ctx) => {
-	const { project_id } = args as { project_id: string };
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+export const getActivitySchedules: Handler = async (args, _ctx) => {
+	const { project_id } = parseArgs(args, getActivitySchedulesSchema);
 
 	const apiClient = getApiClient();
 
@@ -162,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 {