@vibescope/mcp-server 0.2.3 → 0.2.4

package/src/handlers/tasks.test.ts

@@ -1,6 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import {
-	getTasks,
 	getNextTask,
 	addTask,
 	updateTask,
@@ -18,78 +17,6 @@ import { ValidationError } from '../validators.js';
 import { createMockContext } from './__test-utils__.js';
 import { mockApiClient } from './__test-setup__.js';
 
-// ============================================================================
-// getTasks Tests
-// ============================================================================
-
-describe('getTasks', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should throw error for missing project_id', async () => {
-		const ctx = createMockContext();
-		await expect(getTasks({}, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for invalid project_id UUID', async () => {
-		const ctx = createMockContext();
-		await expect(getTasks({ project_id: 'invalid' }, ctx)).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for invalid status', async () => {
-		const ctx = createMockContext();
-		await expect(
-			getTasks({ project_id: '123e4567-e89b-12d3-a456-426614174000', status: 'invalid' }, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should return tasks successfully', async () => {
-		mockApiClient.getTasks.mockResolvedValue({
-			ok: true,
-			data: {
-				tasks: [
-					{ id: 'task-1', title: 'Test task', status: 'pending', priority: 1 },
-				],
-				total_count: 1,
-				has_more: false,
-			},
-		});
-
-		const ctx = createMockContext();
-		const result = await getTasks(
-			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			tasks: expect.any(Array),
-			total_count: 1,
-			has_more: false,
-		});
-		expect(mockApiClient.getTasks).toHaveBeenCalledWith(
-			'123e4567-e89b-12d3-a456-426614174000',
-			expect.any(Object)
-		);
-	});
-
-	it('should pass status filter to API', async () => {
-		mockApiClient.getTasks.mockResolvedValue({
-			ok: true,
-			data: { tasks: [], total_count: 0, has_more: false },
-		});
-
-		const ctx = createMockContext();
-		await getTasks(
-			{ project_id: '123e4567-e89b-12d3-a456-426614174000', status: 'pending' },
-			ctx
-		);
-
-		expect(mockApiClient.getTasks).toHaveBeenCalledWith(
-			'123e4567-e89b-12d3-a456-426614174000',
-			expect.objectContaining({ status: 'pending' })
-		);
-	});
-});
-
 // ============================================================================
 // getNextTask Tests
 // ============================================================================

package/src/handlers/tasks.ts

@@ -2,7 +2,11 @@
  * Task Handlers (Migrated to API Client)
  *
  * Handles task CRUD and management:
- * - get_tasks
+ * - get_task (single task by ID)
+ * - search_tasks (text search)
+ * - get_tasks_by_priority (priority filter)
+ * - get_recent_tasks (by date)
+ * - get_task_stats (aggregate counts)
  * - get_next_task
  * - add_task
  * - update_task
@@ -16,6 +20,7 @@
  * - get_subtasks
  */
 
+import os from 'os';
 import type { Handler, HandlerRegistry } from './types.js';
 import {
 	parseArgs,
@@ -29,6 +34,9 @@ import {
 } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
+// Auto-detect machine hostname for worktree tracking
+const MACHINE_HOSTNAME = os.hostname();
+
 // Valid task types
 const VALID_TASK_TYPES = [
 	'frontend', 'backend', 'database', 'feature', 'bugfix',
@@ -39,16 +47,6 @@ const VALID_TASK_TYPES = [
 // Argument Schemas
 // ============================================================================
 
-const getTasksSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	status: { type: 'string' as const, validate: taskStatusValidator },
-	limit: { type: 'number' as const, default: 50 },
-	offset: { type: 'number' as const, default: 0 },
-	search_query: { type: 'string' as const },
-	include_subtasks: { type: 'boolean' as const, default: false },
-	include_metadata: { type: 'boolean' as const, default: false },
-};
-
 const getNextTaskSchema = {
 	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
 };
@@ -117,6 +115,47 @@ const addSubtaskSchema = {
 const getSubtasksSchema = {
 	parent_task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
 	status: { type: 'string' as const, validate: taskStatusValidator },
+	limit: { type: 'number' as const, default: 20 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+// ============================================================================
+// New Targeted Task Query Schemas
+// ============================================================================
+
+const getTaskSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	include_subtasks: { type: 'boolean' as const, default: false },
+	include_milestones: { type: 'boolean' as const, default: false },
+};
+
+const searchTasksSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	query: { type: 'string' as const, required: true as const },
+	status: { type: 'array' as const },
+	limit: { type: 'number' as const, default: 10 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+const getTasksByPrioritySchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	priority: { type: 'number' as const, validate: priorityValidator },
+	priority_max: { type: 'number' as const, validate: priorityValidator },
+	status: { type: 'string' as const, validate: taskStatusValidator },
+	limit: { type: 'number' as const, default: 10 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+const getRecentTasksSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	order: { type: 'string' as const, validate: createEnumValidator(['newest', 'oldest']) },
+	status: { type: 'string' as const, validate: taskStatusValidator },
+	limit: { type: 'number' as const, default: 10 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+const getTaskStatsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
 };
 
 // ============================================================================
@@ -216,32 +255,6 @@ export function getValidationApprovedGitInstructions(
 // Task Handlers - Using API Client
 // ============================================================================
 
-export const getTasks: Handler = async (args, ctx) => {
-	const { project_id, status, limit, offset, search_query, include_subtasks, include_metadata } = parseArgs(args, getTasksSchema);
-
-	const api = getApiClient();
-	const response = await api.getTasks(project_id, {
-		status,
-		limit: Math.min(limit ?? 50, 200),
-		offset,
-		include_subtasks,
-		search_query,
-		include_metadata,
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to fetch tasks' }, isError: true };
-	}
-
-	return {
-		result: {
-			tasks: response.data?.tasks || [],
-			total_count: response.data?.total_count || 0,
-			has_more: response.data?.has_more || false,
-		},
-	};
-};
-
 export const getNextTask: Handler = async (args, ctx) => {
 	const { project_id } = parseArgs(args, getNextTaskSchema);
 
@@ -400,6 +413,17 @@ export const updateTask: Handler = async (args, ctx) => {
 		result.next_step = data.next_step;
 	}
 
+	// Add test reminder when starting work on a task
+	if (status === 'in_progress') {
+		result.test_reminder = {
+			message: 'Remember to write tests for this task before marking it complete.',
+			minimum_expectation: 'Basic tests that validate the task requirements are met',
+			ideal: 'Tests that also cover edge cases and error handling',
+			test_patterns: ['*.test.ts', '*.spec.ts', '*.test.js', '*.spec.js', '__tests__/*'],
+			note: 'Validators will check for test file changes during review. Documentation-only or config changes may not require tests.',
+		};
+	}
+
 	return { result };
 };
 
@@ -640,12 +664,199 @@ export const getSubtasks: Handler = async (args, ctx) => {
 	};
 };
 
+// ============================================================================
+// New Targeted Task Query Handlers
+// ============================================================================
+
+/**
+ * Get a single task by ID with optional subtasks and milestones
+ */
+export const getTask: Handler = async (args, ctx) => {
+	const { task_id, include_subtasks, include_milestones } = parseArgs(args, getTaskSchema);
+
+	const api = getApiClient();
+	const response = await api.getTaskById(task_id, {
+		include_subtasks,
+		include_milestones,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to fetch task' }, isError: true };
+	}
+
+	const result: Record<string, unknown> = {
+		task: response.data?.task,
+	};
+
+	if (include_subtasks && response.data?.subtasks) {
+		result.subtasks = response.data.subtasks;
+	}
+
+	if (include_milestones && response.data?.milestones) {
+		result.milestones = response.data.milestones;
+	}
+
+	return { result };
+};
+
+/**
+ * Search tasks by text query with pagination
+ */
+export const searchTasks: Handler = async (args, ctx) => {
+	const { project_id, query, status, limit, offset } = parseArgs(args, searchTasksSchema);
+
+	// Validate query length
+	if (query.length < 2) {
+		return {
+			result: {
+				error: 'query_too_short',
+				message: 'Search query must be at least 2 characters',
+			},
+		};
+	}
+
+	// Cap limit at 20, safe offset
+	const cappedLimit = Math.min(limit ?? 10, 20);
+	const safeOffset = Math.max(0, offset ?? 0);
+
+	const api = getApiClient();
+	const response = await api.searchTasks(project_id, {
+		query,
+		status: status as string[] | undefined,
+		limit: cappedLimit,
+		offset: safeOffset,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to search tasks' }, isError: true };
+	}
+
+	const tasks = response.data?.tasks || [];
+	const totalMatches = response.data?.total_matches || 0;
+
+	return {
+		result: {
+			tasks,
+			total_matches: totalMatches,
+			has_more: safeOffset + tasks.length < totalMatches,
+			offset: safeOffset,
+			limit: cappedLimit,
+		},
+	};
+};
+
+/**
+ * Get tasks filtered by priority with pagination
+ */
+export const getTasksByPriority: Handler = async (args, ctx) => {
+	const { project_id, priority, priority_max, status, limit, offset } = parseArgs(args, getTasksByPrioritySchema);
+
+	// Cap limit at 20, safe offset
+	const cappedLimit = Math.min(limit ?? 10, 20);
+	const safeOffset = Math.max(0, offset ?? 0);
+
+	const api = getApiClient();
+	const response = await api.getTasksByPriority(project_id, {
+		priority,
+		priority_max,
+		status,
+		limit: cappedLimit,
+		offset: safeOffset,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to fetch tasks by priority' }, isError: true };
+	}
+
+	const tasks = response.data?.tasks || [];
+	const totalCount = response.data?.total_count || 0;
+
+	return {
+		result: {
+			tasks,
+			total_count: totalCount,
+			has_more: safeOffset + tasks.length < totalCount,
+			offset: safeOffset,
+			limit: cappedLimit,
+		},
+	};
+};
+
+/**
+ * Get recent tasks (newest or oldest) with pagination
+ */
+export const getRecentTasks: Handler = async (args, ctx) => {
+	const { project_id, order, status, limit, offset } = parseArgs(args, getRecentTasksSchema);
+
+	// Cap limit at 20, safe offset
+	const cappedLimit = Math.min(limit ?? 10, 20);
+	const safeOffset = Math.max(0, offset ?? 0);
+
+	const api = getApiClient();
+	const response = await api.getRecentTasks(project_id, {
+		order: order as 'newest' | 'oldest' | undefined,
+		status,
+		limit: cappedLimit,
+		offset: safeOffset,
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to fetch recent tasks' }, isError: true };
+	}
+
+	const tasks = response.data?.tasks || [];
+	const totalCount = response.data?.total_count || 0;
+
+	return {
+		result: {
+			tasks,
+			total_count: totalCount,
+			has_more: safeOffset + tasks.length < totalCount,
+			offset: safeOffset,
+			limit: cappedLimit,
+		},
+	};
+};
+
+/**
+ * Get task statistics for a project (aggregate counts only, minimal tokens)
+ */
+export const getTaskStats: Handler = async (args, ctx) => {
+	const { project_id } = parseArgs(args, getTaskStatsSchema);
+
+	const api = getApiClient();
+	const response = await api.getTaskStats(project_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to fetch task stats' }, isError: true };
+	}
+
+	return {
+		result: {
+			total: response.data?.total || 0,
+			by_status: response.data?.by_status || {
+				backlog: 0,
+				pending: 0,
+				in_progress: 0,
+				completed: 0,
+				cancelled: 0,
+			},
+			by_priority: response.data?.by_priority || { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 },
+			awaiting_validation: response.data?.awaiting_validation || 0,
+			oldest_pending_days: response.data?.oldest_pending_days ?? null,
+		},
+	};
+};
+
 // ============================================================================
 // Worktree Cleanup Handlers
 // ============================================================================
 
 const getStaleWorktreesSchema = {
 	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	hostname: { type: 'string' as const }, // Machine hostname to filter worktrees
+	limit: { type: 'number' as const, default: 20 },
+	offset: { type: 'number' as const, default: 0 },
 };
 
 const clearWorktreePathSchema = {
@@ -653,10 +864,16 @@ const clearWorktreePathSchema = {
 };
 
 export const getStaleWorktrees: Handler = async (args, ctx) => {
-	const { project_id } = parseArgs(args, getStaleWorktreesSchema);
+	const { project_id, hostname: providedHostname, limit, offset } = parseArgs(args, getStaleWorktreesSchema);
+
+	// Use auto-detected hostname if not provided - filters to only worktrees on THIS machine
+	const hostname = providedHostname || MACHINE_HOSTNAME;
+
+	// Cap limit to prevent context bloating
+	const cappedLimit = Math.min(limit ?? 20, 50);
 
 	const api = getApiClient();
-	const response = await api.getStaleWorktrees(project_id);
+	const response = await api.getStaleWorktrees(project_id, { hostname, limit: cappedLimit, offset });
 
 	if (!response.ok) {
 		return { result: { error: response.error || 'Failed to get stale worktrees' }, isError: true };
@@ -667,9 +884,15 @@ export const getStaleWorktrees: Handler = async (args, ctx) => {
 		result: {
 			project_id: data?.project_id,
 			project_name: data?.project_name,
+			hostname_filter: data?.hostname_filter,
 			stale_worktrees: data?.stale_worktrees || [],
 			count: data?.count || 0,
+			local_count: data?.local_count || 0,
+			remote_count: data?.remote_count || 0,
+			total_count: data?.total_count || 0,
+			has_more: data?.has_more || false,
 			cleanup_instructions: data?.cleanup_instructions,
+			remote_worktree_note: data?.remote_worktree_note,
 		},
 	};
 };
@@ -697,7 +920,13 @@ export const clearWorktreePath: Handler = async (args, ctx) => {
  * Task handlers registry
  */
 export const taskHandlers: HandlerRegistry = {
-	get_tasks: getTasks,
+	// Targeted task query endpoints (token-efficient)
+	get_task: getTask,
+	search_tasks: searchTasks,
+	get_tasks_by_priority: getTasksByPriority,
+	get_recent_tasks: getRecentTasks,
+	get_task_stats: getTaskStats,
+	// Core task operations
 	get_next_task: getNextTask,
 	add_task: addTask,
 	update_task: updateTask,

package/src/handlers/tool-docs.ts

@@ -92,13 +92,73 @@ Sync README content to the dashboard.
 - project_id (required): Project UUID
 - readme_content (required): Markdown content`,
 
-	get_tasks: `# get_tasks
-Get tasks for a project.
+	get_task: `# get_task
+Get a single task by ID with optional subtasks and milestones.
+
+**Parameters:**
+- task_id (required): Task UUID
+- include_subtasks (optional): Include subtasks array (default: false)
+- include_milestones (optional): Include milestones array (default: false)`,
+
+	search_tasks: `# search_tasks
+Search tasks by text query. Supports pagination.
+
+**Parameters:**
+- project_id (required): Project UUID
+- query (required): Search query (min 2 chars)
+- status (optional): Array of statuses to filter
+- limit (optional): Max results per page (1-20, default: 10)
+- offset (optional): Number of results to skip (default: 0)
+
+**Returns:**
+- tasks: Array of matching tasks
+- total_matches: Total number of matching tasks
+- has_more: Whether more results exist beyond current page
+- offset: Current offset
+- limit: Current limit`,
+
+	get_tasks_by_priority: `# get_tasks_by_priority
+Get tasks filtered by priority. Supports pagination.
+
+**Parameters:**
+- project_id (required): Project UUID
+- priority (optional): Exact priority (1-5)
+- priority_max (optional): Max priority for range query
+- status (optional): Filter by status (default: pending)
+- limit (optional): Max results per page (1-20, default: 10)
+- offset (optional): Number of results to skip (default: 0)
+
+**Returns:**
+- tasks: Array of matching tasks
+- total_count: Total number of matching tasks
+- has_more: Whether more results exist beyond current page
+- offset: Current offset
+- limit: Current limit`,
+
+	get_recent_tasks: `# get_recent_tasks
+Get tasks ordered by creation date. Supports pagination.
+
+**Parameters:**
+- project_id (required): Project UUID
+- order (optional): 'newest' or 'oldest' (default: newest)
+- status (optional): Filter by status
+- limit (optional): Max results per page (1-20, default: 10)
+- offset (optional): Number of results to skip (default: 0)
+
+**Returns:**
+- tasks: Array of matching tasks
+- total_count: Total number of matching tasks
+- has_more: Whether more results exist beyond current page
+- offset: Current offset
+- limit: Current limit`,
+
+	get_task_stats: `# get_task_stats
+Get aggregate task statistics. Most token-efficient way to understand project state.
 
 **Parameters:**
 - project_id (required): Project UUID
-- status (optional): pending, in_progress, completed, cancelled
-- limit (optional): Max tasks (default 50)`,
+
+**Returns:** Counts by status and priority, no task data`,
 
 	get_next_task: `# get_next_task
 Get highest priority pending task not claimed by another agent.
@@ -145,6 +205,18 @@ Delete a task.
 **Parameters:**
 - task_id (required): Task UUID`,
 
+	cancel_task: `# cancel_task
+Cancel a task with an optional reason. Use this when a task should be marked as cancelled rather than deleted (e.g., PR was closed, work was superseded). The task remains visible with a cancelled status for historical tracking.
+
+**Parameters:**
+- task_id (required): Task UUID
+- cancelled_reason (optional): One of: pr_closed, superseded, user_cancelled, validation_failed, obsolete, blocked
+- cancellation_note (optional): Additional context about the cancellation
+
+**Returns:** task_id, cancelled_reason, message, sprint info (if auto-completed)
+
+**Example:** cancel_task(task_id: "abc", cancelled_reason: "pr_closed", cancellation_note: "PR was closed without merging")`,
+
 	batch_update_tasks: `# batch_update_tasks
 Update multiple tasks at once.
 
@@ -1018,7 +1090,7 @@ Query aggregated project knowledge in a single call. Reduces token usage by comb
 - stats: counts for each category, findings by severity
 - Category data based on selection
 
-**Token savings:** Replaces up to 6 separate tool calls (get_findings, get_decisions, get_tasks, get_blockers, etc.) with one call.
+**Token savings:** Replaces multiple tool calls (get_findings, get_decisions, get_blockers, etc.) with one call.
 
 **Example:** query_knowledge_base(project_id, categories: ["findings", "decisions"], limit: 10)`,
 };