@vibescope/mcp-server 0.4.0 → 0.4.2

package/dist/api-client/fallback.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Fallback Activity API Methods
+ *
+ * Handles background activities when agents are idle with no pending tasks.
+ */
+import type { ApiResponse, ProxyFn } from './types.js';
+export interface FallbackActivityResult {
+    success: boolean;
+    activity: string;
+    message: string;
+    git_workflow?: {
+        workflow: string;
+        base_branch: string;
+        worktree_recommended: boolean;
+        note: string;
+    };
+    worktree_setup?: {
+        message: string;
+        commands: string[];
+        worktree_path: string;
+        branch_name: string;
+        cleanup_command: string;
+        report_worktree: string;
+    };
+    next_step?: string;
+}
+export interface FallbackMethods {
+    startFallbackActivity(projectId: string, activity: string, sessionId?: string): Promise<ApiResponse<FallbackActivityResult>>;
+    stopFallbackActivity(projectId: string, summary?: string, sessionId?: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+}
+export declare function createFallbackMethods(proxy: ProxyFn): FallbackMethods;

package/dist/api-client/fallback.js

@@ -0,0 +1,21 @@
+/**
+ * Fallback Activity API Methods
+ *
+ * Handles background activities when agents are idle with no pending tasks.
+ */
+export function createFallbackMethods(proxy) {
+    return {
+        async startFallbackActivity(projectId, activity, sessionId) {
+            return proxy('start_fallback_activity', {
+                project_id: projectId,
+                activity
+            }, sessionId ? { session_id: sessionId } : undefined);
+        },
+        async stopFallbackActivity(projectId, summary, sessionId) {
+            return proxy('stop_fallback_activity', {
+                project_id: projectId,
+                summary
+            }, sessionId ? { session_id: sessionId } : undefined);
+        }
+    };
+}

package/dist/api-client/findings.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Findings API Methods
+ *
+ * Handles security findings, code quality issues, and audit findings.
+ */
+import type { ApiResponse, ProxyFn } from './types.js';
+export interface Finding {
+    id: string;
+    title: string;
+    description?: string;
+    category: string;
+    severity: string;
+    status: string;
+    file_path?: string;
+    line_number?: number;
+    resolution_note?: string;
+    created_at: string;
+}
+export interface FindingsStats {
+    total: number;
+    by_status: Record<string, number>;
+    by_severity: Record<string, number>;
+    by_category: Record<string, number>;
+}
+export interface FindingsMethods {
+    getFindings(projectId: string, params?: {
+        category?: string;
+        severity?: string;
+        status?: string;
+        limit?: number;
+        offset?: number;
+        search_query?: string;
+        summary_only?: boolean;
+    }): Promise<ApiResponse<{
+        findings: Finding[];
+        total_count?: number;
+        has_more?: boolean;
+    }>>;
+    getFinding(findingId: string): Promise<ApiResponse<{
+        finding: Finding;
+    }>>;
+    getFindingsStats(projectId: string): Promise<ApiResponse<FindingsStats>>;
+    addFinding(projectId: string, params: {
+        title: string;
+        description?: string;
+        category?: string;
+        severity?: string;
+        file_path?: string;
+        line_number?: number;
+        related_task_id?: string;
+    }, sessionId?: string): Promise<ApiResponse<{
+        success: boolean;
+        finding_id: string;
+    }>>;
+    updateFinding(findingId: string, updates: {
+        title?: string;
+        description?: string;
+        severity?: string;
+        status?: string;
+        resolution_note?: string;
+    }): Promise<ApiResponse<{
+        success: boolean;
+        finding_id: string;
+    }>>;
+    deleteFinding(findingId: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+}
+export declare function createFindingsMethods(proxy: ProxyFn): FindingsMethods;

package/dist/api-client/findings.js

@@ -0,0 +1,36 @@
+/**
+ * Findings API Methods
+ *
+ * Handles security findings, code quality issues, and audit findings.
+ */
+export function createFindingsMethods(proxy) {
+    return {
+        async getFindings(projectId, params) {
+            return proxy('get_findings', {
+                project_id: projectId,
+                ...params
+            });
+        },
+        async getFinding(findingId) {
+            return proxy('get_finding', { finding_id: findingId });
+        },
+        async getFindingsStats(projectId) {
+            return proxy('get_findings_stats', { project_id: projectId });
+        },
+        async addFinding(projectId, params, sessionId) {
+            return proxy('add_finding', {
+                project_id: projectId,
+                ...params
+            }, sessionId ? { session_id: sessionId } : undefined);
+        },
+        async updateFinding(findingId, updates) {
+            return proxy('update_finding', {
+                finding_id: findingId,
+                ...updates
+            });
+        },
+        async deleteFinding(findingId) {
+            return proxy('delete_finding', { finding_id: findingId });
+        }
+    };
+}

package/dist/api-client/index.d.ts

@@ -16,6 +16,10 @@ import { type DiscoveryMethods } from './discovery.js';
 import { type DecisionsMethods } from './decisions.js';
 import { type IdeasMethods } from './ideas.js';
 import { type TasksMethods } from './tasks.js';
+import { type FindingsMethods } from './findings.js';
+import { type MilestonesMethods } from './milestones.js';
+import { type ValidationMethods } from './validation.js';
+import { type FallbackMethods } from './fallback.js';
 export type { ApiClientConfig, ApiResponse, RetryConfig, RequestFn, ProxyFn } from './types.js';
 export type { SessionMethods } from './session.js';
 export type { ProjectMethods } from './project.js';
@@ -26,10 +30,14 @@ 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';
 /**
  * Combined interface for all API methods
  */
-export interface VibescopeApiClientMethods extends SessionMethods, ProjectMethods, BlockersMethods, CostMethods, WorktreesMethods, DiscoveryMethods, DecisionsMethods, IdeasMethods, TasksMethods {
+export interface VibescopeApiClientMethods extends SessionMethods, ProjectMethods, BlockersMethods, CostMethods, WorktreesMethods, DiscoveryMethods, DecisionsMethods, IdeasMethods, TasksMethods, FindingsMethods, MilestonesMethods, ValidationMethods, FallbackMethods {
 }
 export declare class VibescopeApiClient implements VibescopeApiClientMethods {
     private apiKey;
@@ -44,6 +52,10 @@ export declare class VibescopeApiClient implements VibescopeApiClientMethods {
     private decisionsMethods;
     private ideasMethods;
     private tasksMethods;
+    private findingsMethods;
+    private milestonesMethods;
+    private validationMethods;
+    private fallbackMethods;
     constructor(config: ApiClientConfig);
     private request;
     /**
@@ -744,6 +756,71 @@ export declare class VibescopeApiClient implements VibescopeApiClientMethods {
             error?: string;
         }>;
     }>>;
+    getFindings: (projectId: string, params?: Parameters<FindingsMethods["getFindings"]>[1]) => Promise<ApiResponse<{
+        findings: import("./findings.js").Finding[];
+        total_count?: number;
+        has_more?: boolean;
+    }>>;
+    getFinding: (findingId: string) => Promise<ApiResponse<{
+        finding: import("./findings.js").Finding;
+    }>>;
+    getFindingsStats: (projectId: string) => Promise<ApiResponse<import("./findings.js").FindingsStats>>;
+    addFinding: (projectId: string, params: Parameters<FindingsMethods["addFinding"]>[1], sessionId?: string) => Promise<ApiResponse<{
+        success: boolean;
+        finding_id: string;
+    }>>;
+    updateFinding: (findingId: string, updates: Parameters<FindingsMethods["updateFinding"]>[1]) => Promise<ApiResponse<{
+        success: boolean;
+        finding_id: string;
+    }>>;
+    deleteFinding: (findingId: string) => Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+    getMilestones: (taskId: string) => Promise<ApiResponse<{
+        milestones: import("./milestones.js").Milestone[];
+        stats: import("./milestones.js").MilestoneStats;
+    }>>;
+    addMilestone: (taskId: string, params: Parameters<MilestonesMethods["addMilestone"]>[1], sessionId?: string) => Promise<ApiResponse<{
+        success: boolean;
+        milestone_id: string;
+    }>>;
+    updateMilestone: (milestoneId: string, updates: Parameters<MilestonesMethods["updateMilestone"]>[1]) => 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;
+    }>>;
+    getTasksAwaitingValidation: (projectId: string) => Promise<ApiResponse<{
+        tasks: import("./validation.js").TaskAwaitingValidation[];
+    }>>;
+    claimValidation: (taskId: string, sessionId?: string) => Promise<ApiResponse<{
+        success: boolean;
+        task_id: string;
+    }>>;
+    validateTask: (taskId: string, params: Parameters<ValidationMethods["validateTask"]>[1], sessionId?: string) => Promise<ApiResponse<{
+        success: boolean;
+        approved: boolean;
+        task_id: string;
+        message?: string;
+        workflow?: string;
+    }>>;
+    startFallbackActivity: (projectId: string, activity: string, sessionId?: string) => Promise<ApiResponse<import("./fallback.js").FallbackActivityResult>>;
+    stopFallbackActivity: (projectId: string, summary?: string, sessionId?: string) => Promise<ApiResponse<{
+        success: boolean;
+    }>>;
 }
 export declare function getApiClient(): VibescopeApiClient;
 export declare function initApiClient(config: ApiClientConfig): VibescopeApiClient;

package/dist/api-client/index.js

@@ -15,6 +15,10 @@ import { createDiscoveryMethods } from './discovery.js';
 import { createDecisionsMethods } from './decisions.js';
 import { createIdeasMethods } from './ideas.js';
 import { createTasksMethods } from './tasks.js';
+import { createFindingsMethods } from './findings.js';
+import { createMilestonesMethods } from './milestones.js';
+import { createValidationMethods } from './validation.js';
+import { createFallbackMethods } from './fallback.js';
 const DEFAULT_API_URL = 'https://vibescope.dev';
 // Retry configuration defaults
 const DEFAULT_RETRY_STATUS_CODES = [429, 503, 504];
@@ -52,6 +56,10 @@ export class VibescopeApiClient {
     decisionsMethods;
     ideasMethods;
     tasksMethods;
+    findingsMethods;
+    milestonesMethods;
+    validationMethods;
+    fallbackMethods;
     constructor(config) {
         this.apiKey = config.apiKey;
         this.baseUrl = config.baseUrl || process.env.VIBESCOPE_API_URL || DEFAULT_API_URL;
@@ -75,6 +83,10 @@ export class VibescopeApiClient {
         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);
     }
     async request(method, path, body) {
         const url = `${this.baseUrl}${path}`;
@@ -242,19 +254,77 @@ export class VibescopeApiClient {
     removeTaskReference = (taskId, url) => this.tasksMethods.removeTaskReference(taskId, url);
     batchUpdateTasks = (updates) => this.tasksMethods.batchUpdateTasks(updates);
     batchCompleteTasks = (completions) => this.tasksMethods.batchCompleteTasks(completions);
+    // ============================================================================
+    // Findings methods (delegated)
+    // ============================================================================
+    getFindings = (projectId, params) => this.findingsMethods.getFindings(projectId, params);
+    getFinding = (findingId) => this.findingsMethods.getFinding(findingId);
+    getFindingsStats = (projectId) => this.findingsMethods.getFindingsStats(projectId);
+    addFinding = (projectId, params, sessionId) => this.findingsMethods.addFinding(projectId, params, sessionId);
+    updateFinding = (findingId, updates) => this.findingsMethods.updateFinding(findingId, updates);
+    deleteFinding = (findingId) => this.findingsMethods.deleteFinding(findingId);
+    // ============================================================================
+    // Milestones methods (delegated)
+    // ============================================================================
+    getMilestones = (taskId) => this.milestonesMethods.getMilestones(taskId);
+    addMilestone = (taskId, params, sessionId) => this.milestonesMethods.addMilestone(taskId, params, sessionId);
+    updateMilestone = (milestoneId, updates) => this.milestonesMethods.updateMilestone(milestoneId, updates);
+    completeMilestone = (milestoneId) => this.milestonesMethods.completeMilestone(milestoneId);
+    deleteMilestone = (milestoneId) => this.milestonesMethods.deleteMilestone(milestoneId);
+    // ============================================================================
+    // Validation methods (delegated)
+    // ============================================================================
+    getTasksAwaitingValidation = (projectId) => this.validationMethods.getTasksAwaitingValidation(projectId);
+    claimValidation = (taskId, sessionId) => this.validationMethods.claimValidation(taskId, sessionId);
+    validateTask = (taskId, params, sessionId) => this.validationMethods.validateTask(taskId, params, sessionId);
+    // ============================================================================
+    // Fallback activity methods (delegated)
+    // ============================================================================
+    startFallbackActivity = (projectId, activity, sessionId) => this.fallbackMethods.startFallbackActivity(projectId, activity, sessionId);
+    stopFallbackActivity = (projectId, summary, sessionId) => this.fallbackMethods.stopFallbackActivity(projectId, summary, sessionId);
 }
 // Singleton instance
 let apiClient = null;
 export function getApiClient() {
     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() {
+    // 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) {
     apiClient = new VibescopeApiClient(config);
     return apiClient;

package/dist/api-client/milestones.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 declare function createMilestonesMethods(proxy: ProxyFn): MilestonesMethods;

package/dist/api-client/milestones.js

@@ -0,0 +1,30 @@
+/**
+ * Milestones API Methods
+ *
+ * Handles task milestones for tracking granular progress within tasks.
+ */
+export function createMilestonesMethods(proxy) {
+    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/dist/api-client/validation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 declare function createValidationMethods(proxy: ProxyFn): ValidationMethods;

package/dist/api-client/validation.js

@@ -0,0 +1,23 @@
+/**
+ * Validation API Methods
+ *
+ * Handles task validation workflow for code review and approval.
+ */
+export function createValidationMethods(proxy) {
+    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/dist/api-client.d.ts

@@ -60,6 +60,10 @@ export declare 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;

package/dist/cli-init.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Vibescope Init CLI
+ *
+ * Usage: npx vibescope init
+ *
+ * Detects installed AI agents, configures MCP, and stores credentials.
+ */
+export declare function readCredentials(): {
+    apiKey?: string;
+};
+export declare function writeCredentials(apiKey: string): void;
+/**
+ * Resolve API key from env var or credentials file.
+ * Used by the MCP server at startup.
+ */
+export declare function resolveApiKey(): string | null;