@vibescope/mcp-server 0.2.8 → 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/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[];