@vibescope/mcp-server 0.0.1

package/README.md

@@ -0,0 +1,98 @@
+# @vibescope/mcp-server
+
+MCP server for Vibescope - enables AI agents to track project progress, tasks, blockers, and decisions.
+
+## Installation Options
+
+### Option 1: From GitHub Package Registry (Recommended)
+
+```bash
+# Authenticate with GitHub (one-time)
+npm login --registry=https://npm.pkg.github.com
+
+# Install globally
+npm install -g @vibescope/mcp-server --registry=https://npm.pkg.github.com
+```
+
+### Option 2: From Source (Local Development)
+
+```bash
+# Clone the repo
+git clone https://github.com/Nonatomic/Vibescope.git
+cd Vibescope
+
+# Install dependencies and build
+pnpm install
+pnpm build
+
+# Link globally
+cd packages/mcp-server
+npm link
+```
+
+### Option 3: Direct Path (No Installation)
+
+Point your MCP config directly to the built file:
+
+```json
+{
+  "mcpServers": {
+    "vibescope": {
+      "command": "node",
+      "args": ["/path/to/Vibescope/packages/mcp-server/dist/index.js"],
+      "env": {
+        "VIBESCOPE_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+Add to your Claude Code MCP config (`~/.claude/claude_desktop_config.json` or project `.claude/settings.local.json`):
+
+```json
+{
+  "mcpServers": {
+    "vibescope": {
+      "command": "vibescope-mcp",
+      "env": {
+        "VIBESCOPE_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Getting an API Key
+
+1. Sign up at [vibescope.dev](https://vibescope.dev)
+2. Go to Settings
+3. Generate an API key
+
+## Available Tools
+
+The MCP server provides these tools for AI agents:
+
+| Tool | Description |
+|------|-------------|
+| `start_work_session` | Initialize a work session for a project |
+| `get_project_context` | Get full project context including tasks, blockers, and user updates |
+| `get_tasks` | List tasks, optionally filtered by status |
+| `get_next_task` | Get the highest priority pending task |
+| `add_task` | Create a new task |
+| `update_task` | Update task status, progress, or details |
+| `complete_task` | Mark a task as completed |
+| `log_progress` | Log a progress update |
+| `add_blocker` | Flag a blocker needing human input |
+| `resolve_blocker` | Mark a blocker as resolved |
+| `log_decision` | Record an architectural or technical decision |
+| `add_idea` | Record an improvement idea |
+| `create_project` | Create a new project |
+| `update_project` | Update project details |
+
+## Rate Limits
+
+- 60 requests per minute per API key
+- Warning shown when quota drops below 10 requests

package/dist/cli.d.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Vibescope CLI - Enforcement verification tool
+ *
+ * Used by Claude Code Stop hook to verify agent compliance with Vibescope tracking.
+ * Exit codes:
+ *   0 = Compliant (allow exit)
+ *   1 = Non-compliant (block exit, loop back)
+ *   2 = Error (allow exit with warning)
+ */
+export interface AuthContext {
+    userId: string;
+    apiKeyId: string;
+}
+export interface VerificationResult {
+    status: 'compliant' | 'non_compliant' | 'no_session' | 'error';
+    reason: string;
+    continuation_prompt?: string;
+    details?: {
+        session_started: boolean;
+        project_id: string | null;
+        project_name: string | null;
+        git_url: string | null;
+        in_progress_tasks: number;
+        tasks_completed_this_session: number;
+        progress_logs_this_session: number;
+        blockers_logged_this_session: number;
+        session_duration_minutes: number | null;
+    };
+}
+export declare function detectGitUrl(): string | null;
+export declare function hashApiKey(key: string): string;
+export declare function validateApiKey(supabase: any, apiKey: string): Promise<AuthContext | null>;
+export declare function verify(gitUrl?: string, projectId?: string): Promise<VerificationResult>;

package/dist/cli.js

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+/**
+ * Vibescope CLI - Enforcement verification tool
+ *
+ * Used by Claude Code Stop hook to verify agent compliance with Vibescope tracking.
+ * Exit codes:
+ *   0 = Compliant (allow exit)
+ *   1 = Non-compliant (block exit, loop back)
+ *   2 = Error (allow exit with warning)
+ */
+import { createClient } from '@supabase/supabase-js';
+import { createHash } from 'crypto';
+import { execSync } from 'child_process';
+import { normalizeGitUrl } from './utils.js';
+// ============================================================================
+// Configuration
+// ============================================================================
+const SUPABASE_URL = process.env.SUPABASE_URL || process.env.PUBLIC_SUPABASE_URL;
+const SUPABASE_SERVICE_KEY = process.env.SUPABASE_SERVICE_KEY;
+const API_KEY = process.env.VIBESCOPE_API_KEY;
+// ============================================================================
+// Git URL Detection
+// ============================================================================
+export function detectGitUrl() {
+    try {
+        const url = execSync('git config --get remote.origin.url', {
+            encoding: 'utf8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        // Normalize: remove .git suffix, convert SSH to HTTPS format
+        return normalizeGitUrl(url);
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Authentication (reused from index.ts)
+// ============================================================================
+export function hashApiKey(key) {
+    return createHash('sha256').update(key).digest('hex');
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function validateApiKey(supabase, apiKey) {
+    const keyHash = hashApiKey(apiKey);
+    const { data, error } = await supabase
+        .from('api_keys')
+        .select('id, user_id')
+        .eq('key_hash', keyHash)
+        .single();
+    if (error || !data) {
+        return null;
+    }
+    // Cast to expected shape since we're using untyped client
+    const row = data;
+    return {
+        userId: row.user_id,
+        apiKeyId: row.id,
+    };
+}
+// ============================================================================
+// Verification Logic
+// ============================================================================
+export async function verify(gitUrl, projectId) {
+    // Check environment
+    if (!SUPABASE_URL || !SUPABASE_SERVICE_KEY) {
+        return {
+            status: 'error',
+            reason: 'Missing SUPABASE_URL or SUPABASE_SERVICE_KEY environment variables',
+        };
+    }
+    if (!API_KEY) {
+        return {
+            status: 'error',
+            reason: 'VIBESCOPE_API_KEY environment variable not set',
+        };
+    }
+    const supabase = createClient(SUPABASE_URL, SUPABASE_SERVICE_KEY);
+    // Validate API key
+    const auth = await validateApiKey(supabase, API_KEY);
+    if (!auth) {
+        return {
+            status: 'error',
+            reason: 'Invalid VIBESCOPE_API_KEY',
+        };
+    }
+    // Auto-detect git URL if not provided
+    if (!gitUrl && !projectId) {
+        gitUrl = detectGitUrl() || undefined;
+    }
+    // Find project
+    let projectQuery = supabase
+        .from('projects')
+        .select('id, name, git_url')
+        .eq('user_id', auth.userId);
+    if (projectId) {
+        projectQuery = projectQuery.eq('id', projectId);
+    }
+    else if (gitUrl) {
+        projectQuery = projectQuery.eq('git_url', gitUrl);
+    }
+    else {
+        return {
+            status: 'no_session',
+            reason: 'Could not detect git URL and no project_id provided',
+            continuation_prompt: 'Could not detect which project you are working on. Please call start_work_session(git_url: "...") with your repository URL.',
+        };
+    }
+    const { data: project, error: projectError } = await projectQuery.single();
+    if (projectError || !project) {
+        // Project not found - this is OK, might be an untracked repo
+        return {
+            status: 'compliant',
+            reason: `No Vibescope project found for ${gitUrl || projectId}. Untracked repository - exit allowed.`,
+            details: {
+                session_started: false,
+                project_id: null,
+                project_name: null,
+                git_url: gitUrl || null,
+                in_progress_tasks: 0,
+                tasks_completed_this_session: 0,
+                progress_logs_this_session: 0,
+                blockers_logged_this_session: 0,
+                session_duration_minutes: null,
+            },
+        };
+    }
+    // Check for agent session
+    const { data: session } = await supabase
+        .from('agent_sessions')
+        .select('id, last_synced_at, created_at')
+        .eq('api_key_id', auth.apiKeyId)
+        .eq('project_id', project.id)
+        .single();
+    if (!session) {
+        return {
+            status: 'non_compliant',
+            reason: 'No Vibescope session started for this project',
+            continuation_prompt: `[VIBESCOPE ENFORCEMENT] You have not started a Vibescope work session.
+
+BEFORE you can exit, you MUST call:
+  start_work_session(git_url: "${project.git_url || project.id}")
+
+This registers your session and gives you project context.`,
+            details: {
+                session_started: false,
+                project_id: project.id,
+                project_name: project.name,
+                git_url: project.git_url,
+                in_progress_tasks: 0,
+                tasks_completed_this_session: 0,
+                progress_logs_this_session: 0,
+                blockers_logged_this_session: 0,
+                session_duration_minutes: null,
+            },
+        };
+    }
+    const sessionStartTime = new Date(session.created_at);
+    const lastSyncTime = new Date(session.last_synced_at);
+    const now = new Date();
+    const sessionDurationMinutes = Math.round((now.getTime() - sessionStartTime.getTime()) / 60000);
+    // Grace period: if session is less than 1 minute, allow exit
+    if (sessionDurationMinutes < 1) {
+        return {
+            status: 'compliant',
+            reason: 'Very short session (< 1 minute) - exit allowed',
+            details: {
+                session_started: true,
+                project_id: project.id,
+                project_name: project.name,
+                git_url: project.git_url,
+                in_progress_tasks: 0,
+                tasks_completed_this_session: 0,
+                progress_logs_this_session: 0,
+                blockers_logged_this_session: 0,
+                session_duration_minutes: sessionDurationMinutes,
+            },
+        };
+    }
+    // Check for in-progress tasks
+    const { data: inProgressTasks } = await supabase
+        .from('tasks')
+        .select('id, title, progress_percentage')
+        .eq('project_id', project.id)
+        .eq('status', 'in_progress');
+    const inProgressCount = inProgressTasks?.length || 0;
+    if (inProgressCount > 0) {
+        const taskList = inProgressTasks
+            .map((t) => `  - ${t.title} (${t.progress_percentage}% complete)`)
+            .join('\n');
+        return {
+            status: 'non_compliant',
+            reason: `You have ${inProgressCount} task(s) still in_progress`,
+            continuation_prompt: `[VIBESCOPE ENFORCEMENT] You have ${inProgressCount} task(s) still marked as in_progress:
+
+${taskList}
+
+You MUST either:
+1. Complete them: complete_task(task_id: "...", summary: "...")
+2. Log why you're stopping: log_progress(project_id: "${project.id}", summary: "Stopping because...")`,
+            details: {
+                session_started: true,
+                project_id: project.id,
+                project_name: project.name,
+                git_url: project.git_url,
+                in_progress_tasks: inProgressCount,
+                tasks_completed_this_session: 0,
+                progress_logs_this_session: 0,
+                blockers_logged_this_session: 0,
+                session_duration_minutes: sessionDurationMinutes,
+            },
+        };
+    }
+    // Check for activity this session
+    const sessionStartIso = sessionStartTime.toISOString();
+    const [completedResult, progressResult, blockerResult] = await Promise.all([
+        // Tasks completed after session start
+        supabase
+            .from('tasks')
+            .select('id', { count: 'exact' })
+            .eq('project_id', project.id)
+            .eq('status', 'completed')
+            .gte('completed_at', sessionStartIso),
+        // Progress logs by agent after session start
+        supabase
+            .from('progress_logs')
+            .select('id', { count: 'exact' })
+            .eq('project_id', project.id)
+            .eq('created_by', 'agent')
+            .gte('created_at', sessionStartIso),
+        // Blockers logged by agent after session start
+        supabase
+            .from('blockers')
+            .select('id', { count: 'exact' })
+            .eq('project_id', project.id)
+            .eq('created_by', 'agent')
+            .gte('created_at', sessionStartIso),
+    ]);
+    const tasksCompleted = completedResult.count || 0;
+    const progressLogsCount = progressResult.count || 0;
+    const blockersLogged = blockerResult.count || 0;
+    // Check if any tracked work was done
+    const anyWorkTracked = tasksCompleted > 0 || progressLogsCount > 0 || blockersLogged > 0;
+    if (!anyWorkTracked && sessionDurationMinutes >= 5) {
+        return {
+            status: 'non_compliant',
+            reason: `Session active for ${sessionDurationMinutes} minutes but no work was tracked`,
+            continuation_prompt: `[VIBESCOPE ENFORCEMENT] Your session has been active for ${sessionDurationMinutes} minutes but no work was tracked.
+
+The human is watching the dashboard and will see an empty session.
+
+You MUST either:
+1. Pick a task and work on it: get_next_task(project_id: "${project.id}")
+2. Log why you did nothing: log_progress(project_id: "${project.id}", summary: "No work done because...")`,
+            details: {
+                session_started: true,
+                project_id: project.id,
+                project_name: project.name,
+                git_url: project.git_url,
+                in_progress_tasks: 0,
+                tasks_completed_this_session: tasksCompleted,
+                progress_logs_this_session: progressLogsCount,
+                blockers_logged_this_session: blockersLogged,
+                session_duration_minutes: sessionDurationMinutes,
+            },
+        };
+    }
+    // All checks passed - compliant!
+    return {
+        status: 'compliant',
+        reason: 'All tracked work completed properly',
+        details: {
+            session_started: true,
+            project_id: project.id,
+            project_name: project.name,
+            git_url: project.git_url,
+            in_progress_tasks: 0,
+            tasks_completed_this_session: tasksCompleted,
+            progress_logs_this_session: progressLogsCount,
+            blockers_logged_this_session: blockersLogged,
+            session_duration_minutes: sessionDurationMinutes,
+        },
+    };
+}
+// ============================================================================
+// CLI Entry Point
+// ============================================================================
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (command === 'verify') {
+        // Parse --git-url and --project-id flags
+        let gitUrl;
+        let projectId;
+        for (let i = 1; i < args.length; i++) {
+            if (args[i] === '--git-url' && args[i + 1]) {
+                gitUrl = args[++i];
+            }
+            else if (args[i] === '--project-id' && args[i + 1]) {
+                projectId = args[++i];
+            }
+        }
+        const result = await verify(gitUrl, projectId);
+        console.log(JSON.stringify(result, null, 2));
+        // Exit codes: 0=compliant, 1=non-compliant, 2=error
+        if (result.status === 'compliant') {
+            process.exit(0);
+        }
+        else if (result.status === 'error') {
+            process.exit(2);
+        }
+        else {
+            process.exit(1);
+        }
+    }
+    else if (command === 'help' || command === '--help' || command === '-h') {
+        console.log(`
+Vibescope CLI - Enforcement verification tool
+
+Usage:
+  vibescope-cli verify [options]    Check Vibescope compliance before exit
+
+Options:
+  --git-url <url>       Git repository URL (auto-detected if not provided)
+  --project-id <id>     Vibescope project UUID
+
+Exit Codes:
+  0  Compliant - agent can exit
+  1  Non-compliant - agent should continue work
+  2  Error - allow exit with warning
+
+Environment Variables:
+  VIBESCOPE_API_KEY       Required - Your Vibescope API key
+  SUPABASE_URL            Required - Supabase project URL
+  SUPABASE_SERVICE_KEY    Required - Supabase service role key
+`);
+        process.exit(0);
+    }
+    else {
+        console.error('Usage: vibescope-cli verify [--git-url <url>] [--project-id <id>]');
+        console.error('       vibescope-cli --help');
+        process.exit(2);
+    }
+}
+// Only run main when executed directly (not when imported for testing)
+const isMainModule = import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`;
+if (isMainModule || process.argv[1]?.endsWith('cli.js')) {
+    main().catch((err) => {
+        console.error(JSON.stringify({
+            status: 'error',
+            reason: err instanceof Error ? err.message : 'Unknown error',
+        }));
+        process.exit(2);
+    });
+}

package/dist/cli.test.d.ts

@@ -0,0 +1 @@
+export {};