@vibescope/mcp-server 0.2.2 → 0.2.4

package/src/api-client.ts

@@ -85,6 +85,8 @@ export class VibescopeApiClient {
 		mode?: 'lite' | 'full';
 		model?: 'opus' | 'sonnet' | 'haiku';
 		role?: 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer';
+		hostname?: string; // Machine hostname for worktree tracking
+		agent_type?: 'claude' | 'gemini' | 'cursor' | 'windsurf' | 'other'; // Agent type for onboarding
 	}): Promise<ApiResponse<{
 		session_started: boolean;
 		session_id?: string;
@@ -150,6 +152,32 @@ export class VibescopeApiClient {
 			example: string;
 			note: string;
 		};
+		// Agent onboarding - returned when a new agent type connects to an existing project
+		agent_setup?: {
+			agent_type: string;
+			is_new_agent_type: boolean;
+			setup_required: boolean;
+			instructions: string;
+			config_file: string; // e.g., '.gemini/GEMINI.md'
+			template_url?: string;
+			steps: string[];
+		};
+		// Stale worktrees that need cleanup
+		stale_worktrees?: Array<{
+			task_id: string;
+			task_title: string;
+			worktree_path: string;
+			worktree_hostname?: string | null;
+		}>;
+		stale_worktrees_count?: number;
+		cleanup_action?: string;
+		// Validation info for validators
+		awaiting_validation?: Array<{
+			id: string;
+			title?: string;
+		}>;
+		validation_priority?: boolean;
+		next_action?: string;
 		error?: string;
 	}>> {
 		return this.request('POST', '/api/mcp/sessions/start', params);
@@ -157,6 +185,7 @@ export class VibescopeApiClient {
 
 	async heartbeat(sessionId: string, options?: {
 		current_worktree_path?: string | null;
+		hostname?: string; // Machine hostname for worktree tracking
 	}): Promise<ApiResponse<{
 		success: boolean;
 		session_id: string;
@@ -273,6 +302,15 @@ export class VibescopeApiClient {
 		git_auto_tag?: boolean;
 		deployment_instructions?: string;
 		agent_instructions?: string;
+		// New project settings columns
+		git_delete_branch_on_merge?: boolean;
+		require_pr_for_validation?: boolean;
+		auto_merge_on_approval?: boolean;
+		validation_required?: boolean;
+		default_task_priority?: number;
+		require_time_estimates?: boolean;
+		fallback_activities_enabled?: boolean;
+		preferred_fallback_activities?: string[];
 	}): Promise<ApiResponse<{
 		success: boolean;
 		project_id: string;
@@ -390,6 +428,158 @@ export class VibescopeApiClient {
 		return this.request('GET', `/api/mcp/tasks/${taskId}`);
 	}
 
+	/**
+	 * Get a single task by ID with optional subtasks and milestones
+	 */
+	async getTaskById(taskId: string, params?: {
+		include_subtasks?: boolean;
+		include_milestones?: boolean;
+	}): Promise<ApiResponse<{
+		task: {
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			status: string;
+			progress_percentage?: number;
+			estimated_minutes?: number;
+			started_at?: string;
+			completed_at?: string;
+			git_branch?: string;
+			references?: Array<{ url: string; label?: string }>;
+		};
+		subtasks?: Array<{
+			id: string;
+			title: string;
+			status: string;
+			progress_percentage?: number;
+		}>;
+		milestones?: Array<{
+			id: string;
+			title: string;
+			status: string;
+			order_index: number;
+		}>;
+	}>> {
+		return this.proxy('get_task', {
+			task_id: taskId,
+			include_subtasks: params?.include_subtasks,
+			include_milestones: params?.include_milestones,
+		});
+	}
+
+	/**
+	 * Search tasks by text query with pagination
+	 */
+	async searchTasks(projectId: string, params: {
+		query: string;
+		status?: string[];
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		tasks: Array<{
+			id: string;
+			title: string;
+			status: string;
+			priority: number;
+			snippet?: string;
+		}>;
+		total_matches: number;
+		hint?: string;
+	}>> {
+		return this.proxy('search_tasks', {
+			project_id: projectId,
+			query: params.query,
+			status: params.status,
+			limit: params.limit,
+			offset: params.offset,
+		});
+	}
+
+	/**
+	 * Get tasks filtered by priority with pagination
+	 */
+	async getTasksByPriority(projectId: string, params?: {
+		priority?: number;
+		priority_max?: number;
+		status?: string;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		tasks: Array<{
+			id: string;
+			title: string;
+			priority: number;
+			status: string;
+			estimated_minutes?: number;
+		}>;
+		total_count: number;
+	}>> {
+		return this.proxy('get_tasks_by_priority', {
+			project_id: projectId,
+			priority: params?.priority,
+			priority_max: params?.priority_max,
+			status: params?.status,
+			limit: params?.limit,
+			offset: params?.offset,
+		});
+	}
+
+	/**
+	 * Get recent tasks (newest or oldest) with pagination
+	 */
+	async getRecentTasks(projectId: string, params?: {
+		order?: 'newest' | 'oldest';
+		status?: string;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		tasks: Array<{
+			id: string;
+			title: string;
+			status: string;
+			priority: number;
+			created_at: string;
+			age?: string;
+		}>;
+		total_count: number;
+	}>> {
+		return this.proxy('get_recent_tasks', {
+			project_id: projectId,
+			order: params?.order,
+			status: params?.status,
+			limit: params?.limit,
+			offset: params?.offset,
+		});
+	}
+
+	/**
+	 * Get task statistics for a project
+	 */
+	async getTaskStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+		by_status: {
+			backlog: number;
+			pending: number;
+			in_progress: number;
+			completed: number;
+			cancelled: number;
+		};
+		by_priority: {
+			1: number;
+			2: number;
+			3: number;
+			4: number;
+			5: number;
+		};
+		awaiting_validation: number;
+		oldest_pending_days: number | null;
+	}>> {
+		return this.proxy('get_task_stats', {
+			project_id: projectId,
+		});
+	}
+
 	async updateTask(taskId: string, updates: {
 		title?: string;
 		description?: string;
@@ -444,7 +634,11 @@ export class VibescopeApiClient {
 		next_action: string;
 		warnings?: string[];
 	}>> {
-		return this.request('POST', `/api/mcp/tasks/${taskId}/complete`, params);
+		// Use proxy endpoint for consistency - direct endpoint had routing issues on Vercel
+		return this.proxy('complete_task', {
+			task_id: taskId,
+			summary: params.summary,
+		}, params.session_id ? { session_id: params.session_id, persona: null, instance_id: '' } : undefined);
 	}
 
 	async deleteTask(taskId: string): Promise<ApiResponse<{
@@ -556,6 +750,15 @@ export class VibescopeApiClient {
 		return this.proxy('delete_blocker', { blocker_id: blockerId });
 	}
 
+	async getBlockersStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+		by_status: Record<string, number>;
+	}>> {
+		return this.proxy('get_blockers_stats', {
+			project_id: projectId
+		});
+	}
+
 	// ============================================================================
 	// Decision endpoints
 	// ============================================================================
@@ -597,6 +800,14 @@ export class VibescopeApiClient {
 		return this.proxy('delete_decision', { decision_id: decisionId });
 	}
 
+	async getDecisionsStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+	}>> {
+		return this.proxy('get_decisions_stats', {
+			project_id: projectId
+		});
+	}
+
 	// ============================================================================
 	// Idea endpoints
 	// ============================================================================
@@ -835,15 +1046,21 @@ export class VibescopeApiClient {
 	// ============================================================================
 	// Request endpoints
 	// ============================================================================
-	async getPendingRequests(projectId: string, sessionId?: string): Promise<ApiResponse<{
+	async getPendingRequests(projectId: string, sessionId?: string, limit?: number, offset?: number): Promise<ApiResponse<{
 		requests: Array<{
 			id: string;
 			request_type: string;
 			message: string;
 			created_at: string;
 		}>;
+		total_count: number;
+		has_more: boolean;
 	}>> {
-		return this.proxy('get_pending_requests', { project_id: projectId }, sessionId ? {
+		return this.proxy('get_pending_requests', {
+			project_id: projectId,
+			...(limit !== undefined && { limit }),
+			...(offset !== undefined && { offset }),
+		}, sessionId ? {
 			session_id: sessionId,
 			persona: null,
 			instance_id: ''
@@ -968,7 +1185,10 @@ export class VibescopeApiClient {
 		});
 	}
 
-	async getActivitySchedules(projectId: string): Promise<ApiResponse<{
+	async getActivitySchedules(projectId: string, params?: {
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
 		schedules: Array<{
 			id: string;
 			activity_type: string;
@@ -976,10 +1196,13 @@ export class VibescopeApiClient {
 			next_run_at?: string;
 			enabled: boolean;
 		}>;
-		due_activities: string[];
-		count: number;
+		total_count: number;
+		has_more: boolean;
 	}>> {
-		return this.proxy('get_activity_schedules', { project_id: projectId });
+		return this.proxy('get_activity_schedules', {
+			project_id: projectId,
+			...params
+		});
 	}
 
 	// ============================================================================
@@ -1199,6 +1422,33 @@ export class VibescopeApiClient {
 		});
 	}
 
+	/**
+	 * Report actual API token usage for accurate cost tracking.
+	 * This records token usage to the session and attributes cost to the current task.
+	 */
+	async reportTokenUsage(sessionId: string, params: {
+		input_tokens: number;
+		output_tokens: number;
+		model?: 'opus' | 'sonnet' | 'haiku';
+	}): Promise<ApiResponse<{
+		success: boolean;
+		reported: {
+			session_id: string;
+			model: string;
+			input_tokens: number;
+			output_tokens: number;
+			total_tokens: number;
+			estimated_cost_usd: number;
+		};
+		task_attributed: boolean;
+		task_id?: string;
+	}>> {
+		return this.proxy('report_token_usage', {
+			session_id: sessionId,
+			...params
+		});
+	}
+
 	// ============================================================================
 	// Organization endpoints
 	// ============================================================================
@@ -1522,6 +1772,7 @@ export class VibescopeApiClient {
 		issue_type?: string;
 		branch?: string;
 		limit?: number;
+		offset?: number;
 	}): Promise<ApiResponse<{
 		git_issues: Array<{
 			id: string;
@@ -1742,6 +1993,8 @@ export class VibescopeApiClient {
 	async getDeploymentRequirements(projectId: string, params?: {
 		status?: string;
 		stage?: string;
+		limit?: number;
+		offset?: number;
 	}): Promise<ApiResponse<{
 		requirements: Array<{
 			id: string;
@@ -1751,6 +2004,8 @@ export class VibescopeApiClient {
 			status: string;
 			stage: string;
 		}>;
+		total_count: number;
+		has_more: boolean;
 	}>> {
 		return this.proxy('get_deployment_requirements', {
 			project_id: projectId,
@@ -1758,6 +2013,17 @@ export class VibescopeApiClient {
 		});
 	}
 
+	async getDeploymentRequirementsStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+		by_status: Record<string, number>;
+		by_stage: Record<string, number>;
+		by_type: Record<string, number>;
+	}>> {
+		return this.proxy('get_deployment_requirements_stats', {
+			project_id: projectId
+		});
+	}
+
 	async completeDeploymentRequirement(requirementId: string): Promise<ApiResponse<{
 		success: boolean;
 	}>> {
@@ -1783,7 +2049,11 @@ export class VibescopeApiClient {
 		});
 	}
 
-	async getScheduledDeployments(projectId: string, includeDisabled?: boolean): Promise<ApiResponse<{
+	async getScheduledDeployments(projectId: string, params?: {
+		includeDisabled?: boolean;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
 		schedules: Array<{
 			id: string;
 			scheduled_at: string;
@@ -1796,12 +2066,14 @@ export class VibescopeApiClient {
 			git_ref?: string;
 			notes?: string;
 		}>;
-		count: number;
-		due_count: number;
+		total_count: number;
+		has_more: boolean;
 	}>> {
 		return this.proxy('get_scheduled_deployments', {
 			project_id: projectId,
-			include_disabled: includeDisabled
+			include_disabled: params?.includeDisabled,
+			limit: params?.limit,
+			offset: params?.offset
 		});
 	}
 
@@ -1872,6 +2144,54 @@ export class VibescopeApiClient {
 		});
 	}
 
+	async getProjectSummary(projectId: string): Promise<ApiResponse<{
+		project: {
+			id: string;
+			name: string;
+			description?: string;
+			goal?: string;
+			status: string;
+			git_url?: string;
+			tech_stack?: string[];
+			git_workflow?: string;
+		};
+		tasks: {
+			total: number;
+			by_status: Record<string, number>;
+		};
+		blockers: {
+			total: number;
+			open: number;
+			resolved: number;
+		};
+		findings: {
+			total: number;
+			by_severity: Record<string, number>;
+			by_status: Record<string, number>;
+		};
+		agents: {
+			active_count: number;
+			total_tokens_this_session: number;
+			total_tool_calls: number;
+		};
+		activity: {
+			tasks_completed_today: number;
+			progress_entries_today: number;
+		};
+		deployment: {
+			active: boolean;
+			status: string | null;
+			last_deployment_at: string | null;
+		};
+		planning: {
+			active_sprints: number;
+			active_bodies_of_work: number;
+			pending_deployment_requirements: number;
+		};
+	}>> {
+		return this.proxy('get_project_summary', { project_id: projectId });
+	}
+
 	// ============================================================================
 	// Help Topics (database-backed)
 	// ============================================================================
@@ -1932,6 +2252,7 @@ export class VibescopeApiClient {
 		status?: string;
 		file_path?: string;
 		limit?: number;
+		offset?: number;
 	}): Promise<ApiResponse<{
 		checkouts: Array<{
 			id: string;
@@ -1962,28 +2283,51 @@ export class VibescopeApiClient {
 		return this.proxy('abandon_checkout', params);
 	}
 
+	async getFileCheckoutsStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+		by_status: Record<string, number>;
+	}>> {
+		return this.proxy('get_file_checkouts_stats', { project_id: projectId });
+	}
+
 	// ============================================================================
 	// Worktree Management
 	// ============================================================================
 
-	async getStaleWorktrees(projectId: string): Promise<ApiResponse<{
+	async getStaleWorktrees(projectId: string, params?: {
+		hostname?: string;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
 		project_id: string;
 		project_name: string;
+		hostname_filter: string | null;
 		stale_worktrees: Array<{
 			task_id: string;
 			task_title: string;
 			worktree_path: string;
+			worktree_hostname: string | null;
 			git_branch: string | null;
 			status: string;
 			completed_at: string | null;
 			updated_at: string;
 			pr_url: string | null;
 			stale_reason: 'task_finished' | 'potentially_abandoned';
+			can_cleanup_locally: boolean;
 		}>;
 		count: number;
+		local_count: number;
+		remote_count: number;
+		total_count: number;
+		has_more: boolean;
 		cleanup_instructions: string[] | null;
+		remote_worktree_note: string | null;
 	}>> {
-		return this.request('GET', `/api/mcp/worktrees/stale?project_id=${projectId}`);
+		const queryParams = new URLSearchParams({ project_id: projectId });
+		if (params?.hostname !== undefined) queryParams.set('hostname', params.hostname);
+		if (params?.limit !== undefined) queryParams.set('limit', String(params.limit));
+		if (params?.offset !== undefined) queryParams.set('offset', String(params.offset));
+		return this.request('GET', `/api/mcp/worktrees/stale?${queryParams.toString()}`);
 	}
 
 	async clearWorktreePath(taskId: string): Promise<ApiResponse<{
@@ -2114,6 +2458,25 @@ export class VibescopeApiClient {
 	}>> {
 		return this.proxy('get_connector_events', params);
 	}
+
+	// ============================================================================
+	// Agent onboarding endpoints
+	// ============================================================================
+
+	/**
+	 * Confirm that agent setup is complete for a project.
+	 * This marks the agent type as onboarded so future sessions don't receive setup instructions.
+	 */
+	async confirmAgentSetup(projectId: string, agentType: 'claude' | 'gemini' | 'cursor' | 'windsurf' | 'other'): Promise<ApiResponse<{
+		success: boolean;
+		project_id: string;
+		agent_type: string;
+	}>> {
+		return this.proxy('confirm_agent_setup', {
+			project_id: projectId,
+			agent_type: agentType
+		});
+	}
 }
 
 // Singleton instance

package/src/handlers/__test-setup__.ts

@@ -26,6 +26,7 @@ export const mockApiClient = {
 	heartbeat: vi.fn(),
 	syncSession: vi.fn(),
 	endSession: vi.fn(),
+	reportTokenUsage: vi.fn(),
 
 	// Project
 	listProjects: vi.fn(),
@@ -60,11 +61,13 @@ export const mockApiClient = {
 	addBlocker: vi.fn(),
 	resolveBlocker: vi.fn(),
 	getBlockers: vi.fn(),
+	getBlockersStats: vi.fn(),
 	deleteBlocker: vi.fn(),
 
 	// Decisions
 	logDecision: vi.fn(),
 	getDecisions: vi.fn(),
+	getDecisionsStats: vi.fn(),
 	deleteDecision: vi.fn(),
 
 	// Ideas
@@ -154,6 +157,7 @@ export const mockApiClient = {
 	addDeploymentRequirement: vi.fn(),
 	completeDeploymentRequirement: vi.fn(),
 	getDeploymentRequirements: vi.fn(),
+	getDeploymentRequirementsStats: vi.fn(),
 	scheduleDeployment: vi.fn(),
 	getScheduledDeployments: vi.fn(),
 	updateScheduledDeployment: vi.fn(),
@@ -174,6 +178,7 @@ export const mockApiClient = {
 	checkoutFile: vi.fn(),
 	checkinFile: vi.fn(),
 	getFileCheckouts: vi.fn(),
+	getFileCheckoutsStats: vi.fn(),
 	abandonCheckout: vi.fn(),
 
 	// Connectors

package/src/handlers/blockers.test.ts

@@ -3,6 +3,7 @@ import {
 	addBlocker,
 	resolveBlocker,
 	getBlockers,
+	getBlockersStats,
 	deleteBlocker,
 } from './blockers.js';
 import { ValidationError } from '../validators.js';
@@ -390,3 +391,78 @@ describe('deleteBlocker', () => {
 		});
 	});
 });
+
+// ============================================================================
+// getBlockersStats Tests
+// ============================================================================
+
+describe('getBlockersStats', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(getBlockersStats({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid project_id UUID', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			getBlockersStats({ project_id: 'invalid' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should return blockers stats', async () => {
+		mockApiClient.getBlockersStats.mockResolvedValue({
+			ok: true,
+			data: {
+				total: 5,
+				by_status: { open: 3, resolved: 2 },
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await getBlockersStats(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			total: 5,
+			by_status: { open: 3, resolved: 2 },
+		});
+	});
+
+	it('should call API client getBlockersStats', async () => {
+		mockApiClient.getBlockersStats.mockResolvedValue({
+			ok: true,
+			data: { total: 0, by_status: {} },
+		});
+		const ctx = createMockContext();
+
+		await getBlockersStats(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(mockApiClient.getBlockersStats).toHaveBeenCalledWith(
+			'123e4567-e89b-12d3-a456-426614174000'
+		);
+	});
+
+	it('should return error when API call fails', async () => {
+		mockApiClient.getBlockersStats.mockResolvedValue({
+			ok: false,
+			error: 'Query failed',
+		});
+		const ctx = createMockContext();
+
+		const result = await getBlockersStats({ project_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Query failed',
+		});
+	});
+});