@vibescope/mcp-server 0.1.0 → 0.2.1

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,14 +8,35 @@
  * - get_help
  * - get_token_usage
  */
-import { KNOWLEDGE_BASE } from '../knowledge.js';
+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({
@@ -39,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 {
@@ -114,7 +135,7 @@ export const startWorkSession = async (args, ctx) => {
     return { result };
 };
 export const heartbeat = async (args, ctx) => {
-    const { session_id } = args;
+    const { session_id, current_worktree_path } = parseArgs(args, heartbeatSchema);
     const { session } = ctx;
     const targetSession = session_id || session.currentSessionId;
     if (!targetSession) {
@@ -125,8 +146,10 @@ export const heartbeat = async (args, ctx) => {
         };
     }
     const apiClient = getApiClient();
-    // Send heartbeat
-    const heartbeatResponse = await apiClient.heartbeat(targetSession);
+    // Send heartbeat with optional worktree path
+    const heartbeatResponse = await apiClient.heartbeat(targetSession, {
+        current_worktree_path,
+    });
     if (!heartbeatResponse.ok) {
         return {
             result: {
@@ -149,7 +172,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) {
@@ -204,17 +227,31 @@ export const endWorkSession = async (args, ctx) => {
     };
 };
 export const getHelp = async (args, _ctx) => {
-    const { topic } = args;
-    const content = KNOWLEDGE_BASE[topic];
-    if (!content) {
+    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}`,
+            },
+        };
+    }
+    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: Object.keys(KNOWLEDGE_BASE),
+                available,
             },
         };
     }
-    return { result: { topic, content } };
+    return { result: { topic, content: response.data.content } };
 };
 // Model pricing rates (USD per 1M tokens)
 const MODEL_PRICING = {

package/dist/handlers/sprints.js

@@ -14,25 +14,76 @@
  * - get_sprint_backlog
  * - get_sprint_velocity
  */
-import { validateRequired, validateUUID, validateEnum } from '../validators.js';
+import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 const SPRINT_STATUSES = ['planning', 'active', 'in_review', 'retrospective', 'completed', 'cancelled'];
 const TASK_PHASES = ['pre', 'core', 'post'];
 const DEPLOY_ENVIRONMENTS = ['development', 'staging', 'production'];
 const VERSION_BUMPS = ['patch', 'minor', 'major'];
+// ============================================================================
+// Argument Schemas
+// ============================================================================
+const createSprintSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    title: { type: 'string', required: true },
+    goal: { type: 'string' },
+    start_date: { type: 'string', required: true },
+    end_date: { type: 'string', required: true },
+    auto_deploy_on_completion: { type: 'boolean' },
+    deploy_environment: { type: 'string', validate: createEnumValidator(DEPLOY_ENVIRONMENTS) },
+    deploy_version_bump: { type: 'string', validate: createEnumValidator(VERSION_BUMPS) },
+};
+const updateSprintSchema = {
+    sprint_id: { type: 'string', required: true, validate: uuidValidator },
+    title: { type: 'string' },
+    goal: { type: 'string' },
+    start_date: { type: 'string' },
+    end_date: { type: 'string' },
+    auto_deploy_on_completion: { type: 'boolean' },
+    deploy_environment: { type: 'string', validate: createEnumValidator(DEPLOY_ENVIRONMENTS) },
+    deploy_version_bump: { type: 'string', validate: createEnumValidator(VERSION_BUMPS) },
+};
+const getSprintSchema = {
+    sprint_id: { type: 'string', required: true, validate: uuidValidator },
+    summary_only: { type: 'boolean', default: false },
+};
+const getSprintsSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    status: { type: 'string', validate: createEnumValidator(SPRINT_STATUSES) },
+    limit: { type: 'number', default: 20 },
+    offset: { type: 'number', default: 0 },
+};
+const deleteSprintSchema = {
+    sprint_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const startSprintSchema = {
+    sprint_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const completeSprintSchema = {
+    sprint_id: { type: 'string', required: true, validate: uuidValidator },
+    retrospective_notes: { type: 'string' },
+    skip_retrospective: { type: 'boolean' },
+};
+const addTaskToSprintSchema = {
+    sprint_id: { type: 'string', required: true, validate: uuidValidator },
+    task_id: { type: 'string', required: true, validate: uuidValidator },
+    story_points: { type: 'number' },
+    phase: { type: 'string', validate: createEnumValidator(TASK_PHASES) },
+};
+const removeTaskFromSprintSchema = {
+    sprint_id: { type: 'string', required: true, validate: uuidValidator },
+    task_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const getSprintBacklogSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    sprint_id: { type: 'string', validate: uuidValidator },
+};
+const getSprintVelocitySchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    limit: { type: 'number', default: 10 },
+};
 export const createSprint = async (args, ctx) => {
-    const { project_id, title, goal, start_date, end_date, auto_deploy_on_completion, deploy_environment, deploy_version_bump, } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
-    validateRequired(title, 'title');
-    validateRequired(start_date, 'start_date');
-    validateRequired(end_date, 'end_date');
-    if (deploy_environment) {
-        validateEnum(deploy_environment, DEPLOY_ENVIRONMENTS, 'deploy_environment');
-    }
-    if (deploy_version_bump) {
-        validateEnum(deploy_version_bump, VERSION_BUMPS, 'deploy_version_bump');
-    }
+    const { project_id, title, goal, start_date, end_date, auto_deploy_on_completion, deploy_environment, deploy_version_bump, } = parseArgs(args, createSprintSchema);
     // Validate date format and order
     const startDateObj = new Date(start_date);
     const endDateObj = new Date(end_date);
@@ -78,15 +129,7 @@ export const createSprint = async (args, ctx) => {
     };
 };
 export const updateSprint = async (args, ctx) => {
-    const { sprint_id, title, goal, start_date, end_date, auto_deploy_on_completion, deploy_environment, deploy_version_bump, } = args;
-    validateRequired(sprint_id, 'sprint_id');
-    validateUUID(sprint_id, 'sprint_id');
-    if (deploy_environment) {
-        validateEnum(deploy_environment, DEPLOY_ENVIRONMENTS, 'deploy_environment');
-    }
-    if (deploy_version_bump) {
-        validateEnum(deploy_version_bump, VERSION_BUMPS, 'deploy_version_bump');
-    }
+    const { sprint_id, title, goal, start_date, end_date, auto_deploy_on_completion, deploy_environment, deploy_version_bump, } = parseArgs(args, updateSprintSchema);
     // Validate dates if provided
     if (start_date) {
         const startDateObj = new Date(start_date);
@@ -117,28 +160,22 @@ export const updateSprint = async (args, ctx) => {
     return { result: { success: true, sprint_id } };
 };
 export const getSprint = async (args, ctx) => {
-    const { sprint_id } = args;
-    validateRequired(sprint_id, 'sprint_id');
-    validateUUID(sprint_id, 'sprint_id');
+    const { sprint_id, summary_only } = parseArgs(args, getSprintSchema);
     const apiClient = getApiClient();
-    const response = await apiClient.proxy('get_sprint', { sprint_id });
+    // Response type varies based on summary_only
+    const response = await apiClient.proxy('get_sprint', { sprint_id, summary_only });
     if (!response.ok) {
         throw new Error(`Failed to get sprint: ${response.error}`);
     }
     return { result: response.data };
 };
 export const getSprints = async (args, ctx) => {
-    const { project_id, status, limit = 20, offset = 0 } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
-    if (status) {
-        validateEnum(status, SPRINT_STATUSES, 'status');
-    }
+    const { project_id, status, limit, offset } = parseArgs(args, getSprintsSchema);
     const apiClient = getApiClient();
     const response = await apiClient.proxy('get_sprints', {
         project_id,
         status,
-        limit: Math.min(limit, 100),
+        limit: Math.min(limit ?? 20, 100),
         offset,
     });
     if (!response.ok) {
@@ -147,9 +184,7 @@ export const getSprints = async (args, ctx) => {
     return { result: response.data };
 };
 export const deleteSprint = async (args, ctx) => {
-    const { sprint_id } = args;
-    validateRequired(sprint_id, 'sprint_id');
-    validateUUID(sprint_id, 'sprint_id');
+    const { sprint_id } = parseArgs(args, deleteSprintSchema);
     const apiClient = getApiClient();
     const response = await apiClient.proxy('delete_sprint', {
         sprint_id
@@ -160,9 +195,7 @@ export const deleteSprint = async (args, ctx) => {
     return { result: { success: true, message: 'Sprint deleted. Tasks are preserved.' } };
 };
 export const startSprint = async (args, ctx) => {
-    const { sprint_id } = args;
-    validateRequired(sprint_id, 'sprint_id');
-    validateUUID(sprint_id, 'sprint_id');
+    const { sprint_id } = parseArgs(args, startSprintSchema);
     const apiClient = getApiClient();
     const response = await apiClient.proxy('start_sprint', { sprint_id });
     if (!response.ok) {
@@ -171,9 +204,7 @@ export const startSprint = async (args, ctx) => {
     return { result: response.data };
 };
 export const completeSprint = async (args, ctx) => {
-    const { sprint_id, retrospective_notes, skip_retrospective } = args;
-    validateRequired(sprint_id, 'sprint_id');
-    validateUUID(sprint_id, 'sprint_id');
+    const { sprint_id, retrospective_notes, skip_retrospective } = parseArgs(args, completeSprintSchema);
     const apiClient = getApiClient();
     const response = await apiClient.proxy('complete_sprint', {
         sprint_id,
@@ -186,14 +217,7 @@ export const completeSprint = async (args, ctx) => {
     return { result: response.data };
 };
 export const addTaskToSprint = async (args, ctx) => {
-    const { sprint_id, task_id, story_points, phase } = args;
-    validateRequired(sprint_id, 'sprint_id');
-    validateUUID(sprint_id, 'sprint_id');
-    validateRequired(task_id, 'task_id');
-    validateUUID(task_id, 'task_id');
-    if (phase) {
-        validateEnum(phase, TASK_PHASES, 'phase');
-    }
+    const { sprint_id, task_id, story_points, phase } = parseArgs(args, addTaskToSprintSchema);
     if (story_points !== undefined && (story_points < 0 || !Number.isInteger(story_points))) {
         throw new Error('story_points must be a non-negative integer');
     }
@@ -210,11 +234,7 @@ export const addTaskToSprint = async (args, ctx) => {
     return { result: response.data };
 };
 export const removeTaskFromSprint = async (args, ctx) => {
-    const { sprint_id, task_id } = args;
-    validateRequired(sprint_id, 'sprint_id');
-    validateUUID(sprint_id, 'sprint_id');
-    validateRequired(task_id, 'task_id');
-    validateUUID(task_id, 'task_id');
+    const { sprint_id, task_id } = parseArgs(args, removeTaskFromSprintSchema);
     const apiClient = getApiClient();
     const response = await apiClient.proxy('remove_task_from_sprint', {
         sprint_id,
@@ -226,12 +246,7 @@ export const removeTaskFromSprint = async (args, ctx) => {
     return { result: response.data };
 };
 export const getSprintBacklog = async (args, ctx) => {
-    const { project_id, sprint_id } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
-    if (sprint_id) {
-        validateUUID(sprint_id, 'sprint_id');
-    }
+    const { project_id, sprint_id } = parseArgs(args, getSprintBacklogSchema);
     const apiClient = getApiClient();
     const response = await apiClient.proxy('get_sprint_backlog', {
         project_id,
@@ -243,13 +258,11 @@ export const getSprintBacklog = async (args, ctx) => {
     return { result: response.data };
 };
 export const getSprintVelocity = async (args, ctx) => {
-    const { project_id, limit = 10 } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
+    const { project_id, limit } = parseArgs(args, getSprintVelocitySchema);
     const apiClient = getApiClient();
     const response = await apiClient.proxy('get_sprint_velocity', {
         project_id,
-        limit: Math.min(limit, 50),
+        limit: Math.min(limit ?? 10, 50),
     });
     if (!response.ok) {
         throw new Error(`Failed to get sprint velocity: ${response.error}`);