@vibescope/mcp-server 0.1.0 → 0.2.1

package/src/api-client.ts

@@ -47,7 +47,8 @@ export class VibescopeApiClient {
 				return {
 					ok: false,
 					status: response.status,
-					error: data.error || `HTTP ${response.status}`
+					error: data.error || `HTTP ${response.status}`,
+					data // Include full response data for additional error context
 				};
 			}
 
@@ -137,13 +138,16 @@ export class VibescopeApiClient {
 		return this.request('POST', '/api/mcp/sessions/start', params);
 	}
 
-	async heartbeat(sessionId: string): Promise<ApiResponse<{
+	async heartbeat(sessionId: string, options?: {
+		current_worktree_path?: string | null;
+	}): Promise<ApiResponse<{
 		success: boolean;
 		session_id: string;
 		timestamp: string;
 	}>> {
 		return this.request('POST', '/api/mcp/sessions/heartbeat', {
-			session_id: sessionId
+			session_id: sessionId,
+			...options
 		});
 	}
 
@@ -303,6 +307,7 @@ export class VibescopeApiClient {
 		estimated_minutes?: number;
 		blocking?: boolean;
 		session_id?: string;
+		task_type?: string;
 	}): Promise<ApiResponse<{
 		success: boolean;
 		task_id: string;
@@ -381,6 +386,20 @@ export class VibescopeApiClient {
 	}): Promise<ApiResponse<{
 		success: boolean;
 		task_id: string;
+		git_workflow?: {
+			workflow: string;
+			base_branch: string;
+			suggested_branch: string;
+			worktree_required: boolean;
+		};
+		worktree_setup?: {
+			message: string;
+			commands: string[];
+			worktree_path: string;
+			branch_name: string;
+			cleanup_command: string;
+		};
+		next_step?: string;
 	}>> {
 		return this.request('PATCH', `/api/mcp/tasks/${taskId}`, updates);
 	}
@@ -405,6 +424,7 @@ export class VibescopeApiClient {
 			deployment?: string;
 		};
 		next_action: string;
+		warnings?: string[];
 	}>> {
 		return this.request('POST', `/api/mcp/tasks/${taskId}/complete`, params);
 	}
@@ -521,7 +541,11 @@ export class VibescopeApiClient {
 	// ============================================================================
 	// Decision endpoints
 	// ============================================================================
-	async getDecisions(projectId: string): Promise<ApiResponse<{
+	async getDecisions(projectId: string, options?: {
+		limit?: number;
+		offset?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
 		decisions: Array<{
 			id: string;
 			title: string;
@@ -531,7 +555,7 @@ export class VibescopeApiClient {
 			created_at: string;
 		}>;
 	}>> {
-		return this.proxy('get_decisions', { project_id: projectId });
+		return this.proxy('get_decisions', { project_id: projectId, ...options });
 	}
 
 	async logDecision(projectId: string, params: {
@@ -642,6 +666,9 @@ export class VibescopeApiClient {
 		severity?: string;
 		status?: string;
 		limit?: number;
+		offset?: number;
+		search_query?: string;
+		summary_only?: boolean;
 	}): Promise<ApiResponse<{
 		findings: Array<{
 			id: string;
@@ -655,6 +682,8 @@ export class VibescopeApiClient {
 			resolution_note?: string;
 			created_at: string;
 		}>;
+		total_count?: number;
+		has_more?: boolean;
 	}>> {
 		return this.proxy('get_findings', {
 			project_id: projectId,
@@ -662,6 +691,17 @@ export class VibescopeApiClient {
 		});
 	}
 
+	async getFindingsStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+		by_status: Record<string, number>;
+		by_severity: Record<string, number>;
+		by_category: Record<string, number>;
+	}>> {
+		return this.proxy('get_findings_stats', {
+			project_id: projectId
+		});
+	}
+
 	async addFinding(projectId: string, params: {
 		title: string;
 		description?: string;
@@ -839,11 +879,13 @@ export class VibescopeApiClient {
 	async validateTask(taskId: string, params: {
 		approved: boolean;
 		validation_notes?: string;
+		skip_pr_check?: boolean;
 	}, sessionId?: string): Promise<ApiResponse<{
 		success: boolean;
 		approved: boolean;
 		task_id: string;
 		message?: string;
+		workflow?: string;
 	}>> {
 		return this.proxy('validate_task', {
 			task_id: taskId,
@@ -858,6 +900,21 @@ export class VibescopeApiClient {
 		success: boolean;
 		activity: string;
 		message: string;
+		git_workflow?: {
+			workflow: string;
+			base_branch: string;
+			worktree_recommended: boolean;
+			note: string;
+		};
+		worktree_setup?: {
+			message: string;
+			commands: string[];
+			worktree_path: string;
+			branch_name: string;
+			cleanup_command: string;
+			report_worktree: string;
+		};
+		next_step?: string;
 	}>> {
 		return this.proxy('start_fallback_activity', {
 			project_id: projectId,
@@ -954,6 +1011,8 @@ export class VibescopeApiClient {
 	async getActivityFeed(projectId: string, params?: {
 		limit?: number;
 		since?: string;
+		types?: string[];
+		created_by?: string;
 	}): Promise<ApiResponse<{
 		activities: Array<{
 			type: string;
@@ -1088,14 +1147,17 @@ export class VibescopeApiClient {
 	// Knowledge base endpoint
 	// ============================================================================
 	async queryKnowledgeBase(projectId: string, params?: {
+		scope?: 'summary' | 'detailed';
 		categories?: string[];
 		limit?: number;
 		search_query?: string;
 	}): Promise<ApiResponse<{
-		findings?: Array<{ id: string; title: string; category: string; severity: string }>;
-		decisions?: Array<{ id: string; title: string; description: string }>;
-		completed_tasks?: Array<{ id: string; title: string; completed_at: string }>;
+		findings?: Array<{ id: string; title: string; category: string; severity: string; description?: string }>;
+		decisions?: Array<{ id: string; title: string; description: string; rationale?: string }>;
+		completed_tasks?: Array<{ id: string; title: string; completed_at: string; summary?: string }>;
 		resolved_blockers?: Array<{ id: string; description: string; resolution_note?: string }>;
+		progress?: Array<{ id: string; summary: string; details?: string }>;
+		qa?: Array<{ id: string; question: string; answer: string }>;
 	}>> {
 		return this.proxy('query_knowledge_base', {
 			project_id: projectId,
@@ -1591,6 +1653,7 @@ export class VibescopeApiClient {
 		file_path?: string;
 		stage?: string;
 		blocking?: boolean;
+		recurring?: boolean;
 	}): Promise<ApiResponse<{
 		success: boolean;
 		requirement_id: string;
@@ -1730,6 +1793,96 @@ export class VibescopeApiClient {
 			readme_content: readmeContent
 		});
 	}
+
+	// ============================================================================
+	// Help Topics (database-backed)
+	// ============================================================================
+	async getHelpTopic(slug: string): Promise<ApiResponse<{
+		slug: string;
+		title: string;
+		content: string;
+	} | null>> {
+		return this.proxy('get_help_topic', { slug });
+	}
+
+	async getHelpTopics(): Promise<ApiResponse<Array<{
+		slug: string;
+		title: string;
+	}>>> {
+		return this.proxy('get_help_topics', {});
+	}
+
+	// ============================================================================
+	// File Checkout endpoints (multi-agent coordination)
+	// ============================================================================
+	async checkoutFile(projectId: string, filePath: string, reason?: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		checkout_id: string;
+		file_path: string;
+		already_checked_out?: boolean;
+		message: string;
+	}>> {
+		return this.proxy('checkout_file', {
+			project_id: projectId,
+			file_path: filePath,
+			reason
+		}, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async checkinFile(params: {
+		checkout_id?: string;
+		project_id?: string;
+		file_path?: string;
+		summary?: string;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		checkout_id: string;
+		message: string;
+	}>> {
+		return this.proxy('checkin_file', params, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async getFileCheckouts(projectId: string, options?: {
+		status?: string;
+		file_path?: string;
+		limit?: number;
+	}): Promise<ApiResponse<{
+		checkouts: Array<{
+			id: string;
+			file_path: string;
+			status: string;
+			checked_out_at: string;
+			checkout_reason?: string;
+			checked_in_at?: string;
+			checkin_summary?: string;
+			checked_out_by?: string;
+		}>;
+	}>> {
+		return this.proxy('get_file_checkouts', {
+			project_id: projectId,
+			...options
+		});
+	}
+
+	async abandonCheckout(params: {
+		checkout_id?: string;
+		project_id?: string;
+		file_path?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		checkout_id: string;
+		message: string;
+	}>> {
+		return this.proxy('abandon_checkout', params);
+	}
 }
 
 // Singleton instance

package/src/handlers/__test-setup__.ts

@@ -77,8 +77,10 @@ export const mockApiClient = {
 	// Findings
 	addFinding: vi.fn(),
 	getFindings: vi.fn(),
+	getFindingsStats: vi.fn(),
 	updateFinding: vi.fn(),
 	deleteFinding: vi.fn(),
+	queryKnowledgeBase: vi.fn(),
 
 	// Requests
 	getPendingRequests: vi.fn(),
@@ -164,6 +166,16 @@ export const mockApiClient = {
 	claimValidation: vi.fn(),
 	validateTask: vi.fn(),
 
+	// Help Topics
+	getHelpTopic: vi.fn(),
+	getHelpTopics: vi.fn(),
+
+	// File Checkouts
+	checkoutFile: vi.fn(),
+	checkinFile: vi.fn(),
+	getFileCheckouts: vi.fn(),
+	abandonCheckout: vi.fn(),
+
 	// Proxy (generic)
 	proxy: vi.fn(),
 };

package/src/handlers/bodies-of-work.ts

@@ -19,14 +19,96 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
-import { validateRequired, validateUUID } from '../validators.js';
+import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
-type BodyOfWorkStatus = 'draft' | 'active' | 'completed' | 'cancelled';
-type TaskPhase = 'pre' | 'core' | 'post';
-type DeployEnvironment = 'development' | 'staging' | 'production';
-type VersionBump = 'patch' | 'minor' | 'major';
-type DeployTrigger = 'all_completed' | 'all_completed_validated';
+const BODY_OF_WORK_STATUSES = ['draft', 'active', 'completed', 'cancelled'] as const;
+const TASK_PHASES = ['pre', 'core', 'post'] as const;
+const DEPLOY_ENVIRONMENTS = ['development', 'staging', 'production'] as const;
+const VERSION_BUMPS = ['patch', 'minor', 'major'] as const;
+const DEPLOY_TRIGGERS = ['all_completed', 'all_completed_validated'] as const;
+
+type BodyOfWorkStatus = typeof BODY_OF_WORK_STATUSES[number];
+type TaskPhase = typeof TASK_PHASES[number];
+type DeployEnvironment = typeof DEPLOY_ENVIRONMENTS[number];
+type VersionBump = typeof VERSION_BUMPS[number];
+type DeployTrigger = typeof DEPLOY_TRIGGERS[number];
+
+// ============================================================================
+// Argument Schemas
+// ============================================================================
+
+const createBodyOfWorkSchema = {
+	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 },
+	auto_deploy_on_completion: { type: 'boolean' as const },
+	deploy_environment: { type: 'string' as const, validate: createEnumValidator(DEPLOY_ENVIRONMENTS) },
+	deploy_version_bump: { type: 'string' as const, validate: createEnumValidator(VERSION_BUMPS) },
+	deploy_trigger: { type: 'string' as const, validate: createEnumValidator(DEPLOY_TRIGGERS) },
+};
+
+const updateBodyOfWorkSchema = {
+	body_of_work_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const },
+	description: { type: 'string' as const },
+	auto_deploy_on_completion: { type: 'boolean' as const },
+	deploy_environment: { type: 'string' as const, validate: createEnumValidator(DEPLOY_ENVIRONMENTS) },
+	deploy_version_bump: { type: 'string' as const, validate: createEnumValidator(VERSION_BUMPS) },
+	deploy_trigger: { type: 'string' as const, validate: createEnumValidator(DEPLOY_TRIGGERS) },
+};
+
+const getBodyOfWorkSchema = {
+	body_of_work_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	summary_only: { type: 'boolean' as const, default: false },
+};
+
+const getBodiesOfWorkSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	status: { type: 'string' as const, validate: createEnumValidator(BODY_OF_WORK_STATUSES) },
+	limit: { type: 'number' as const, default: 50 },
+	offset: { type: 'number' as const, default: 0 },
+	search_query: { type: 'string' as const },
+};
+
+const deleteBodyOfWorkSchema = {
+	body_of_work_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const addTaskToBodyOfWorkSchema = {
+	body_of_work_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	phase: { type: 'string' as const, validate: createEnumValidator(TASK_PHASES) },
+	order_index: { type: 'number' as const },
+};
+
+const removeTaskFromBodyOfWorkSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const activateBodyOfWorkSchema = {
+	body_of_work_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const addTaskDependencySchema = {
+	body_of_work_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	depends_on_task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const removeTaskDependencySchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	depends_on_task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const getTaskDependenciesSchema = {
+	body_of_work_id: { type: 'string' as const, validate: uuidValidator },
+	task_id: { type: 'string' as const, validate: uuidValidator },
+};
+
+const getNextBodyOfWorkTaskSchema = {
+	body_of_work_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
 
 export const createBodyOfWork: Handler = async (args, ctx) => {
 	const {
@@ -37,19 +119,7 @@ export const createBodyOfWork: Handler = async (args, ctx) => {
 		deploy_environment,
 		deploy_version_bump,
 		deploy_trigger,
-	} = args as {
-		project_id: string;
-		title: string;
-		description?: string;
-		auto_deploy_on_completion?: boolean;
-		deploy_environment?: DeployEnvironment;
-		deploy_version_bump?: VersionBump;
-		deploy_trigger?: DeployTrigger;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
-	validateRequired(title, 'title');
+	} = parseArgs(args, createBodyOfWorkSchema);
 
 	const { session } = ctx;
 	const apiClient = getApiClient();
@@ -95,18 +165,7 @@ export const updateBodyOfWork: Handler = async (args, ctx) => {
 		deploy_environment,
 		deploy_version_bump,
 		deploy_trigger,
-	} = args as {
-		body_of_work_id: string;
-		title?: string;
-		description?: string;
-		auto_deploy_on_completion?: boolean;
-		deploy_environment?: DeployEnvironment;
-		deploy_version_bump?: VersionBump;
-		deploy_trigger?: DeployTrigger;
-	};
-
-	validateRequired(body_of_work_id, 'body_of_work_id');
-	validateUUID(body_of_work_id, 'body_of_work_id');
+	} = parseArgs(args, updateBodyOfWorkSchema);
 
 	// Check if any updates provided
 	if (title === undefined && description === undefined && auto_deploy_on_completion === undefined &&
@@ -134,24 +193,37 @@ export const updateBodyOfWork: Handler = async (args, ctx) => {
 };
 
 export const getBodyOfWork: Handler = async (args, ctx) => {
-	const { body_of_work_id } = args as { body_of_work_id: string };
-
-	validateRequired(body_of_work_id, 'body_of_work_id');
-	validateUUID(body_of_work_id, 'body_of_work_id');
+	const { body_of_work_id, summary_only } = parseArgs(args, getBodyOfWorkSchema);
 
 	const apiClient = getApiClient();
 
+	// Response type varies based on summary_only
 	const response = await apiClient.proxy<{
-		id: string;
-		title: string;
-		description?: string;
-		status: string;
-		progress_percentage: number;
-		pre_tasks: unknown[];
-		core_tasks: unknown[];
-		post_tasks: unknown[];
-		total_tasks: number;
-	}>('get_body_of_work', { body_of_work_id });
+		body_of_work: {
+			id: string;
+			title: string;
+			description?: string;
+			status: string;
+			progress_percentage: number;
+		};
+		// Full response includes tasks grouped by phase
+		tasks?: {
+			pre: unknown[];
+			core: unknown[];
+			post: unknown[];
+		};
+		// Summary response includes counts and next task
+		task_counts?: {
+			pre: { total: number; completed: number };
+			core: { total: number; completed: number };
+			post: { total: number; completed: number };
+			total: number;
+			completed: number;
+			in_progress: number;
+		};
+		current_task?: { id: string; title: string } | null;
+		next_task?: { id: string; title: string; priority: number } | null;
+	}>('get_body_of_work', { body_of_work_id, summary_only });
 
 	if (!response.ok) {
 		throw new Error(`Failed to get body of work: ${response.error}`);
@@ -161,16 +233,7 @@ export const getBodyOfWork: Handler = async (args, ctx) => {
 };
 
 export const getBodiesOfWork: Handler = async (args, ctx) => {
-	const { project_id, status, limit = 50, offset = 0, search_query } = args as {
-		project_id: string;
-		status?: BodyOfWorkStatus;
-		limit?: number;
-		offset?: number;
-		search_query?: string;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+	const { project_id, status, limit, offset, search_query } = parseArgs(args, getBodiesOfWorkSchema);
 
 	const apiClient = getApiClient();
 
@@ -192,7 +255,7 @@ export const getBodiesOfWork: Handler = async (args, ctx) => {
 	}>('get_bodies_of_work', {
 		project_id,
 		status,
-		limit: Math.min(limit, 100),
+		limit: Math.min(limit ?? 50, 100),
 		offset,
 		search_query
 	});
@@ -205,10 +268,7 @@ export const getBodiesOfWork: Handler = async (args, ctx) => {
 };
 
 export const deleteBodyOfWork: Handler = async (args, ctx) => {
-	const { body_of_work_id } = args as { body_of_work_id: string };
-
-	validateRequired(body_of_work_id, 'body_of_work_id');
-	validateUUID(body_of_work_id, 'body_of_work_id');
+	const { body_of_work_id } = parseArgs(args, deleteBodyOfWorkSchema);
 
 	const apiClient = getApiClient();
 
@@ -224,17 +284,7 @@ export const deleteBodyOfWork: Handler = async (args, ctx) => {
 };
 
 export const addTaskToBodyOfWork: Handler = async (args, ctx) => {
-	const { body_of_work_id, task_id, phase, order_index } = args as {
-		body_of_work_id: string;
-		task_id: string;
-		phase?: TaskPhase;
-		order_index?: number;
-	};
-
-	validateRequired(body_of_work_id, 'body_of_work_id');
-	validateUUID(body_of_work_id, 'body_of_work_id');
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
+	const { body_of_work_id, task_id, phase, order_index } = parseArgs(args, addTaskToBodyOfWorkSchema);
 
 	const apiClient = getApiClient();
 
@@ -259,10 +309,7 @@ export const addTaskToBodyOfWork: Handler = async (args, ctx) => {
 };
 
 export const removeTaskFromBodyOfWork: Handler = async (args, ctx) => {
-	const { task_id } = args as { task_id: string };
-
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
+	const { task_id } = parseArgs(args, removeTaskFromBodyOfWorkSchema);
 
 	const apiClient = getApiClient();
 
@@ -280,10 +327,7 @@ export const removeTaskFromBodyOfWork: Handler = async (args, ctx) => {
 };
 
 export const activateBodyOfWork: Handler = async (args, ctx) => {
-	const { body_of_work_id } = args as { body_of_work_id: string };
-
-	validateRequired(body_of_work_id, 'body_of_work_id');
-	validateUUID(body_of_work_id, 'body_of_work_id');
+	const { body_of_work_id } = parseArgs(args, activateBodyOfWorkSchema);
 
 	const apiClient = getApiClient();
 
@@ -303,18 +347,7 @@ export const activateBodyOfWork: Handler = async (args, ctx) => {
 };
 
 export const addTaskDependency: Handler = async (args, ctx) => {
-	const { body_of_work_id, task_id, depends_on_task_id } = args as {
-		body_of_work_id: string;
-		task_id: string;
-		depends_on_task_id: string;
-	};
-
-	validateRequired(body_of_work_id, 'body_of_work_id');
-	validateUUID(body_of_work_id, 'body_of_work_id');
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
-	validateRequired(depends_on_task_id, 'depends_on_task_id');
-	validateUUID(depends_on_task_id, 'depends_on_task_id');
+	const { body_of_work_id, task_id, depends_on_task_id } = parseArgs(args, addTaskDependencySchema);
 
 	if (task_id === depends_on_task_id) {
 		throw new Error('A task cannot depend on itself');
@@ -342,15 +375,7 @@ export const addTaskDependency: Handler = async (args, ctx) => {
 };
 
 export const removeTaskDependency: Handler = async (args, ctx) => {
-	const { task_id, depends_on_task_id } = args as {
-		task_id: string;
-		depends_on_task_id: string;
-	};
-
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
-	validateRequired(depends_on_task_id, 'depends_on_task_id');
-	validateUUID(depends_on_task_id, 'depends_on_task_id');
+	const { task_id, depends_on_task_id } = parseArgs(args, removeTaskDependencySchema);
 
 	const apiClient = getApiClient();
 
@@ -371,18 +396,12 @@ export const removeTaskDependency: Handler = async (args, ctx) => {
 };
 
 export const getTaskDependencies: Handler = async (args, ctx) => {
-	const { body_of_work_id, task_id } = args as {
-		body_of_work_id?: string;
-		task_id?: string;
-	};
+	const { body_of_work_id, task_id } = parseArgs(args, getTaskDependenciesSchema);
 
 	if (!body_of_work_id && !task_id) {
 		throw new Error('Either body_of_work_id or task_id is required');
 	}
 
-	if (body_of_work_id) validateUUID(body_of_work_id, 'body_of_work_id');
-	if (task_id) validateUUID(task_id, 'task_id');
-
 	const apiClient = getApiClient();
 
 	const response = await apiClient.proxy<{
@@ -405,10 +424,7 @@ export const getTaskDependencies: Handler = async (args, ctx) => {
 };
 
 export const getNextBodyOfWorkTask: Handler = async (args, ctx) => {
-	const { body_of_work_id } = args as { body_of_work_id: string };
-
-	validateRequired(body_of_work_id, 'body_of_work_id');
-	validateUUID(body_of_work_id, 'body_of_work_id');
+	const { body_of_work_id } = parseArgs(args, getNextBodyOfWorkTaskSchema);
 
 	const apiClient = getApiClient();