@vibescope/mcp-server 0.3.1 → 0.4.0

package/dist/api-client/index.js

@@ -0,0 +1,261 @@
+/**
+ * Vibescope API Client
+ *
+ * HTTP client for communicating with the Vibescope API.
+ * All database operations are handled server-side through these endpoints.
+ *
+ * This module composes domain-specific API methods into a unified client.
+ */
+import { createSessionMethods } from './session.js';
+import { createProjectMethods } from './project.js';
+import { createBlockersMethods } from './blockers.js';
+import { createCostMethods } from './cost.js';
+import { createWorktreesMethods } from './worktrees.js';
+import { createDiscoveryMethods } from './discovery.js';
+import { createDecisionsMethods } from './decisions.js';
+import { createIdeasMethods } from './ideas.js';
+import { createTasksMethods } from './tasks.js';
+const DEFAULT_API_URL = 'https://vibescope.dev';
+// Retry configuration defaults
+const DEFAULT_RETRY_STATUS_CODES = [429, 503, 504];
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BASE_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 30000;
+/**
+ * Calculate delay for exponential backoff with jitter
+ */
+function calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs, retryAfter) {
+    if (retryAfter !== undefined && retryAfter > 0) {
+        return Math.min(retryAfter * 1000, maxDelayMs);
+    }
+    const exponentialDelay = baseDelayMs * Math.pow(2, attempt);
+    const jitter = Math.random() * 0.3 * exponentialDelay;
+    return Math.min(exponentialDelay + jitter, maxDelayMs);
+}
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+export class VibescopeApiClient {
+    apiKey;
+    baseUrl;
+    retryConfig;
+    // Domain method implementations
+    sessionMethods;
+    projectMethods;
+    blockersMethods;
+    costMethods;
+    worktreesMethods;
+    discoveryMethods;
+    decisionsMethods;
+    ideasMethods;
+    tasksMethods;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl || process.env.VIBESCOPE_API_URL || DEFAULT_API_URL;
+        this.retryConfig = {
+            maxRetries: config.retry?.maxRetries ?? DEFAULT_MAX_RETRIES,
+            baseDelayMs: config.retry?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS,
+            maxDelayMs: config.retry?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS,
+            retryStatusCodes: config.retry?.retryStatusCodes ?? DEFAULT_RETRY_STATUS_CODES,
+        };
+        // Create bound request and proxy functions for domain modules
+        const request = this.request.bind(this);
+        const proxy = this.proxy.bind(this);
+        const getApiKey = () => this.apiKey;
+        // Initialize domain methods
+        this.sessionMethods = createSessionMethods(request, getApiKey);
+        this.projectMethods = createProjectMethods(request);
+        this.blockersMethods = createBlockersMethods(request);
+        this.costMethods = createCostMethods(request);
+        this.worktreesMethods = createWorktreesMethods(request);
+        this.discoveryMethods = createDiscoveryMethods(request);
+        this.decisionsMethods = createDecisionsMethods(proxy);
+        this.ideasMethods = createIdeasMethods(proxy);
+        this.tasksMethods = createTasksMethods(request, proxy);
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const { maxRetries, baseDelayMs, maxDelayMs, retryStatusCodes } = this.retryConfig;
+        let lastError = null;
+        let lastResponse = null;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const response = await fetch(url, {
+                    method,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-API-Key': this.apiKey
+                    },
+                    body: body ? JSON.stringify(body) : undefined
+                });
+                if (retryStatusCodes.includes(response.status) && attempt < maxRetries) {
+                    lastResponse = response;
+                    const retryAfterHeader = response.headers.get('Retry-After');
+                    let retryAfter;
+                    if (retryAfterHeader) {
+                        const parsed = parseInt(retryAfterHeader, 10);
+                        if (!isNaN(parsed)) {
+                            retryAfter = parsed;
+                        }
+                    }
+                    const delay = calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs, retryAfter);
+                    await sleep(delay);
+                    continue;
+                }
+                if (!response.ok) {
+                    const errorData = await response.json().catch(() => ({}));
+                    return {
+                        ok: false,
+                        status: response.status,
+                        error: errorData.error || errorData.message || `HTTP ${response.status}`
+                    };
+                }
+                const data = await response.json();
+                return {
+                    ok: true,
+                    status: response.status,
+                    data
+                };
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < maxRetries) {
+                    const delay = calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs);
+                    await sleep(delay);
+                    continue;
+                }
+            }
+        }
+        if (lastResponse && !lastResponse.ok) {
+            return {
+                ok: false,
+                status: lastResponse.status,
+                error: `Request failed after ${maxRetries + 1} attempts with status ${lastResponse.status}`
+            };
+        }
+        return {
+            ok: false,
+            status: 0,
+            error: lastError?.message || 'Request failed after all retries'
+        };
+    }
+    /**
+     * Generic proxy method for operations that go through the MCP proxy endpoint
+     */
+    async proxy(operation, args, sessionContext) {
+        return this.request('POST', '/api/mcp/proxy', {
+            operation,
+            args,
+            ...sessionContext
+        });
+    }
+    // ============================================================================
+    // Session methods (delegated)
+    // ============================================================================
+    validateAuth = () => this.sessionMethods.validateAuth();
+    startSession = (params) => this.sessionMethods.startSession(params);
+    heartbeat = (sessionId, options) => this.sessionMethods.heartbeat(sessionId, options);
+    endSession = (sessionId) => this.sessionMethods.endSession(sessionId);
+    signalIdle = (sessionId) => this.sessionMethods.signalIdle(sessionId);
+    syncSession = (sessionId, params) => this.sessionMethods.syncSession(sessionId, params);
+    confirmAgentSetup = (projectId, agentType) => this.sessionMethods.confirmAgentSetup(projectId, agentType);
+    // ============================================================================
+    // Project methods (delegated)
+    // ============================================================================
+    listProjects = () => this.projectMethods.listProjects();
+    createProject = (params) => this.projectMethods.createProject(params);
+    getProject = (projectId, gitUrl) => this.projectMethods.getProject(projectId, gitUrl);
+    updateProject = (projectId, updates) => this.projectMethods.updateProject(projectId, updates);
+    getGitWorkflow = (projectId, taskId) => this.projectMethods.getGitWorkflow(projectId, taskId);
+    updateProjectReadme = (projectId, readmeContent) => this.projectMethods.updateProjectReadme(projectId, readmeContent);
+    getProjectSummary = (projectId) => this.projectMethods.getProjectSummary(projectId);
+    // ============================================================================
+    // Blockers methods (delegated)
+    // ============================================================================
+    getBlockers = (projectId, params) => this.blockersMethods.getBlockers(projectId, params);
+    addBlocker = (projectId, description, sessionId) => this.blockersMethods.addBlocker(projectId, description, sessionId);
+    resolveBlocker = (blockerId, resolutionNote) => this.blockersMethods.resolveBlocker(blockerId, resolutionNote);
+    deleteBlocker = (blockerId) => this.blockersMethods.deleteBlocker(blockerId);
+    getBlockersStats = (projectId) => this.blockersMethods.getBlockersStats(projectId);
+    // ============================================================================
+    // Cost methods (delegated)
+    // ============================================================================
+    getCostSummary = (projectId, params) => this.costMethods.getCostSummary(projectId, params);
+    getCostAlerts = () => this.costMethods.getCostAlerts();
+    addCostAlert = (params) => this.costMethods.addCostAlert(params);
+    updateCostAlert = (alertId, updates) => this.costMethods.updateCostAlert(alertId, updates);
+    deleteCostAlert = (alertId) => this.costMethods.deleteCostAlert(alertId);
+    getTaskCosts = (projectId, limit) => this.costMethods.getTaskCosts(projectId, limit);
+    getBodyOfWorkCosts = (params) => this.costMethods.getBodyOfWorkCosts(params);
+    getSprintCosts = (params) => this.costMethods.getSprintCosts(params);
+    getTokenUsage = () => this.costMethods.getTokenUsage();
+    reportTokenUsage = (sessionId, params) => this.costMethods.reportTokenUsage(sessionId, params);
+    // ============================================================================
+    // Worktrees methods (delegated)
+    // ============================================================================
+    getStaleWorktrees = (projectId, params) => this.worktreesMethods.getStaleWorktrees(projectId, params);
+    clearWorktreePath = (taskId) => this.worktreesMethods.clearWorktreePath(taskId);
+    // ============================================================================
+    // Discovery methods (delegated)
+    // ============================================================================
+    queryKnowledgeBase = (projectId, params) => this.discoveryMethods.queryKnowledgeBase(projectId, params);
+    getHelpTopic = (slug) => this.discoveryMethods.getHelpTopic(slug);
+    getHelpTopics = () => this.discoveryMethods.getHelpTopics();
+    // ============================================================================
+    // Decisions methods (delegated)
+    // ============================================================================
+    getDecisions = (projectId, options) => this.decisionsMethods.getDecisions(projectId, options);
+    getDecision = (decisionId) => this.decisionsMethods.getDecision(decisionId);
+    logDecision = (projectId, params, sessionId) => this.decisionsMethods.logDecision(projectId, params, sessionId);
+    deleteDecision = (decisionId) => this.decisionsMethods.deleteDecision(decisionId);
+    getDecisionsStats = (projectId) => this.decisionsMethods.getDecisionsStats(projectId);
+    // ============================================================================
+    // Ideas methods (delegated)
+    // ============================================================================
+    getIdeas = (projectId, params) => this.ideasMethods.getIdeas(projectId, params);
+    getIdea = (ideaId) => this.ideasMethods.getIdea(ideaId);
+    addIdea = (projectId, params, sessionId) => this.ideasMethods.addIdea(projectId, params, sessionId);
+    updateIdea = (ideaId, updates) => this.ideasMethods.updateIdea(ideaId, updates);
+    deleteIdea = (ideaId) => this.ideasMethods.deleteIdea(ideaId);
+    convertIdeaToTask = (ideaId, params) => this.ideasMethods.convertIdeaToTask(ideaId, params);
+    // ============================================================================
+    // Tasks methods (delegated)
+    // ============================================================================
+    getTasks = (projectId, params) => this.tasksMethods.getTasks(projectId, params);
+    createTask = (projectId, params) => this.tasksMethods.createTask(projectId, params);
+    getNextTask = (projectId, sessionId) => this.tasksMethods.getNextTask(projectId, sessionId);
+    getTask = (taskId) => this.tasksMethods.getTask(taskId);
+    getTaskById = (taskId, params) => this.tasksMethods.getTaskById(taskId, params);
+    searchTasks = (projectId, params) => this.tasksMethods.searchTasks(projectId, params);
+    getTasksByPriority = (projectId, params) => this.tasksMethods.getTasksByPriority(projectId, params);
+    getRecentTasks = (projectId, params) => this.tasksMethods.getRecentTasks(projectId, params);
+    getTaskStats = (projectId) => this.tasksMethods.getTaskStats(projectId);
+    updateTask = (taskId, updates) => this.tasksMethods.updateTask(taskId, updates);
+    completeTask = (taskId, params) => this.tasksMethods.completeTask(taskId, params);
+    deleteTask = (taskId) => this.tasksMethods.deleteTask(taskId);
+    releaseTask = (taskId, params) => this.tasksMethods.releaseTask(taskId, params);
+    cancelTask = (taskId, params) => this.tasksMethods.cancelTask(taskId, params);
+    addTaskReference = (taskId, url, label) => this.tasksMethods.addTaskReference(taskId, url, label);
+    removeTaskReference = (taskId, url) => this.tasksMethods.removeTaskReference(taskId, url);
+    batchUpdateTasks = (updates) => this.tasksMethods.batchUpdateTasks(updates);
+    batchCompleteTasks = (completions) => this.tasksMethods.batchCompleteTasks(completions);
+}
+// 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');
+        }
+        apiClient = new VibescopeApiClient({ apiKey });
+    }
+    return apiClient;
+}
+export function initApiClient(config) {
+    apiClient = new VibescopeApiClient(config);
+    return apiClient;
+}

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

@@ -0,0 +1,132 @@
+/**
+ * Project API Methods
+ *
+ * Methods for project management:
+ * - listProjects: List all projects
+ * - createProject: Create a new project
+ * - getProject: Get project details
+ * - updateProject: Update project settings
+ * - getGitWorkflow: Get git workflow configuration
+ * - updateProjectReadme: Update project README
+ * - getProjectSummary: Get project summary
+ */
+import type { ApiResponse, RequestFn } from './types.js';
+export interface ProjectMethods {
+    listProjects(): Promise<ApiResponse<{
+        projects: Array<{
+            id: string;
+            name: string;
+            description?: string;
+            status: string;
+            git_url?: string;
+            goal?: string;
+            tech_stack?: string[];
+        }>;
+    }>>;
+    createProject(params: {
+        name: string;
+        description?: string;
+        goal?: string;
+        git_url?: string;
+        tech_stack?: string[];
+    }): Promise<ApiResponse<{
+        success: boolean;
+        project: {
+            id: string;
+            name: string;
+        };
+    }>>;
+    getProject(projectId: string, gitUrl?: string): Promise<ApiResponse<{
+        found: boolean;
+        project?: {
+            id: string;
+            name: string;
+            description?: string;
+            goal?: string;
+            status: string;
+            git_url?: string;
+            agent_instructions?: string;
+            tech_stack?: string[];
+            git_workflow?: string;
+            git_main_branch?: string;
+            git_develop_branch?: string;
+            git_auto_branch?: boolean;
+            git_auto_tag?: boolean;
+            deployment_instructions?: string;
+        };
+        active_tasks?: Array<{
+            id: string;
+            title: string;
+            description?: string;
+            priority: number;
+            status: string;
+            progress_percentage?: number;
+            estimated_minutes?: number;
+        }>;
+        open_blockers?: Array<{
+            id: string;
+            description: string;
+        }>;
+        recent_decisions?: Array<{
+            id: string;
+            title: string;
+            description?: string;
+        }>;
+        message?: string;
+    }>>;
+    updateProject(projectId: string, updates: {
+        name?: string;
+        description?: string;
+        goal?: string;
+        git_url?: string;
+        tech_stack?: string[];
+        status?: string;
+        git_workflow?: string;
+        git_main_branch?: string;
+        git_develop_branch?: string;
+        git_auto_branch?: boolean;
+        git_auto_tag?: boolean;
+        deployment_instructions?: string;
+        agent_instructions?: string;
+        git_delete_branch_on_merge?: boolean;
+        require_pr_for_validation?: boolean;
+        auto_merge_on_approval?: boolean;
+        validation_required?: boolean;
+        default_task_priority?: number;
+        require_time_estimates?: boolean;
+        fallback_activities_enabled?: boolean;
+        preferred_fallback_activities?: string[];
+    }): Promise<ApiResponse<{
+        success: boolean;
+        project_id: string;
+    }>>;
+    getGitWorkflow(projectId: string, taskId?: string): Promise<ApiResponse<{
+        workflow: string;
+        main_branch: string;
+        develop_branch?: string;
+        suggested_branch?: string;
+        base_branch?: string;
+    }>>;
+    updateProjectReadme(projectId: string, readmeContent: string): Promise<ApiResponse<{
+        success: boolean;
+        project_id: string;
+    }>>;
+    getProjectSummary(projectId: string): Promise<ApiResponse<{
+        project: {
+            id: string;
+            name: string;
+            description?: string;
+            goal?: string;
+            status: string;
+        };
+        stats: {
+            total_tasks: number;
+            completed_tasks: number;
+            in_progress_tasks: number;
+            pending_tasks: number;
+            open_blockers: number;
+            total_decisions: number;
+        };
+    }>>;
+}
+export declare function createProjectMethods(request: RequestFn): ProjectMethods;

package/dist/api-client/project.js

@@ -0,0 +1,45 @@
+/**
+ * Project API Methods
+ *
+ * Methods for project management:
+ * - listProjects: List all projects
+ * - createProject: Create a new project
+ * - getProject: Get project details
+ * - updateProject: Update project settings
+ * - getGitWorkflow: Get git workflow configuration
+ * - updateProjectReadme: Update project README
+ * - getProjectSummary: Get project summary
+ */
+export function createProjectMethods(request) {
+    return {
+        async listProjects() {
+            return request('GET', '/api/mcp/projects');
+        },
+        async createProject(params) {
+            return request('POST', '/api/mcp/projects', params);
+        },
+        async getProject(projectId, gitUrl) {
+            const url = gitUrl
+                ? `/api/mcp/projects/${projectId}?git_url=${encodeURIComponent(gitUrl)}`
+                : `/api/mcp/projects/${projectId}`;
+            return request('GET', url);
+        },
+        async updateProject(projectId, updates) {
+            return request('PATCH', `/api/mcp/projects/${projectId}`, updates);
+        },
+        async getGitWorkflow(projectId, taskId) {
+            const url = taskId
+                ? `/api/mcp/projects/${projectId}/git-workflow?task_id=${taskId}`
+                : `/api/mcp/projects/${projectId}/git-workflow`;
+            return request('GET', url);
+        },
+        async updateProjectReadme(projectId, readmeContent) {
+            return request('PATCH', `/api/mcp/projects/${projectId}/readme`, {
+                readme_content: readmeContent
+            });
+        },
+        async getProjectSummary(projectId) {
+            return request('GET', `/api/mcp/projects/${projectId}/summary`);
+        }
+    };
+}

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

@@ -0,0 +1,163 @@
+/**
+ * Session API Methods
+ *
+ * Methods for session lifecycle management:
+ * - validateAuth: Validate API key
+ * - startSession: Start a new work session
+ * - heartbeat: Maintain active status
+ * - endSession: End session and release tasks
+ * - signalIdle: Signal agent is idle
+ * - syncSession: Sync session state
+ * - confirmAgentSetup: Confirm agent setup completion
+ */
+import type { ApiResponse, RequestFn } from './types.js';
+export interface SessionMethods {
+    validateAuth(): Promise<ApiResponse<{
+        valid: boolean;
+        user_id: string;
+        api_key_id: string;
+        key_name: string;
+    }>>;
+    startSession(params: {
+        project_id?: string;
+        git_url?: string;
+        mode?: 'lite' | 'full';
+        model?: string;
+        role?: string;
+        hostname?: string;
+        agent_type?: string;
+        agent_name?: string;
+    }): Promise<ApiResponse<{
+        session_started: boolean;
+        session_id?: string;
+        persona?: string;
+        role?: string;
+        project?: {
+            id: string;
+            name: string;
+            description?: string;
+            goal?: string;
+            status?: string;
+            git_url?: string;
+            agent_instructions?: string;
+            tech_stack?: string[];
+            git_workflow?: string;
+            git_main_branch?: string;
+            git_develop_branch?: string;
+            git_auto_branch?: boolean;
+        };
+        active_tasks?: Array<{
+            id: string;
+            title: string;
+            status: string;
+            priority: number;
+            progress_percentage?: number;
+            estimated_minutes?: number;
+        }>;
+        blockers?: Array<{
+            id: string;
+            description: string;
+            status: string;
+        }>;
+        next_task?: {
+            id: string;
+            title: string;
+            priority: number;
+            estimated_minutes?: number;
+        } | null;
+        pending_requests?: Array<{
+            id: string;
+            request_type: string;
+            message: string;
+            created_at: string;
+        }>;
+        pending_requests_count?: number;
+        URGENT_QUESTIONS?: {
+            count: number;
+            oldest_waiting_minutes: number;
+            action_required: string;
+            requests: Array<{
+                id: string;
+                message: string;
+                waiting_minutes: number;
+            }>;
+        };
+        directive?: string;
+        blockers_count?: number;
+        validation_count?: number;
+        project_not_found?: boolean;
+        message?: string;
+        suggestion?: {
+            action: string;
+            example: string;
+            note: string;
+        };
+        agent_setup?: {
+            agent_type: string;
+            is_new_agent_type: boolean;
+            setup_required: boolean;
+            instructions: string;
+            config_file: string;
+            template_url?: string;
+            steps: string[];
+        };
+        stale_worktrees?: Array<{
+            task_id: string;
+            task_title: string;
+            worktree_path: string;
+            worktree_hostname?: string | null;
+        }>;
+        stale_worktrees_count?: number;
+        cleanup_action?: string;
+        awaiting_validation?: Array<{
+            id: string;
+            title?: string;
+        }>;
+        validation_priority?: boolean;
+        next_action?: string;
+        error?: string;
+    }>>;
+    heartbeat(sessionId: string, options?: {
+        current_worktree_path?: string | null;
+        hostname?: string;
+    }): Promise<ApiResponse<{
+        success: boolean;
+        session_id: string;
+        timestamp: string;
+    }>>;
+    endSession(sessionId: string): Promise<ApiResponse<{
+        success: boolean;
+        ended_session_id?: string;
+        session_summary?: {
+            agent_name: string;
+            tasks_completed_this_session: number;
+            tasks_awaiting_validation: number;
+            tasks_released: number;
+        };
+        reminders?: string[];
+    }>>;
+    signalIdle(sessionId: string): Promise<ApiResponse<{
+        success: boolean;
+        session_id: string;
+        status: string;
+        message: string;
+    }>>;
+    syncSession(sessionId: string, params?: {
+        include_project?: boolean;
+        include_tasks?: boolean;
+    }): Promise<ApiResponse<{
+        session: {
+            id: string;
+            status: string;
+            agent_name: string;
+        };
+        project?: unknown;
+        tasks?: unknown[];
+    }>>;
+    confirmAgentSetup(projectId: string, agentType: string): Promise<ApiResponse<{
+        success: boolean;
+        project_id: string;
+        agent_type: string;
+    }>>;
+}
+export declare function createSessionMethods(request: RequestFn, getApiKey: () => string): SessionMethods;

package/dist/api-client/session.js

@@ -0,0 +1,52 @@
+/**
+ * Session API Methods
+ *
+ * Methods for session lifecycle management:
+ * - validateAuth: Validate API key
+ * - startSession: Start a new work session
+ * - heartbeat: Maintain active status
+ * - endSession: End session and release tasks
+ * - signalIdle: Signal agent is idle
+ * - syncSession: Sync session state
+ * - confirmAgentSetup: Confirm agent setup completion
+ */
+export function createSessionMethods(request, getApiKey) {
+    return {
+        async validateAuth() {
+            return request('POST', '/api/mcp/auth/validate', {
+                api_key: getApiKey()
+            });
+        },
+        async startSession(params) {
+            return request('POST', '/api/mcp/sessions/start', params);
+        },
+        async heartbeat(sessionId, options) {
+            return request('POST', '/api/mcp/sessions/heartbeat', {
+                session_id: sessionId,
+                ...options
+            });
+        },
+        async endSession(sessionId) {
+            return request('POST', '/api/mcp/sessions/end', {
+                session_id: sessionId
+            });
+        },
+        async signalIdle(sessionId) {
+            return request('POST', '/api/mcp/sessions/idle', {
+                session_id: sessionId
+            });
+        },
+        async syncSession(sessionId, params) {
+            return request('POST', '/api/mcp/sessions/sync', {
+                session_id: sessionId,
+                ...params
+            });
+        },
+        async confirmAgentSetup(projectId, agentType) {
+            return request('POST', '/api/mcp/agent-setup/confirm', {
+                project_id: projectId,
+                agent_type: agentType
+            });
+        }
+    };
+}