@vibescope/mcp-server 0.2.7 → 0.2.9

package/dist/api-client.d.ts

@@ -29,10 +29,10 @@ export declare class VibescopeApiClient {
         project_id?: string;
         git_url?: string;
         mode?: 'lite' | 'full';
-        model?: 'opus' | 'sonnet' | 'haiku';
-        role?: 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer';
+        model?: string;
+        role?: string;
         hostname?: string;
-        agent_type?: 'claude' | 'gemini' | 'cursor' | 'windsurf' | 'other';
+        agent_type?: string;
     }): Promise<ApiResponse<{
         session_started: boolean;
         session_id?: string;
@@ -970,7 +970,7 @@ export declare class VibescopeApiClient {
     reportTokenUsage(sessionId: string, params: {
         input_tokens: number;
         output_tokens: number;
-        model?: 'opus' | 'sonnet' | 'haiku';
+        model?: string;
     }): Promise<ApiResponse<{
         success: boolean;
         reported: {
@@ -1676,7 +1676,7 @@ export declare class VibescopeApiClient {
      * Confirm that agent setup is complete for a project.
      * This marks the agent type as onboarded so future sessions don't receive setup instructions.
      */
-    confirmAgentSetup(projectId: string, agentType: 'claude' | 'gemini' | 'cursor' | 'windsurf' | 'other'): Promise<ApiResponse<{
+    confirmAgentSetup(projectId: string, agentType: string): Promise<ApiResponse<{
         success: boolean;
         project_id: string;
         agent_type: string;

package/dist/handlers/roles.js

@@ -63,14 +63,7 @@ export const setSessionRole = async (args, ctx) => {
             result: { error: 'role is required' },
         };
     }
-    const validRoles = ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'];
-    if (!validRoles.includes(role)) {
-        return {
-            result: {
-                error: `Invalid role: ${role}. Must be one of: ${validRoles.join(', ')}`,
-            },
-        };
-    }
+    // Role is now open-ended - any role name accepted
     // Update local session state
     updateSession({ currentRole: role });
     // If there's an active session, update it on the server too

package/dist/handlers/session.js

@@ -12,21 +12,19 @@ import os from 'os';
 import { parseArgs, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 import { getAgentGuidelinesTemplate, getAgentGuidelinesSummary } from '../templates/agent-guidelines.js';
+import { getFallbackHelpContent, getAvailableHelpTopics } from '../templates/help-content.js';
 // Auto-detect machine hostname for worktree tracking
 const MACHINE_HOSTNAME = os.hostname();
 const VALID_MODES = ['lite', 'full'];
-const VALID_MODELS = ['opus', 'sonnet', 'haiku'];
-const VALID_ROLES = ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'];
-const VALID_AGENT_TYPES = ['claude', 'gemini', 'cursor', 'windsurf', 'other'];
 // Argument schemas for type-safe parsing
 const startWorkSessionSchema = {
     project_id: { type: 'string' },
     git_url: { type: 'string' },
     mode: { type: 'string', default: 'lite', validate: createEnumValidator(VALID_MODES) },
-    model: { type: 'string', validate: createEnumValidator(VALID_MODELS) },
-    role: { type: 'string', default: 'developer', validate: createEnumValidator(VALID_ROLES) },
+    model: { type: 'string' }, // Open-ended - any model name accepted
+    role: { type: 'string', default: 'developer' }, // Open-ended - any role name accepted
     hostname: { type: 'string' }, // Machine hostname for worktree tracking
-    agent_type: { type: 'string', validate: createEnumValidator(VALID_AGENT_TYPES) }, // Agent type for onboarding
+    agent_type: { type: 'string' }, // Open-ended - any agent type accepted
 };
 const heartbeatSchema = {
     session_id: { type: 'string' },
@@ -45,17 +43,15 @@ export const startWorkSession = async (args, ctx) => {
     const hostname = providedHostname || MACHINE_HOSTNAME;
     const { session, updateSession } = ctx;
     // Reset token tracking for new session with model info
+    // Model is now open-ended - use as-is (normalize Claude model names for consistency)
     const normalizedModel = model ? model.toLowerCase().replace(/^claude[- ]*/i, '') : null;
-    const validModel = normalizedModel && VALID_MODELS.includes(normalizedModel)
-        ? normalizedModel
-        : null;
     updateSession({
         tokenUsage: {
             callCount: 0,
             totalTokens: 0,
             byTool: {},
             byModel: {},
-            currentModel: validModel,
+            currentModel: normalizedModel,
         },
     });
     // Require project_id or git_url
@@ -337,28 +333,23 @@ export const getHelp = async (args, _ctx) => {
     const { topic } = parseArgs(args, getHelpSchema);
     const apiClient = getApiClient();
     const response = await apiClient.getHelpTopic(topic);
-    if (!response.ok) {
-        // If database fetch fails, return error
-        return {
-            result: {
-                error: response.error || `Failed to fetch help topic: ${topic}`,
-            },
-        };
+    // Try database content first
+    if (response.ok && response.data?.content) {
+        return { result: { topic, content: response.data.content } };
     }
-    if (!response.data) {
-        // Topic not found - fetch available topics
-        const topicsResponse = await apiClient.getHelpTopics();
-        const available = topicsResponse.ok && topicsResponse.data
-            ? topicsResponse.data.map(t => t.slug)
-            : ['getting_started', 'tasks', 'validation', 'deployment', 'git', 'blockers', 'milestones', 'fallback', 'session', 'tokens', 'sprints', 'topics'];
-        return {
-            result: {
-                error: `Unknown topic: ${topic}`,
-                available,
-            },
-        };
+    // Fall back to local content if database is empty or unavailable
+    const fallback = getFallbackHelpContent(topic);
+    if (fallback) {
+        return { result: { topic, content: fallback.content } };
     }
-    return { result: { topic, content: response.data.content } };
+    // Topic not found in either source - show available topics
+    const available = getAvailableHelpTopics();
+    return {
+        result: {
+            error: `Unknown topic: ${topic}`,
+            available,
+        },
+    };
 };
 const MODEL_PRICING = {
     standard: {
@@ -479,11 +470,11 @@ export const getTokenUsage = async (_args, ctx) => {
 const reportTokenUsageSchema = {
     input_tokens: { type: 'number', required: true },
     output_tokens: { type: 'number', required: true },
-    model: { type: 'string', validate: createEnumValidator(VALID_MODELS) },
+    model: { type: 'string' }, // Open-ended - any model name accepted
 };
 const confirmAgentSetupSchema = {
     project_id: { type: 'string', required: true },
-    agent_type: { type: 'string', required: true, validate: createEnumValidator(VALID_AGENT_TYPES) },
+    agent_type: { type: 'string', required: true }, // Open-ended - any agent type accepted
 };
 /**
  * Report actual Claude API token usage for accurate cost tracking.

package/dist/handlers/validation.js

@@ -6,6 +6,7 @@
  * - claim_validation
  * - validate_task
  */
+import { error, success } from './types.js';
 import { parseArgs, uuidValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 // Argument schemas for type-safe parsing
@@ -26,9 +27,14 @@ export const getTasksAwaitingValidation = async (args, _ctx) => {
     const apiClient = getApiClient();
     const response = await apiClient.getTasksAwaitingValidation(project_id);
     if (!response.ok) {
-        return { result: { error: response.error || 'Failed to fetch tasks awaiting validation' }, isError: true };
+        return error(response.error || 'Failed to fetch tasks awaiting validation');
     }
-    return { result: response.data };
+    // Check for application-level errors (200 OK but error in body)
+    if (response.data && typeof response.data === 'object' && 'error' in response.data) {
+        const errMsg = typeof response.data.error === 'string' ? response.data.error : 'Unknown error';
+        return error(errMsg);
+    }
+    return success(response.data);
 };
 export const claimValidation = async (args, ctx) => {
     const { task_id } = parseArgs(args, claimValidationSchema);
@@ -37,9 +43,14 @@ export const claimValidation = async (args, ctx) => {
     const apiClient = getApiClient();
     const response = await apiClient.claimValidation(task_id, currentSessionId || undefined);
     if (!response.ok) {
-        return { result: { error: response.error || 'Failed to claim task for validation' }, isError: true };
+        return error(response.error || 'Failed to claim task for validation');
+    }
+    // Check for application-level errors (200 OK but error in body)
+    if (response.data && typeof response.data === 'object' && 'error' in response.data) {
+        const errMsg = typeof response.data.error === 'string' ? response.data.error : 'Unknown error';
+        return error(errMsg);
     }
-    return { result: response.data };
+    return success(response.data);
 };
 export const validateTask = async (args, ctx) => {
     const { task_id, approved, validation_notes, skip_pr_check } = parseArgs(args, validateTaskSchema);
@@ -54,18 +65,20 @@ export const validateTask = async (args, ctx) => {
     if (!response.ok) {
         // Handle PR required error specially
         if (response.error === 'pr_required') {
-            return {
-                result: {
-                    error: 'pr_required',
-                    message: response.data?.message || 'A Pull Request is required before validation approval. Create a PR and add it via add_task_reference.',
-                    workflow: response.data?.workflow,
-                    action_required: 'Create a PR for this task and add it via add_task_reference(task_id, pr_url, label: "Pull Request")',
-                },
-            };
+            return error('pr_required', {
+                message: response.data?.message || 'A Pull Request is required before validation approval. Create a PR and add it via add_task_reference.',
+                workflow: response.data?.workflow,
+                action_required: 'Create a PR for this task and add it via add_task_reference(task_id, pr_url, label: "Pull Request")',
+            });
         }
-        return { result: { error: response.error || 'Failed to validate task' }, isError: true };
+        return error(response.error || 'Failed to validate task');
+    }
+    // Check for application-level errors (200 OK but error in body)
+    if (response.data && typeof response.data === 'object' && 'error' in response.data) {
+        const errMsg = typeof response.data.error === 'string' ? response.data.error : 'Unknown error';
+        return error(errMsg);
     }
-    return { result: response.data };
+    return success(response.data);
 };
 /**
  * Validation handlers registry

package/dist/index.js

@@ -41,8 +41,8 @@ const handlerRegistry = buildHandlerRegistry();
 // ============================================================================
 const KNOWLEDGE_BASE = {
     getting_started: `# Getting Started
-1. Call start_work_session(git_url, model: "opus"|"sonnet"|"haiku") to initialize
-   - IMPORTANT: Pass your model for accurate cost tracking
+1. Call start_work_session(git_url, model: "your-model-name") to initialize
+   - IMPORTANT: Pass your model for accurate cost tracking (e.g., "opus", "sonnet", "gemini", "gpt-4o")
    - Check your system prompt for "You are powered by the model named..." to find it
 2. Response includes next_task - start working on it immediately
 3. Use update_task to mark in_progress and track progress
@@ -99,7 +99,7 @@ When no tasks available, get_next_task suggests activities:
 3. stop_fallback_activity(project_id, summary: "...")`,
     session: `# Session Management
 - start_work_session(git_url, model) initializes and returns next_task
-- ALWAYS pass model parameter ("opus", "sonnet", "haiku") for cost tracking
+- ALWAYS pass model parameter for cost tracking (e.g., "opus", "sonnet", "gemini", "gpt-4o")
 - Use mode:'lite' (default) or mode:'full' for complete context
 - heartbeat every 30-60 seconds maintains active status
 - end_work_session releases claimed tasks and returns summary

package/dist/setup.js

@@ -10,7 +10,7 @@ import { homedir, platform } from 'node:os';
 import { join, dirname } from 'node:path';
 import { exec } from 'node:child_process';
 const VIBESCOPE_SETTINGS_URL = 'https://vibescope.dev/dashboard/settings';
-const DEFAULT_SUPABASE_URL = 'https://uuneucmuubpgswvfijwd.supabase.co';
+const VIBESCOPE_API_URL = 'https://vibescope.dev';
 // ============================================================================
 // Config Path Helpers
 // ============================================================================
@@ -134,18 +134,21 @@ function openBrowser(url) {
 }
 export async function validateApiKey(apiKey) {
     try {
-        const response = await fetch(DEFAULT_SUPABASE_URL + '/rest/v1/api_keys?key=eq.' + apiKey + '&select=id', {
+        const response = await fetch(VIBESCOPE_API_URL + '/api/mcp/auth/validate', {
+            method: 'POST',
             headers: {
-                'apikey': apiKey,
-                'Authorization': 'Bearer ' + apiKey,
+                'Content-Type': 'application/json',
+                'X-API-Key': apiKey,
             },
+            body: JSON.stringify({ api_key: apiKey }),
         });
         if (response.ok) {
-            return { valid: true, message: 'API key validated successfully!' };
-        }
-        else {
-            return { valid: false, message: 'API key appears to be invalid.' };
+            const data = await response.json();
+            if (data.valid) {
+                return { valid: true, message: 'API key validated successfully!' };
+            }
         }
+        return { valid: false, message: 'API key appears to be invalid.' };
     }
     catch {
         return { valid: true, message: 'Could not validate API key (network issue), but proceeding.' };
@@ -239,23 +242,43 @@ export async function runSetup() {
             }
         }
     }
-    // Step 4: Get API key
+    // Step 4: Get API key (with retry logic)
     console.log('\n--- Step 1: Get your API key ---\n');
     console.log('Opening Vibescope settings page in your browser...');
     console.log("Create an API key if you don't have one, then copy it.\n");
     await openBrowser(VIBESCOPE_SETTINGS_URL);
-    const apiKey = await prompt('Paste your Vibescope API key: ');
-    if (!apiKey) {
-        console.error('\nError: API key is required.');
-        process.exit(1);
-    }
-    // Validate API key
-    console.log('\nValidating API key...');
-    const validation = await validateApiKey(apiKey);
-    console.log(validation.message);
-    if (!validation.valid) {
-        const proceed = await prompt('Proceed anyway? (y/N): ');
-        if (proceed.toLowerCase() !== 'y') {
+    const MAX_ATTEMPTS = 3;
+    let apiKey = '';
+    let attempts = 0;
+    while (attempts < MAX_ATTEMPTS) {
+        attempts++;
+        const attemptsRemaining = MAX_ATTEMPTS - attempts;
+        apiKey = await prompt('Paste your Vibescope API key: ');
+        if (!apiKey) {
+            if (attemptsRemaining > 0) {
+                console.log('\nAPI key is required. Please try again. (' + attemptsRemaining + ' attempt' + (attemptsRemaining === 1 ? '' : 's') + ' remaining)\n');
+                continue;
+            }
+            else {
+                console.error('\nError: API key is required. Setup cancelled.');
+                process.exit(1);
+            }
+        }
+        // Validate API key
+        console.log('\nValidating API key...');
+        const validation = await validateApiKey(apiKey);
+        console.log(validation.message);
+        if (validation.valid) {
+            break; // Success - exit the retry loop
+        }
+        // Invalid key
+        if (attemptsRemaining > 0) {
+            console.log('\nPlease check your API key and try again. (' + attemptsRemaining + ' attempt' + (attemptsRemaining === 1 ? '' : 's') + ' remaining)\n');
+        }
+        else {
+            console.error('\nMaximum attempts reached. Please verify your API key at:');
+            console.error('  ' + VIBESCOPE_SETTINGS_URL);
+            console.error('\nSetup cancelled.');
             process.exit(1);
         }
     }
@@ -302,7 +325,14 @@ export async function runSetup() {
             console.log('Next steps:');
             console.log('  1. Restart Gemini CLI');
             console.log('  2. Verify connection: gemini mcp list');
-            console.log('  3. Start using Vibescope in your conversation');
+            console.log('  3. In your conversation, call the MCP tool: start_work_session(git_url: "...", agent_type: "gemini")');
+            console.log('');
+            console.log('IMPORTANT: Vibescope tools are MCP tool calls, NOT CLI commands.');
+            console.log('Do NOT run "vibescope-cli start_work_session" - that command does not exist.');
+            console.log('');
+            console.log('NOTE: If you manually edit the config later, do NOT use $VAR_NAME syntax');
+            console.log('for environment variables - Gemini CLI has a bug where this does not work.');
+            console.log('Always hardcode API keys directly or use ~/.gemini/.env instead.');
             break;
         default:
             console.log('Next steps:');

package/dist/templates/help-content.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Fallback Help Content
+ *
+ * This provides comprehensive help content for each topic when the backend
+ * database has no content populated. Ensures agents always get useful guidance.
+ */
+export declare const HELP_TOPICS: Record<string, {
+    title: string;
+    content: string;
+}>;
+/**
+ * Get fallback help content for a topic
+ * @param topic The help topic slug
+ * @returns The help content or null if topic not found
+ */
+export declare function getFallbackHelpContent(topic: string): {
+    title: string;
+    content: string;
+} | null;
+/**
+ * Get list of available help topics
+ * @returns Array of topic slugs
+ */
+export declare function getAvailableHelpTopics(): string[];