@vibescope/mcp-server 0.2.1 → 0.2.2

package/dist/handlers/sprints.js

@@ -88,13 +88,13 @@ export const createSprint = async (args, ctx) => {
     const startDateObj = new Date(start_date);
     const endDateObj = new Date(end_date);
     if (isNaN(startDateObj.getTime())) {
-        throw new Error('Invalid start_date format. Use YYYY-MM-DD');
+        return { result: { error: 'Invalid start_date format. Use YYYY-MM-DD' }, isError: true };
     }
     if (isNaN(endDateObj.getTime())) {
-        throw new Error('Invalid end_date format. Use YYYY-MM-DD');
+        return { result: { error: 'Invalid end_date format. Use YYYY-MM-DD' }, isError: true };
     }
     if (endDateObj < startDateObj) {
-        throw new Error('end_date must be on or after start_date');
+        return { result: { error: 'end_date must be on or after start_date' }, isError: true };
     }
     const { session } = ctx;
     const apiClient = getApiClient();
@@ -113,7 +113,7 @@ export const createSprint = async (args, ctx) => {
         instance_id: session.instanceId
     });
     if (!response.ok) {
-        throw new Error(`Failed to create sprint: ${response.error}`);
+        return { result: { error: response.error || 'Failed to create sprint' }, isError: true };
     }
     return {
         result: {
@@ -134,13 +134,13 @@ export const updateSprint = async (args, ctx) => {
     if (start_date) {
         const startDateObj = new Date(start_date);
         if (isNaN(startDateObj.getTime())) {
-            throw new Error('Invalid start_date format. Use YYYY-MM-DD');
+            return { result: { error: 'Invalid start_date format. Use YYYY-MM-DD' }, isError: true };
         }
     }
     if (end_date) {
         const endDateObj = new Date(end_date);
         if (isNaN(endDateObj.getTime())) {
-            throw new Error('Invalid end_date format. Use YYYY-MM-DD');
+            return { result: { error: 'Invalid end_date format. Use YYYY-MM-DD' }, isError: true };
         }
     }
     const apiClient = getApiClient();
@@ -155,7 +155,7 @@ export const updateSprint = async (args, ctx) => {
         deploy_version_bump,
     });
     if (!response.ok) {
-        throw new Error(`Failed to update sprint: ${response.error}`);
+        return { result: { error: response.error || 'Failed to update sprint' }, isError: true };
     }
     return { result: { success: true, sprint_id } };
 };
@@ -165,7 +165,7 @@ export const getSprint = async (args, ctx) => {
     // Response type varies based on summary_only
     const response = await apiClient.proxy('get_sprint', { sprint_id, summary_only });
     if (!response.ok) {
-        throw new Error(`Failed to get sprint: ${response.error}`);
+        return { result: { error: response.error || 'Failed to get sprint' }, isError: true };
     }
     return { result: response.data };
 };
@@ -179,7 +179,7 @@ export const getSprints = async (args, ctx) => {
         offset,
     });
     if (!response.ok) {
-        throw new Error(`Failed to fetch sprints: ${response.error}`);
+        return { result: { error: response.error || 'Failed to fetch sprints' }, isError: true };
     }
     return { result: response.data };
 };
@@ -190,7 +190,7 @@ export const deleteSprint = async (args, ctx) => {
         sprint_id
     });
     if (!response.ok) {
-        throw new Error(`Failed to delete sprint: ${response.error}`);
+        return { result: { error: response.error || 'Failed to delete sprint' }, isError: true };
     }
     return { result: { success: true, message: 'Sprint deleted. Tasks are preserved.' } };
 };
@@ -199,7 +199,7 @@ export const startSprint = async (args, ctx) => {
     const apiClient = getApiClient();
     const response = await apiClient.proxy('start_sprint', { sprint_id });
     if (!response.ok) {
-        throw new Error(`Failed to start sprint: ${response.error}`);
+        return { result: { error: response.error || 'Failed to start sprint' }, isError: true };
     }
     return { result: response.data };
 };
@@ -212,14 +212,14 @@ export const completeSprint = async (args, ctx) => {
         skip_retrospective,
     });
     if (!response.ok) {
-        throw new Error(`Failed to complete sprint: ${response.error}`);
+        return { result: { error: response.error || 'Failed to complete sprint' }, isError: true };
     }
     return { result: response.data };
 };
 export const addTaskToSprint = async (args, ctx) => {
     const { sprint_id, task_id, story_points, phase } = parseArgs(args, addTaskToSprintSchema);
     if (story_points !== undefined && (story_points < 0 || !Number.isInteger(story_points))) {
-        throw new Error('story_points must be a non-negative integer');
+        return { result: { error: 'story_points must be a non-negative integer' }, isError: true };
     }
     const apiClient = getApiClient();
     const response = await apiClient.proxy('add_task_to_sprint', {
@@ -229,7 +229,7 @@ export const addTaskToSprint = async (args, ctx) => {
         phase: phase || 'core',
     });
     if (!response.ok) {
-        throw new Error(`Failed to add task to sprint: ${response.error}`);
+        return { result: { error: response.error || 'Failed to add task to sprint' }, isError: true };
     }
     return { result: response.data };
 };
@@ -241,7 +241,7 @@ export const removeTaskFromSprint = async (args, ctx) => {
         task_id,
     });
     if (!response.ok) {
-        throw new Error(`Failed to remove task from sprint: ${response.error}`);
+        return { result: { error: response.error || 'Failed to remove task from sprint' }, isError: true };
     }
     return { result: response.data };
 };
@@ -253,7 +253,7 @@ export const getSprintBacklog = async (args, ctx) => {
         sprint_id,
     });
     if (!response.ok) {
-        throw new Error(`Failed to get sprint backlog: ${response.error}`);
+        return { result: { error: response.error || 'Failed to get sprint backlog' }, isError: true };
     }
     return { result: response.data };
 };
@@ -265,7 +265,7 @@ export const getSprintVelocity = async (args, ctx) => {
         limit: Math.min(limit ?? 10, 50),
     });
     if (!response.ok) {
-        throw new Error(`Failed to get sprint velocity: ${response.error}`);
+        return { result: { error: response.error || 'Failed to get sprint velocity' }, isError: true };
     }
     return { result: response.data };
 };

package/dist/handlers/tasks.d.ts

@@ -42,6 +42,8 @@ export declare const batchUpdateTasks: Handler;
 export declare const batchCompleteTasks: Handler;
 export declare const addSubtask: Handler;
 export declare const getSubtasks: Handler;
+export declare const getStaleWorktrees: Handler;
+export declare const clearWorktreePath: Handler;
 /**
  * Task handlers registry
  */

package/dist/handlers/tasks.js

@@ -56,7 +56,9 @@ const updateTaskSchema = {
     progress_note: { type: 'string' },
     estimated_minutes: { type: 'number', validate: minutesValidator },
     git_branch: { type: 'string' },
+    worktree_path: { type: 'string' },
     task_type: { type: 'string', validate: createEnumValidator(VALID_TASK_TYPES) },
+    skip_worktree_requirement: { type: 'boolean', default: false },
 };
 const completeTaskSchema = {
     task_id: { type: 'string', required: true, validate: uuidValidator },
@@ -153,7 +155,7 @@ export const getTasks = async (args, ctx) => {
         include_metadata,
     });
     if (!response.ok) {
-        throw new Error(`Failed to fetch tasks: ${response.error}`);
+        return { result: { error: response.error || 'Failed to fetch tasks' }, isError: true };
     }
     return {
         result: {
@@ -168,7 +170,7 @@ export const getNextTask = async (args, ctx) => {
     const api = getApiClient();
     const response = await api.getNextTask(project_id, ctx.session.currentSessionId || undefined);
     if (!response.ok) {
-        throw new Error(`Failed to get next task: ${response.error}`);
+        return { result: { error: response.error || 'Failed to get next task' }, isError: true };
     }
     const data = response.data;
     if (!data) {
@@ -219,7 +221,7 @@ export const addTask = async (args, ctx) => {
         task_type,
     });
     if (!response.ok) {
-        throw new Error(`Failed to add task: ${response.error}`);
+        return { result: { error: response.error || 'Failed to add task' }, isError: true };
     }
     const data = response.data;
     const result = {
@@ -234,8 +236,24 @@ export const addTask = async (args, ctx) => {
     return { result };
 };
 export const updateTask = async (args, ctx) => {
-    const { task_id, title, description, priority, status, progress_percentage, progress_note, estimated_minutes, git_branch, task_type } = parseArgs(args, updateTaskSchema);
-    const updates = { title, description, priority, status, progress_percentage, estimated_minutes, git_branch, task_type };
+    const { task_id, title, description, priority, status, progress_percentage, progress_note, estimated_minutes, git_branch, worktree_path, task_type, skip_worktree_requirement } = parseArgs(args, updateTaskSchema);
+    const updates = { title, description, priority, status, progress_percentage, estimated_minutes, git_branch, worktree_path, task_type };
+    // Enforce worktree creation: require git_branch when marking task as in_progress
+    // This ensures multi-agent collaboration works properly with isolated worktrees
+    if (status === 'in_progress' && !git_branch && !skip_worktree_requirement) {
+        return {
+            result: {
+                error: 'worktree_required',
+                message: 'git_branch is required when marking a task as in_progress. Create a worktree first and provide the branch name.',
+                hint: 'Create a worktree with: git worktree add ../PROJECT-task-TASKID -b feature/TASKID-description BASE_BRANCH, then call update_task with both status and git_branch parameters.',
+                worktree_example: {
+                    command: `git worktree add ../worktree-${task_id.substring(0, 8)} -b feature/${task_id.substring(0, 8)}-task develop`,
+                    then: `update_task(task_id: "${task_id}", status: "in_progress", git_branch: "feature/${task_id.substring(0, 8)}-task")`,
+                },
+                skip_option: 'If this project does not use git branching (trunk-based or no git workflow), pass skip_worktree_requirement: true',
+            },
+        };
+    }
     const api = getApiClient();
     const response = await api.updateTask(task_id, {
         ...updates,
@@ -278,7 +296,7 @@ export const updateTask = async (args, ctx) => {
                 },
             };
         }
-        throw new Error(`Failed to update task: ${response.error}`);
+        return { result: { error: response.error || 'Failed to update task' }, isError: true };
     }
     // Build result - include git workflow info when transitioning to in_progress
     const data = response.data;
@@ -292,11 +310,6 @@ export const updateTask = async (args, ctx) => {
     if (data?.next_step) {
         result.next_step = data.next_step;
     }
-    // Warn if transitioning to in_progress without git_branch
-    if (updates.status === 'in_progress' && !updates.git_branch) {
-        result.warning = 'git_branch not set. For multi-agent collaboration, set git_branch when marking in_progress to track your worktree.';
-        result.hint = 'Call update_task again with git_branch parameter after creating your worktree.';
-    }
     return { result };
 };
 export const completeTask = async (args, ctx) => {
@@ -307,11 +320,11 @@ export const completeTask = async (args, ctx) => {
         session_id: ctx.session.currentSessionId || undefined,
     });
     if (!response.ok) {
-        throw new Error(`Failed to complete task: ${response.error}`);
+        return { result: { error: response.error || 'Failed to complete task' }, isError: true };
     }
     const data = response.data;
     if (!data) {
-        throw new Error('No response data from complete task');
+        return { result: { error: 'No response data from complete task' }, isError: true };
     }
     // Build result matching expected format
     const result = {
@@ -338,7 +351,7 @@ export const deleteTask = async (args, ctx) => {
     const api = getApiClient();
     const response = await api.deleteTask(task_id);
     if (!response.ok) {
-        throw new Error(`Failed to delete task: ${response.error}`);
+        return { result: { error: response.error || 'Failed to delete task' }, isError: true };
     }
     return { result: { success: true, deleted_id: task_id } };
 };
@@ -350,7 +363,7 @@ export const addTaskReference = async (args, ctx) => {
         if (response.error?.includes('already exists')) {
             return { result: { success: false, error: 'Reference with this URL already exists' } };
         }
-        throw new Error(`Failed to add reference: ${response.error}`);
+        return { result: { error: response.error || 'Failed to add reference' }, isError: true };
     }
     return {
         result: {
@@ -367,7 +380,7 @@ export const removeTaskReference = async (args, ctx) => {
         if (response.error?.includes('not found')) {
             return { result: { success: false, error: 'Reference with this URL not found' } };
         }
-        throw new Error(`Failed to remove reference: ${response.error}`);
+        return { result: { error: response.error || 'Failed to remove reference' }, isError: true };
     }
     return { result: { success: true } };
 };
@@ -390,7 +403,7 @@ export const batchUpdateTasks = async (args, ctx) => {
     const api = getApiClient();
     const response = await api.batchUpdateTasks(typedUpdates);
     if (!response.ok) {
-        throw new Error(`Failed to batch update tasks: ${response.error}`);
+        return { result: { error: response.error || 'Failed to batch update tasks' }, isError: true };
     }
     return {
         result: {
@@ -419,7 +432,7 @@ export const batchCompleteTasks = async (args, ctx) => {
     const api = getApiClient();
     const response = await api.batchCompleteTasks(typedCompletions);
     if (!response.ok) {
-        throw new Error(`Failed to batch complete tasks: ${response.error}`);
+        return { result: { error: response.error || 'Failed to batch complete tasks' }, isError: true };
     }
     const data = response.data;
     return {
@@ -454,7 +467,7 @@ export const addSubtask = async (args, ctx) => {
                 },
             };
         }
-        throw new Error(`Failed to add subtask: ${response.error}`);
+        return { result: { error: response.error || 'Failed to add subtask' }, isError: true };
     }
     return {
         result: {
@@ -469,7 +482,7 @@ export const getSubtasks = async (args, ctx) => {
     const api = getApiClient();
     const response = await api.getSubtasks(parent_task_id, status);
     if (!response.ok) {
-        throw new Error(`Failed to fetch subtasks: ${response.error}`);
+        return { result: { error: response.error || 'Failed to fetch subtasks' }, isError: true };
     }
     return {
         result: {
@@ -482,6 +495,48 @@ export const getSubtasks = async (args, ctx) => {
         },
     };
 };
+// ============================================================================
+// Worktree Cleanup Handlers
+// ============================================================================
+const getStaleWorktreesSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const clearWorktreePathSchema = {
+    task_id: { type: 'string', required: true, validate: uuidValidator },
+};
+export const getStaleWorktrees = async (args, ctx) => {
+    const { project_id } = parseArgs(args, getStaleWorktreesSchema);
+    const api = getApiClient();
+    const response = await api.getStaleWorktrees(project_id);
+    if (!response.ok) {
+        return { result: { error: response.error || 'Failed to get stale worktrees' }, isError: true };
+    }
+    const data = response.data;
+    return {
+        result: {
+            project_id: data?.project_id,
+            project_name: data?.project_name,
+            stale_worktrees: data?.stale_worktrees || [],
+            count: data?.count || 0,
+            cleanup_instructions: data?.cleanup_instructions,
+        },
+    };
+};
+export const clearWorktreePath = async (args, ctx) => {
+    const { task_id } = parseArgs(args, clearWorktreePathSchema);
+    const api = getApiClient();
+    const response = await api.clearWorktreePath(task_id);
+    if (!response.ok) {
+        return { result: { error: response.error || 'Failed to clear worktree path' }, isError: true };
+    }
+    return {
+        result: {
+            success: true,
+            task_id,
+            message: 'Worktree path cleared. The worktree can now be safely removed if not already done.',
+        },
+    };
+};
 /**
  * Task handlers registry
  */
@@ -499,4 +554,7 @@ export const taskHandlers = {
     // Subtask handlers
     add_subtask: addSubtask,
     get_subtasks: getSubtasks,
+    // Worktree cleanup handlers
+    get_stale_worktrees: getStaleWorktrees,
+    clear_worktree_path: clearWorktreePath,
 };

package/dist/handlers/types.d.ts

@@ -82,9 +82,40 @@ export interface HandlerContext {
     extractProjectNameFromGitUrl?: (gitUrl: string) => string;
 }
 /**
- * Result returned by handlers
+ * Success result with typed data
  */
-export interface HandlerResult {
+export interface SuccessResult<T = unknown> {
+    result: T;
+    content?: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError?: false;
+}
+/**
+ * Error result with error information
+ */
+export interface ErrorResult {
+    result: {
+        error: string;
+        [key: string]: unknown;
+    };
+    content?: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError: true;
+}
+/**
+ * Result returned by handlers - discriminated union for type safety
+ * Use the helper functions success() and error() to create properly typed results.
+ */
+export type HandlerResult<T = unknown> = SuccessResult<T> | ErrorResult;
+/**
+ * Legacy HandlerResult interface for backward compatibility
+ * @deprecated Use HandlerResult<T> discriminated union instead
+ */
+export interface LegacyHandlerResult {
     result?: unknown;
     content?: Array<{
         type: string;
@@ -92,6 +123,37 @@ export interface HandlerResult {
     }>;
     isError?: boolean;
 }
+/**
+ * Create a success result with typed data
+ * @example
+ * return success({ tasks: data, total_count: count });
+ */
+export declare function success<T>(data: T): SuccessResult<T>;
+/**
+ * Create an error result
+ * @example
+ * return error('Task not found');
+ * return error('Validation failed', { field: 'title', reason: 'too long' });
+ */
+export declare function error(message: string, details?: Record<string, unknown>): ErrorResult;
+/**
+ * Check if a handler result is a success (not an error)
+ * @example
+ * const result = await handler(args, ctx);
+ * if (isSuccess(result)) {
+ *   console.log(result.result); // typed as T
+ * }
+ */
+export declare function isSuccess<T>(result: HandlerResult<T>): result is SuccessResult<T>;
+/**
+ * Check if a handler result is an error
+ * @example
+ * const result = await handler(args, ctx);
+ * if (isError(result)) {
+ *   console.log(result.result.error); // string
+ * }
+ */
+export declare function isError(result: HandlerResult<unknown>): result is ErrorResult;
 /**
  * Handler function type
  */

package/dist/handlers/types.js

@@ -1 +1,48 @@
-export {};
+// ============================================================================
+// Result Factory Functions - use these for type-safe handler results
+// ============================================================================
+/**
+ * Create a success result with typed data
+ * @example
+ * return success({ tasks: data, total_count: count });
+ */
+export function success(data) {
+    return { result: data };
+}
+/**
+ * Create an error result
+ * @example
+ * return error('Task not found');
+ * return error('Validation failed', { field: 'title', reason: 'too long' });
+ */
+export function error(message, details) {
+    return {
+        result: { error: message, ...details },
+        isError: true
+    };
+}
+// ============================================================================
+// Type Predicates - use for runtime type narrowing
+// ============================================================================
+/**
+ * Check if a handler result is a success (not an error)
+ * @example
+ * const result = await handler(args, ctx);
+ * if (isSuccess(result)) {
+ *   console.log(result.result); // typed as T
+ * }
+ */
+export function isSuccess(result) {
+    return !result.isError;
+}
+/**
+ * Check if a handler result is an error
+ * @example
+ * const result = await handler(args, ctx);
+ * if (isError(result)) {
+ *   console.log(result.result.error); // string
+ * }
+ */
+export function isError(result) {
+    return result.isError === true;
+}

package/dist/handlers/validation.js

@@ -26,7 +26,7 @@ export const getTasksAwaitingValidation = async (args, _ctx) => {
     const apiClient = getApiClient();
     const response = await apiClient.getTasksAwaitingValidation(project_id);
     if (!response.ok) {
-        throw new Error(response.error || 'Failed to fetch tasks awaiting validation');
+        return { result: { error: response.error || 'Failed to fetch tasks awaiting validation' }, isError: true };
     }
     return { result: response.data };
 };
@@ -37,7 +37,7 @@ export const claimValidation = async (args, ctx) => {
     const apiClient = getApiClient();
     const response = await apiClient.claimValidation(task_id, currentSessionId || undefined);
     if (!response.ok) {
-        throw new Error(response.error || 'Failed to claim task for validation');
+        return { result: { error: response.error || 'Failed to claim task for validation' }, isError: true };
     }
     return { result: response.data };
 };
@@ -63,7 +63,7 @@ export const validateTask = async (args, ctx) => {
                 },
             };
         }
-        throw new Error(response.error || 'Failed to validate task');
+        return { result: { error: response.error || 'Failed to validate task' }, isError: true };
     }
     return { result: response.data };
 };