@vibescope/mcp-server 0.1.0 → 0.2.1

package/src/handlers/file-checkouts.ts

@@ -0,0 +1,127 @@
+/**
+ * File Checkouts Handlers
+ *
+ * Handles file checkout/checkin for multi-agent coordination:
+ * - checkout_file: Check out a file before editing
+ * - checkin_file: Check in a file after editing
+ * - get_file_checkouts: Get active checkouts for a project
+ * - abandon_checkout: Force release a checkout
+ */
+
+import type { Handler, HandlerRegistry } from './types.js';
+import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
+import { getApiClient } from '../api-client.js';
+
+const VALID_CHECKOUT_STATUSES = ['checked_out', 'checked_in', 'abandoned'] as const;
+
+// Argument schemas for type-safe parsing
+const checkoutFileSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	file_path: { type: 'string' as const, required: true as const },
+	reason: { type: 'string' as const },
+};
+
+const checkinFileSchema = {
+	checkout_id: { type: 'string' as const, validate: uuidValidator },
+	project_id: { type: 'string' as const, validate: uuidValidator },
+	file_path: { type: 'string' as const },
+	summary: { type: 'string' as const },
+};
+
+const getFileCheckoutsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	status: { type: 'string' as const, validate: createEnumValidator(VALID_CHECKOUT_STATUSES) },
+	file_path: { type: 'string' as const },
+	limit: { type: 'number' as const, default: 50 },
+};
+
+const abandonCheckoutSchema = {
+	checkout_id: { type: 'string' as const, validate: uuidValidator },
+	project_id: { type: 'string' as const, validate: uuidValidator },
+	file_path: { type: 'string' as const },
+};
+
+export const checkoutFile: Handler = async (args, ctx) => {
+	const { project_id, file_path, reason } = parseArgs(args, checkoutFileSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.checkoutFile(project_id, file_path, reason, ctx.session.currentSessionId || undefined);
+
+	if (!response.ok) {
+		throw new Error(response.error || 'Failed to checkout file');
+	}
+
+	return { result: response.data };
+};
+
+export const checkinFile: Handler = async (args, ctx) => {
+	const { checkout_id, project_id, file_path, summary } = parseArgs(args, checkinFileSchema);
+
+	// Validate that either checkout_id or both project_id and file_path are provided
+	if (!checkout_id && (!project_id || !file_path)) {
+		throw new Error('Either checkout_id or both project_id and file_path are required');
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.checkinFile({
+		checkout_id,
+		project_id,
+		file_path,
+		summary
+	}, ctx.session.currentSessionId || undefined);
+
+	if (!response.ok) {
+		throw new Error(response.error || 'Failed to checkin file');
+	}
+
+	return { result: response.data };
+};
+
+export const getFileCheckouts: Handler = async (args, _ctx) => {
+	const { project_id, status, file_path, limit } = parseArgs(args, getFileCheckoutsSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getFileCheckouts(project_id, {
+		status,
+		file_path,
+		limit
+	});
+
+	if (!response.ok) {
+		throw new Error(response.error || 'Failed to get file checkouts');
+	}
+
+	return { result: response.data };
+};
+
+export const abandonCheckout: Handler = async (args, _ctx) => {
+	const { checkout_id, project_id, file_path } = parseArgs(args, abandonCheckoutSchema);
+
+	// Validate that either checkout_id or both project_id and file_path are provided
+	if (!checkout_id && (!project_id || !file_path)) {
+		throw new Error('Either checkout_id or both project_id and file_path are required');
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.abandonCheckout({
+		checkout_id,
+		project_id,
+		file_path
+	});
+
+	if (!response.ok) {
+		throw new Error(response.error || 'Failed to abandon checkout');
+	}
+
+	return { result: response.data };
+};
+
+/**
+ * File Checkouts handlers registry
+ */
+export const fileCheckoutHandlers: HandlerRegistry = {
+	checkout_file: checkoutFile,
+	checkin_file: checkinFile,
+	get_file_checkouts: getFileCheckouts,
+	abandon_checkout: abandonCheckout,
+};

package/src/handlers/findings.test.ts

@@ -2,8 +2,10 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import {
 	addFinding,
 	getFindings,
+	getFindingsStats,
 	updateFinding,
 	deleteFinding,
+	queryKnowledgeBase,
 } from './findings.js';
 import { ValidationError } from '../validators.js';
 import { createMockContext } from './__test-utils__.js';
@@ -171,12 +173,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 +409,211 @@ 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');
+	});
+});
+
+// ============================================================================
+// queryKnowledgeBase Tests
+// ============================================================================
+
+describe('queryKnowledgeBase', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(queryKnowledgeBase({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid project_id UUID', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			queryKnowledgeBase({ project_id: 'invalid' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should query with default parameters', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: true,
+			data: {
+				findings: [],
+				decisions: [],
+				completed_tasks: [],
+				resolved_blockers: [],
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await queryKnowledgeBase({ project_id: VALID_UUID }, ctx);
+
+		expect(result.result).toMatchObject({
+			findings: [],
+			decisions: [],
+		});
+		expect(mockApiClient.queryKnowledgeBase).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({
+				scope: 'summary',
+				limit: 5,
+			})
+		);
+	});
+
+	it('should pass scope parameter', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: true,
+			data: { findings: [] },
+		});
+		const ctx = createMockContext();
+
+		await queryKnowledgeBase({ project_id: VALID_UUID, scope: 'detailed' }, ctx);
+
+		expect(mockApiClient.queryKnowledgeBase).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({ scope: 'detailed' })
+		);
+	});
+
+	it('should pass categories filter', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: true,
+			data: { findings: [], decisions: [] },
+		});
+		const ctx = createMockContext();
+
+		await queryKnowledgeBase({
+			project_id: VALID_UUID,
+			categories: ['findings', 'decisions']
+		}, ctx);
+
+		expect(mockApiClient.queryKnowledgeBase).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({
+				categories: ['findings', 'decisions']
+			})
+		);
+	});
+
+	it('should cap limit at 20', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: true,
+			data: { findings: [] },
+		});
+		const ctx = createMockContext();
+
+		await queryKnowledgeBase({ project_id: VALID_UUID, limit: 100 }, ctx);
+
+		expect(mockApiClient.queryKnowledgeBase).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({ limit: 20 })
+		);
+	});
+
+	it('should enforce minimum limit of 1', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: true,
+			data: { findings: [] },
+		});
+		const ctx = createMockContext();
+
+		await queryKnowledgeBase({ project_id: VALID_UUID, limit: -5 }, ctx);
+
+		expect(mockApiClient.queryKnowledgeBase).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({ limit: 1 })
+		);
+	});
+
+	it('should pass search_query', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: true,
+			data: { findings: [] },
+		});
+		const ctx = createMockContext();
+
+		await queryKnowledgeBase({
+			project_id: VALID_UUID,
+			search_query: 'security'
+		}, ctx);
+
+		expect(mockApiClient.queryKnowledgeBase).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({ search_query: 'security' })
+		);
+	});
+
+	it('should throw error when API call fails', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: false,
+			error: 'Query failed',
+		});
+		const ctx = createMockContext();
+
+		await expect(
+			queryKnowledgeBase({ project_id: VALID_UUID }, ctx)
+		).rejects.toThrow('Query failed');
+	});
+});

package/src/handlers/findings.ts

@@ -3,42 +3,83 @@
  *
  * 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
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
-import { validateRequired, validateUUID } from '../validators.js';
+import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
-type FindingCategory = 'performance' | 'security' | 'code_quality' | 'accessibility' | 'documentation' | 'architecture' | 'testing' | 'other';
-type FindingSeverity = 'info' | 'low' | 'medium' | 'high' | 'critical';
-type FindingStatus = 'open' | 'addressed' | 'dismissed' | 'wontfix';
+const VALID_FINDING_CATEGORIES = ['performance', 'security', 'code_quality', 'accessibility', 'documentation', 'architecture', 'testing', 'other'] as const;
+const VALID_FINDING_SEVERITIES = ['info', 'low', 'medium', 'high', 'critical'] as const;
+const VALID_FINDING_STATUSES = ['open', 'addressed', 'dismissed', 'wontfix'] as const;
+
+type FindingCategory = typeof VALID_FINDING_CATEGORIES[number];
+type FindingSeverity = typeof VALID_FINDING_SEVERITIES[number];
+type FindingStatus = typeof VALID_FINDING_STATUSES[number];
+
+// Argument schemas for type-safe parsing
+const addFindingSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const, required: true as const },
+	description: { type: 'string' as const },
+	category: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_CATEGORIES) },
+	severity: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_SEVERITIES) },
+	file_path: { type: 'string' as const },
+	line_number: { type: 'number' as const },
+	related_task_id: { type: 'string' as const, validate: uuidValidator },
+};
+
+const getFindingsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	category: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_CATEGORIES) },
+	severity: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_SEVERITIES) },
+	status: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_STATUSES) },
+	limit: { type: 'number' as const, default: 50 },
+	offset: { type: 'number' as const, default: 0 },
+	search_query: { type: 'string' as const },
+	summary_only: { type: 'boolean' as const, default: false },
+};
+
+const getFindingsStatsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const updateFindingSchema = {
+	finding_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const },
+	description: { type: 'string' as const },
+	severity: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_SEVERITIES) },
+	status: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_STATUSES) },
+	resolution_note: { type: 'string' as const },
+};
+
+const deleteFindingSchema = {
+	finding_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const VALID_SCOPES = ['summary', 'detailed'] as const;
+
+const queryKnowledgeBaseSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	scope: { type: 'string' as const, default: 'summary', validate: createEnumValidator(VALID_SCOPES) },
+	categories: { type: 'array' as const },
+	limit: { type: 'number' as const, default: 5 },
+	search_query: { type: 'string' as const },
+};
 
 export const addFinding: Handler = async (args, ctx) => {
-	const { project_id, category, title, description, severity, file_path, line_number, related_task_id } = args as {
-		project_id: string;
-		category?: FindingCategory;
-		title: string;
-		description?: string;
-		severity?: FindingSeverity;
-		file_path?: string;
-		line_number?: number;
-		related_task_id?: string;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
-	validateRequired(title, 'title');
-	if (related_task_id) validateUUID(related_task_id, 'related_task_id');
+	const { project_id, title, description, category, severity, file_path, line_number, related_task_id } = parseArgs(args, addFindingSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.addFinding(project_id, {
 		title,
 		description,
-		category,
-		severity,
+		category: category as FindingCategory | undefined,
+		severity: severity as FindingSeverity | undefined,
 		file_path,
 		line_number,
 		related_task_id
@@ -51,26 +92,18 @@ export const addFinding: Handler = async (args, ctx) => {
 	return { result: response.data };
 };
 
-export const getFindings: Handler = async (args, ctx) => {
-	const { project_id, category, severity, status, limit = 50, offset = 0, search_query } = args as {
-		project_id: string;
-		category?: FindingCategory;
-		severity?: FindingSeverity;
-		status?: FindingStatus;
-		limit?: number;
-		offset?: number;
-		search_query?: string;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+export const getFindings: Handler = async (args, _ctx) => {
+	const { project_id, category, severity, status, limit, offset, search_query, summary_only } = parseArgs(args, getFindingsSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.getFindings(project_id, {
-		category,
-		severity,
-		status,
-		limit
+		category: category as FindingCategory | undefined,
+		severity: severity as FindingSeverity | undefined,
+		status: status as FindingStatus | undefined,
+		limit,
+		offset,
+		search_query,
+		summary_only
 	});
 
 	if (!response.ok) {
@@ -80,25 +113,33 @@ export const getFindings: Handler = async (args, ctx) => {
 	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;
-		status?: FindingStatus;
-		resolution_note?: string;
-		title?: string;
-		description?: string;
-		severity?: FindingSeverity;
-	};
+/**
+ * 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 } = parseArgs(args, getFindingsStatsSchema);
 
-	validateRequired(finding_id, 'finding_id');
-	validateUUID(finding_id, 'finding_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, title, description, severity, status, resolution_note } = parseArgs(args, updateFindingSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.updateFinding(finding_id, {
 		title,
 		description,
-		severity,
-		status,
+		severity: severity as FindingSeverity | undefined,
+		status: status as FindingStatus | undefined,
 		resolution_note
 	});
 
@@ -109,11 +150,8 @@ export const updateFinding: Handler = async (args, ctx) => {
 	return { result: response.data };
 };
 
-export const deleteFinding: Handler = async (args, ctx) => {
-	const { finding_id } = args as { finding_id: string };
-
-	validateRequired(finding_id, 'finding_id');
-	validateUUID(finding_id, 'finding_id');
+export const deleteFinding: Handler = async (args, _ctx) => {
+	const { finding_id } = parseArgs(args, deleteFindingSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.deleteFinding(finding_id);
@@ -125,12 +163,40 @@ export const deleteFinding: Handler = async (args, ctx) => {
 	return { result: response.data };
 };
 
+/**
+ * Query aggregated project knowledge in a single call.
+ * Returns findings, Q&A, decisions, completed tasks, and resolved blockers.
+ * Use this instead of multiple separate tool calls to reduce token usage.
+ */
+export const queryKnowledgeBase: Handler = async (args, _ctx) => {
+	const { project_id, scope, categories, limit, search_query } = parseArgs(args, queryKnowledgeBaseSchema);
+
+	// Validate limit range
+	const effectiveLimit = Math.min(Math.max(1, limit ?? 5), 20);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.queryKnowledgeBase(project_id, {
+		scope: scope as 'summary' | 'detailed' | undefined,
+		categories: categories as string[] | undefined,
+		limit: effectiveLimit,
+		search_query
+	});
+
+	if (!response.ok) {
+		throw new Error(response.error || 'Failed to query knowledge base');
+	}
+
+	return { result: response.data };
+};
+
 /**
  * Findings handlers registry
  */
 export const findingHandlers: HandlerRegistry = {
 	add_finding: addFinding,
 	get_findings: getFindings,
+	get_findings_stats: getFindingsStats,
 	update_finding: updateFinding,
 	delete_finding: deleteFinding,
+	query_knowledge_base: queryKnowledgeBase,
 };