@vibescope/mcp-server 0.4.0 → 0.4.2

package/src/api-client/index.ts

@@ -17,6 +17,10 @@ import { createDiscoveryMethods, type DiscoveryMethods } from './discovery.js';
 import { createDecisionsMethods, type DecisionsMethods } from './decisions.js';
 import { createIdeasMethods, type IdeasMethods } from './ideas.js';
 import { createTasksMethods, type TasksMethods } from './tasks.js';
+import { createFindingsMethods, type FindingsMethods } from './findings.js';
+import { createMilestonesMethods, type MilestonesMethods } from './milestones.js';
+import { createValidationMethods, type ValidationMethods } from './validation.js';
+import { createFallbackMethods, type FallbackMethods } from './fallback.js';
 
 // Re-export types
 export type { ApiClientConfig, ApiResponse, RetryConfig, RequestFn, ProxyFn } from './types.js';
@@ -29,6 +33,10 @@ export type { DiscoveryMethods } from './discovery.js';
 export type { DecisionsMethods } from './decisions.js';
 export type { IdeasMethods } from './ideas.js';
 export type { TasksMethods } from './tasks.js';
+export type { FindingsMethods } from './findings.js';
+export type { MilestonesMethods } from './milestones.js';
+export type { ValidationMethods } from './validation.js';
+export type { FallbackMethods } from './fallback.js';
 
 const DEFAULT_API_URL = 'https://vibescope.dev';
 
@@ -74,7 +82,11 @@ export interface VibescopeApiClientMethods
 		DiscoveryMethods,
 		DecisionsMethods,
 		IdeasMethods,
-		TasksMethods {}
+		TasksMethods,
+		FindingsMethods,
+		MilestonesMethods,
+		ValidationMethods,
+		FallbackMethods {}
 
 export class VibescopeApiClient implements VibescopeApiClientMethods {
 	private apiKey: string;
@@ -91,6 +103,10 @@ export class VibescopeApiClient implements VibescopeApiClientMethods {
 	private decisionsMethods: DecisionsMethods;
 	private ideasMethods: IdeasMethods;
 	private tasksMethods: TasksMethods;
+	private findingsMethods: FindingsMethods;
+	private milestonesMethods: MilestonesMethods;
+	private validationMethods: ValidationMethods;
+	private fallbackMethods: FallbackMethods;
 
 	constructor(config: ApiClientConfig) {
 		this.apiKey = config.apiKey;
@@ -117,6 +133,10 @@ export class VibescopeApiClient implements VibescopeApiClientMethods {
 		this.decisionsMethods = createDecisionsMethods(proxy);
 		this.ideasMethods = createIdeasMethods(proxy);
 		this.tasksMethods = createTasksMethods(request, proxy);
+		this.findingsMethods = createFindingsMethods(proxy);
+		this.milestonesMethods = createMilestonesMethods(proxy);
+		this.validationMethods = createValidationMethods(proxy);
+		this.fallbackMethods = createFallbackMethods(proxy);
 	}
 
 	private async request<T>(method: string, path: string, body?: unknown): Promise<ApiResponse<T>> {
@@ -304,14 +324,42 @@ export class VibescopeApiClient implements VibescopeApiClientMethods {
 	batchUpdateTasks = (updates: Parameters<TasksMethods['batchUpdateTasks']>[0]) => this.tasksMethods.batchUpdateTasks(updates);
 	batchCompleteTasks = (completions: Parameters<TasksMethods['batchCompleteTasks']>[0]) => this.tasksMethods.batchCompleteTasks(completions);
 
+	// ============================================================================
+	// Findings methods (delegated)
+	// ============================================================================
+	getFindings = (projectId: string, params?: Parameters<FindingsMethods['getFindings']>[1]) => this.findingsMethods.getFindings(projectId, params);
+	getFinding = (findingId: string) => this.findingsMethods.getFinding(findingId);
+	getFindingsStats = (projectId: string) => this.findingsMethods.getFindingsStats(projectId);
+	addFinding = (projectId: string, params: Parameters<FindingsMethods['addFinding']>[1], sessionId?: string) => this.findingsMethods.addFinding(projectId, params, sessionId);
+	updateFinding = (findingId: string, updates: Parameters<FindingsMethods['updateFinding']>[1]) => this.findingsMethods.updateFinding(findingId, updates);
+	deleteFinding = (findingId: string) => this.findingsMethods.deleteFinding(findingId);
+
+	// ============================================================================
+	// Milestones methods (delegated)
+	// ============================================================================
+	getMilestones = (taskId: string) => this.milestonesMethods.getMilestones(taskId);
+	addMilestone = (taskId: string, params: Parameters<MilestonesMethods['addMilestone']>[1], sessionId?: string) => this.milestonesMethods.addMilestone(taskId, params, sessionId);
+	updateMilestone = (milestoneId: string, updates: Parameters<MilestonesMethods['updateMilestone']>[1]) => this.milestonesMethods.updateMilestone(milestoneId, updates);
+	completeMilestone = (milestoneId: string) => this.milestonesMethods.completeMilestone(milestoneId);
+	deleteMilestone = (milestoneId: string) => this.milestonesMethods.deleteMilestone(milestoneId);
+
+	// ============================================================================
+	// Validation methods (delegated)
+	// ============================================================================
+	getTasksAwaitingValidation = (projectId: string) => this.validationMethods.getTasksAwaitingValidation(projectId);
+	claimValidation = (taskId: string, sessionId?: string) => this.validationMethods.claimValidation(taskId, sessionId);
+	validateTask = (taskId: string, params: Parameters<ValidationMethods['validateTask']>[1], sessionId?: string) => this.validationMethods.validateTask(taskId, params, sessionId);
+
+	// ============================================================================
+	// Fallback activity methods (delegated)
+	// ============================================================================
+	startFallbackActivity = (projectId: string, activity: string, sessionId?: string) => this.fallbackMethods.startFallbackActivity(projectId, activity, sessionId);
+	stopFallbackActivity = (projectId: string, summary?: string, sessionId?: string) => this.fallbackMethods.stopFallbackActivity(projectId, summary, sessionId);
+
 	// ============================================================================
 	// TODO: Additional methods to be migrated from original api-client.ts
 	// The following domains need to be split into separate files:
-	// - findings.ts (getFindings, addFinding, etc.)
-	// - milestones.ts (getMilestones, addMilestone, etc.)
 	// - requests.ts (getPendingRequests, answerQuestion, etc.)
-	// - validation.ts (getTasksAwaitingValidation, validateTask, etc.)
-	// - fallback.ts (startFallbackActivity, stopFallbackActivity)
 	// - deployment.ts (requestDeployment, startDeployment, etc.)
 	// - organizations.ts (listOrganizations, etc.)
 	// - bodies-of-work.ts (createBodyOfWork, etc.)
@@ -329,15 +377,49 @@ let apiClient: VibescopeApiClient | null = null;
 
 export function getApiClient(): VibescopeApiClient {
 	if (!apiClient) {
-		const apiKey = process.env.VIBESCOPE_API_KEY;
-		if (!apiKey) {
-			throw new Error('VIBESCOPE_API_KEY environment variable is required');
-		}
+		const apiKey = resolveApiKeyFromSources();
 		apiClient = new VibescopeApiClient({ apiKey });
 	}
 	return apiClient;
 }
 
+/**
+ * Resolve API key from multiple sources in priority order:
+ * 1. VIBESCOPE_API_KEY env var (CI/cloud agents)
+ * 2. ~/.vibescope/credentials.json (local dev)
+ * 3. Error with helpful message
+ */
+function resolveApiKeyFromSources(): string {
+	// 1. Environment variable
+	if (process.env.VIBESCOPE_API_KEY) {
+		return process.env.VIBESCOPE_API_KEY;
+	}
+
+	// 2. Credentials file
+	try {
+		const { existsSync, readFileSync } = require('node:fs');
+		const { homedir } = require('node:os');
+		const { join } = require('node:path');
+		const credPath = join(homedir(), '.vibescope', 'credentials.json');
+		if (existsSync(credPath)) {
+			const data = JSON.parse(readFileSync(credPath, 'utf-8'));
+			if (data.apiKey) {
+				return data.apiKey;
+			}
+		}
+	} catch {
+		// ignore read errors
+	}
+
+	// 3. Not found
+	throw new Error(
+		'Vibescope API key not found.\n\n' +
+		'Set it up with:\n' +
+		'  npx vibescope init\n\n' +
+		'Or set the VIBESCOPE_API_KEY environment variable.'
+	);
+}
+
 export function initApiClient(config: ApiClientConfig): VibescopeApiClient {
 	apiClient = new VibescopeApiClient(config);
 	return apiClient;

package/src/api-client/milestones.ts

@@ -0,0 +1,83 @@
+/**
+ * Milestones API Methods
+ *
+ * Handles task milestones for tracking granular progress within tasks.
+ */
+
+import type { ApiResponse, ProxyFn } from './types.js';
+
+export interface Milestone {
+	id: string;
+	title: string;
+	description?: string;
+	status: string;
+	order_index: number;
+	created_at: string;
+	completed_at?: string;
+}
+
+export interface MilestoneStats {
+	total: number;
+	completed: number;
+	progress_percentage: number;
+}
+
+export interface MilestonesMethods {
+	getMilestones(taskId: string): Promise<ApiResponse<{
+		milestones: Milestone[];
+		stats: MilestoneStats;
+	}>>;
+
+	addMilestone(taskId: string, params: {
+		title: string;
+		description?: string;
+		order_index?: number;
+	}, sessionId?: string): Promise<ApiResponse<{ success: boolean; milestone_id: string }>>;
+
+	updateMilestone(milestoneId: string, updates: {
+		title?: string;
+		description?: string;
+		status?: string;
+		order_index?: number;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		milestone: { id: string; title: string; status: string };
+	}>>;
+
+	completeMilestone(milestoneId: string): Promise<ApiResponse<{
+		success: boolean;
+		milestone: { id: string; title: string; status: string };
+	}>>;
+
+	deleteMilestone(milestoneId: string): Promise<ApiResponse<{ success: boolean }>>;
+}
+
+export function createMilestonesMethods(proxy: ProxyFn): MilestonesMethods {
+	return {
+		async getMilestones(taskId) {
+			return proxy('get_milestones', { task_id: taskId });
+		},
+
+		async addMilestone(taskId, params, sessionId) {
+			return proxy('add_milestone', {
+				task_id: taskId,
+				...params
+			}, sessionId ? { session_id: sessionId } : undefined);
+		},
+
+		async updateMilestone(milestoneId, updates) {
+			return proxy('update_milestone', {
+				milestone_id: milestoneId,
+				...updates
+			});
+		},
+
+		async completeMilestone(milestoneId) {
+			return proxy('complete_milestone', { milestone_id: milestoneId });
+		},
+
+		async deleteMilestone(milestoneId) {
+			return proxy('delete_milestone', { milestone_id: milestoneId });
+		}
+	};
+}

package/src/api-client/validation.ts

@@ -0,0 +1,60 @@
+/**
+ * Validation API Methods
+ *
+ * Handles task validation workflow for code review and approval.
+ */
+
+import type { ApiResponse, ProxyFn } from './types.js';
+
+export interface TaskAwaitingValidation {
+	id: string;
+	title: string;
+	completed_at?: string;
+	completed_by_session_id?: string;
+}
+
+export interface ValidationMethods {
+	getTasksAwaitingValidation(projectId: string): Promise<ApiResponse<{
+		tasks: TaskAwaitingValidation[];
+	}>>;
+
+	claimValidation(taskId: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+	}>>;
+
+	validateTask(taskId: string, params: {
+		approved: boolean;
+		validation_notes?: string;
+		skip_pr_check?: boolean;
+		pr_checks_passing?: boolean;
+		create_fix_task?: boolean;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		approved: boolean;
+		task_id: string;
+		message?: string;
+		workflow?: string;
+	}>>;
+}
+
+export function createValidationMethods(proxy: ProxyFn): ValidationMethods {
+	return {
+		async getTasksAwaitingValidation(projectId) {
+			return proxy('get_tasks_awaiting_validation', { project_id: projectId });
+		},
+
+		async claimValidation(taskId, sessionId) {
+			return proxy('claim_validation', { task_id: taskId }, sessionId ? {
+				session_id: sessionId
+			} : undefined);
+		},
+
+		async validateTask(taskId, params, sessionId) {
+			return proxy('validate_task', {
+				task_id: taskId,
+				...params
+			}, sessionId ? { session_id: sessionId } : undefined);
+		}
+	};
+}

package/src/api-client.ts

@@ -203,6 +203,10 @@ export class VibescopeApiClient {
 			git_main_branch?: string;
 			git_develop_branch?: string;
 			git_auto_branch?: boolean;
+			validation_required?: boolean;
+			auto_merge_on_approval?: boolean;
+			fallback_activities_enabled?: boolean;
+			require_pr_for_validation?: boolean;
 		};
 		active_tasks?: Array<{
 			id: string;