@vibescope/mcp-server 0.2.0 → 0.2.1

package/src/handlers/findings.test.ts

@@ -5,6 +5,7 @@ import {
 	getFindingsStats,
 	updateFinding,
 	deleteFinding,
+	queryKnowledgeBase,
 } from './findings.js';
 import { ValidationError } from '../validators.js';
 import { createMockContext } from './__test-utils__.js';
@@ -472,3 +473,147 @@ describe('getFindingsStats', () => {
 		).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

@@ -10,36 +10,76 @@
  */
 
 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
@@ -52,26 +92,14 @@ 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, summary_only = false } = args as {
-		project_id: string;
-		category?: FindingCategory;
-		severity?: FindingSeverity;
-		status?: FindingStatus;
-		limit?: number;
-		offset?: number;
-		search_query?: string;
-		summary_only?: boolean;
-	};
-
-	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,
+		category: category as FindingCategory | undefined,
+		severity: severity as FindingSeverity | undefined,
+		status: status as FindingStatus | undefined,
 		limit,
 		offset,
 		search_query,
@@ -90,13 +118,8 @@ export const getFindings: Handler = async (args, ctx) => {
  * 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');
+export const getFindingsStats: Handler = async (args, _ctx) => {
+	const { project_id } = parseArgs(args, getFindingsStatsSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.getFindingsStats(project_id);
@@ -108,25 +131,15 @@ export const getFindingsStats: 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;
-	};
-
-	validateRequired(finding_id, 'finding_id');
-	validateUUID(finding_id, 'finding_id');
+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
 	});
 
@@ -137,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);
@@ -153,6 +163,32 @@ 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
  */
@@ -162,4 +198,5 @@ export const findingHandlers: HandlerRegistry = {
 	get_findings_stats: getFindingsStats,
 	update_finding: updateFinding,
 	delete_finding: deleteFinding,
+	query_knowledge_base: queryKnowledgeBase,
 };

package/src/handlers/git-issues.ts

@@ -9,7 +9,7 @@
  */
 
 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';
 
 const VALID_GIT_ISSUE_TYPES = [
@@ -25,41 +25,38 @@ const VALID_GIT_ISSUE_STATUSES = ['open', 'resolved'] as const;
 type GitIssueType = (typeof VALID_GIT_ISSUE_TYPES)[number];
 type GitIssueStatus = (typeof VALID_GIT_ISSUE_STATUSES)[number];
 
-export const addGitIssue: Handler = async (args, ctx) => {
-	const {
-		project_id,
-		issue_type,
-		branch,
-		target_branch,
-		pr_url,
-		conflicting_files,
-		error_message,
-		task_id,
-	} = args as {
-		project_id: string;
-		issue_type: string;
-		branch: string;
-		target_branch?: string;
-		pr_url?: string;
-		conflicting_files?: string[];
-		error_message?: string;
-		task_id?: string;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
-	validateRequired(issue_type, 'issue_type');
-	validateRequired(branch, 'branch');
-
-	if (!VALID_GIT_ISSUE_TYPES.includes(issue_type as GitIssueType)) {
-		throw new Error(
-			`Invalid issue_type. Valid types: ${VALID_GIT_ISSUE_TYPES.join(', ')}`
-		);
-	}
+// Argument schemas for type-safe parsing
+const addGitIssueSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	issue_type: { type: 'string' as const, required: true as const, validate: createEnumValidator(VALID_GIT_ISSUE_TYPES) },
+	branch: { type: 'string' as const, required: true as const },
+	target_branch: { type: 'string' as const },
+	pr_url: { type: 'string' as const },
+	conflicting_files: { type: 'array' as const },
+	error_message: { type: 'string' as const },
+	task_id: { type: 'string' as const, validate: uuidValidator },
+};
 
-	if (task_id) {
-		validateUUID(task_id, 'task_id');
-	}
+const resolveGitIssueSchema = {
+	git_issue_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	resolution_note: { type: 'string' as const },
+	auto_resolved: { type: 'boolean' as const },
+};
+
+const getGitIssuesSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	status: { type: 'string' as const, default: 'open', validate: createEnumValidator(VALID_GIT_ISSUE_STATUSES) },
+	issue_type: { type: 'string' as const, validate: createEnumValidator(VALID_GIT_ISSUE_TYPES) },
+	branch: { type: 'string' as const },
+	limit: { type: 'number' as const, default: 50 },
+};
+
+const deleteGitIssueSchema = {
+	git_issue_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+export const addGitIssue: Handler = async (args, ctx) => {
+	const { project_id, issue_type, branch, target_branch, pr_url, conflicting_files, error_message, task_id } = parseArgs(args, addGitIssueSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.addGitIssue(project_id, {
@@ -67,7 +64,7 @@ export const addGitIssue: Handler = async (args, ctx) => {
 		branch,
 		target_branch,
 		pr_url,
-		conflicting_files,
+		conflicting_files: conflicting_files as string[] | undefined,
 		error_message,
 		task_id
 	}, ctx.session.currentSessionId || undefined);
@@ -80,14 +77,7 @@ export const addGitIssue: Handler = async (args, ctx) => {
 };
 
 export const resolveGitIssue: Handler = async (args, ctx) => {
-	const { git_issue_id, resolution_note, auto_resolved } = args as {
-		git_issue_id: string;
-		resolution_note?: string;
-		auto_resolved?: boolean;
-	};
-
-	validateRequired(git_issue_id, 'git_issue_id');
-	validateUUID(git_issue_id, 'git_issue_id');
+	const { git_issue_id, resolution_note, auto_resolved } = parseArgs(args, resolveGitIssueSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.resolveGitIssue(git_issue_id, {
@@ -102,40 +92,13 @@ export const resolveGitIssue: Handler = async (args, ctx) => {
 	return { result: response.data };
 };
 
-export const getGitIssues: Handler = async (args, ctx) => {
-	const {
-		project_id,
-		status = 'open',
-		issue_type,
-		branch,
-		limit = 50,
-	} = args as {
-		project_id: string;
-		status?: string;
-		issue_type?: string;
-		branch?: string;
-		limit?: number;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
-
-	if (status && !VALID_GIT_ISSUE_STATUSES.includes(status as GitIssueStatus)) {
-		throw new Error(
-			`Invalid status. Valid statuses: ${VALID_GIT_ISSUE_STATUSES.join(', ')}`
-		);
-	}
-
-	if (issue_type && !VALID_GIT_ISSUE_TYPES.includes(issue_type as GitIssueType)) {
-		throw new Error(
-			`Invalid issue_type. Valid types: ${VALID_GIT_ISSUE_TYPES.join(', ')}`
-		);
-	}
+export const getGitIssues: Handler = async (args, _ctx) => {
+	const { project_id, status, issue_type, branch, limit } = parseArgs(args, getGitIssuesSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.getGitIssues(project_id, {
-		status,
-		issue_type,
+		status: status as GitIssueStatus | undefined,
+		issue_type: issue_type as GitIssueType | undefined,
 		branch,
 		limit
 	});
@@ -147,11 +110,8 @@ export const getGitIssues: Handler = async (args, ctx) => {
 	return { result: response.data };
 };
 
-export const deleteGitIssue: Handler = async (args, ctx) => {
-	const { git_issue_id } = args as { git_issue_id: string };
-
-	validateRequired(git_issue_id, 'git_issue_id');
-	validateUUID(git_issue_id, 'git_issue_id');
+export const deleteGitIssue: Handler = async (args, _ctx) => {
+	const { git_issue_id } = parseArgs(args, deleteGitIssueSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.deleteGitIssue(git_issue_id);