@vibescope/mcp-server 0.0.1 → 0.2.0

package/dist/handlers/checkouts.js

@@ -1,377 +0,0 @@
-/**
- * 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/knowledge-query.d.ts

@@ -1,22 +0,0 @@
-/**
- * Knowledge Query Handler
- *
- * Provides a queryable knowledge base from project data:
- * - Findings (code quality, security, performance audits)
- * - Questions and answers
- * - Completed tasks with summaries
- * - Decisions with rationales
- * - Resolved blockers (lessons learned)
- *
- * Designed to reduce tool calls by aggregating multiple data sources in one query.
- */
-import type { Handler, HandlerRegistry } from './types.js';
-/**
- * Query the knowledge base for aggregated project information.
- * Replaces multiple tool calls with a single comprehensive query.
- */
-export declare const queryKnowledgeBase: Handler;
-/**
- * Knowledge query handlers registry
- */
-export declare const knowledgeQueryHandlers: HandlerRegistry;

package/dist/handlers/knowledge-query.js

@@ -1,253 +0,0 @@
-/**
- * Knowledge Query Handler
- *
- * Provides a queryable knowledge base from project data:
- * - Findings (code quality, security, performance audits)
- * - Questions and answers
- * - Completed tasks with summaries
- * - Decisions with rationales
- * - Resolved blockers (lessons learned)
- *
- * Designed to reduce tool calls by aggregating multiple data sources in one query.
- */
-import { validateRequired, validateUUID } from '../validators.js';
-/**
- * Query the knowledge base for aggregated project information.
- * Replaces multiple tool calls with a single comprehensive query.
- */
-export const queryKnowledgeBase = async (args, ctx) => {
-    const { project_id, scope = 'summary', categories, limit = 5, search_query, } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
-    const { supabase } = ctx;
-    const effectiveLimit = Math.min(limit, 20); // Cap at 20 to prevent huge responses
-    // Default to all categories if not specified
-    const selectedCategories = new Set(categories || ['findings', 'qa', 'decisions', 'completed_tasks', 'blockers', 'progress']);
-    // Fetch project info first
-    const { data: project, error: projectError } = await supabase
-        .from('projects')
-        .select('name, goal, tech_stack')
-        .eq('id', project_id)
-        .single();
-    if (projectError || !project) {
-        return { result: { error: 'Project not found', project_id } };
-    }
-    // Fetch all stats counts in parallel
-    const [findingsStatsResult, qaCountResult, unansweredQaCountResult, decisionsCountResult, completedTasksCountResult, resolvedBlockersCountResult,] = await Promise.all([
-        supabase
-            .from('findings')
-            .select('severity', { count: 'exact' })
-            .eq('project_id', project_id)
-            .eq('status', 'open'),
-        supabase
-            .from('agent_requests')
-            .select('id', { count: 'exact', head: true })
-            .eq('project_id', project_id)
-            .eq('request_type', 'question'),
-        supabase
-            .from('agent_requests')
-            .select('id', { count: 'exact', head: true })
-            .eq('project_id', project_id)
-            .eq('request_type', 'question')
-            .is('answer', null),
-        supabase
-            .from('decisions')
-            .select('id', { count: 'exact', head: true })
-            .eq('project_id', project_id),
-        supabase
-            .from('tasks')
-            .select('id', { count: 'exact', head: true })
-            .eq('project_id', project_id)
-            .eq('status', 'completed'),
-        supabase
-            .from('blockers')
-            .select('id', { count: 'exact', head: true })
-            .eq('project_id', project_id)
-            .eq('status', 'resolved'),
-    ]);
-    // Build stats
-    const severityCounts = {};
-    if (findingsStatsResult.data) {
-        for (const finding of findingsStatsResult.data) {
-            severityCounts[finding.severity] = (severityCounts[finding.severity] || 0) + 1;
-        }
-    }
-    const stats = {
-        findings_count: findingsStatsResult.count || 0,
-        open_findings_by_severity: severityCounts,
-        qa_count: qaCountResult.count || 0,
-        unanswered_qa_count: unansweredQaCountResult.count || 0,
-        decisions_count: decisionsCountResult.count || 0,
-        completed_tasks_count: completedTasksCountResult.count || 0,
-        resolved_blockers_count: resolvedBlockersCountResult.count || 0,
-    };
-    // Build result object
-    const result = {
-        project: {
-            name: project.name,
-            goal: project.goal || undefined,
-            tech_stack: project.tech_stack || undefined,
-        },
-        stats,
-    };
-    // Fetch detailed data for selected categories in parallel
-    const detailQueries = [];
-    if (selectedCategories.has('findings')) {
-        detailQueries.push((async () => {
-            let query = supabase
-                .from('findings')
-                .select('id, title, category, severity, file_path, status')
-                .eq('project_id', project_id)
-                .order('severity', { ascending: true })
-                .order('created_at', { ascending: false })
-                .limit(effectiveLimit);
-            if (search_query) {
-                query = query.or(`title.ilike.%${search_query}%,description.ilike.%${search_query}%`);
-            }
-            const { data } = await query;
-            if (data && data.length > 0) {
-                result.findings = data;
-            }
-        })());
-    }
-    if (selectedCategories.has('qa')) {
-        detailQueries.push((async () => {
-            let query = supabase
-                .from('agent_requests')
-                .select('id, message, answer, answered_at, created_at')
-                .eq('project_id', project_id)
-                .eq('request_type', 'question')
-                .order('created_at', { ascending: false })
-                .limit(effectiveLimit);
-            if (search_query) {
-                query = query.or(`message.ilike.%${search_query}%,answer.ilike.%${search_query}%`);
-            }
-            const { data } = await query;
-            if (data && data.length > 0) {
-                result.qa = data.map((q) => ({
-                    id: q.id,
-                    question: q.message,
-                    answer: q.answer,
-                    answered_at: q.answered_at,
-                    created_at: q.created_at,
-                }));
-            }
-        })());
-    }
-    if (selectedCategories.has('decisions')) {
-        detailQueries.push((async () => {
-            // Always fetch full fields, the interface handles optional display
-            let query = supabase
-                .from('decisions')
-                .select('id, title, description, rationale, created_at')
-                .eq('project_id', project_id)
-                .order('created_at', { ascending: false })
-                .limit(effectiveLimit);
-            if (search_query) {
-                query = query.or(`title.ilike.%${search_query}%,description.ilike.%${search_query}%`);
-            }
-            const { data } = await query;
-            if (data && data.length > 0) {
-                result.decisions = data.map((d) => ({
-                    id: d.id,
-                    title: d.title,
-                    description: scope === 'detailed' ? d.description : undefined,
-                    rationale: scope === 'detailed' ? d.rationale : undefined,
-                    created_at: d.created_at,
-                }));
-            }
-        })());
-    }
-    if (selectedCategories.has('completed_tasks')) {
-        detailQueries.push((async () => {
-            let query = supabase
-                .from('tasks')
-                .select('id, title, completion_summary, completed_at')
-                .eq('project_id', project_id)
-                .eq('status', 'completed')
-                .not('completed_at', 'is', null)
-                .order('completed_at', { ascending: false })
-                .limit(effectiveLimit);
-            if (search_query) {
-                query = query.or(`title.ilike.%${search_query}%,completion_summary.ilike.%${search_query}%`);
-            }
-            const { data } = await query;
-            if (data && data.length > 0) {
-                result.completed_tasks = data.map((t) => ({
-                    id: t.id,
-                    title: t.title,
-                    summary: t.completion_summary || undefined,
-                    completed_at: t.completed_at,
-                }));
-            }
-        })());
-    }
-    if (selectedCategories.has('blockers')) {
-        detailQueries.push((async () => {
-            let query = supabase
-                .from('blockers')
-                .select('id, description, resolution_note, resolved_at')
-                .eq('project_id', project_id)
-                .eq('status', 'resolved')
-                .order('resolved_at', { ascending: false })
-                .limit(effectiveLimit);
-            if (search_query) {
-                query = query.or(`description.ilike.%${search_query}%,resolution_note.ilike.%${search_query}%`);
-            }
-            const { data } = await query;
-            if (data && data.length > 0) {
-                result.resolved_blockers = data;
-            }
-        })());
-    }
-    if (selectedCategories.has('progress')) {
-        detailQueries.push((async () => {
-            let query = supabase
-                .from('progress_logs')
-                .select('id, summary, created_at, task_id')
-                .eq('project_id', project_id)
-                .order('created_at', { ascending: false })
-                .limit(effectiveLimit);
-            if (search_query) {
-                query = query.ilike('summary', `%${search_query}%`);
-            }
-            const { data } = await query;
-            if (data && data.length > 0) {
-                // Fetch task titles for progress logs that have task_id
-                const taskIds = data.filter((p) => p.task_id).map((p) => p.task_id);
-                let taskTitles = {};
-                if (taskIds.length > 0) {
-                    const { data: tasks } = await supabase
-                        .from('tasks')
-                        .select('id, title')
-                        .in('id', taskIds);
-                    if (tasks) {
-                        taskTitles = Object.fromEntries(tasks.map((t) => [t.id, t.title]));
-                    }
-                }
-                result.recent_progress = data.map((p) => ({
-                    id: p.id,
-                    summary: p.summary,
-                    task_title: p.task_id ? taskTitles[p.task_id] : undefined,
-                    created_at: p.created_at,
-                }));
-            }
-        })());
-    }
-    // Execute all detail queries in parallel
-    await Promise.all(detailQueries);
-    return {
-        result,
-        // Add hint about token savings
-        _meta: {
-            categories_queried: Array.from(selectedCategories),
-            tool_calls_saved: selectedCategories.size, // Would have been N separate calls
-        },
-    };
-};
-/**
- * Knowledge query handlers registry
- */
-export const knowledgeQueryHandlers = {
-    query_knowledge_base: queryKnowledgeBase,
-};

package/dist/handlers/knowledge.d.ts

@@ -1,12 +0,0 @@
-/**
- * Knowledge Handlers
- *
- * Unified knowledge query to reduce tool calls and token costs.
- * Aggregates decisions, findings, blockers, Q&A, and task history.
- */
-import type { Handler, HandlerRegistry } from './types.js';
-export declare const queryKnowledge: Handler;
-/**
- * Knowledge handlers registry
- */
-export declare const knowledgeHandlers: HandlerRegistry;