@vibescope/mcp-server 0.3.0 → 0.3.3

package/src/handlers/session.ts

@@ -37,6 +37,7 @@ const startWorkSessionSchema = {
 	role: { type: 'string' as const, default: 'developer' }, // Open-ended - any role name accepted
 	hostname: { type: 'string' as const }, // Machine hostname for worktree tracking
 	agent_type: { type: 'string' as const }, // Open-ended - any agent type accepted
+	agent_name: { type: 'string' as const }, // Explicit agent name for cloud/remote agents (skips persona pool)
 };
 
 const heartbeatSchema = {
@@ -54,7 +55,7 @@ const getHelpSchema = {
 };
 
 export const startWorkSession: Handler = async (args, ctx) => {
-	const { project_id, git_url, mode, model, role, hostname: providedHostname, agent_type } = parseArgs(args, startWorkSessionSchema);
+	const { project_id, git_url, mode, model, role, hostname: providedHostname, agent_type, agent_name } = parseArgs(args, startWorkSessionSchema);
 
 	// Use auto-detected hostname if not provided - enables machine-aware worktree filtering
 	const hostname = providedHostname || MACHINE_HOSTNAME;
@@ -100,6 +101,7 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		role: role as SessionRole,
 		hostname, // Machine hostname for worktree tracking
 		agent_type: agent_type as AgentType | undefined, // Agent type for onboarding
+		agent_name: agent_name as string | undefined, // Explicit name for cloud/remote agents
 	});
 
 	if (!response.ok) {

package/src/handlers/tasks.ts

@@ -35,6 +35,7 @@ import {
 	ValidationError,
 } from '../validators.js';
 import { getApiClient } from '../api-client.js';
+import { capPagination, PAGINATION_LIMITS } from '../utils.js';
 
 // Auto-detect machine hostname for worktree tracking
 const MACHINE_HOSTNAME = os.hostname();
@@ -889,9 +890,8 @@ export const searchTasks: Handler = async (args, ctx) => {
 		};
 	}
 
-	// Cap limit at 20, safe offset
-	const cappedLimit = Math.min(limit ?? 10, 20);
-	const safeOffset = Math.max(0, offset ?? 0);
+	// Cap pagination to safe values
+	const { cappedLimit, safeOffset } = capPagination(limit ?? 10, offset, PAGINATION_LIMITS.TASK_LIMIT);
 
 	const api = getApiClient();
 	const response = await api.searchTasks(project_id, {
@@ -925,9 +925,8 @@ export const searchTasks: Handler = async (args, ctx) => {
 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);
+	// Cap pagination to safe values
+	const { cappedLimit, safeOffset } = capPagination(limit ?? 10, offset, PAGINATION_LIMITS.TASK_LIMIT);
 
 	const api = getApiClient();
 	const response = await api.getTasksByPriority(project_id, {
@@ -962,9 +961,8 @@ export const getTasksByPriority: Handler = async (args, ctx) => {
 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);
+	// Cap pagination to safe values
+	const { cappedLimit, safeOffset } = capPagination(limit ?? 10, offset, PAGINATION_LIMITS.TASK_LIMIT);
 
 	const api = getApiClient();
 	const response = await api.getRecentTasks(project_id, {
@@ -1043,11 +1041,11 @@ export const getStaleWorktrees: Handler = async (args, ctx) => {
 	// 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);
+	// Cap pagination to safe values
+	const { cappedLimit, safeOffset } = capPagination(limit, offset, PAGINATION_LIMITS.DEFAULT_MAX_LIMIT);
 
 	const api = getApiClient();
-	const response = await api.getStaleWorktrees(project_id, { hostname, limit: cappedLimit, offset });
+	const response = await api.getStaleWorktrees(project_id, { hostname, limit: cappedLimit, offset: safeOffset });
 
 	if (!response.ok) {
 		return { result: { error: response.error || 'Failed to get stale worktrees' }, isError: true };

package/src/handlers/tool-categories.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { tools } from '../tools.js';
+import { tools } from '../tools/index.js';
 import { TOOL_CATEGORIES } from './discovery.js';
 
 describe('Documentation Generator Prerequisites', () => {

package/src/handlers/types.ts

@@ -45,6 +45,7 @@ export interface SessionState {
 	currentSessionId: string | null;
 	currentPersona: string | null;
 	currentRole: AgentRole | null;
+	currentProjectId: string | null;
 	tokenUsage: TokenUsage;
 }
 
@@ -64,7 +65,7 @@ export interface HandlerContext {
 	auth: AuthContext;
 	session: SessionState;
 	/** Update session state (for handlers that modify session) */
-	updateSession: (updates: Partial<Pick<SessionState, 'currentSessionId' | 'currentPersona' | 'currentRole' | 'tokenUsage'>>) => void;
+	updateSession: (updates: Partial<Pick<SessionState, 'currentSessionId' | 'currentPersona' | 'currentRole' | 'currentProjectId' | 'tokenUsage'>>) => void;
 	/** Get user updates since last sync (for session handlers) */
 	getUserUpdates?: (projectId: string) => Promise<UserUpdates | undefined>;
 	/** Select an available persona for the agent */

package/src/handlers/validation.ts

@@ -26,6 +26,7 @@ const validateTaskSchema = {
 	approved: { type: 'boolean' as const, required: true as const },
 	validation_notes: { type: 'string' as const },
 	skip_pr_check: { type: 'boolean' as const },
+	// Note: pr_checks_passing may arrive as string from some MCP clients, handled in validateTask
 	pr_checks_passing: { type: 'boolean' as const },
 };
 
@@ -100,12 +101,16 @@ export const validateTask: Handler = async (args, ctx) => {
 	const { session } = ctx;
 	const currentSessionId = session.currentSessionId;
 
+	// Ensure pr_checks_passing is a proper boolean (MCP may send as string)
+	// Cast to unknown first to satisfy TypeScript
+	const checksPassingBool = pr_checks_passing === true || (pr_checks_passing as unknown) === 'true';
+
 	const apiClient = getApiClient();
 	const response = await apiClient.validateTask(task_id, {
 		approved,
 		validation_notes,
 		skip_pr_check,
-		pr_checks_passing,
+		pr_checks_passing: pr_checks_passing !== undefined ? checksPassingBool : undefined,
 	}, currentSessionId || undefined);
 
 	if (!response.ok) {

package/src/index.test.ts

@@ -636,12 +636,12 @@ describe('MCP Server Entry Point', () => {
 	// =========================================================================
 	describe('Tools Registration', () => {
 		it('should export tools array', async () => {
-			const { tools } = await import('./tools.js');
+			const { tools } = await import('./tools/index.js');
 			expect(Array.isArray(tools)).toBe(true);
 		});
 
 		it('should have required tool properties', async () => {
-			const { tools } = await import('./tools.js');
+			const { tools } = await import('./tools/index.js');
 			tools.forEach((tool) => {
 				expect(tool).toHaveProperty('name');
 				expect(tool).toHaveProperty('description');

package/src/index.ts

@@ -33,9 +33,10 @@ import {
 	RateLimiter,
 	extractProjectNameFromGitUrl,
 	isValidStatusTransition,
+	getErrorMessage,
 } from './utils.js';
 import { buildHandlerRegistry, type HandlerContext } from './handlers/index.js';
-import { tools } from './tools.js';
+import { tools } from './tools/index.js';
 import {
 	createTokenUsage,
 	trackTokenUsage as trackTokens,
@@ -59,6 +60,9 @@ let currentPersona: string | null = null;
 // Current role for this agent instance
 let currentRole: 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer' | null = null;
 
+// Current project ID for this agent instance
+let currentProjectId: string | null = null;
+
 // Token usage tracking for this session (using token-tracking module)
 let sessionTokenUsage: TokenUsage = createTokenUsage();
 
@@ -619,12 +623,14 @@ async function handleTool(
 				currentSessionId,
 				currentPersona,
 				currentRole,
+				currentProjectId,
 				tokenUsage: sessionTokenUsage,
 			},
 			updateSession: (updates) => {
 				if (updates.currentSessionId !== undefined) currentSessionId = updates.currentSessionId;
 				if (updates.currentPersona !== undefined) currentPersona = updates.currentPersona;
 				if (updates.currentRole !== undefined) currentRole = updates.currentRole;
+				if (updates.currentProjectId !== undefined) currentProjectId = updates.currentProjectId;
 				if (updates.tokenUsage !== undefined) sessionTokenUsage = updates.tokenUsage;
 			},
 		};
@@ -754,7 +760,7 @@ async function main() {
 			}
 
 			// Handle database errors with better context
-			const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+			const errorMessage = getErrorMessage(error);
 			let hint: string | undefined;
 
 			if (errorMessage.includes('violates foreign key constraint')) {

package/src/token-tracking.ts

@@ -5,6 +5,8 @@
  * Extracted from index.ts to enable unit testing.
  */
 
+import { getErrorMessage } from './utils.js';
+
 // ============================================================================
 // Types
 // ============================================================================
@@ -39,8 +41,7 @@ export function estimateTokens(obj: unknown): number {
 		return Math.max(1, Math.ceil(json.length / 4));
 	} catch (error) {
 		// Log warning when serialization fails (e.g., circular references, BigInt)
-		const errorMessage = error instanceof Error ? error.message : String(error);
-		console.warn(`[Vibescope] Token estimation failed: ${errorMessage}. Returning minimal estimate of 1 token.`);
+		console.warn(`[Vibescope] Token estimation failed: ${getErrorMessage(error)}. Returning minimal estimate of 1 token.`);
 		return 1;
 	}
 }

package/src/tools/blockers.ts

@@ -0,0 +1,122 @@
+/**
+ * Blocker Tool Definitions
+ *
+ * Tools for managing blockers:
+ * - add_blocker
+ * - resolve_blocker
+ * - get_blocker
+ * - get_blockers
+ * - get_blockers_stats
+ * - delete_blocker
+ */
+
+import type { Tool } from './types.js';
+
+export const blockerTools: Tool[] = [
+	{
+		name: 'add_blocker',
+		description: `Record a blocker preventing progress.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				description: {
+					type: 'string',
+					description: 'What is blocking progress?',
+				},
+			},
+			required: ['project_id', 'description'],
+		},
+	},
+	{
+		name: 'resolve_blocker',
+		description: `Mark a blocker as resolved.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				blocker_id: {
+					type: 'string',
+					description: 'Blocker UUID',
+				},
+				resolution_note: {
+					type: 'string',
+					description: 'How was it resolved?',
+				},
+			},
+			required: ['blocker_id'],
+		},
+	},
+	{
+		name: 'get_blocker',
+		description: `Get a single blocker by ID. More token-efficient than get_blockers when you need details for a specific blocker.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				blocker_id: {
+					type: 'string',
+					description: 'Blocker UUID',
+				},
+			},
+			required: ['blocker_id'],
+		},
+	},
+	{
+		name: 'get_blockers',
+		description: `Get blockers for a project, optionally filtered by status.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				status: {
+					type: 'string',
+					enum: ['open', 'resolved'],
+					description: 'Filter by status (default: open)',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max number of blockers to return (default 10, max 200)',
+				},
+				offset: {
+					type: 'number',
+					description: 'Number of blockers to skip for pagination (default 0)',
+				},
+				search_query: {
+					type: 'string',
+					description: 'Search blockers by description',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'get_blockers_stats',
+		description: `Get aggregate statistics about blockers for a project. Returns total count and breakdown by status. Much more token-efficient than get_blockers when you just need to understand the overall state.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: { type: 'string', description: 'Project UUID' },
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'delete_blocker',
+		description: `Delete a blocker.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				blocker_id: {
+					type: 'string',
+					description: 'Blocker UUID',
+				},
+			},
+			required: ['blocker_id'],
+		},
+	},
+];

package/src/tools/bodies-of-work.ts

@@ -0,0 +1,283 @@
+/**
+ * Bodies of Work Tool Definitions
+ *
+ * Tools for managing grouped task collections:
+ * - create_body_of_work
+ * - update_body_of_work
+ * - get_body_of_work
+ * - get_bodies_of_work
+ * - delete_body_of_work
+ * - add_task_to_body_of_work
+ * - remove_task_from_body_of_work
+ * - activate_body_of_work
+ * - add_task_dependency
+ * - remove_task_dependency
+ * - get_task_dependencies
+ * - get_next_body_of_work_task
+ */
+
+import type { Tool } from './types.js';
+
+export const bodiesOfWorkTools: Tool[] = [
+	{
+		name: 'create_body_of_work',
+		description: `Create a new body of work to group tasks into phases (pre/core/post).
+Bodies of work allow organizing related tasks with optional auto-deployment on completion.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				title: {
+					type: 'string',
+					description: 'Title for the body of work',
+				},
+				description: {
+					type: 'string',
+					description: 'Optional description',
+				},
+				auto_deploy_on_completion: {
+					type: 'boolean',
+					description: 'Automatically request deployment when all tasks complete (default: false)',
+				},
+				deploy_environment: {
+					type: 'string',
+					enum: ['development', 'staging', 'production'],
+					description: 'Target environment for auto-deploy (default: production)',
+				},
+				deploy_version_bump: {
+					type: 'string',
+					enum: ['patch', 'minor', 'major'],
+					description: 'Version bump for auto-deploy (default: minor)',
+				},
+				deploy_trigger: {
+					type: 'string',
+					enum: ['all_completed', 'all_completed_validated'],
+					description: 'When to trigger auto-deploy: all_completed (immediate) or all_completed_validated (requires validation, default)',
+				},
+			},
+			required: ['project_id', 'title'],
+		},
+	},
+	{
+		name: 'update_body_of_work',
+		description: `Update a body of work's settings.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+				title: {
+					type: 'string',
+					description: 'Updated title',
+				},
+				description: {
+					type: 'string',
+					description: 'Updated description',
+				},
+				auto_deploy_on_completion: {
+					type: 'boolean',
+					description: 'Auto-deploy setting',
+				},
+				deploy_environment: {
+					type: 'string',
+					enum: ['development', 'staging', 'production'],
+					description: 'Target environment',
+				},
+				deploy_version_bump: {
+					type: 'string',
+					enum: ['patch', 'minor', 'major'],
+					description: 'Version bump type',
+				},
+				deploy_trigger: {
+					type: 'string',
+					enum: ['all_completed', 'all_completed_validated'],
+					description: 'When to trigger auto-deploy',
+				},
+			},
+			required: ['body_of_work_id'],
+		},
+	},
+	{
+		name: 'get_body_of_work',
+		description: `Get a body of work with all its tasks organized by phase.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+			},
+			required: ['body_of_work_id'],
+		},
+	},
+	{
+		name: 'get_bodies_of_work',
+		description: `List bodies of work for a project with task counts per phase.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				status: {
+					type: 'string',
+					enum: ['draft', 'active', 'completed', 'cancelled'],
+					description: 'Filter by status (optional)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'delete_body_of_work',
+		description: `Delete a body of work. Tasks are preserved but no longer grouped.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+			},
+			required: ['body_of_work_id'],
+		},
+	},
+	{
+		name: 'add_task_to_body_of_work',
+		description: `Add a task to a body of work in a specific phase.
+Phases control execution order: pre tasks run first, then core, then post.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+				task_id: {
+					type: 'string',
+					description: 'Task UUID to add',
+				},
+				phase: {
+					type: 'string',
+					enum: ['pre', 'core', 'post'],
+					description: 'Task phase (default: core)',
+				},
+				order_index: {
+					type: 'number',
+					description: 'Order within phase (auto-assigned if not specified)',
+				},
+			},
+			required: ['body_of_work_id', 'task_id'],
+		},
+	},
+	{
+		name: 'remove_task_from_body_of_work',
+		description: `Remove a task from its body of work. The task is preserved.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID to remove',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	{
+		name: 'activate_body_of_work',
+		description: `Activate a draft body of work to start execution.
+Requires at least one task. Once active, tasks can be worked on following phase order.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+			},
+			required: ['body_of_work_id'],
+		},
+	},
+	{
+		name: 'add_task_dependency',
+		description: `Add a dependency between tasks in a body of work.
+The dependent task cannot start until the dependency is completed. Prevents circular dependencies.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+				task_id: {
+					type: 'string',
+					description: 'Task that depends on another task',
+				},
+				depends_on_task_id: {
+					type: 'string',
+					description: 'Task that must complete first',
+				},
+			},
+			required: ['body_of_work_id', 'task_id', 'depends_on_task_id'],
+		},
+	},
+	{
+		name: 'remove_task_dependency',
+		description: `Remove a dependency between tasks.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+				depends_on_task_id: {
+					type: 'string',
+					description: 'Dependency task UUID',
+				},
+			},
+			required: ['task_id', 'depends_on_task_id'],
+		},
+	},
+	{
+		name: 'get_task_dependencies',
+		description: `Get task dependencies for a body of work or specific task.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID (optional if task_id provided)',
+				},
+				task_id: {
+					type: 'string',
+					description: 'Specific task UUID (optional if body_of_work_id provided)',
+				},
+			},
+		},
+	},
+	{
+		name: 'get_next_body_of_work_task',
+		description: `Get the next available task from a body of work.
+Considers phase order (pre → core → post) and task dependencies.
+Only returns tasks where all dependencies are completed.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+			},
+			required: ['body_of_work_id'],
+		},
+	},
+];

package/src/tools/cloud-agents.ts

@@ -0,0 +1,70 @@
+/**
+ * Cloud Agent Tool Definitions
+ *
+ * Tools for managing cloud-spawned agents:
+ * - cleanup_stale_cloud_agents
+ * - list_cloud_agents
+ */
+
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const cloudAgentTools: Tool[] = [
+	{
+		name: 'cleanup_stale_cloud_agents',
+		description: `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.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID (required)'
+				},
+				stale_minutes: {
+					type: 'number',
+					description: 'Consider agents stale after this many minutes (default: 5)'
+				},
+				include_running: {
+					type: 'boolean',
+					description: 'Also clean up "running" agents with no recent heartbeat (default: false)'
+				},
+				dry_run: {
+					type: 'boolean',
+					description: 'If true, just report what would be cleaned without actually cleaning (default: false)'
+				}
+			},
+			required: ['project_id']
+		}
+	},
+	{
+		name: 'list_cloud_agents',
+		description: `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.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID (required)'
+				},
+				status: {
+					type: 'string',
+					enum: ['starting', 'running', 'stopped', 'failed', 'all'],
+					description: 'Filter by status (default: all)'
+				}
+			},
+			required: ['project_id']
+		}
+	}
+];