@vibescope/mcp-server 0.3.0 → 0.3.3

package/dist/api-client/tasks.d.ts

@@ -0,0 +1,328 @@
+/**
+ * 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 declare function createTasksMethods(request: RequestFn, proxy: ProxyFn): TasksMethods;

package/dist/api-client/tasks.js

@@ -0,0 +1,132 @@
+/**
+ * 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
+ */
+export function createTasksMethods(request, proxy) {
+    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/dist/api-client/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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;
+}
+export type RequestFn = <T>(method: string, path: string, body?: unknown) => Promise<ApiResponse<T>>;
+export type ProxyFn = <T>(operation: string, args: Record<string, unknown>, sessionContext?: {
+    session_id?: string;
+    project_id?: string;
+}) => Promise<ApiResponse<T>>;

package/dist/api-client/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared Types for Vibescope API Client
+ */
+export {};

package/dist/api-client/worktrees.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 declare function createWorktreesMethods(request: RequestFn): WorktreesMethods;

package/dist/api-client/worktrees.js

@@ -0,0 +1,26 @@
+/**
+ * Worktrees API Methods
+ *
+ * Methods for git worktree management:
+ * - getStaleWorktrees: List stale worktrees for cleanup
+ * - clearWorktreePath: Clear worktree path from a task
+ */
+export function createWorktreesMethods(request) {
+    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`);
+        }
+    };
+}

package/dist/api-client.d.ts

@@ -4,9 +4,16 @@
  * HTTP client for communicating with the Vibescope API.
  * All database operations are handled server-side through these endpoints.
  */
+interface RetryConfig {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    retryStatusCodes?: number[];
+}
 interface ApiClientConfig {
     apiKey: string;
     baseUrl?: string;
+    retry?: RetryConfig;
 }
 interface ApiResponse<T> {
     ok: boolean;
@@ -17,6 +24,7 @@ interface ApiResponse<T> {
 export declare class VibescopeApiClient {
     private apiKey;
     private baseUrl;
+    private retryConfig;
     constructor(config: ApiClientConfig);
     private request;
     validateAuth(): Promise<ApiResponse<{
@@ -33,6 +41,7 @@ export declare class VibescopeApiClient {
         role?: string;
         hostname?: string;
         agent_type?: string;
+        agent_name?: string;
     }): Promise<ApiResponse<{
         session_started: boolean;
         session_id?: string;