@vibescope/mcp-server 0.0.1

package/dist/handlers/ideas.js

@@ -0,0 +1,188 @@
+/**
+ * Ideas Handlers
+ *
+ * Handles feature ideas tracking:
+ * - add_idea
+ * - update_idea
+ * - get_ideas
+ * - delete_idea
+ */
+import { validateRequired, validateUUID, validatePriority, validateEstimatedMinutes } from '../validators.js';
+export const addIdea = async (args, ctx) => {
+    const { project_id, title, description, status } = args;
+    validateRequired(project_id, 'project_id');
+    validateUUID(project_id, 'project_id');
+    validateRequired(title, 'title');
+    const { supabase, session } = ctx;
+    const { data, error } = await supabase
+        .from('ideas')
+        .insert({
+        project_id,
+        title,
+        description: description || null,
+        status: status || 'raw',
+        created_by: 'agent',
+        created_by_session_id: session.currentSessionId,
+    })
+        .select('id')
+        .single();
+    if (error)
+        throw new Error(`Failed to add idea: ${error.message}`);
+    return { result: { success: true, idea_id: data.id, title } };
+};
+export const updateIdea = async (args, ctx) => {
+    const { idea_id, title, description, status, doc_url } = args;
+    validateRequired(idea_id, 'idea_id');
+    validateUUID(idea_id, 'idea_id');
+    const { supabase } = ctx;
+    // Get current idea status
+    const { data: existingIdea } = await supabase
+        .from('ideas')
+        .select('status')
+        .eq('id', idea_id)
+        .single();
+    if (!existingIdea) {
+        throw new Error(`Idea not found: ${idea_id}`);
+    }
+    // Build update object
+    const updates = { updated_at: new Date().toISOString() };
+    if (title !== undefined)
+        updates.title = title;
+    if (description !== undefined)
+        updates.description = description;
+    if (doc_url !== undefined)
+        updates.doc_url = doc_url;
+    if (status !== undefined) {
+        updates.status = status;
+        // Set planned_at when transitioning to planned status
+        if (status === 'planned' && existingIdea.status !== 'planned') {
+            updates.planned_at = new Date().toISOString();
+        }
+    }
+    const { error } = await supabase
+        .from('ideas')
+        .update(updates)
+        .eq('id', idea_id);
+    if (error)
+        throw new Error(`Failed to update idea: ${error.message}`);
+    return { result: { success: true, idea_id } };
+};
+export const getIdeas = async (args, ctx) => {
+    const { project_id, status } = args;
+    validateRequired(project_id, 'project_id');
+    validateUUID(project_id, 'project_id');
+    const { supabase } = ctx;
+    let query = supabase
+        .from('ideas')
+        .select('id, title, description, status, doc_url')
+        .eq('project_id', project_id);
+    if (status) {
+        query = query.eq('status', status);
+    }
+    const { data, error } = await query.order('created_at', { ascending: false });
+    if (error)
+        throw new Error(`Failed to fetch ideas: ${error.message}`);
+    return { result: { ideas: data || [] } };
+};
+export const deleteIdea = async (args, ctx) => {
+    const { idea_id } = args;
+    validateRequired(idea_id, 'idea_id');
+    validateUUID(idea_id, 'idea_id');
+    const { error } = await ctx.supabase
+        .from('ideas')
+        .delete()
+        .eq('id', idea_id);
+    if (error)
+        throw new Error(`Failed to delete idea: ${error.message}`);
+    return { result: { success: true } };
+};
+export const convertIdeaToTask = async (args, ctx) => {
+    const { idea_id, priority = 3, estimated_minutes, update_status = true } = args;
+    validateRequired(idea_id, 'idea_id');
+    validateUUID(idea_id, 'idea_id');
+    validatePriority(priority);
+    validateEstimatedMinutes(estimated_minutes);
+    const { supabase, session } = ctx;
+    const currentSessionId = session.currentSessionId;
+    // Get the idea
+    const { data: idea, error: fetchError } = await supabase
+        .from('ideas')
+        .select('id, project_id, title, description, status, converted_to_task_id')
+        .eq('id', idea_id)
+        .single();
+    if (fetchError || !idea) {
+        throw new Error(`Idea not found: ${idea_id}`);
+    }
+    // Check if already converted
+    if (idea.converted_to_task_id) {
+        return {
+            result: {
+                success: false,
+                error: 'Idea has already been converted to a task',
+                existing_task_id: idea.converted_to_task_id,
+                hint: 'Use get_tasks to find the existing task',
+            },
+        };
+    }
+    // Create the task
+    const { data: task, error: taskError } = await supabase
+        .from('tasks')
+        .insert({
+        project_id: idea.project_id,
+        title: idea.title,
+        description: idea.description || `Converted from idea: ${idea.title}`,
+        priority,
+        estimated_minutes: estimated_minutes || null,
+        created_by: 'agent',
+        created_by_session_id: currentSessionId,
+    })
+        .select('id, title')
+        .single();
+    if (taskError || !task) {
+        throw new Error(`Failed to create task: ${taskError?.message}`);
+    }
+    // Update the idea with the task reference and optionally update status
+    const ideaUpdates = {
+        converted_to_task_id: task.id,
+        updated_at: new Date().toISOString(),
+    };
+    if (update_status && idea.status !== 'shipped') {
+        ideaUpdates.status = 'in_development';
+    }
+    const { error: updateError } = await supabase
+        .from('ideas')
+        .update(ideaUpdates)
+        .eq('id', idea_id);
+    if (updateError) {
+        // Log but don't fail - task was created successfully
+        console.error(`Failed to update idea after conversion: ${updateError.message}`);
+    }
+    // Log progress
+    await supabase.from('progress_logs').insert({
+        project_id: idea.project_id,
+        task_id: task.id,
+        summary: `Converted idea "${idea.title}" to task`,
+        created_by: 'agent',
+        created_by_session_id: currentSessionId,
+    });
+    return {
+        result: {
+            success: true,
+            task_id: task.id,
+            task_title: task.title,
+            idea_id: idea.id,
+            idea_status: update_status ? 'in_development' : idea.status,
+            message: `Created task from idea. Start with: update_task(task_id: "${task.id}", status: "in_progress")`,
+        },
+    };
+};
+/**
+ * Ideas handlers registry
+ */
+export const ideaHandlers = {
+    add_idea: addIdea,
+    update_idea: updateIdea,
+    get_ideas: getIdeas,
+    delete_idea: deleteIdea,
+    convert_idea_to_task: convertIdeaToTask,
+};

package/dist/handlers/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MCP Server Handlers
+ *
+ * This module exports all tool handlers organized by category.
+ * Each handler receives a HandlerContext and returns a HandlerResult.
+ */
+export * from './types.js';
+export * from './milestones.js';
+export * from './session.js';
+export * from './ideas.js';
+export * from './findings.js';
+export * from './blockers.js';
+export * from './decisions.js';
+export * from './progress.js';
+export * from './requests.js';
+export * from './tasks.js';
+export * from './project.js';
+export * from './deployment.js';
+export * from './validation.js';
+export * from './fallback.js';
+export * from './bodies-of-work.js';
+export * from './discovery.js';
+export * from './organizations.js';
+export * from './cost.js';
+import type { HandlerRegistry } from './types.js';
+/**
+ * Build the complete handler registry from all modules
+ */
+export declare function buildHandlerRegistry(): HandlerRegistry;

package/dist/handlers/index.js

@@ -0,0 +1,65 @@
+/**
+ * MCP Server Handlers
+ *
+ * This module exports all tool handlers organized by category.
+ * Each handler receives a HandlerContext and returns a HandlerResult.
+ */
+export * from './types.js';
+export * from './milestones.js';
+export * from './session.js';
+export * from './ideas.js';
+export * from './findings.js';
+export * from './blockers.js';
+export * from './decisions.js';
+export * from './progress.js';
+export * from './requests.js';
+export * from './tasks.js';
+export * from './project.js';
+export * from './deployment.js';
+export * from './validation.js';
+export * from './fallback.js';
+export * from './bodies-of-work.js';
+export * from './discovery.js';
+export * from './organizations.js';
+export * from './cost.js';
+import { milestoneHandlers } from './milestones.js';
+import { sessionHandlers } from './session.js';
+import { ideaHandlers } from './ideas.js';
+import { findingHandlers } from './findings.js';
+import { blockerHandlers } from './blockers.js';
+import { decisionHandlers } from './decisions.js';
+import { progressHandlers } from './progress.js';
+import { requestHandlers } from './requests.js';
+import { taskHandlers } from './tasks.js';
+import { projectHandlers } from './project.js';
+import { deploymentHandlers } from './deployment.js';
+import { validationHandlers } from './validation.js';
+import { fallbackHandlers } from './fallback.js';
+import { bodiesOfWorkHandlers } from './bodies-of-work.js';
+import { discoveryHandlers } from './discovery.js';
+import { organizationHandlers } from './organizations.js';
+import { costHandlers } from './cost.js';
+/**
+ * Build the complete handler registry from all modules
+ */
+export function buildHandlerRegistry() {
+    return {
+        ...milestoneHandlers,
+        ...sessionHandlers,
+        ...ideaHandlers,
+        ...findingHandlers,
+        ...blockerHandlers,
+        ...decisionHandlers,
+        ...progressHandlers,
+        ...requestHandlers,
+        ...taskHandlers,
+        ...projectHandlers,
+        ...deploymentHandlers,
+        ...validationHandlers,
+        ...fallbackHandlers,
+        ...bodiesOfWorkHandlers,
+        ...discoveryHandlers,
+        ...organizationHandlers,
+        ...costHandlers,
+    };
+}

package/dist/handlers/knowledge-query.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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

@@ -0,0 +1,253 @@
+/**
+ * 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

@@ -0,0 +1,12 @@
+/**
+ * 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;

package/dist/handlers/knowledge.js

@@ -0,0 +1,108 @@
+/**
+ * Knowledge Handlers
+ *
+ * Unified knowledge query to reduce tool calls and token costs.
+ * Aggregates decisions, findings, blockers, Q&A, and task history.
+ */
+import { validateRequired, validateUUID } from '../validators.js';
+const VALID_QUERY_TYPES = ['context', 'architecture', 'issues', 'history', 'qa'];
+const QUERY_TYPE_DESCRIPTIONS = {
+    context: 'Key decisions, open blockers, recent Q&As, critical findings - use when starting work',
+    architecture: 'All decisions + architecture-related findings - use when understanding codebase',
+    issues: 'Open findings + blockers sorted by severity - use when fixing bugs',
+    history: 'Completed tasks with summaries - use when understanding what was done',
+    qa: 'Answered questions as Q&A pairs - use when looking for common questions',
+};
+export const queryKnowledge = async (args, ctx) => {
+    const { project_id, query_type = 'context', limit = 20 } = args;
+    validateRequired(project_id, 'project_id');
+    validateUUID(project_id, 'project_id');
+    if (!VALID_QUERY_TYPES.includes(query_type)) {
+        throw new Error(`Invalid query_type '${query_type}'. Must be one of: ${VALID_QUERY_TYPES.join(', ')}`);
+    }
+    const { supabase } = ctx;
+    // Call the database function
+    const { data, error } = await supabase.rpc('query_knowledge', {
+        p_project_id: project_id,
+        p_query_type: query_type,
+        p_limit: Math.min(limit, 50), // Cap at 50 to limit response size
+    });
+    if (error) {
+        throw new Error(`Failed to query knowledge: ${error.message}`);
+    }
+    // Map database results to typed items
+    const items = (data || []).map((row) => ({
+        type: row.item_type,
+        id: row.id,
+        title: row.title,
+        content: row.content,
+        ...(row.severity && { severity: row.severity }),
+        ...(row.status && { status: row.status }),
+        created_at: row.created_at,
+    }));
+    // Generate summary based on query type and results
+    const summary = generateSummary(query_type, items);
+    // Estimate tokens (rough: ~4 chars per token)
+    const responseJson = JSON.stringify({ items, summary });
+    const tokenEstimate = Math.ceil(responseJson.length / 4);
+    return {
+        result: {
+            query_type,
+            project_id,
+            description: QUERY_TYPE_DESCRIPTIONS[query_type],
+            summary,
+            items,
+            count: items.length,
+            token_estimate: tokenEstimate,
+        },
+    };
+};
+function generateSummary(queryType, items) {
+    const counts = items.reduce((acc, item) => {
+        acc[item.type] = (acc[item.type] || 0) + 1;
+        return acc;
+    }, {});
+    const parts = [];
+    switch (queryType) {
+        case 'context':
+            if (counts.blocker)
+                parts.push(`${counts.blocker} open blocker(s)`);
+            if (counts.finding)
+                parts.push(`${counts.finding} critical/high finding(s)`);
+            if (counts.decision)
+                parts.push(`${counts.decision} recent decision(s)`);
+            if (counts.qa)
+                parts.push(`${counts.qa} answered question(s)`);
+            break;
+        case 'architecture':
+            if (counts.decision)
+                parts.push(`${counts.decision} architectural decision(s)`);
+            if (counts.finding)
+                parts.push(`${counts.finding} architecture finding(s)`);
+            break;
+        case 'issues':
+            if (counts.blocker)
+                parts.push(`${counts.blocker} blocker(s)`);
+            if (counts.finding)
+                parts.push(`${counts.finding} open finding(s)`);
+            break;
+        case 'history':
+            if (counts.task)
+                parts.push(`${counts.task} completed task(s)`);
+            break;
+        case 'qa':
+            if (counts.qa)
+                parts.push(`${counts.qa} Q&A pair(s)`);
+            break;
+    }
+    if (parts.length === 0) {
+        return `No ${queryType} items found.`;
+    }
+    return `Found ${parts.join(', ')}.`;
+}
+/**
+ * Knowledge handlers registry
+ */
+export const knowledgeHandlers = {
+    query_knowledge: queryKnowledge,
+};