@vibescope/mcp-server 0.1.0 → 0.2.0

package/src/handlers/fallback.test.ts

@@ -145,6 +145,84 @@ describe('startFallbackActivity', () => {
 			}, ctx)
 		).rejects.toThrow('Failed to start fallback activity');
 	});
+
+	it('should pass through worktree guidance when API returns it', async () => {
+		mockApiClient.startFallbackActivity.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				activity: 'code_review',
+				message: 'Started code_review',
+				git_workflow: {
+					workflow: 'git-flow',
+					base_branch: 'develop',
+					worktree_recommended: true,
+					note: 'Fallback activities use the base branch directly (read-only).',
+				},
+				worktree_setup: {
+					message: 'RECOMMENDED: Create a worktree to avoid conflicts.',
+					commands: [
+						'git checkout develop',
+						'git pull origin develop',
+						'git worktree add ../Project-code-review develop',
+						'cd ../Project-code-review',
+					],
+					worktree_path: '../Project-code-review',
+					branch_name: 'develop',
+					cleanup_command: 'git worktree remove ../Project-code-review',
+					report_worktree: 'heartbeat(current_worktree_path: "../Project-code-review")',
+				},
+				next_step: 'After setting up worktree: call heartbeat to report your location.',
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await startFallbackActivity(
+			{
+				project_id: '123e4567-e89b-12d3-a456-426614174000',
+				activity: 'code_review',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			activity: 'code_review',
+		});
+		expect((result.result as { git_workflow?: unknown }).git_workflow).toBeDefined();
+		expect((result.result as { git_workflow: { workflow: string } }).git_workflow.workflow).toBe('git-flow');
+		expect((result.result as { worktree_setup?: unknown }).worktree_setup).toBeDefined();
+		expect((result.result as { worktree_setup: { worktree_path: string } }).worktree_setup.worktree_path).toBe('../Project-code-review');
+		expect((result.result as { next_step?: string }).next_step).toContain('heartbeat');
+	});
+
+	it('should not include worktree guidance when API does not return it', async () => {
+		mockApiClient.startFallbackActivity.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				activity: 'code_review',
+				message: 'Started code_review',
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await startFallbackActivity(
+			{
+				project_id: '123e4567-e89b-12d3-a456-426614174000',
+				activity: 'code_review',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			activity: 'code_review',
+		});
+		expect((result.result as { git_workflow?: unknown }).git_workflow).toBeUndefined();
+		expect((result.result as { worktree_setup?: unknown }).worktree_setup).toBeUndefined();
+		expect((result.result as { next_step?: string }).next_step).toBeUndefined();
+	});
 });
 
 // ============================================================================

package/src/handlers/fallback.ts

@@ -51,16 +51,27 @@ export const startFallbackActivity: Handler = async (args, ctx) => {
 	// Get the activity details for the response
 	const activityInfo = FALLBACK_ACTIVITIES.find((a) => a.activity === activity);
 
-	return {
-		result: {
-			success: true,
-			activity,
-			title: activityInfo?.title || activity,
-			description: activityInfo?.description || '',
-			prompt: activityInfo?.prompt || '',
-			message: response.data?.message || `Started fallback activity: ${activityInfo?.title || activity}`,
-		},
+	const result: Record<string, unknown> = {
+		success: true,
+		activity,
+		title: activityInfo?.title || activity,
+		description: activityInfo?.description || '',
+		prompt: activityInfo?.prompt || '',
+		message: response.data?.message || `Started fallback activity: ${activityInfo?.title || activity}`,
 	};
+
+	// Pass through worktree guidance if provided
+	if (response.data?.git_workflow) {
+		result.git_workflow = response.data.git_workflow;
+	}
+	if (response.data?.worktree_setup) {
+		result.worktree_setup = response.data.worktree_setup;
+	}
+	if (response.data?.next_step) {
+		result.next_step = response.data.next_step;
+	}
+
+	return { result };
 };
 
 export const stopFallbackActivity: Handler = async (args, ctx) => {

package/src/handlers/findings.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import {
 	addFinding,
 	getFindings,
+	getFindingsStats,
 	updateFinding,
 	deleteFinding,
 } from './findings.js';
@@ -171,12 +172,74 @@ describe('getFindings', () => {
 
 		expect(mockApiClient.getFindings).toHaveBeenCalledWith(
 			VALID_UUID,
-			{
+			expect.objectContaining({
 				category: 'security',
 				severity: 'critical',
 				status: 'open',
 				limit: 10,
-			}
+			})
+		);
+	});
+
+	it('should pass summary_only parameter to API client', async () => {
+		mockApiClient.getFindings.mockResolvedValue({
+			ok: true,
+			data: { findings: [], total_count: 0, has_more: false },
+		});
+		const ctx = createMockContext();
+
+		await getFindings({
+			project_id: VALID_UUID,
+			summary_only: true
+		}, ctx);
+
+		expect(mockApiClient.getFindings).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({
+				summary_only: true,
+			})
+		);
+	});
+
+	it('should pass search_query parameter to API client', async () => {
+		mockApiClient.getFindings.mockResolvedValue({
+			ok: true,
+			data: { findings: [], total_count: 0, has_more: false },
+		});
+		const ctx = createMockContext();
+
+		await getFindings({
+			project_id: VALID_UUID,
+			search_query: 'security'
+		}, ctx);
+
+		expect(mockApiClient.getFindings).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({
+				search_query: 'security',
+			})
+		);
+	});
+
+	it('should pass offset parameter to API client', async () => {
+		mockApiClient.getFindings.mockResolvedValue({
+			ok: true,
+			data: { findings: [], total_count: 100, has_more: true },
+		});
+		const ctx = createMockContext();
+
+		await getFindings({
+			project_id: VALID_UUID,
+			offset: 50,
+			limit: 25
+		}, ctx);
+
+		expect(mockApiClient.getFindings).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({
+				offset: 50,
+				limit: 25,
+			})
 		);
 	});
 
@@ -345,3 +408,67 @@ describe('deleteFinding', () => {
 		).rejects.toThrow('Delete failed');
 	});
 });
+
+// ============================================================================
+// getFindingsStats Tests
+// ============================================================================
+
+describe('getFindingsStats', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(getFindingsStats({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid project_id UUID', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			getFindingsStats({ project_id: 'invalid' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should return findings stats for project', async () => {
+		const mockStats = {
+			total: 10,
+			by_status: { open: 5, addressed: 3, dismissed: 2 },
+			by_severity: { critical: 1, high: 3, medium: 4, low: 2 },
+			by_category: { security: 3, performance: 4, code_quality: 3 },
+		};
+		mockApiClient.getFindingsStats.mockResolvedValue({
+			ok: true,
+			data: mockStats,
+		});
+		const ctx = createMockContext();
+
+		const result = await getFindingsStats({ project_id: VALID_UUID }, ctx);
+
+		expect(result.result).toMatchObject(mockStats);
+	});
+
+	it('should call API client getFindingsStats with project_id', async () => {
+		mockApiClient.getFindingsStats.mockResolvedValue({
+			ok: true,
+			data: { total: 0, by_status: {}, by_severity: {}, by_category: {} },
+		});
+		const ctx = createMockContext();
+
+		await getFindingsStats({ project_id: VALID_UUID }, ctx);
+
+		expect(mockApiClient.getFindingsStats).toHaveBeenCalledWith(VALID_UUID);
+	});
+
+	it('should throw error when API call fails', async () => {
+		mockApiClient.getFindingsStats.mockResolvedValue({
+			ok: false,
+			error: 'Query failed',
+		});
+		const ctx = createMockContext();
+
+		await expect(
+			getFindingsStats({ project_id: VALID_UUID }, ctx)
+		).rejects.toThrow('Query failed');
+	});
+});

package/src/handlers/findings.ts

@@ -3,7 +3,8 @@
  *
  * Handles audit findings and knowledge base:
  * - add_finding
- * - get_findings
+ * - get_findings (supports summary_only for reduced tokens)
+ * - get_findings_stats (aggregate counts for minimal tokens)
  * - update_finding
  * - delete_finding
  */
@@ -52,7 +53,7 @@ export const addFinding: Handler = async (args, ctx) => {
 };
 
 export const getFindings: Handler = async (args, ctx) => {
-	const { project_id, category, severity, status, limit = 50, offset = 0, search_query } = args as {
+	const { project_id, category, severity, status, limit = 50, offset = 0, search_query, summary_only = false } = args as {
 		project_id: string;
 		category?: FindingCategory;
 		severity?: FindingSeverity;
@@ -60,6 +61,7 @@ export const getFindings: Handler = async (args, ctx) => {
 		limit?: number;
 		offset?: number;
 		search_query?: string;
+		summary_only?: boolean;
 	};
 
 	validateRequired(project_id, 'project_id');
@@ -70,7 +72,10 @@ export const getFindings: Handler = async (args, ctx) => {
 		category,
 		severity,
 		status,
-		limit
+		limit,
+		offset,
+		search_query,
+		summary_only
 	});
 
 	if (!response.ok) {
@@ -80,6 +85,29 @@ export const getFindings: Handler = async (args, ctx) => {
 	return { result: response.data };
 };
 
+/**
+ * Get aggregate statistics about findings for a project.
+ * Returns counts by category, severity, and status without the actual finding data.
+ * This is much more token-efficient than get_findings for understanding the overall state.
+ */
+export const getFindingsStats: Handler = async (args, ctx) => {
+	const { project_id } = args as {
+		project_id: string;
+	};
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getFindingsStats(project_id);
+
+	if (!response.ok) {
+		throw new Error(response.error || 'Failed to get findings stats');
+	}
+
+	return { result: response.data };
+};
+
 export const updateFinding: Handler = async (args, ctx) => {
 	const { finding_id, status, resolution_note, title, description, severity } = args as {
 		finding_id: string;
@@ -131,6 +159,7 @@ export const deleteFinding: Handler = async (args, ctx) => {
 export const findingHandlers: HandlerRegistry = {
 	add_finding: addFinding,
 	get_findings: getFindings,
+	get_findings_stats: getFindingsStats,
 	update_finding: updateFinding,
 	delete_finding: deleteFinding,
 };

package/src/handlers/session.test.ts

@@ -31,7 +31,7 @@ describe('heartbeat', () => {
 			session_id: 'session-123',
 		});
 		expect(result.result).toHaveProperty('timestamp');
-		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('session-123');
+		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('session-123', { current_worktree_path: undefined });
 	});
 
 	it('should use provided session_id over current session', async () => {
@@ -48,7 +48,20 @@ describe('heartbeat', () => {
 			success: true,
 			session_id: 'other-session-456',
 		});
-		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('other-session-456');
+		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('other-session-456', { current_worktree_path: undefined });
+	});
+
+	it('should pass worktree_path to API', async () => {
+		const ctx = createMockContext();
+		mockApiClient.heartbeat.mockResolvedValue({
+			ok: true,
+			data: { timestamp: '2026-01-14T10:00:00Z' },
+		});
+		mockApiClient.syncSession.mockResolvedValue({ ok: true });
+
+		await heartbeat({ current_worktree_path: '../project-task-abc123' }, ctx);
+
+		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('session-123', { current_worktree_path: '../project-task-abc123' });
 	});
 
 	it('should return error when no active session', async () => {
@@ -101,6 +114,10 @@ describe('getHelp', () => {
 
 	it('should return help content for valid topic', async () => {
 		const ctx = createMockContext();
+		mockApiClient.getHelpTopic.mockResolvedValue({
+			ok: true,
+			data: { slug: 'tasks', title: 'Task Workflow', content: '# Task Workflow\nTest content' },
+		});
 
 		const result = await getHelp({ topic: 'tasks' }, ctx);
 
@@ -110,6 +127,10 @@ describe('getHelp', () => {
 
 	it('should return getting_started help', async () => {
 		const ctx = createMockContext();
+		mockApiClient.getHelpTopic.mockResolvedValue({
+			ok: true,
+			data: { slug: 'getting_started', title: 'Getting Started', content: '# Getting Started\nTest content' },
+		});
 
 		const result = await getHelp({ topic: 'getting_started' }, ctx);
 
@@ -119,6 +140,11 @@ describe('getHelp', () => {
 
 	it('should return error for unknown topic', async () => {
 		const ctx = createMockContext();
+		mockApiClient.getHelpTopic.mockResolvedValue({ ok: true, data: null });
+		mockApiClient.getHelpTopics.mockResolvedValue({
+			ok: true,
+			data: [{ slug: 'tasks', title: 'Tasks' }, { slug: 'getting_started', title: 'Getting Started' }],
+		});
 
 		const result = await getHelp({ topic: 'unknown_topic' }, ctx);
 
@@ -130,6 +156,15 @@ describe('getHelp', () => {
 
 	it('should list available topics for unknown topic', async () => {
 		const ctx = createMockContext();
+		mockApiClient.getHelpTopic.mockResolvedValue({ ok: true, data: null });
+		mockApiClient.getHelpTopics.mockResolvedValue({
+			ok: true,
+			data: [
+				{ slug: 'tasks', title: 'Tasks' },
+				{ slug: 'getting_started', title: 'Getting Started' },
+				{ slug: 'validation', title: 'Validation' },
+			],
+		});
 
 		const result = await getHelp({ topic: 'nonexistent' }, ctx);
 

package/src/handlers/session.ts

@@ -10,7 +10,6 @@
  */
 
 import type { Handler, HandlerRegistry, TokenUsage } from './types.js';
-import { KNOWLEDGE_BASE } from '../knowledge.js';
 import { getApiClient } from '../api-client.js';
 
 export const startWorkSession: Handler = async (args, ctx) => {
@@ -140,7 +139,10 @@ export const startWorkSession: Handler = async (args, ctx) => {
 };
 
 export const heartbeat: Handler = async (args, ctx) => {
-	const { session_id } = args as { session_id?: string };
+	const { session_id, current_worktree_path } = args as {
+		session_id?: string;
+		current_worktree_path?: string | null;
+	};
 	const { session } = ctx;
 	const targetSession = session_id || session.currentSessionId;
 
@@ -154,8 +156,10 @@ export const heartbeat: Handler = async (args, ctx) => {
 
 	const apiClient = getApiClient();
 
-	// Send heartbeat
-	const heartbeatResponse = await apiClient.heartbeat(targetSession);
+	// Send heartbeat with optional worktree path
+	const heartbeatResponse = await apiClient.heartbeat(targetSession, {
+		current_worktree_path,
+	});
 
 	if (!heartbeatResponse.ok) {
 		return {
@@ -249,17 +253,34 @@ export const endWorkSession: Handler = async (args, ctx) => {
 export const getHelp: Handler = async (args, _ctx) => {
 	const { topic } = args as { topic: string };
 
-	const content = KNOWLEDGE_BASE[topic];
-	if (!content) {
+	const apiClient = getApiClient();
+	const response = await apiClient.getHelpTopic(topic);
+
+	if (!response.ok) {
+		// If database fetch fails, return error
+		return {
+			result: {
+				error: response.error || `Failed to fetch help topic: ${topic}`,
+			},
+		};
+	}
+
+	if (!response.data) {
+		// Topic not found - fetch available topics
+		const topicsResponse = await apiClient.getHelpTopics();
+		const available = topicsResponse.ok && topicsResponse.data
+			? topicsResponse.data.map(t => t.slug)
+			: ['getting_started', 'tasks', 'validation', 'deployment', 'git', 'blockers', 'milestones', 'fallback', 'session', 'tokens', 'sprints', 'topics'];
+
 		return {
 			result: {
 				error: `Unknown topic: ${topic}`,
-				available: Object.keys(KNOWLEDGE_BASE),
+				available,
 			},
 		};
 	}
 
-	return { result: { topic, content } };
+	return { result: { topic, content: response.data.content } };
 };
 
 // Model pricing rates (USD per 1M tokens)

package/src/handlers/sprints.ts

@@ -182,13 +182,14 @@ export const updateSprint: Handler = async (args, ctx) => {
 };
 
 export const getSprint: Handler = async (args, ctx) => {
-	const { sprint_id } = args as { sprint_id: string };
+	const { sprint_id, summary_only = false } = args as { sprint_id: string; summary_only?: boolean };
 
 	validateRequired(sprint_id, 'sprint_id');
 	validateUUID(sprint_id, 'sprint_id');
 
 	const apiClient = getApiClient();
 
+	// Response type varies based on summary_only
 	const response = await apiClient.proxy<{
 		id: string;
 		title: string;
@@ -200,11 +201,23 @@ export const getSprint: Handler = async (args, ctx) => {
 		progress_percentage: number;
 		velocity_points: number;
 		committed_points: number;
-		pre_tasks: unknown[];
-		core_tasks: unknown[];
-		post_tasks: unknown[];
-		total_tasks: number;
-	}>('get_sprint', { sprint_id });
+		// Full response includes task arrays
+		pre_tasks?: unknown[];
+		core_tasks?: unknown[];
+		post_tasks?: unknown[];
+		total_tasks?: number;
+		// Summary response includes counts and next task
+		task_counts?: {
+			pre: { total: number; completed: number };
+			core: { total: number; completed: number };
+			post: { total: number; completed: number };
+			total: number;
+			completed: number;
+			in_progress: number;
+		};
+		current_task?: { id: string; title: string } | null;
+		next_task?: { id: string; title: string; priority: number } | null;
+	}>('get_sprint', { sprint_id, summary_only });
 
 	if (!response.ok) {
 		throw new Error(`Failed to get sprint: ${response.error}`);

package/src/handlers/tasks.test.ts

@@ -352,6 +352,67 @@ describe('updateTask', () => {
 			error: 'task_claimed',
 		});
 	});
+
+	it('should warn when setting in_progress without git_branch', async () => {
+		mockApiClient.updateTask.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			warning: expect.stringContaining('git_branch not set'),
+			hint: expect.stringContaining('update_task again'),
+		});
+	});
+
+	it('should not warn when setting in_progress with git_branch', async () => {
+		mockApiClient.updateTask.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+				git_branch: 'feature/my-task',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+		expect(result.result).not.toHaveProperty('warning');
+	});
+
+	it('should not warn when updating status other than in_progress', async () => {
+		mockApiClient.updateTask.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'completed',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+		expect(result.result).not.toHaveProperty('warning');
+	});
 });
 
 // ============================================================================

package/src/handlers/tasks.ts

@@ -313,7 +313,27 @@ export const updateTask: Handler = async (args, ctx) => {
 		throw new Error(`Failed to update task: ${response.error}`);
 	}
 
-	return { result: { success: true, task_id } };
+	// Build result - include git workflow info when transitioning to in_progress
+	const data = response.data;
+	const result: Record<string, unknown> = { success: true, task_id };
+
+	if (data?.git_workflow) {
+		result.git_workflow = data.git_workflow;
+	}
+	if (data?.worktree_setup) {
+		result.worktree_setup = data.worktree_setup;
+	}
+	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: Handler = async (args, ctx) => {
@@ -353,6 +373,11 @@ export const completeTask: Handler = async (args, ctx) => {
 		result.context = data.context;
 	}
 
+	// Pass through warnings (e.g., missing git_branch)
+	if (data.warnings) {
+		result.warnings = data.warnings;
+	}
+
 	// Git workflow instructions are already in API response but we need to fetch
 	// task details if we want to include them (API should return these)
 	result.next_action = data.next_action;