@vibescope/mcp-server 0.2.2 → 0.2.4

package/src/handlers/blockers.ts

@@ -29,10 +29,14 @@ const resolveBlockerSchema = {
 	resolution_note: { type: 'string' as const },
 };
 
+const getBlockerSchema = {
+	blocker_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
 const getBlockersSchema = {
 	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
 	status: { type: 'string' as const, default: 'open', validate: createEnumValidator(VALID_BLOCKER_STATUSES) },
-	limit: { type: 'number' as const, default: 50 },
+	limit: { type: 'number' as const, default: 10 },
 	offset: { type: 'number' as const, default: 0 },
 	search_query: { type: 'string' as const },
 };
@@ -41,6 +45,10 @@ const deleteBlockerSchema = {
 	blocker_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
 };
 
+const getBlockersStatsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
 export const addBlocker: Handler = async (args, ctx) => {
 	const { project_id, description } = parseArgs(args, addBlockerSchema);
 
@@ -67,13 +75,39 @@ export const resolveBlocker: Handler = async (args, _ctx) => {
 	return success(response.data);
 };
 
+/**
+ * Get a single blocker by ID.
+ * More token-efficient than get_blockers when you need details for a specific blocker.
+ */
+export const getBlocker: Handler = async (args, _ctx) => {
+	const { blocker_id } = parseArgs(args, getBlockerSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.proxy<{
+		blocker: {
+			id: string;
+			description: string;
+			status: string;
+			resolution_note?: string;
+			created_at: string;
+			resolved_at?: string;
+		};
+	}>('get_blocker', { blocker_id });
+
+	if (!response.ok) {
+		return error(response.error || 'Failed to get blocker');
+	}
+
+	return success(response.data);
+};
+
 export const getBlockers: Handler = async (args, _ctx) => {
 	const { project_id, status, limit, offset, search_query } = parseArgs(args, getBlockersSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.getBlockers(project_id, {
 		status,
-		limit,
+		limit: Math.min(limit ?? 10, 200),
 		offset,
 		search_query
 	});
@@ -98,12 +132,32 @@ export const deleteBlocker: Handler = async (args, _ctx) => {
 	return success(response.data);
 };
 
+/**
+ * Get aggregate statistics about blockers for a project.
+ * Returns total count and breakdown by status without the actual blocker data.
+ * This is much more token-efficient than get_blockers for understanding the overall state.
+ */
+export const getBlockersStats: Handler = async (args, _ctx) => {
+	const { project_id } = parseArgs(args, getBlockersStatsSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getBlockersStats(project_id);
+
+	if (!response.ok) {
+		return error(response.error || 'Failed to get blockers stats');
+	}
+
+	return success(response.data);
+};
+
 /**
  * Blockers handlers registry
  */
 export const blockerHandlers: HandlerRegistry = {
 	add_blocker: addBlocker,
 	resolve_blocker: resolveBlocker,
+	get_blocker: getBlocker,
 	get_blockers: getBlockers,
+	get_blockers_stats: getBlockersStats,
 	delete_blocker: deleteBlocker,
 };

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

@@ -22,7 +22,7 @@ import type { Handler, HandlerRegistry } from './types.js';
 import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
-const BODY_OF_WORK_STATUSES = ['draft', 'active', 'completed', 'cancelled'] as const;
+const BODY_OF_WORK_STATUSES = ['draft', 'active', 'completed', 'cancelled', 'archived'] as const;
 const TASK_PHASES = ['pre', 'core', 'post'] as const;
 const DEPLOY_ENVIRONMENTS = ['development', 'staging', 'production'] as const;
 const VERSION_BUMPS = ['patch', 'minor', 'major'] as const;
@@ -205,6 +205,8 @@ export const getBodyOfWork: Handler = async (args, ctx) => {
 			description?: string;
 			status: string;
 			progress_percentage: number;
+			total_estimated_minutes?: number;
+			completed_estimated_minutes?: number;
 		};
 		// Full response includes tasks grouped by phase
 		tasks?: {
@@ -244,6 +246,8 @@ export const getBodiesOfWork: Handler = async (args, ctx) => {
 			description?: string;
 			status: string;
 			progress_percentage: number;
+			total_estimated_minutes?: number;
+			completed_estimated_minutes?: number;
 			task_counts: {
 				pre: { total: number; completed: number };
 				core: { total: number; completed: number };
@@ -449,6 +453,58 @@ export const getNextBodyOfWorkTask: Handler = async (args, ctx) => {
 	return { result: response.data };
 };
 
+// ============================================================================
+// Archive / Unarchive Handlers
+// ============================================================================
+
+const archiveBodyOfWorkSchema = {
+	body_of_work_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const unarchiveBodyOfWorkSchema = {
+	body_of_work_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+export const archiveBodyOfWork: Handler = async (args, ctx) => {
+	const { body_of_work_id } = parseArgs(args, archiveBodyOfWorkSchema);
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		body_of_work_id: string;
+		title: string;
+		previous_status: string;
+		new_status: string;
+	}>('archive_body_of_work', { body_of_work_id });
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to archive body of work' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const unarchiveBodyOfWork: Handler = async (args, ctx) => {
+	const { body_of_work_id } = parseArgs(args, unarchiveBodyOfWorkSchema);
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		body_of_work_id: string;
+		title: string;
+		previous_status: string;
+		new_status: string;
+	}>('unarchive_body_of_work', { body_of_work_id });
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to unarchive body of work' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
 /**
  * Bodies of Work handlers registry
  */
@@ -465,4 +521,6 @@ export const bodiesOfWorkHandlers: HandlerRegistry = {
 	remove_task_dependency: removeTaskDependency,
 	get_task_dependencies: getTaskDependencies,
 	get_next_body_of_work_task: getNextBodyOfWorkTask,
+	archive_body_of_work: archiveBodyOfWork,
+	unarchive_body_of_work: unarchiveBodyOfWork,
 };

package/src/handlers/connectors.ts

@@ -86,7 +86,7 @@ export const getConnectors: Handler = async (args, _ctx) => {
 	const response = await apiClient.getConnectors(project_id, {
 		type,
 		status,
-		limit,
+		limit: Math.min(limit ?? 50, 50),
 		offset
 	});
 
@@ -204,7 +204,7 @@ export const getConnectorEvents: Handler = async (args, _ctx) => {
 		connector_id,
 		project_id,
 		status,
-		limit,
+		limit: Math.min(limit ?? 50, 50),
 		offset
 	});
 

package/src/handlers/decisions.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { logDecision, getDecisions, deleteDecision } from './decisions.js';
+import { logDecision, getDecisions, getDecisionsStats, deleteDecision } from './decisions.js';
 import { ValidationError } from '../validators.js';
 import { createMockContext } from './__test-utils__.js';
 import { mockApiClient } from './__test-setup__.js';
@@ -215,7 +215,7 @@ describe('getDecisions', () => {
 
 		expect(mockApiClient.getDecisions).toHaveBeenCalledWith(
 			'123e4567-e89b-12d3-a456-426614174000',
-			{ limit: 50, offset: 0, search_query: undefined }
+			{ limit: 10, offset: 0, search_query: undefined }
 		);
 	});
 
@@ -311,3 +311,72 @@ describe('deleteDecision', () => {
 		});
 	});
 });
+
+// ============================================================================
+// getDecisionsStats Tests
+// ============================================================================
+
+describe('getDecisionsStats', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(getDecisionsStats({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid project_id UUID', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			getDecisionsStats({ project_id: 'invalid' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should return decisions stats', async () => {
+		mockApiClient.getDecisionsStats.mockResolvedValue({
+			ok: true,
+			data: { total: 10 },
+		});
+		const ctx = createMockContext();
+
+		const result = await getDecisionsStats(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ total: 10 });
+	});
+
+	it('should call API client getDecisionsStats', async () => {
+		mockApiClient.getDecisionsStats.mockResolvedValue({
+			ok: true,
+			data: { total: 0 },
+		});
+		const ctx = createMockContext();
+
+		await getDecisionsStats(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(mockApiClient.getDecisionsStats).toHaveBeenCalledWith(
+			'123e4567-e89b-12d3-a456-426614174000'
+		);
+	});
+
+	it('should return error when API call fails', async () => {
+		mockApiClient.getDecisionsStats.mockResolvedValue({
+			ok: false,
+			error: 'Query failed',
+		});
+		const ctx = createMockContext();
+
+		const result = await getDecisionsStats({ project_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Query failed',
+		});
+	});
+});

package/src/handlers/decisions.ts

@@ -22,9 +22,13 @@ const logDecisionSchema = {
 	alternatives_considered: { type: 'array' as const },
 };
 
+const getDecisionSchema = {
+	decision_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
 const getDecisionsSchema = {
 	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	limit: { type: 'number' as const, default: 50 },
+	limit: { type: 'number' as const, default: 10 },
 	offset: { type: 'number' as const, default: 0 },
 	search_query: { type: 'string' as const },
 };
@@ -33,6 +37,10 @@ const deleteDecisionSchema = {
 	decision_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
 };
 
+const getDecisionsStatsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
 export const logDecision: Handler = async (args, ctx) => {
 	const { project_id, title, description, rationale, alternatives_considered } = parseArgs(args, logDecisionSchema);
 
@@ -53,13 +61,39 @@ export const logDecision: Handler = async (args, ctx) => {
 	return { result: { success: true, title, decision_id: response.data?.decision_id } };
 };
 
+/**
+ * Get a single decision by ID.
+ * More token-efficient than get_decisions when you need details for a specific decision.
+ */
+export const getDecision: Handler = async (args, _ctx) => {
+	const { decision_id } = parseArgs(args, getDecisionSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.proxy<{
+		decision: {
+			id: string;
+			title: string;
+			description: string;
+			rationale?: string;
+			alternatives_considered?: string[];
+			created_at: string;
+		};
+	}>('get_decision', { decision_id });
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get decision' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
 export const getDecisions: Handler = async (args, _ctx) => {
 	const { project_id, limit, offset, search_query } = parseArgs(args, getDecisionsSchema);
 
 	const apiClient = getApiClient();
 
 	const response = await apiClient.getDecisions(project_id, {
-		limit,
+		limit: Math.min(limit ?? 10, 200),
 		offset,
 		search_query
 	});
@@ -89,11 +123,31 @@ export const deleteDecision: Handler = async (args, _ctx) => {
 	return { result: { success: true } };
 };
 
+/**
+ * Get aggregate statistics about decisions for a project.
+ * Returns total count without the actual decision data.
+ * This is more token-efficient than get_decisions for understanding overall state.
+ */
+export const getDecisionsStats: Handler = async (args, _ctx) => {
+	const { project_id } = parseArgs(args, getDecisionsStatsSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getDecisionsStats(project_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get decisions stats' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
 /**
  * Decisions handlers registry
  */
 export const decisionHandlers: HandlerRegistry = {
 	log_decision: logDecision,
+	get_decision: getDecision,
 	get_decisions: getDecisions,
+	get_decisions_stats: getDecisionsStats,
 	delete_decision: deleteDecision,
 };

package/src/handlers/deployment.test.ts

@@ -8,6 +8,7 @@ import {
 	cancelDeployment,
 	addDeploymentRequirement,
 	getDeploymentRequirements,
+	getDeploymentRequirementsStats,
 } from './deployment.js';
 import { ValidationError } from '../validators.js';
 import { createMockContext } from './__test-utils__.js';
@@ -467,4 +468,84 @@ describe('getDeploymentRequirements', () => {
 		expect((result.result as { requirements: unknown[] }).requirements).toHaveLength(2);
 		expect(result.result).toHaveProperty('deployment_blocked', true);
 	});
+
+	it('should pass pagination params to API client', async () => {
+		mockApiClient.getDeploymentRequirements.mockResolvedValue({
+			ok: true,
+			data: { requirements: [], deployment_blocked: false },
+		});
+		const ctx = createMockContext();
+
+		await getDeploymentRequirements(
+			{ project_id: VALID_UUID, limit: 10, offset: 5 },
+			ctx
+		);
+
+		expect(mockApiClient.getDeploymentRequirements).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({ limit: 10, offset: 5 })
+		);
+	});
+});
+
+// ============================================================================
+// getDeploymentRequirementsStats Tests
+// ============================================================================
+
+describe('getDeploymentRequirementsStats', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+		await expect(getDeploymentRequirementsStats({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid project_id UUID', async () => {
+		const ctx = createMockContext();
+		await expect(
+			getDeploymentRequirementsStats({ project_id: 'invalid' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should return stats from API client', async () => {
+		const mockStats = {
+			total: 5,
+			by_status: { pending: 3, completed: 2 },
+			by_stage: { preparation: 2, deployment: 2, verification: 1 },
+			by_type: { migration: 2, env_var: 2, manual: 1 },
+		};
+		mockApiClient.getDeploymentRequirementsStats.mockResolvedValue({
+			ok: true,
+			data: mockStats,
+		});
+		const ctx = createMockContext();
+
+		const result = await getDeploymentRequirementsStats({ project_id: VALID_UUID }, ctx);
+
+		expect(result.result).toMatchObject(mockStats);
+	});
+
+	it('should call API client with correct project_id', async () => {
+		mockApiClient.getDeploymentRequirementsStats.mockResolvedValue({
+			ok: true,
+			data: { total: 0, by_status: {}, by_stage: {}, by_type: {} },
+		});
+		const ctx = createMockContext();
+
+		await getDeploymentRequirementsStats({ project_id: VALID_UUID }, ctx);
+
+		expect(mockApiClient.getDeploymentRequirementsStats).toHaveBeenCalledWith(VALID_UUID);
+	});
+
+	it('should handle API error', async () => {
+		mockApiClient.getDeploymentRequirementsStats.mockResolvedValue({
+			ok: false,
+			error: 'Database error',
+		});
+		const ctx = createMockContext();
+
+		const result = await getDeploymentRequirementsStats({ project_id: VALID_UUID }, ctx);
+
+		expect(result.result).toHaveProperty('error');
+	});
 });

package/src/handlers/deployment.ts

@@ -87,7 +87,7 @@ const addDeploymentRequirementSchema = {
 	file_path: { type: 'string' as const },
 	stage: { type: 'string' as const, default: 'preparation', validate: createEnumValidator(REQUIREMENT_STAGES) },
 	blocking: { type: 'boolean' as const, default: false },
-	recurring: { type: 'boolean' as const, default: false },
+	recurring: { type: 'boolean' as const, default: true },
 };
 
 const completeDeploymentRequirementSchema = {
@@ -98,6 +98,12 @@ const getDeploymentRequirementsSchema = {
 	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
 	status: { type: 'string' as const, default: 'pending', validate: createEnumValidator(REQUIREMENT_STATUSES) },
 	stage: { type: 'string' as const, validate: createEnumValidator([...REQUIREMENT_STAGES, 'all'] as const) },
+	limit: { type: 'number' as const, default: 50 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+const getDeploymentRequirementsStatsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
 };
 
 const scheduleDeploymentSchema = {
@@ -115,6 +121,8 @@ const scheduleDeploymentSchema = {
 const getScheduledDeploymentsSchema = {
 	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
 	include_disabled: { type: 'boolean' as const, default: false },
+	limit: { type: 'number' as const, default: 50 },
+	offset: { type: 'number' as const, default: 0 },
 };
 
 const updateScheduledDeploymentSchema = {
@@ -291,12 +299,14 @@ export const completeDeploymentRequirement: Handler = async (args, ctx) => {
 };
 
 export const getDeploymentRequirements: Handler = async (args, ctx) => {
-	const { project_id, status, stage } = parseArgs(args, getDeploymentRequirementsSchema);
+	const { project_id, status, stage, limit, offset } = parseArgs(args, getDeploymentRequirementsSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.getDeploymentRequirements(project_id, {
 		status: status as 'pending' | 'completed' | 'converted_to_task' | 'all',
-		stage: stage as 'preparation' | 'deployment' | 'verification' | 'all' | undefined
+		stage: stage as 'preparation' | 'deployment' | 'verification' | 'all' | undefined,
+		limit,
+		offset
 	});
 
 	if (!response.ok) {
@@ -306,6 +316,24 @@ export const getDeploymentRequirements: Handler = async (args, ctx) => {
 	return { result: response.data };
 };
 
+/**
+ * Get aggregate statistics about deployment requirements for a project.
+ * Returns total count and breakdowns by status, stage, and type.
+ * More token-efficient than get_deployment_requirements when you just need to understand the overall state.
+ */
+export const getDeploymentRequirementsStats: Handler = async (args, ctx) => {
+	const { project_id } = parseArgs(args, getDeploymentRequirementsStatsSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getDeploymentRequirementsStats(project_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get deployment requirements stats' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
 // ============================================================================
 // Scheduled Deployments
 // ============================================================================
@@ -366,10 +394,14 @@ export const scheduleDeployment: Handler = async (args, ctx) => {
 };
 
 export const getScheduledDeployments: Handler = async (args, ctx) => {
-	const { project_id, include_disabled } = parseArgs(args, getScheduledDeploymentsSchema);
+	const { project_id, include_disabled, limit, offset } = parseArgs(args, getScheduledDeploymentsSchema);
 
 	const apiClient = getApiClient();
-	const response = await apiClient.getScheduledDeployments(project_id, include_disabled);
+	const response = await apiClient.getScheduledDeployments(project_id, {
+		includeDisabled: include_disabled,
+		limit,
+		offset
+	});
 
 	if (!response.ok) {
 		return { result: { error: response.error || 'Failed to get scheduled deployments' }, isError: true };
@@ -498,6 +530,7 @@ export const deploymentHandlers: HandlerRegistry = {
 	add_deployment_requirement: addDeploymentRequirement,
 	complete_deployment_requirement: completeDeploymentRequirement,
 	get_deployment_requirements: getDeploymentRequirements,
+	get_deployment_requirements_stats: getDeploymentRequirementsStats,
 	// Scheduled deployments
 	schedule_deployment: scheduleDeployment,
 	get_scheduled_deployments: getScheduledDeployments,