@vibescope/mcp-server 0.2.0 → 0.2.2

package/dist/handlers/progress.js

@@ -7,13 +7,24 @@
  *
  * MIGRATED: Uses Vibescope API client instead of direct Supabase
  */
-import { validateRequired, validateUUID } from '../validators.js';
+import { parseArgs, uuidValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
+// Argument schemas for type-safe parsing
+const logProgressSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    task_id: { type: 'string', validate: uuidValidator },
+    summary: { type: 'string', required: true },
+    details: { type: 'string' },
+};
+const getActivityFeedSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    limit: { type: 'number', default: 50 },
+    since: { type: 'string' },
+    types: { type: 'array' },
+    created_by: { type: 'string' },
+};
 export const logProgress = async (args, ctx) => {
-    const { project_id, task_id, summary, details } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
-    validateRequired(summary, 'summary');
+    const { project_id, task_id, summary, details } = parseArgs(args, logProgressSchema);
     const { session } = ctx;
     const apiClient = getApiClient();
     const response = await apiClient.logProgress(project_id, {
@@ -23,22 +34,22 @@ export const logProgress = async (args, ctx) => {
         session_id: session.currentSessionId || undefined
     });
     if (!response.ok) {
-        throw new Error(`Failed to log progress: ${response.error}`);
+        return { result: { error: response.error || 'Failed to log progress' }, isError: true };
     }
     return { result: { success: true, progress_id: response.data?.progress_id } };
 };
-export const getActivityFeed = async (args, ctx) => {
-    const { project_id, limit = 50, since } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
+export const getActivityFeed = async (args, _ctx) => {
+    const { project_id, limit, since, types, created_by } = parseArgs(args, getActivityFeedSchema);
     const apiClient = getApiClient();
-    const effectiveLimit = Math.min(limit, 200);
+    const effectiveLimit = Math.min(limit ?? 50, 200);
     const response = await apiClient.getActivityFeed(project_id, {
         limit: effectiveLimit,
-        since
+        since,
+        types: types,
+        created_by
     });
     if (!response.ok) {
-        throw new Error(`Failed to fetch activity feed: ${response.error}`);
+        return { result: { error: response.error || 'Failed to fetch activity feed' }, isError: true };
     }
     return { result: { activities: response.data?.activities || [] } };
 };

package/dist/handlers/project.js

@@ -8,23 +8,59 @@
  * - update_project
  * - update_project_readme
  */
-import { validateRequired, validateUUID, validateProjectStatus } from '../validators.js';
+import { parseArgs, uuidValidator, projectStatusValidator, createEnumValidator, } from '../validators.js';
 import { getApiClient } from '../api-client.js';
-export const getProjectContext = async (args, ctx) => {
-    const { project_id, git_url } = args;
+const VALID_GIT_WORKFLOWS = ['none', 'trunk-based', 'github-flow', 'git-flow'];
+// Argument schemas for type-safe parsing
+const getProjectContextSchema = {
+    project_id: { type: 'string', validate: uuidValidator },
+    git_url: { type: 'string' },
+};
+const getGitWorkflowSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    task_id: { type: 'string', validate: uuidValidator },
+};
+const createProjectSchema = {
+    name: { type: 'string', required: true },
+    description: { type: 'string' },
+    goal: { type: 'string' },
+    git_url: { type: 'string' },
+    tech_stack: { type: 'array' },
+};
+const updateProjectSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    name: { type: 'string' },
+    description: { type: 'string' },
+    goal: { type: 'string' },
+    git_url: { type: 'string' },
+    tech_stack: { type: 'array' },
+    status: { type: 'string', validate: projectStatusValidator },
+    git_workflow: { type: 'string', validate: createEnumValidator(VALID_GIT_WORKFLOWS) },
+    git_main_branch: { type: 'string' },
+    git_develop_branch: { type: 'string' },
+    git_auto_branch: { type: 'boolean' },
+    git_auto_tag: { type: 'boolean' },
+    deployment_instructions: { type: 'string' },
+};
+const updateProjectReadmeSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    readme_content: { type: 'string', required: true },
+};
+export const getProjectContext = async (args, _ctx) => {
+    const { project_id, git_url } = parseArgs(args, getProjectContextSchema);
     const apiClient = getApiClient();
     // If no project_id or git_url, list all projects
     if (!project_id && !git_url) {
         const response = await apiClient.listProjects();
         if (!response.ok) {
-            throw new Error(response.error || 'Failed to fetch projects');
+            return { result: { error: response.error || 'Failed to fetch projects' }, isError: true };
         }
         return { result: { projects: response.data?.projects || [] } };
     }
     // Find project by ID or git_url
     const response = await apiClient.getProject(project_id || 'by-git-url', git_url);
     if (!response.ok) {
-        throw new Error(response.error || 'Failed to fetch project');
+        return { result: { error: response.error || 'Failed to fetch project' }, isError: true };
     }
     if (!response.data?.found) {
         return {
@@ -36,54 +72,58 @@ export const getProjectContext = async (args, ctx) => {
     }
     return { result: response.data };
 };
-export const getGitWorkflow = async (args, ctx) => {
-    const { project_id, task_id } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
+export const getGitWorkflow = async (args, _ctx) => {
+    const { project_id, task_id } = parseArgs(args, getGitWorkflowSchema);
     const apiClient = getApiClient();
     const response = await apiClient.getGitWorkflow(project_id, task_id);
     if (!response.ok) {
-        throw new Error(response.error || 'Failed to get git workflow');
+        return { result: { error: response.error || 'Failed to get git workflow' }, isError: true };
     }
     return { result: response.data };
 };
-export const createProject = async (args, ctx) => {
-    const { name, description, goal, git_url, tech_stack } = args;
-    validateRequired(name, 'name');
+export const createProject = async (args, _ctx) => {
+    const { name, description, goal, git_url, tech_stack } = parseArgs(args, createProjectSchema);
     const apiClient = getApiClient();
     const response = await apiClient.createProject({
         name,
         description,
         goal,
         git_url,
-        tech_stack
+        tech_stack: tech_stack
     });
     if (!response.ok) {
-        throw new Error(response.error || 'Failed to create project');
+        return { result: { error: response.error || 'Failed to create project' }, isError: true };
     }
     return { result: response.data };
 };
-export const updateProject = async (args, ctx) => {
-    const { project_id, ...updates } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
-    validateProjectStatus(updates.status);
+export const updateProject = async (args, _ctx) => {
+    const { project_id, name, description, goal, git_url, tech_stack, status, git_workflow, git_main_branch, git_develop_branch, git_auto_branch, git_auto_tag, deployment_instructions } = parseArgs(args, updateProjectSchema);
     const apiClient = getApiClient();
-    const response = await apiClient.updateProject(project_id, updates);
+    const response = await apiClient.updateProject(project_id, {
+        name,
+        description,
+        goal,
+        git_url,
+        tech_stack: tech_stack,
+        status: status,
+        git_workflow: git_workflow,
+        git_main_branch,
+        git_develop_branch,
+        git_auto_branch,
+        git_auto_tag,
+        deployment_instructions
+    });
     if (!response.ok) {
-        throw new Error(response.error || 'Failed to update project');
+        return { result: { error: response.error || 'Failed to update project' }, isError: true };
     }
     return { result: response.data };
 };
-export const updateProjectReadme = async (args, ctx) => {
-    const { project_id, readme_content } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
-    validateRequired(readme_content, 'readme_content');
+export const updateProjectReadme = async (args, _ctx) => {
+    const { project_id, readme_content } = parseArgs(args, updateProjectReadmeSchema);
     const apiClient = getApiClient();
     const response = await apiClient.updateProjectReadme(project_id, readme_content);
     if (!response.ok) {
-        throw new Error(response.error || 'Failed to update README');
+        return { result: { error: response.error || 'Failed to update README' }, isError: true };
     }
     return { result: response.data };
 };

package/dist/handlers/requests.js

@@ -8,17 +8,26 @@
  *
  * MIGRATED: Uses Vibescope API client instead of direct Supabase
  */
-import { validateRequired, validateUUID } from '../validators.js';
+import { parseArgs, uuidValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
+// Argument schemas for type-safe parsing
+const getPendingRequestsSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const acknowledgeRequestSchema = {
+    request_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const answerQuestionSchema = {
+    request_id: { type: 'string', required: true, validate: uuidValidator },
+    answer: { type: 'string', required: true },
+};
 export const getPendingRequests = async (args, ctx) => {
-    const { project_id } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
+    const { project_id } = parseArgs(args, getPendingRequestsSchema);
     const { session } = ctx;
     const apiClient = getApiClient();
     const response = await apiClient.getPendingRequests(project_id, session.currentSessionId || undefined);
     if (!response.ok) {
-        throw new Error(`Failed to get pending requests: ${response.error}`);
+        return { result: { error: response.error || 'Failed to get pending requests' }, isError: true };
     }
     return {
         result: {
@@ -28,14 +37,12 @@ export const getPendingRequests = async (args, ctx) => {
     };
 };
 export const acknowledgeRequest = async (args, ctx) => {
-    const { request_id } = args;
-    validateRequired(request_id, 'request_id');
-    validateUUID(request_id, 'request_id');
+    const { request_id } = parseArgs(args, acknowledgeRequestSchema);
     const { session } = ctx;
     const apiClient = getApiClient();
     const response = await apiClient.acknowledgeRequest(request_id, session.currentSessionId || undefined);
     if (!response.ok) {
-        throw new Error(`Failed to acknowledge request: ${response.error}`);
+        return { result: { error: response.error || 'Failed to acknowledge request' }, isError: true };
     }
     return {
         result: {
@@ -44,15 +51,12 @@ export const acknowledgeRequest = async (args, ctx) => {
     };
 };
 export const answerQuestion = async (args, ctx) => {
-    const { request_id, answer } = args;
-    validateRequired(request_id, 'request_id');
-    validateRequired(answer, 'answer');
-    validateUUID(request_id, 'request_id');
+    const { request_id, answer } = parseArgs(args, answerQuestionSchema);
     const { session } = ctx;
     const apiClient = getApiClient();
     const response = await apiClient.answerQuestion(request_id, answer, session.currentSessionId || undefined);
     if (!response.ok) {
-        throw new Error(`Failed to answer question: ${response.error}`);
+        return { result: { error: response.error || 'Failed to answer question' }, isError: true };
     }
     return {
         result: {

package/dist/handlers/roles.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Role Management Handlers
+ *
+ * Handles agent role configuration and assignment:
+ * - get_role_settings: Get role configuration for a project
+ * - update_role_settings: Update role settings for a project
+ * - set_session_role: Set the role for the current session
+ * - get_agents_by_role: Get active agents grouped by their assigned roles
+ */
+import type { Handler, HandlerRegistry } from './types.js';
+export declare const getRoleSettings: Handler;
+export declare const updateRoleSettings: Handler;
+export declare const setSessionRole: Handler;
+export declare const getAgentsByRole: Handler;
+/**
+ * Role handlers registry
+ */
+export declare const roleHandlers: HandlerRegistry;

package/dist/handlers/roles.js

@@ -0,0 +1,130 @@
+/**
+ * Role Management Handlers
+ *
+ * Handles agent role configuration and assignment:
+ * - get_role_settings: Get role configuration for a project
+ * - update_role_settings: Update role settings for a project
+ * - set_session_role: Set the role for the current session
+ * - get_agents_by_role: Get active agents grouped by their assigned roles
+ */
+import { getApiClient } from '../api-client.js';
+export const getRoleSettings = async (args, _ctx) => {
+    const { project_id } = args;
+    if (!project_id) {
+        return {
+            result: { error: 'project_id is required' },
+        };
+    }
+    const apiClient = getApiClient();
+    const response = await apiClient.proxy('get_role_settings', { project_id });
+    if (!response.ok) {
+        return {
+            result: { error: response.error || 'Failed to get role settings' },
+        };
+    }
+    return { result: response.data };
+};
+export const updateRoleSettings = async (args, _ctx) => {
+    const { project_id, role, enabled, display_name, description, priority_filter, fallback_activities, auto_assign_validation, auto_assign_deployment, } = args;
+    if (!project_id) {
+        return {
+            result: { error: 'project_id is required' },
+        };
+    }
+    if (!role) {
+        return {
+            result: { error: 'role is required' },
+        };
+    }
+    const apiClient = getApiClient();
+    const response = await apiClient.proxy('update_role_settings', {
+        project_id,
+        role,
+        enabled,
+        display_name,
+        description,
+        priority_filter,
+        fallback_activities,
+        auto_assign_validation,
+        auto_assign_deployment,
+    });
+    if (!response.ok) {
+        return {
+            result: { error: response.error || 'Failed to update role settings' },
+        };
+    }
+    return { result: response.data };
+};
+export const setSessionRole = async (args, ctx) => {
+    const { role, role_config } = args;
+    const { session, updateSession } = ctx;
+    if (!role) {
+        return {
+            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(', ')}`,
+            },
+        };
+    }
+    // Update local session state
+    updateSession({ currentRole: role });
+    // If there's an active session, update it on the server too
+    if (session.currentSessionId) {
+        const apiClient = getApiClient();
+        const response = await apiClient.proxy('set_session_role', {
+            session_id: session.currentSessionId,
+            role,
+            role_config,
+        });
+        if (!response.ok) {
+            return {
+                result: { error: response.error || 'Failed to update session role' },
+            };
+        }
+        return {
+            result: {
+                success: true,
+                session_id: session.currentSessionId,
+                role,
+                message: `Session role updated to ${role}. Task filtering and fallback suggestions will now be optimized for this role.`,
+            },
+        };
+    }
+    return {
+        result: {
+            success: true,
+            role,
+            message: `Local role set to ${role}. Start a session to persist this role.`,
+        },
+    };
+};
+export const getAgentsByRole = async (args, _ctx) => {
+    const { project_id } = args;
+    if (!project_id) {
+        return {
+            result: { error: 'project_id is required' },
+        };
+    }
+    const apiClient = getApiClient();
+    const response = await apiClient.proxy('get_agents_by_role', { project_id });
+    if (!response.ok) {
+        return {
+            result: { error: response.error || 'Failed to get agents by role' },
+        };
+    }
+    return { result: response.data };
+};
+/**
+ * Role handlers registry
+ */
+export const roleHandlers = {
+    get_role_settings: getRoleSettings,
+    update_role_settings: updateRoleSettings,
+    set_session_role: setSessionRole,
+    get_agents_by_role: getAgentsByRole,
+};

package/dist/handlers/session.js

@@ -8,13 +8,35 @@
  * - get_help
  * - get_token_usage
  */
+import { parseArgs, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
+const VALID_MODES = ['lite', 'full'];
+const VALID_MODELS = ['opus', 'sonnet', 'haiku'];
+const VALID_ROLES = ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'];
+// 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) },
+};
+const heartbeatSchema = {
+    session_id: { type: 'string' },
+    current_worktree_path: { type: 'string' },
+};
+const endWorkSessionSchema = {
+    session_id: { type: 'string' },
+};
+const getHelpSchema = {
+    topic: { type: 'string', required: true },
+};
 export const startWorkSession = async (args, ctx) => {
-    const { project_id, git_url, mode = 'lite', model, role = 'developer' } = args;
+    const { project_id, git_url, mode, model, role } = parseArgs(args, startWorkSessionSchema);
     const { session, updateSession } = ctx;
     // Reset token tracking for new session with model info
     const normalizedModel = model ? model.toLowerCase().replace(/^claude[- ]*/i, '') : null;
-    const validModel = normalizedModel && ['opus', 'sonnet', 'haiku'].includes(normalizedModel)
+    const validModel = normalizedModel && VALID_MODELS.includes(normalizedModel)
         ? normalizedModel
         : null;
     updateSession({
@@ -38,9 +60,9 @@ export const startWorkSession = async (args, ctx) => {
     const response = await apiClient.startSession({
         project_id,
         git_url,
-        mode,
-        model,
-        role
+        mode: mode,
+        model: model,
+        role: role
     });
     if (!response.ok) {
         return {
@@ -61,20 +83,33 @@ export const startWorkSession = async (args, ctx) => {
             currentPersona: data.persona || null,
         });
     }
-    // Build result with directive at top for visibility
+    // Check for urgent questions - these MUST be handled first
+    const hasUrgentQuestions = data.URGENT_QUESTIONS || (data.pending_requests && data.pending_requests.length > 0);
+    // Build result - URGENT_QUESTIONS at absolute top for maximum visibility
     const result = {
         session_started: true,
-        directive: data.directive || 'ACTION_REQUIRED: Start working immediately.',
-        auto_continue: true,
-        session_id: data.session_id,
-        persona: data.persona,
-        role: data.role,
-        project: data.project,
     };
+    // URGENT_QUESTIONS must be the FIRST thing the agent sees
+    if (data.URGENT_QUESTIONS) {
+        result.URGENT_QUESTIONS = data.URGENT_QUESTIONS;
+    }
+    // Directive comes right after urgent questions
+    result.directive = data.directive || 'ACTION_REQUIRED: Start working immediately.';
+    result.auto_continue = true;
+    // Session info
+    result.session_id = data.session_id;
+    result.persona = data.persona;
+    result.role = data.role;
+    result.project = data.project;
     // Add task data
     if (data.next_task) {
         result.next_task = data.next_task;
     }
+    // Add pending requests (questions from user) - these take priority
+    if (data.pending_requests && data.pending_requests.length > 0) {
+        result.pending_requests = data.pending_requests;
+        result.pending_requests_count = data.pending_requests.length;
+    }
     // Add active tasks for full mode
     if (data.active_tasks) {
         result.active_tasks = data.active_tasks;
@@ -103,8 +138,14 @@ export const startWorkSession = async (args, ctx) => {
             worktree_hint: 'CRITICAL: Create a git worktree before starting work. Run get_help("git") for instructions.',
         };
     }
-    // Add next action at end
-    if (data.next_task) {
+    // Add next action at end - pending requests take priority over tasks
+    if (hasUrgentQuestions) {
+        const firstQuestion = data.URGENT_QUESTIONS?.requests?.[0] || data.pending_requests?.[0];
+        result.next_action = firstQuestion
+            ? `answer_question(request_id: "${firstQuestion.id}", answer: "...")`
+            : 'Check pending_requests and respond using answer_question(request_id, answer)';
+    }
+    else if (data.next_task) {
         result.next_action = `update_task(task_id: "${data.next_task.id}", status: "in_progress")`;
     }
     else if (data.project) {
@@ -113,7 +154,7 @@ export const startWorkSession = async (args, ctx) => {
     return { result };
 };
 export const heartbeat = async (args, ctx) => {
-    const { session_id, current_worktree_path } = args;
+    const { session_id, current_worktree_path } = parseArgs(args, heartbeatSchema);
     const { session } = ctx;
     const targetSession = session_id || session.currentSessionId;
     if (!targetSession) {
@@ -150,7 +191,7 @@ export const heartbeat = async (args, ctx) => {
     };
 };
 export const endWorkSession = async (args, ctx) => {
-    const { session_id } = args;
+    const { session_id } = parseArgs(args, endWorkSessionSchema);
     const { session, updateSession } = ctx;
     const targetSession = session_id || session.currentSessionId;
     if (!targetSession) {
@@ -205,7 +246,7 @@ export const endWorkSession = async (args, ctx) => {
     };
 };
 export const getHelp = async (args, _ctx) => {
-    const { topic } = args;
+    const { topic } = parseArgs(args, getHelpSchema);
     const apiClient = getApiClient();
     const response = await apiClient.getHelpTopic(topic);
     if (!response.ok) {