@vibescope/mcp-server 0.0.1

package/dist/handlers/checkouts.js

@@ -0,0 +1,377 @@
+/**
+ * File Checkout Handlers
+ *
+ * Handles file checkout/checkin for multi-agent coordination:
+ * - checkout_file: Reserve a file for editing
+ * - checkin_file: Release a file after editing
+ * - get_file_checkouts: List active and recent checkouts
+ * - abandon_checkout: Force-release a checkout
+ */
+import { validateRequired, validateUUID } from '../validators.js';
+/**
+ * Verify the user owns or has access to the project
+ * This is needed because MCP server uses service_role which bypasses RLS
+ */
+async function verifyProjectAccess(ctx, projectId) {
+    const { supabase, auth } = ctx;
+    // Check if user owns the project
+    const { data: ownedProject } = await supabase
+        .from('projects')
+        .select('id')
+        .eq('id', projectId)
+        .eq('user_id', auth.userId)
+        .single();
+    if (ownedProject)
+        return;
+    // Check if project is shared with user's organization (for org-scoped keys)
+    if (auth.scope === 'organization' && auth.organizationId) {
+        const { data: sharedProject } = await supabase
+            .from('project_shares')
+            .select('project_id')
+            .eq('project_id', projectId)
+            .eq('organization_id', auth.organizationId)
+            .single();
+        if (sharedProject)
+            return;
+    }
+    throw new Error('Project not found or access denied');
+}
+/**
+ * Checkout a file for editing
+ * Prevents other agents from editing the same file
+ */
+export const checkoutFile = async (args, ctx) => {
+    const { project_id, file_path, reason } = args;
+    validateRequired(project_id, 'project_id');
+    validateUUID(project_id, 'project_id');
+    validateRequired(file_path, 'file_path');
+    // Verify user has access to this project
+    await verifyProjectAccess(ctx, project_id);
+    const { supabase, session } = ctx;
+    // Check if file is already checked out
+    const { data: existing } = await supabase
+        .from('file_checkouts')
+        .select('id, checked_out_by_session_id, checked_out_at')
+        .eq('project_id', project_id)
+        .eq('file_path', file_path)
+        .eq('status', 'checked_out')
+        .single();
+    if (existing) {
+        // Get session info for better error message
+        const { data: sessionInfo } = await supabase
+            .from('agent_sessions')
+            .select('persona, instance_id')
+            .eq('id', existing.checked_out_by_session_id)
+            .single();
+        const checkedOutBy = sessionInfo?.persona || sessionInfo?.instance_id?.slice(0, 8) || 'another agent';
+        const minutesAgo = Math.round((Date.now() - new Date(existing.checked_out_at).getTime()) / 60000);
+        return {
+            result: {
+                success: false,
+                error: 'File already checked out',
+                checked_out_by: checkedOutBy,
+                checked_out_minutes_ago: minutesAgo,
+                checkout_id: existing.id,
+                hint: 'Wait for the file to be checked in, or use abandon_checkout if the session is stale',
+            },
+        };
+    }
+    // Create the checkout
+    const { data, error } = await supabase
+        .from('file_checkouts')
+        .insert({
+        project_id,
+        file_path,
+        checked_out_by_session_id: session.currentSessionId,
+        checkout_reason: reason || null,
+    })
+        .select('id')
+        .single();
+    if (error) {
+        // Handle unique constraint violation (race condition)
+        if (error.code === '23505') {
+            return {
+                result: {
+                    success: false,
+                    error: 'File was just checked out by another agent',
+                    hint: 'Retry after a moment or choose a different file',
+                },
+            };
+        }
+        throw new Error(`Failed to checkout file: ${error.message}`);
+    }
+    return {
+        result: {
+            success: true,
+            checkout_id: data.id,
+            file_path,
+            message: `File checked out successfully. Remember to checkin when done.`,
+        },
+    };
+};
+/**
+ * Checkin a file after editing
+ * Releases the file for other agents to edit
+ */
+export const checkinFile = async (args, ctx) => {
+    const { checkout_id, file_path, project_id, summary } = args;
+    const { supabase, session } = ctx;
+    // Allow checkin by checkout_id OR by file_path + project_id
+    let checkoutId = checkout_id;
+    let verifiedProjectId;
+    if (!checkoutId) {
+        if (!file_path || !project_id) {
+            throw new Error('Either checkout_id or both file_path and project_id are required');
+        }
+        validateUUID(project_id, 'project_id');
+        // Verify user has access to this project
+        await verifyProjectAccess(ctx, project_id);
+        verifiedProjectId = project_id;
+        // Find the checkout by file path
+        const { data: checkout, error: findError } = await supabase
+            .from('file_checkouts')
+            .select('id')
+            .eq('project_id', project_id)
+            .eq('file_path', file_path)
+            .eq('status', 'checked_out')
+            .single();
+        if (findError || !checkout) {
+            return {
+                result: {
+                    success: false,
+                    error: 'No active checkout found for this file',
+                    hint: 'The file may not be checked out or was already checked in',
+                },
+            };
+        }
+        checkoutId = checkout.id;
+    }
+    else {
+        validateUUID(checkoutId, 'checkout_id');
+        // Get checkout's project_id to verify access
+        const { data: checkout } = await supabase
+            .from('file_checkouts')
+            .select('project_id')
+            .eq('id', checkoutId)
+            .single();
+        if (!checkout) {
+            return {
+                result: {
+                    success: false,
+                    error: 'Checkout not found',
+                },
+            };
+        }
+        // Verify user has access to this project
+        await verifyProjectAccess(ctx, checkout.project_id);
+        verifiedProjectId = checkout.project_id;
+    }
+    // Perform the checkin
+    const { data, error } = await supabase
+        .from('file_checkouts')
+        .update({
+        status: 'checked_in',
+        checked_in_at: new Date().toISOString(),
+        checked_in_by_session_id: session.currentSessionId,
+        checkin_summary: summary || null,
+        updated_at: new Date().toISOString(),
+    })
+        .eq('id', checkoutId)
+        .eq('status', 'checked_out')
+        .select('file_path')
+        .single();
+    if (error || !data) {
+        return {
+            result: {
+                success: false,
+                error: 'Failed to checkin file',
+                hint: 'The checkout may have already been checked in or abandoned',
+            },
+        };
+    }
+    return {
+        result: {
+            success: true,
+            checkout_id: checkoutId,
+            file_path: data.file_path,
+            message: 'File checked in successfully',
+        },
+    };
+};
+/**
+ * Get file checkouts for a project
+ */
+export const getFileCheckouts = async (args, ctx) => {
+    const { project_id, status, include_completed = false, limit = 50 } = args;
+    validateRequired(project_id, 'project_id');
+    validateUUID(project_id, 'project_id');
+    // Verify user has access to this project
+    await verifyProjectAccess(ctx, project_id);
+    const { supabase } = ctx;
+    let query = supabase
+        .from('file_checkouts')
+        .select(`
+			id,
+			file_path,
+			status,
+			checkout_reason,
+			checkin_summary,
+			checked_out_at,
+			checked_in_at,
+			checked_out_by_session_id,
+			checked_in_by_session_id
+		`)
+        .eq('project_id', project_id)
+        .order('checked_out_at', { ascending: false })
+        .limit(limit);
+    if (status) {
+        query = query.eq('status', status);
+    }
+    else if (!include_completed) {
+        query = query.eq('status', 'checked_out');
+    }
+    const { data, error } = await query;
+    if (error)
+        throw new Error(`Failed to fetch checkouts: ${error.message}`);
+    // Get session info for active checkouts
+    const sessionIds = [...new Set((data || [])
+            .map(c => c.checked_out_by_session_id)
+            .filter(Boolean))];
+    let sessionMap = {};
+    if (sessionIds.length > 0) {
+        const { data: sessions } = await supabase
+            .from('agent_sessions')
+            .select('id, persona, instance_id')
+            .in('id', sessionIds);
+        sessionMap = (sessions || []).reduce((acc, s) => {
+            acc[s.id] = { persona: s.persona, instance_id: s.instance_id };
+            return acc;
+        }, {});
+    }
+    const checkouts = (data || []).map(c => ({
+        ...c,
+        checked_out_by: c.checked_out_by_session_id
+            ? sessionMap[c.checked_out_by_session_id]?.persona ||
+                sessionMap[c.checked_out_by_session_id]?.instance_id?.slice(0, 8) ||
+                'unknown'
+            : null,
+    }));
+    const activeCount = checkouts.filter(c => c.status === 'checked_out').length;
+    return {
+        result: {
+            checkouts,
+            active_count: activeCount,
+            total_count: checkouts.length,
+        },
+    };
+};
+/**
+ * Abandon a checkout (force release)
+ * Use when the original agent session died or is stuck
+ */
+export const abandonCheckout = async (args, ctx) => {
+    const { checkout_id, reason } = args;
+    validateRequired(checkout_id, 'checkout_id');
+    validateUUID(checkout_id, 'checkout_id');
+    const { supabase, session } = ctx;
+    // First get the checkout to verify project access
+    const { data: checkout } = await supabase
+        .from('file_checkouts')
+        .select('project_id')
+        .eq('id', checkout_id)
+        .single();
+    if (!checkout) {
+        return {
+            result: {
+                success: false,
+                error: 'Checkout not found',
+            },
+        };
+    }
+    // Verify user has access to this project
+    await verifyProjectAccess(ctx, checkout.project_id);
+    const { data, error } = await supabase
+        .from('file_checkouts')
+        .update({
+        status: 'abandoned',
+        checkin_summary: reason || 'Checkout abandoned',
+        checked_in_at: new Date().toISOString(),
+        checked_in_by_session_id: session.currentSessionId,
+        updated_at: new Date().toISOString(),
+    })
+        .eq('id', checkout_id)
+        .eq('status', 'checked_out')
+        .select('file_path')
+        .single();
+    if (error || !data) {
+        return {
+            result: {
+                success: false,
+                error: 'Failed to abandon checkout',
+                hint: 'The checkout may have already been checked in or abandoned',
+            },
+        };
+    }
+    return {
+        result: {
+            success: true,
+            checkout_id,
+            file_path: data.file_path,
+            message: 'Checkout abandoned successfully. File is now available.',
+        },
+    };
+};
+/**
+ * Check if a file is available for checkout
+ */
+export const isFileAvailable = async (args, ctx) => {
+    const { project_id, file_path } = args;
+    validateRequired(project_id, 'project_id');
+    validateUUID(project_id, 'project_id');
+    validateRequired(file_path, 'file_path');
+    // Verify user has access to this project
+    await verifyProjectAccess(ctx, project_id);
+    const { supabase } = ctx;
+    const { data } = await supabase
+        .from('file_checkouts')
+        .select('id, checked_out_by_session_id, checked_out_at')
+        .eq('project_id', project_id)
+        .eq('file_path', file_path)
+        .eq('status', 'checked_out')
+        .single();
+    if (!data) {
+        return {
+            result: {
+                available: true,
+                file_path,
+            },
+        };
+    }
+    // Get session info
+    const { data: sessionInfo } = await supabase
+        .from('agent_sessions')
+        .select('persona, instance_id')
+        .eq('id', data.checked_out_by_session_id)
+        .single();
+    const checkedOutBy = sessionInfo?.persona || sessionInfo?.instance_id?.slice(0, 8) || 'another agent';
+    const minutesAgo = Math.round((Date.now() - new Date(data.checked_out_at).getTime()) / 60000);
+    return {
+        result: {
+            available: false,
+            file_path,
+            checked_out_by: checkedOutBy,
+            checked_out_minutes_ago: minutesAgo,
+            checkout_id: data.id,
+        },
+    };
+};
+/**
+ * Checkout handlers registry
+ */
+export const checkoutHandlers = {
+    checkout_file: checkoutFile,
+    checkin_file: checkinFile,
+    get_file_checkouts: getFileCheckouts,
+    abandon_checkout: abandonCheckout,
+    is_file_available: isFileAvailable,
+};

package/dist/handlers/cost.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Cost Handlers
+ *
+ * Handles cost monitoring and alerts:
+ * - get_cost_summary
+ * - get_cost_alerts
+ * - add_cost_alert
+ * - update_cost_alert
+ * - delete_cost_alert
+ */
+import type { Handler, HandlerRegistry } from './types.js';
+/**
+ * Get cost summary for a project (daily, weekly, or monthly)
+ */
+export declare const getCostSummary: Handler;
+/**
+ * Get cost alerts for the current user
+ */
+export declare const getCostAlerts: Handler;
+/**
+ * Add a cost alert
+ */
+export declare const addCostAlert: Handler;
+/**
+ * Update a cost alert
+ */
+export declare const updateCostAlert: Handler;
+/**
+ * Delete a cost alert
+ */
+export declare const deleteCostAlert: Handler;
+/**
+ * Get task costs for a project
+ */
+export declare const getTaskCosts: Handler;
+/**
+ * Cost handlers registry
+ */
+export declare const costHandlers: HandlerRegistry;

package/dist/handlers/cost.js

@@ -0,0 +1,247 @@
+/**
+ * Cost Handlers
+ *
+ * Handles cost monitoring and alerts:
+ * - get_cost_summary
+ * - get_cost_alerts
+ * - add_cost_alert
+ * - update_cost_alert
+ * - delete_cost_alert
+ */
+/**
+ * Get cost summary for a project (daily, weekly, or monthly)
+ */
+export const getCostSummary = async (args, ctx) => {
+    const { project_id, period = 'daily', limit = 30 } = args;
+    const { supabase } = ctx;
+    if (!project_id) {
+        return {
+            result: { error: 'project_id is required' },
+            isError: true,
+        };
+    }
+    // Select the appropriate view based on period
+    const viewName = `${period}_cost_summary`;
+    const { data, error } = await supabase
+        .from(viewName)
+        .select('*')
+        .eq('project_id', project_id)
+        .order(period === 'daily' ? 'date' : period === 'weekly' ? 'week_start' : 'month_start', { ascending: false })
+        .limit(limit);
+    if (error) {
+        return {
+            result: { error: `Failed to get cost summary: ${error.message}` },
+            isError: true,
+        };
+    }
+    // Calculate totals
+    const totals = (data || []).reduce((acc, row) => ({
+        sessions: acc.sessions + (row.session_count || 0),
+        tokens: acc.tokens + (row.total_tokens || 0),
+        calls: acc.calls + (row.total_calls || 0),
+        cost: acc.cost + parseFloat(row.estimated_cost_usd || '0'),
+    }), { sessions: 0, tokens: 0, calls: 0, cost: 0 });
+    return {
+        result: {
+            period,
+            project_id,
+            summary: data || [],
+            totals: {
+                ...totals,
+                cost: Math.round(totals.cost * 100) / 100,
+            },
+        },
+    };
+};
+/**
+ * Get cost alerts for the current user
+ */
+export const getCostAlerts = async (args, ctx) => {
+    const { project_id } = args;
+    const { supabase, auth } = ctx;
+    let query = supabase
+        .from('cost_alerts')
+        .select('*')
+        .eq('user_id', auth.userId)
+        .order('threshold_amount', { ascending: true });
+    if (project_id) {
+        query = query.eq('project_id', project_id);
+    }
+    const { data, error } = await query;
+    if (error) {
+        return {
+            result: { error: `Failed to get cost alerts: ${error.message}` },
+            isError: true,
+        };
+    }
+    return {
+        result: {
+            alerts: data || [],
+            count: data?.length || 0,
+        },
+    };
+};
+/**
+ * Add a cost alert
+ */
+export const addCostAlert = async (args, ctx) => {
+    const { project_id, threshold_amount, threshold_period, alert_type = 'warning', } = args;
+    const { supabase, auth } = ctx;
+    if (!threshold_amount || threshold_amount <= 0) {
+        return {
+            result: { error: 'threshold_amount must be a positive number' },
+            isError: true,
+        };
+    }
+    if (!threshold_period || !['daily', 'weekly', 'monthly'].includes(threshold_period)) {
+        return {
+            result: { error: 'threshold_period must be "daily", "weekly", or "monthly"' },
+            isError: true,
+        };
+    }
+    const { data, error } = await supabase
+        .from('cost_alerts')
+        .insert({
+        user_id: auth.userId,
+        project_id: project_id || null,
+        threshold_amount,
+        threshold_period,
+        alert_type,
+    })
+        .select()
+        .single();
+    if (error) {
+        return {
+            result: { error: `Failed to create cost alert: ${error.message}` },
+            isError: true,
+        };
+    }
+    return {
+        result: {
+            success: true,
+            alert: data,
+            message: `Alert created: ${alert_type} when ${threshold_period} cost exceeds $${threshold_amount}`,
+        },
+    };
+};
+/**
+ * Update a cost alert
+ */
+export const updateCostAlert = async (args, ctx) => {
+    const { alert_id, threshold_amount, threshold_period, alert_type, enabled, } = args;
+    const { supabase, auth } = ctx;
+    if (!alert_id) {
+        return {
+            result: { error: 'alert_id is required' },
+            isError: true,
+        };
+    }
+    const updates = {};
+    if (threshold_amount !== undefined)
+        updates.threshold_amount = threshold_amount;
+    if (threshold_period !== undefined)
+        updates.threshold_period = threshold_period;
+    if (alert_type !== undefined)
+        updates.alert_type = alert_type;
+    if (enabled !== undefined)
+        updates.enabled = enabled;
+    if (Object.keys(updates).length === 0) {
+        return {
+            result: { error: 'No updates provided' },
+            isError: true,
+        };
+    }
+    const { data, error } = await supabase
+        .from('cost_alerts')
+        .update(updates)
+        .eq('id', alert_id)
+        .eq('user_id', auth.userId)
+        .select()
+        .single();
+    if (error) {
+        return {
+            result: { error: `Failed to update cost alert: ${error.message}` },
+            isError: true,
+        };
+    }
+    return {
+        result: {
+            success: true,
+            alert: data,
+        },
+    };
+};
+/**
+ * Delete a cost alert
+ */
+export const deleteCostAlert = async (args, ctx) => {
+    const { alert_id } = args;
+    const { supabase, auth } = ctx;
+    if (!alert_id) {
+        return {
+            result: { error: 'alert_id is required' },
+            isError: true,
+        };
+    }
+    const { error } = await supabase
+        .from('cost_alerts')
+        .delete()
+        .eq('id', alert_id)
+        .eq('user_id', auth.userId);
+    if (error) {
+        return {
+            result: { error: `Failed to delete cost alert: ${error.message}` },
+            isError: true,
+        };
+    }
+    return {
+        result: {
+            success: true,
+            deleted_alert_id: alert_id,
+        },
+    };
+};
+/**
+ * Get task costs for a project
+ */
+export const getTaskCosts = async (args, ctx) => {
+    const { project_id, limit = 20 } = args;
+    const { supabase } = ctx;
+    if (!project_id) {
+        return {
+            result: { error: 'project_id is required' },
+            isError: true,
+        };
+    }
+    const { data, error } = await supabase
+        .from('task_costs')
+        .select('*')
+        .eq('project_id', project_id)
+        .order('estimated_cost_usd', { ascending: false })
+        .limit(limit);
+    if (error) {
+        return {
+            result: { error: `Failed to get task costs: ${error.message}` },
+            isError: true,
+        };
+    }
+    const totalCost = (data || []).reduce((sum, task) => sum + parseFloat(task.estimated_cost_usd || '0'), 0);
+    return {
+        result: {
+            project_id,
+            tasks: data || [],
+            total_cost_usd: Math.round(totalCost * 100) / 100,
+        },
+    };
+};
+/**
+ * Cost handlers registry
+ */
+export const costHandlers = {
+    get_cost_summary: getCostSummary,
+    get_cost_alerts: getCostAlerts,
+    add_cost_alert: addCostAlert,
+    update_cost_alert: updateCostAlert,
+    delete_cost_alert: deleteCostAlert,
+    get_task_costs: getTaskCosts,
+};

package/dist/handlers/decisions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Decisions Handlers
+ *
+ * Handles architectural/technical decisions:
+ * - log_decision
+ * - get_decisions
+ * - delete_decision
+ */
+import type { Handler, HandlerRegistry } from './types.js';
+export declare const logDecision: Handler;
+export declare const getDecisions: Handler;
+export declare const deleteDecision: Handler;
+/**
+ * Decisions handlers registry
+ */
+export declare const decisionHandlers: HandlerRegistry;