@vibescope/mcp-server 0.3.0 → 0.3.3

package/src/api-client/tasks.ts

@@ -0,0 +1,450 @@
+/**
+ * Tasks API Methods
+ *
+ * Methods for task management:
+ * - getTasks: List tasks for a project
+ * - createTask: Create a new task
+ * - getNextTask: Get highest priority pending task
+ * - getTask: Get a single task
+ * - getTaskById: Get task with optional subtasks/milestones
+ * - searchTasks: Search tasks by text query
+ * - getTasksByPriority: Get tasks filtered by priority
+ * - getRecentTasks: Get recently created/modified tasks
+ * - getTaskStats: Get task statistics
+ * - updateTask: Update task details
+ * - completeTask: Mark task as completed
+ * - deleteTask: Delete a task
+ * - releaseTask: Release task back to pending
+ * - cancelTask: Cancel a task
+ * - addTaskReference: Add reference URL to task
+ * - removeTaskReference: Remove reference from task
+ * - batchUpdateTasks: Update multiple tasks
+ * - batchCompleteTasks: Complete multiple tasks
+ */
+
+import type { ApiResponse, RequestFn, ProxyFn } from './types.js';
+
+export interface TasksMethods {
+	getTasks(projectId: string, params?: {
+		status?: string;
+		limit?: number;
+		offset?: number;
+		include_subtasks?: boolean;
+		search_query?: string;
+		include_metadata?: boolean;
+	}): Promise<ApiResponse<{
+		tasks: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			status: string;
+			progress_percentage?: number;
+			estimated_minutes?: number;
+			started_at?: string;
+			completed_at?: string;
+			parent_task_id?: string;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>>;
+
+	createTask(projectId: string, params: {
+		title: string;
+		description?: string;
+		priority?: number;
+		estimated_minutes?: number;
+		blocking?: boolean;
+		session_id?: string;
+		task_type?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+		title: string;
+		blocking?: boolean;
+		message?: string;
+	}>>;
+
+	getNextTask(projectId: string, sessionId?: string): Promise<ApiResponse<{
+		task?: {
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			estimated_minutes?: number;
+			blocking?: boolean;
+		} | null;
+		blocking_task?: boolean;
+		deployment_blocks_tasks?: boolean;
+		deployment?: {
+			id: string;
+			status: string;
+			env: string;
+		};
+		awaiting_validation?: Array<{
+			id: string;
+			title: string;
+		}>;
+		validation_priority?: string;
+		all_claimed?: boolean;
+		is_subtask?: boolean;
+		suggested_activity?: string;
+		directive?: string;
+		message?: string;
+		action?: string;
+	}>>;
+
+	getTask(taskId: string): 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;
+			blocking?: boolean;
+			references?: Array<{ url: string; label?: string }>;
+			parent_task_id?: string;
+			working_agent_session_id?: string;
+		};
+	}>>;
+
+	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;
+		}>;
+	}>>;
+
+	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;
+	}>>;
+
+	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;
+	}>>;
+
+	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;
+	}>>;
+
+	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;
+	}>>;
+
+	updateTask(taskId: string, updates: {
+		title?: string;
+		description?: string;
+		priority?: number;
+		status?: string;
+		progress_percentage?: number;
+		progress_note?: string;
+		estimated_minutes?: number;
+		git_branch?: string;
+		worktree_path?: string;
+		session_id?: string;
+	}): 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;
+	}>>;
+
+	completeTask(taskId: string, params: {
+		summary?: string;
+		session_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		directive: string;
+		auto_continue: boolean;
+		completed_task_id: string;
+		next_task?: {
+			id: string;
+			title: string;
+			priority: number;
+			estimated_minutes?: number;
+		} | null;
+		context?: {
+			validation?: number;
+			blockers?: number;
+			deployment?: string;
+			worktree_path?: string;
+		};
+		next_action: string;
+		warnings?: string[];
+	}>>;
+
+	deleteTask(taskId: string): Promise<ApiResponse<{
+		success: boolean;
+		deleted_id: string;
+	}>>;
+
+	releaseTask(taskId: string, params?: {
+		reason?: string;
+		session_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+		message: string;
+		reason?: string;
+		hint: string;
+	}>>;
+
+	cancelTask(taskId: string, params?: {
+		cancelled_reason?: 'pr_closed' | 'superseded' | 'user_cancelled' | 'validation_failed' | 'obsolete' | 'blocked';
+		cancellation_note?: string;
+		session_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+		cancelled_reason: string | null;
+		message: string;
+	}>>;
+
+	addTaskReference(taskId: string, url: string, label?: string): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+		reference: { url: string; label?: string };
+	}>>;
+
+	removeTaskReference(taskId: string, url: string): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+	}>>;
+
+	batchUpdateTasks(updates: Array<{
+		task_id: string;
+		priority?: number;
+		status?: string;
+		progress_percentage?: number;
+	}>): Promise<ApiResponse<{
+		success: boolean;
+		updated_count: number;
+		results: Array<{ task_id: string; success: boolean; error?: string }>;
+	}>>;
+
+	batchCompleteTasks(completions: Array<{
+		task_id: string;
+		summary?: string;
+	}>): Promise<ApiResponse<{
+		success: boolean;
+		completed_count: number;
+		results: Array<{ task_id: string; success: boolean; error?: string }>;
+	}>>;
+}
+
+export function createTasksMethods(request: RequestFn, proxy: ProxyFn): TasksMethods {
+	return {
+		async getTasks(projectId, params) {
+			const queryParams = new URLSearchParams();
+			if (params?.status) queryParams.set('status', params.status);
+			if (params?.limit) queryParams.set('limit', params.limit.toString());
+			if (params?.offset) queryParams.set('offset', params.offset.toString());
+			if (params?.include_subtasks) queryParams.set('include_subtasks', 'true');
+			if (params?.search_query) queryParams.set('search_query', params.search_query);
+			if (params?.include_metadata) queryParams.set('include_metadata', 'true');
+			const query = queryParams.toString();
+			const url = `/api/mcp/projects/${projectId}/tasks${query ? `?${query}` : ''}`;
+			return request('GET', url);
+		},
+
+		async createTask(projectId, params) {
+			return request('POST', `/api/mcp/projects/${projectId}/tasks`, params);
+		},
+
+		async getNextTask(projectId, sessionId) {
+			const url = sessionId
+				? `/api/mcp/projects/${projectId}/next-task?session_id=${sessionId}`
+				: `/api/mcp/projects/${projectId}/next-task`;
+			return request('GET', url);
+		},
+
+		async getTask(taskId) {
+			return request('GET', `/api/mcp/tasks/${taskId}`);
+		},
+
+		async getTaskById(taskId, params) {
+			return proxy('get_task', {
+				task_id: taskId,
+				include_subtasks: params?.include_subtasks,
+				include_milestones: params?.include_milestones,
+			});
+		},
+
+		async searchTasks(projectId, params) {
+			return proxy('search_tasks', {
+				project_id: projectId,
+				query: params.query,
+				status: params.status,
+				limit: params.limit,
+				offset: params.offset,
+			});
+		},
+
+		async getTasksByPriority(projectId, params) {
+			return 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,
+			});
+		},
+
+		async getRecentTasks(projectId, params) {
+			return proxy('get_recent_tasks', {
+				project_id: projectId,
+				order: params?.order,
+				status: params?.status,
+				limit: params?.limit,
+				offset: params?.offset,
+			});
+		},
+
+		async getTaskStats(projectId) {
+			return proxy('get_task_stats', { project_id: projectId });
+		},
+
+		async updateTask(taskId, updates) {
+			return request('PATCH', `/api/mcp/tasks/${taskId}`, updates);
+		},
+
+		async completeTask(taskId, params) {
+			return proxy('complete_task', {
+				task_id: taskId,
+				summary: params.summary,
+			}, params.session_id ? { session_id: params.session_id } : undefined);
+		},
+
+		async deleteTask(taskId) {
+			return request('DELETE', `/api/mcp/tasks/${taskId}`);
+		},
+
+		async releaseTask(taskId, params) {
+			return proxy('release_task', {
+				task_id: taskId,
+				reason: params?.reason,
+			}, params?.session_id ? { session_id: params.session_id } : undefined);
+		},
+
+		async cancelTask(taskId, params) {
+			return proxy('cancel_task', {
+				task_id: taskId,
+				cancelled_reason: params?.cancelled_reason,
+				cancellation_note: params?.cancellation_note,
+			}, params?.session_id ? { session_id: params.session_id } : undefined);
+		},
+
+		async addTaskReference(taskId, url, label) {
+			return proxy('add_task_reference', { task_id: taskId, url, label });
+		},
+
+		async removeTaskReference(taskId, url) {
+			return proxy('remove_task_reference', { task_id: taskId, url });
+		},
+
+		async batchUpdateTasks(updates) {
+			return proxy('batch_update_tasks', { updates });
+		},
+
+		async batchCompleteTasks(completions) {
+			return proxy('batch_complete_tasks', { completions });
+		}
+	};
+}

package/src/api-client/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared Types for Vibescope API Client
+ */
+
+export interface RetryConfig {
+	maxRetries?: number;
+	baseDelayMs?: number;
+	maxDelayMs?: number;
+	retryStatusCodes?: number[];
+}
+
+export interface ApiClientConfig {
+	apiKey: string;
+	baseUrl?: string;
+	retry?: RetryConfig;
+}
+
+export interface ApiResponse<T> {
+	ok: boolean;
+	status: number;
+	data?: T;
+	error?: string;
+}
+
+// Request function type that domain modules depend on
+export type RequestFn = <T>(method: string, path: string, body?: unknown) => Promise<ApiResponse<T>>;
+
+// Proxy function type for generic operations
+export type ProxyFn = <T>(operation: string, args: Record<string, unknown>, sessionContext?: {
+	session_id?: string;
+	project_id?: string;
+}) => Promise<ApiResponse<T>>;

package/src/api-client/worktrees.ts

@@ -0,0 +1,53 @@
+/**
+ * Worktrees API Methods
+ *
+ * Methods for git worktree management:
+ * - getStaleWorktrees: List stale worktrees for cleanup
+ * - clearWorktreePath: Clear worktree path from a task
+ */
+
+import type { ApiResponse, RequestFn } from './types.js';
+
+export interface WorktreesMethods {
+	getStaleWorktrees(projectId: string, params?: {
+		hostname?: string;
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		stale_worktrees: Array<{
+			task_id: string;
+			task_title: string;
+			worktree_path: string;
+			worktree_hostname?: string | null;
+			last_heartbeat?: string;
+			session_status?: string;
+		}>;
+		total_count: number;
+		has_more: boolean;
+		cleanup_instructions: string;
+	}>>;
+
+	clearWorktreePath(taskId: string): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+		message: string;
+	}>>;
+}
+
+export function createWorktreesMethods(request: RequestFn): WorktreesMethods {
+	return {
+		async getStaleWorktrees(projectId, params) {
+			const queryParams = new URLSearchParams();
+			if (params?.hostname) queryParams.set('hostname', params.hostname);
+			if (params?.limit) queryParams.set('limit', params.limit.toString());
+			if (params?.offset) queryParams.set('offset', params.offset.toString());
+			const query = queryParams.toString();
+			const url = `/api/mcp/projects/${projectId}/worktrees/stale${query ? `?${query}` : ''}`;
+			return request('GET', url);
+		},
+
+		async clearWorktreePath(taskId) {
+			return request('POST', `/api/mcp/tasks/${taskId}/clear-worktree`);
+		}
+	};
+}