@vibescope/mcp-server 0.3.0 → 0.3.3

package/dist/tools/worktrees.js

@@ -0,0 +1,63 @@
+/**
+ * Git Worktree Tool Definitions
+ *
+ * Tools for managing git worktrees:
+ * - get_stale_worktrees: Get worktrees that need cleanup
+ * - clear_worktree_path: Clear worktree_path from a task after cleanup
+ */
+export const worktreeTools = [
+    {
+        name: 'get_stale_worktrees',
+        description: `Get worktrees that need cleanup.
+
+Returns tasks with worktree_path set where:
+- Task is completed or cancelled (worktree should have been cleaned up)
+- Task has been abandoned (no activity for 24+ hours while in_progress)
+
+IMPORTANT: Pass hostname (os.hostname()) to only see worktrees created on THIS machine.
+Worktrees created on other machines cannot be removed locally.
+
+For each stale worktree:
+1. Run: git worktree remove <worktree_path>
+2. Call: clear_worktree_path(task_id)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                hostname: {
+                    type: 'string',
+                    description: 'Machine hostname (os.hostname()). Only returns worktrees created on this machine, preventing attempts to clean up worktrees on other machines.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max worktrees to return (default: 50)',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Number of worktrees to skip for pagination (default: 0)',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'clear_worktree_path',
+        description: `Clear the worktree_path from a task after cleanup.
+
+Call this AFTER removing the worktree with git worktree remove.
+This marks the task as cleaned up so it won't appear in get_stale_worktrees.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID',
+                },
+            },
+            required: ['task_id'],
+        },
+    },
+];

package/dist/utils.d.ts

@@ -159,3 +159,69 @@ export declare function extractProjectNameFromGitUrl(gitUrl: string): string;
  * // Returns: 'https://github.com/nonatomic/vibescope'
  */
 export declare function normalizeGitUrl(gitUrl: string | null | undefined): string | null;
+/**
+ * Extract a human-readable message from any error type.
+ * Handles Error objects, strings, and unknown values.
+ *
+ * @example
+ * try { ... } catch (e) {
+ *   console.error(getErrorMessage(e));
+ * }
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Type guard to check if a value is an object with an 'error' property.
+ * Useful for checking API responses that may contain application-level errors.
+ *
+ * @example
+ * if (hasErrorProperty(response.data)) {
+ *   return error(getErrorMessage(response.data.error));
+ * }
+ */
+export declare function hasErrorProperty(value: unknown): value is {
+    error: unknown;
+};
+/**
+ * Extract an error message from an API response body.
+ * Handles the common pattern where API returns { error: string } or { error: { message: string } }.
+ * Returns null if no error is found.
+ *
+ * @example
+ * const apiError = extractApiError(response.data);
+ * if (apiError) {
+ *   return error(apiError);
+ * }
+ */
+export declare function extractApiError(data: unknown): string | null;
+/**
+ * Default pagination limits
+ */
+export declare const PAGINATION_LIMITS: {
+    /** Default maximum limit for paginated results */
+    readonly DEFAULT_MAX_LIMIT: 50;
+    /** Default limit when not specified */
+    readonly DEFAULT_LIMIT: 20;
+    /** Smaller limit for task listings */
+    readonly TASK_LIMIT: 20;
+};
+/**
+ * Cap pagination parameters to safe values.
+ * Ensures limit is between 1 and maxLimit, and offset is non-negative.
+ *
+ * @param limit - Requested limit (will be capped between 1 and maxLimit)
+ * @param offset - Requested offset (will be made non-negative)
+ * @param maxLimit - Maximum allowed limit (default: PAGINATION_LIMITS.DEFAULT_MAX_LIMIT)
+ * @returns Object with cappedLimit and safeOffset
+ *
+ * @example
+ * const { cappedLimit, safeOffset } = capPagination(limit, offset);
+ * const { data } = await query.range(safeOffset, safeOffset + cappedLimit - 1);
+ *
+ * @example
+ * // With custom max limit
+ * const { cappedLimit, safeOffset } = capPagination(limit, offset, 20);
+ */
+export declare function capPagination(limit: number | undefined, offset: number | undefined, maxLimit?: number): {
+    cappedLimit: number;
+    safeOffset: number;
+};

package/dist/utils.js

@@ -396,3 +396,105 @@ export function normalizeGitUrl(gitUrl) {
     normalized = normalized.toLowerCase();
     return normalized;
 }
+// ============================================================================
+// Error Handling Utilities
+// Shared error extraction and type checking functions
+// ============================================================================
+/**
+ * Extract a human-readable message from any error type.
+ * Handles Error objects, strings, and unknown values.
+ *
+ * @example
+ * try { ... } catch (e) {
+ *   console.error(getErrorMessage(e));
+ * }
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return String(error);
+}
+/**
+ * Type guard to check if a value is an object with an 'error' property.
+ * Useful for checking API responses that may contain application-level errors.
+ *
+ * @example
+ * if (hasErrorProperty(response.data)) {
+ *   return error(getErrorMessage(response.data.error));
+ * }
+ */
+export function hasErrorProperty(value) {
+    return typeof value === 'object' && value !== null && 'error' in value;
+}
+/**
+ * Extract an error message from an API response body.
+ * Handles the common pattern where API returns { error: string } or { error: { message: string } }.
+ * Returns null if no error is found.
+ *
+ * @example
+ * const apiError = extractApiError(response.data);
+ * if (apiError) {
+ *   return error(apiError);
+ * }
+ */
+export function extractApiError(data) {
+    if (!hasErrorProperty(data)) {
+        return null;
+    }
+    const err = data.error;
+    // Direct string error
+    if (typeof err === 'string') {
+        return err;
+    }
+    // Nested error object with message property
+    if (typeof err === 'object' && err !== null && 'message' in err) {
+        const msg = err.message;
+        if (typeof msg === 'string') {
+            return msg;
+        }
+    }
+    // Fallback for unknown error structure
+    return 'Unknown error';
+}
+// ============================================================================
+// Pagination Utilities
+// ============================================================================
+/**
+ * Default pagination limits
+ */
+export const PAGINATION_LIMITS = {
+    /** Default maximum limit for paginated results */
+    DEFAULT_MAX_LIMIT: 50,
+    /** Default limit when not specified */
+    DEFAULT_LIMIT: 20,
+    /** Smaller limit for task listings */
+    TASK_LIMIT: 20,
+};
+/**
+ * Cap pagination parameters to safe values.
+ * Ensures limit is between 1 and maxLimit, and offset is non-negative.
+ *
+ * @param limit - Requested limit (will be capped between 1 and maxLimit)
+ * @param offset - Requested offset (will be made non-negative)
+ * @param maxLimit - Maximum allowed limit (default: PAGINATION_LIMITS.DEFAULT_MAX_LIMIT)
+ * @returns Object with cappedLimit and safeOffset
+ *
+ * @example
+ * const { cappedLimit, safeOffset } = capPagination(limit, offset);
+ * const { data } = await query.range(safeOffset, safeOffset + cappedLimit - 1);
+ *
+ * @example
+ * // With custom max limit
+ * const { cappedLimit, safeOffset } = capPagination(limit, offset, 20);
+ */
+export function capPagination(limit, offset, maxLimit = PAGINATION_LIMITS.DEFAULT_MAX_LIMIT) {
+    const effectiveLimit = limit ?? PAGINATION_LIMITS.DEFAULT_LIMIT;
+    return {
+        cappedLimit: Math.min(Math.max(1, effectiveLimit), maxLimit),
+        safeOffset: Math.max(0, offset ?? 0)
+    };
+}

package/docs/TOOLS.md

@@ -2,9 +2,9 @@
 
 > Auto-generated from tool definitions. Do not edit manually.
 >
-> Generated: 2026-01-24
+> Generated: 2026-02-06
 >
-> Total tools: 152
+> Total tools: 154
 
 ## Table of Contents
 
@@ -33,6 +33,7 @@
 - [roles](#roles) - Agent role management (4 tools)
 - [file_locks](#file-locks) - File checkout/locking for multi-agent (6 tools)
 - [connectors](#connectors) - External integration connectors (7 tools)
+- [cloud_agents](#cloud-agents) - Cloud agent management and cleanup (2 tools)
 
 ## session
 
@@ -59,6 +60,7 @@ Use mode:'full' for complete context, mode:'lite' (default) for minimal tokens.
 | `role` | `string` | No | Agent role (e.g., "developer", "validator", "deployer", "reviewer", "maintainer"). Custom roles accepted. |
 | `hostname` | `string` | No | Machine hostname for worktree tracking. Pass os.hostname() to filter stale worktrees to only those created on this machine. |
 | `agent_type` | `string` | No | Agent type (e.g., "claude", "gemini", "cursor", "windsurf"). Custom agent types accepted. |
+| `agent_name` | `string` | No | Explicit agent name (for cloud/remote agents). If provided, uses this name instead of selecting from persona pool. Cloud agents should pass their spawner-assigned name. |
 
 ---
 
@@ -1025,6 +1027,7 @@ Validate a completed task. Include test results in validation_notes. For github-
 | `approved` | `boolean` | Yes | Whether the task passes validation (true = approved, false = needs more work) |
 | `pr_checks_passing` | `boolean` | No | REQUIRED when approving tasks with PRs. Confirm you verified PR checks are passing via `gh pr view <PR_NUMBER> --json statusCheckRollup`. Set to true only if all required checks pass. |
 | `skip_pr_check` | `boolean` | No | Skip PR existence check (use only for tasks that legitimately do not need a PR) |
+| `create_fix_task` | `boolean` | No | When rejecting (approved: false), create a new fix task linked to the original. The fix task will contain the rejection reason and be assigned the same git branch. |
 
 ---
 
@@ -2404,3 +2407,53 @@ Get event history for a connector or project. Shows delivery status and errors.
 | `offset` | `number` | No | Pagination offset (default: 0) |
 
 ---
+
+## cloud_agents
+
+*Cloud agent management and cleanup*
+
+### cleanup_stale_cloud_agents
+
+Clean up stale cloud agents that failed to start or lost connection.
+
+Finds agents stuck in 'starting' status (or optionally 'running' with no heartbeat) 
+
+and marks them as failed. Only operates on the current session's project.
+
+Use this when:
+
+- You see agents stuck in "starting" status on the dashboard
+
+- Cloud agents failed to spawn but weren't cleaned up
+
+- You want to clear ghost agents from a previous session
+
+SECURITY: This only affects agents in YOUR current project. Cannot access other users' projects.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID (required) |
+| `stale_minutes` | `number` | No | Consider agents stale after this many minutes (default: 5) |
+| `include_running` | `boolean` | No | Also clean up "running" agents with no recent heartbeat (default: false) |
+| `dry_run` | `boolean` | No | If true, just report what would be cleaned without actually cleaning (default: false) |
+
+---
+
+### list_cloud_agents
+
+List cloud agents for a project.
+
+Returns all spawned cloud agents for the project with their current status.
+
+Use this to check the state of cloud agents before/after cleanup.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID (required) |
+| `status` | `"starting" | "running" | "stopped" | "failed" | "all"` | No | Filter by status (default: all) |
+
+---

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@vibescope/mcp-server",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "MCP server for Vibescope - AI project tracking tools",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
     "vibescope-mcp": "dist/index.js",
-    "vibescope-cli": "dist/cli.js"
+    "vibescope-cli": "dist/cli.js",
+    "vibescope": "dist/cli-init.js",
+    "vibescope-init": "dist/cli-init.js"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Nonatomic/Vibescope.git",
+    "url": "https://github.com/PaulNonatomic/Vibescope.git",
     "directory": "packages/mcp-server"
   },
   "publishConfig": {

package/scripts/generate-docs.ts

@@ -9,7 +9,7 @@
  * npm run docs:generate
  */
 
-import { tools } from '../src/tools.js';
+import { tools } from '../src/tools/index.js';
 import { TOOL_CATEGORIES } from '../src/handlers/discovery.js';
 import * as fs from 'fs';
 import * as path from 'path';

package/src/api-client/blockers.ts

@@ -0,0 +1,86 @@
+/**
+ * Blockers API Methods
+ *
+ * Methods for blocker management:
+ * - getBlockers: List blockers for a project
+ * - addBlocker: Create a new blocker
+ * - resolveBlocker: Mark blocker as resolved
+ * - deleteBlocker: Delete a blocker
+ * - getBlockersStats: Get blocker statistics
+ */
+
+import type { ApiResponse, RequestFn } from './types.js';
+
+export interface BlockersMethods {
+	getBlockers(projectId: string, params?: {
+		status?: 'open' | 'resolved';
+		limit?: number;
+		offset?: number;
+	}): Promise<ApiResponse<{
+		blockers: Array<{
+			id: string;
+			description: string;
+			status: string;
+			created_at: string;
+			resolved_at?: string;
+			resolution_note?: string;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>>;
+
+	addBlocker(projectId: string, description: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		blocker_id: string;
+	}>>;
+
+	resolveBlocker(blockerId: string, resolutionNote?: string): Promise<ApiResponse<{
+		success: boolean;
+		blocker_id: string;
+	}>>;
+
+	deleteBlocker(blockerId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>>;
+
+	getBlockersStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+		open: number;
+		resolved: number;
+	}>>;
+}
+
+export function createBlockersMethods(request: RequestFn): BlockersMethods {
+	return {
+		async getBlockers(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());
+			const query = queryParams.toString();
+			const url = `/api/mcp/projects/${projectId}/blockers${query ? `?${query}` : ''}`;
+			return request('GET', url);
+		},
+
+		async addBlocker(projectId, description, sessionId) {
+			return request('POST', `/api/mcp/projects/${projectId}/blockers`, {
+				description,
+				session_id: sessionId
+			});
+		},
+
+		async resolveBlocker(blockerId, resolutionNote) {
+			return request('PATCH', `/api/mcp/blockers/${blockerId}/resolve`, {
+				resolution_note: resolutionNote
+			});
+		},
+
+		async deleteBlocker(blockerId) {
+			return request('DELETE', `/api/mcp/blockers/${blockerId}`);
+		},
+
+		async getBlockersStats(projectId) {
+			return request('GET', `/api/mcp/projects/${projectId}/blockers/stats`);
+		}
+	};
+}

package/src/api-client/cost.ts

@@ -0,0 +1,185 @@
+/**
+ * Cost API Methods
+ *
+ * Methods for cost tracking and alerts:
+ * - getCostSummary: Get cost summary by period
+ * - getCostAlerts: List cost alerts
+ * - addCostAlert: Create a cost alert
+ * - updateCostAlert: Update a cost alert
+ * - deleteCostAlert: Delete a cost alert
+ * - getTaskCosts: Get costs by task
+ * - getBodyOfWorkCosts: Get costs by body of work
+ * - getSprintCosts: Get costs by sprint
+ * - getTokenUsage: Get token usage stats
+ * - reportTokenUsage: Report token usage
+ */
+
+import type { ApiResponse, RequestFn } from './types.js';
+
+export interface CostMethods {
+	getCostSummary(projectId: string, params?: {
+		period?: 'daily' | 'weekly' | 'monthly';
+		limit?: number;
+	}): Promise<ApiResponse<{
+		summary: Array<{
+			period: string;
+			total_cost: number;
+			input_tokens: number;
+			output_tokens: number;
+			api_calls: number;
+		}>;
+	}>>;
+
+	getCostAlerts(): Promise<ApiResponse<{
+		alerts: Array<{
+			id: string;
+			project_id?: string;
+			threshold_amount: number;
+			threshold_period: string;
+			alert_type: string;
+			enabled: boolean;
+		}>;
+	}>>;
+
+	addCostAlert(params: {
+		project_id?: string;
+		threshold_amount: number;
+		threshold_period: 'daily' | 'weekly' | 'monthly';
+		alert_type?: 'warning' | 'critical';
+	}): Promise<ApiResponse<{
+		success: boolean;
+		alert_id: string;
+	}>>;
+
+	updateCostAlert(alertId: string, updates: {
+		threshold_amount?: number;
+		threshold_period?: 'daily' | 'weekly' | 'monthly';
+		alert_type?: 'warning' | 'critical';
+		enabled?: boolean;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		alert_id: string;
+	}>>;
+
+	deleteCostAlert(alertId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>>;
+
+	getTaskCosts(projectId: string, limit?: number): Promise<ApiResponse<{
+		tasks: Array<{
+			task_id: string;
+			task_title: string;
+			total_cost: number;
+			input_tokens: number;
+			output_tokens: number;
+		}>;
+	}>>;
+
+	getBodyOfWorkCosts(params: {
+		body_of_work_id?: string;
+		project_id?: string;
+		limit?: number;
+	}): Promise<ApiResponse<{
+		bodies_of_work: Array<{
+			body_of_work_id: string;
+			title: string;
+			total_cost: number;
+			task_count: number;
+		}>;
+	}>>;
+
+	getSprintCosts(params: {
+		sprint_id?: string;
+		project_id?: string;
+		limit?: number;
+	}): Promise<ApiResponse<{
+		sprints: Array<{
+			sprint_id: string;
+			name: string;
+			total_cost: number;
+			task_count: number;
+		}>;
+	}>>;
+
+	getTokenUsage(): Promise<ApiResponse<{
+		session_tokens: {
+			input: number;
+			output: number;
+		};
+		estimated_cost: number;
+	}>>;
+
+	reportTokenUsage(sessionId: string, params: {
+		input_tokens: number;
+		output_tokens: number;
+		model?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		session_id: string;
+		total_input_tokens: number;
+		total_output_tokens: number;
+	}>>;
+}
+
+export function createCostMethods(request: RequestFn): CostMethods {
+	return {
+		async getCostSummary(projectId, params) {
+			const queryParams = new URLSearchParams();
+			if (params?.period) queryParams.set('period', params.period);
+			if (params?.limit) queryParams.set('limit', params.limit.toString());
+			const query = queryParams.toString();
+			const url = `/api/mcp/projects/${projectId}/cost-summary${query ? `?${query}` : ''}`;
+			return request('GET', url);
+		},
+
+		async getCostAlerts() {
+			return request('GET', '/api/mcp/cost-alerts');
+		},
+
+		async addCostAlert(params) {
+			return request('POST', '/api/mcp/cost-alerts', params);
+		},
+
+		async updateCostAlert(alertId, updates) {
+			return request('PATCH', `/api/mcp/cost-alerts/${alertId}`, updates);
+		},
+
+		async deleteCostAlert(alertId) {
+			return request('DELETE', `/api/mcp/cost-alerts/${alertId}`);
+		},
+
+		async getTaskCosts(projectId, limit) {
+			const url = limit
+				? `/api/mcp/projects/${projectId}/task-costs?limit=${limit}`
+				: `/api/mcp/projects/${projectId}/task-costs`;
+			return request('GET', url);
+		},
+
+		async getBodyOfWorkCosts(params) {
+			const queryParams = new URLSearchParams();
+			if (params.body_of_work_id) queryParams.set('body_of_work_id', params.body_of_work_id);
+			if (params.project_id) queryParams.set('project_id', params.project_id);
+			if (params.limit) queryParams.set('limit', params.limit.toString());
+			return request('GET', `/api/mcp/cost/bodies-of-work?${queryParams.toString()}`);
+		},
+
+		async getSprintCosts(params) {
+			const queryParams = new URLSearchParams();
+			if (params.sprint_id) queryParams.set('sprint_id', params.sprint_id);
+			if (params.project_id) queryParams.set('project_id', params.project_id);
+			if (params.limit) queryParams.set('limit', params.limit.toString());
+			return request('GET', `/api/mcp/cost/sprints?${queryParams.toString()}`);
+		},
+
+		async getTokenUsage() {
+			return request('GET', '/api/mcp/sessions/token-usage');
+		},
+
+		async reportTokenUsage(sessionId, params) {
+			return request('POST', '/api/mcp/sessions/token-usage', {
+				session_id: sessionId,
+				...params
+			});
+		}
+	};
+}