@vibescope/mcp-server 0.2.0 → 0.2.1

package/dist/handlers/validation.js

@@ -6,12 +6,23 @@
  * - claim_validation
  * - validate_task
  */
-import { validateRequired, validateUUID } from '../validators.js';
+import { parseArgs, uuidValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
-export const getTasksAwaitingValidation = async (args, ctx) => {
-    const { project_id } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
+// Argument schemas for type-safe parsing
+const getTasksAwaitingValidationSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const claimValidationSchema = {
+    task_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const validateTaskSchema = {
+    task_id: { type: 'string', required: true, validate: uuidValidator },
+    approved: { type: 'boolean', required: true },
+    validation_notes: { type: 'string' },
+    skip_pr_check: { type: 'boolean' },
+};
+export const getTasksAwaitingValidation = async (args, _ctx) => {
+    const { project_id } = parseArgs(args, getTasksAwaitingValidationSchema);
     const apiClient = getApiClient();
     const response = await apiClient.getTasksAwaitingValidation(project_id);
     if (!response.ok) {
@@ -20,9 +31,7 @@ export const getTasksAwaitingValidation = async (args, ctx) => {
     return { result: response.data };
 };
 export const claimValidation = async (args, ctx) => {
-    const { task_id } = args;
-    validateRequired(task_id, 'task_id');
-    validateUUID(task_id, 'task_id');
+    const { task_id } = parseArgs(args, claimValidationSchema);
     const { session } = ctx;
     const currentSessionId = session.currentSessionId;
     const apiClient = getApiClient();
@@ -33,12 +42,7 @@ export const claimValidation = async (args, ctx) => {
     return { result: response.data };
 };
 export const validateTask = async (args, ctx) => {
-    const { task_id, validation_notes, approved, skip_pr_check } = args;
-    validateRequired(task_id, 'task_id');
-    validateUUID(task_id, 'task_id');
-    if (approved === undefined) {
-        throw new Error('approved is required');
-    }
+    const { task_id, approved, validation_notes, skip_pr_check } = parseArgs(args, validateTaskSchema);
     const { session } = ctx;
     const currentSessionId = session.currentSessionId;
     const apiClient = getApiClient();

package/dist/tools.js

@@ -2525,4 +2525,391 @@ Only returns tasks where all dependencies are completed.`,
             required: ['project_id'],
         },
     },
+    // ============================================================================
+    // Sprint Tools
+    // ============================================================================
+    {
+        name: 'create_sprint',
+        description: `Create a new sprint. Sprints are time-bounded bodies of work with velocity tracking.
+Sprints start in 'planning' status where tasks can be added with story points.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                title: {
+                    type: 'string',
+                    description: 'Sprint title (e.g., "Sprint 5" or "Q1 Release")',
+                },
+                goal: {
+                    type: 'string',
+                    description: 'Sprint goal statement',
+                },
+                start_date: {
+                    type: 'string',
+                    description: 'Start date (YYYY-MM-DD)',
+                },
+                end_date: {
+                    type: 'string',
+                    description: 'End date (YYYY-MM-DD)',
+                },
+                auto_deploy_on_completion: {
+                    type: 'boolean',
+                    description: 'Automatically request deployment when sprint completes (default: false)',
+                },
+                deploy_environment: {
+                    type: 'string',
+                    enum: ['development', 'staging', 'production'],
+                    description: 'Target environment for auto-deploy (default: production)',
+                },
+                deploy_version_bump: {
+                    type: 'string',
+                    enum: ['patch', 'minor', 'major'],
+                    description: 'Version bump for auto-deploy (default: minor)',
+                },
+            },
+            required: ['project_id', 'title', 'start_date', 'end_date'],
+        },
+    },
+    {
+        name: 'update_sprint',
+        description: `Update a sprint's details. Can update title, goal, dates, and deployment settings.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sprint_id: {
+                    type: 'string',
+                    description: 'Sprint UUID',
+                },
+                title: {
+                    type: 'string',
+                    description: 'New sprint title',
+                },
+                goal: {
+                    type: 'string',
+                    description: 'New sprint goal',
+                },
+                start_date: {
+                    type: 'string',
+                    description: 'New start date (YYYY-MM-DD)',
+                },
+                end_date: {
+                    type: 'string',
+                    description: 'New end date (YYYY-MM-DD)',
+                },
+                auto_deploy_on_completion: {
+                    type: 'boolean',
+                    description: 'Auto-deploy setting',
+                },
+                deploy_environment: {
+                    type: 'string',
+                    enum: ['development', 'staging', 'production'],
+                    description: 'Target environment',
+                },
+                deploy_version_bump: {
+                    type: 'string',
+                    enum: ['patch', 'minor', 'major'],
+                    description: 'Version bump type',
+                },
+            },
+            required: ['sprint_id'],
+        },
+    },
+    {
+        name: 'get_sprint',
+        description: `Get a sprint with all its tasks organized by phase (pre/core/post).
+Includes progress percentage, velocity points, and committed points.
+Use summary_only: true to get task counts and next task instead of full task arrays (saves tokens).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sprint_id: {
+                    type: 'string',
+                    description: 'Sprint UUID',
+                },
+                summary_only: {
+                    type: 'boolean',
+                    description: 'Return task counts and next task instead of full task arrays (default: false)',
+                },
+            },
+            required: ['sprint_id'],
+        },
+    },
+    {
+        name: 'get_sprints',
+        description: `List sprints for a project with velocity metrics.
+Returns sprints sorted by sprint_number descending (most recent first).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['planning', 'active', 'in_review', 'retrospective', 'completed', 'cancelled'],
+                    description: 'Filter by sprint status (optional)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max sprints to return (default: 20, max: 100)',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'delete_sprint',
+        description: `Delete a sprint. Tasks are preserved but no longer grouped.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sprint_id: {
+                    type: 'string',
+                    description: 'Sprint UUID',
+                },
+            },
+            required: ['sprint_id'],
+        },
+    },
+    {
+        name: 'start_sprint',
+        description: `Start a sprint. Transitions from 'planning' to 'active' status.
+Locks the committed_points at the current total story points.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sprint_id: {
+                    type: 'string',
+                    description: 'Sprint UUID',
+                },
+            },
+            required: ['sprint_id'],
+        },
+    },
+    {
+        name: 'complete_sprint',
+        description: `Complete a sprint. Handles retrospective phase and auto-deployment if configured.
+Status flow: active → in_review → retrospective → completed`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sprint_id: {
+                    type: 'string',
+                    description: 'Sprint UUID',
+                },
+                retrospective_notes: {
+                    type: 'string',
+                    description: 'Sprint retrospective notes',
+                },
+                skip_retrospective: {
+                    type: 'boolean',
+                    description: 'Skip retrospective phase and go directly to completed (default: false)',
+                },
+            },
+            required: ['sprint_id'],
+        },
+    },
+    {
+        name: 'add_task_to_sprint',
+        description: `Add a task to a sprint with optional story points.
+Tasks can be added during 'planning' status. Story points contribute to committed_points.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sprint_id: {
+                    type: 'string',
+                    description: 'Sprint UUID',
+                },
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID to add',
+                },
+                story_points: {
+                    type: 'number',
+                    description: 'Story point estimate (optional, must be non-negative integer)',
+                },
+                phase: {
+                    type: 'string',
+                    enum: ['pre', 'core', 'post'],
+                    description: 'Task phase (default: core)',
+                },
+            },
+            required: ['sprint_id', 'task_id'],
+        },
+    },
+    {
+        name: 'remove_task_from_sprint',
+        description: `Remove a task from a sprint. Task is preserved but returns to backlog.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sprint_id: {
+                    type: 'string',
+                    description: 'Sprint UUID',
+                },
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID to remove',
+                },
+            },
+            required: ['sprint_id', 'task_id'],
+        },
+    },
+    {
+        name: 'get_sprint_backlog',
+        description: `Get tasks from backlog/pending that can be added to a sprint.
+Returns tasks not already assigned to any body of work or sprint.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                sprint_id: {
+                    type: 'string',
+                    description: 'Sprint UUID to exclude already-added tasks (optional)',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'get_sprint_velocity',
+        description: `Get velocity metrics for completed sprints.
+Returns committed vs completed points and average velocity.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Number of sprints to analyze (default: 10, max: 50)',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    // ============================================================================
+    // Git Issue Tools
+    // ============================================================================
+    {
+        name: 'add_git_issue',
+        description: `Record a git-related issue (merge conflict, push failure, etc.). Auto-created by claim_validation when conflicts detected.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                issue_type: {
+                    type: 'string',
+                    enum: ['merge_conflict', 'push_failed', 'rebase_needed', 'branch_diverged', 'pr_not_mergeable'],
+                    description: 'Type of git issue',
+                },
+                branch: {
+                    type: 'string',
+                    description: 'Branch where the issue occurred',
+                },
+                target_branch: {
+                    type: 'string',
+                    description: 'Target branch for merge/rebase (optional)',
+                },
+                pr_url: {
+                    type: 'string',
+                    description: 'Pull request URL if applicable (optional)',
+                },
+                conflicting_files: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'List of files with conflicts (optional)',
+                },
+                error_message: {
+                    type: 'string',
+                    description: 'Error message from git operation (optional)',
+                },
+                task_id: {
+                    type: 'string',
+                    description: 'Related task UUID (optional)',
+                },
+            },
+            required: ['project_id', 'issue_type', 'branch'],
+        },
+    },
+    {
+        name: 'resolve_git_issue',
+        description: `Mark a git issue as resolved.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                git_issue_id: {
+                    type: 'string',
+                    description: 'Git issue UUID',
+                },
+                resolution_note: {
+                    type: 'string',
+                    description: 'How the issue was resolved (optional)',
+                },
+                auto_resolved: {
+                    type: 'boolean',
+                    description: 'Whether this was auto-resolved (e.g., PR became mergeable)',
+                },
+            },
+            required: ['git_issue_id'],
+        },
+    },
+    {
+        name: 'get_git_issues',
+        description: `Get git issues for a project, optionally filtered by status, type, or branch.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['open', 'resolved'],
+                    description: 'Filter by status (default: open)',
+                },
+                issue_type: {
+                    type: 'string',
+                    enum: ['merge_conflict', 'push_failed', 'rebase_needed', 'branch_diverged', 'pr_not_mergeable'],
+                    description: 'Filter by issue type (optional)',
+                },
+                branch: {
+                    type: 'string',
+                    description: 'Filter by branch (optional)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max issues to return (default: 50)',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'delete_git_issue',
+        description: `Delete a git issue.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                git_issue_id: {
+                    type: 'string',
+                    description: 'Git issue UUID',
+                },
+            },
+            required: ['git_issue_id'],
+        },
+    },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibescope/mcp-server",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "MCP server for Vibescope - AI project tracking tools",
   "type": "module",
   "main": "dist/index.js",

package/src/api-client.ts

@@ -47,7 +47,8 @@ export class VibescopeApiClient {
 				return {
 					ok: false,
 					status: response.status,
-					error: data.error || `HTTP ${response.status}`
+					error: data.error || `HTTP ${response.status}`,
+					data // Include full response data for additional error context
 				};
 			}
 
@@ -306,6 +307,7 @@ export class VibescopeApiClient {
 		estimated_minutes?: number;
 		blocking?: boolean;
 		session_id?: string;
+		task_type?: string;
 	}): Promise<ApiResponse<{
 		success: boolean;
 		task_id: string;
@@ -539,7 +541,11 @@ export class VibescopeApiClient {
 	// ============================================================================
 	// Decision endpoints
 	// ============================================================================
-	async getDecisions(projectId: string): Promise<ApiResponse<{
+	async getDecisions(projectId: string, options?: {
+		limit?: number;
+		offset?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
 		decisions: Array<{
 			id: string;
 			title: string;
@@ -549,7 +555,7 @@ export class VibescopeApiClient {
 			created_at: string;
 		}>;
 	}>> {
-		return this.proxy('get_decisions', { project_id: projectId });
+		return this.proxy('get_decisions', { project_id: projectId, ...options });
 	}
 
 	async logDecision(projectId: string, params: {
@@ -1005,6 +1011,8 @@ export class VibescopeApiClient {
 	async getActivityFeed(projectId: string, params?: {
 		limit?: number;
 		since?: string;
+		types?: string[];
+		created_by?: string;
 	}): Promise<ApiResponse<{
 		activities: Array<{
 			type: string;
@@ -1139,14 +1147,17 @@ export class VibescopeApiClient {
 	// Knowledge base endpoint
 	// ============================================================================
 	async queryKnowledgeBase(projectId: string, params?: {
+		scope?: 'summary' | 'detailed';
 		categories?: string[];
 		limit?: number;
 		search_query?: string;
 	}): Promise<ApiResponse<{
-		findings?: Array<{ id: string; title: string; category: string; severity: string }>;
-		decisions?: Array<{ id: string; title: string; description: string }>;
-		completed_tasks?: Array<{ id: string; title: string; completed_at: string }>;
+		findings?: Array<{ id: string; title: string; category: string; severity: string; description?: string }>;
+		decisions?: Array<{ id: string; title: string; description: string; rationale?: string }>;
+		completed_tasks?: Array<{ id: string; title: string; completed_at: string; summary?: string }>;
 		resolved_blockers?: Array<{ id: string; description: string; resolution_note?: string }>;
+		progress?: Array<{ id: string; summary: string; details?: string }>;
+		qa?: Array<{ id: string; question: string; answer: string }>;
 	}>> {
 		return this.proxy('query_knowledge_base', {
 			project_id: projectId,
@@ -1800,6 +1811,78 @@ export class VibescopeApiClient {
 	}>>> {
 		return this.proxy('get_help_topics', {});
 	}
+
+	// ============================================================================
+	// File Checkout endpoints (multi-agent coordination)
+	// ============================================================================
+	async checkoutFile(projectId: string, filePath: string, reason?: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		checkout_id: string;
+		file_path: string;
+		already_checked_out?: boolean;
+		message: string;
+	}>> {
+		return this.proxy('checkout_file', {
+			project_id: projectId,
+			file_path: filePath,
+			reason
+		}, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async checkinFile(params: {
+		checkout_id?: string;
+		project_id?: string;
+		file_path?: string;
+		summary?: string;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		checkout_id: string;
+		message: string;
+	}>> {
+		return this.proxy('checkin_file', params, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async getFileCheckouts(projectId: string, options?: {
+		status?: string;
+		file_path?: string;
+		limit?: number;
+	}): Promise<ApiResponse<{
+		checkouts: Array<{
+			id: string;
+			file_path: string;
+			status: string;
+			checked_out_at: string;
+			checkout_reason?: string;
+			checked_in_at?: string;
+			checkin_summary?: string;
+			checked_out_by?: string;
+		}>;
+	}>> {
+		return this.proxy('get_file_checkouts', {
+			project_id: projectId,
+			...options
+		});
+	}
+
+	async abandonCheckout(params: {
+		checkout_id?: string;
+		project_id?: string;
+		file_path?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		checkout_id: string;
+		message: string;
+	}>> {
+		return this.proxy('abandon_checkout', params);
+	}
 }
 
 // Singleton instance

package/src/handlers/__test-setup__.ts

@@ -80,6 +80,7 @@ export const mockApiClient = {
 	getFindingsStats: vi.fn(),
 	updateFinding: vi.fn(),
 	deleteFinding: vi.fn(),
+	queryKnowledgeBase: vi.fn(),
 
 	// Requests
 	getPendingRequests: vi.fn(),
@@ -169,6 +170,12 @@ export const mockApiClient = {
 	getHelpTopic: vi.fn(),
 	getHelpTopics: vi.fn(),
 
+	// File Checkouts
+	checkoutFile: vi.fn(),
+	checkinFile: vi.fn(),
+	getFileCheckouts: vi.fn(),
+	abandonCheckout: vi.fn(),
+
 	// Proxy (generic)
 	proxy: vi.fn(),
 };