@vibescope/mcp-server 0.1.0 → 0.2.0

package/dist/tools.js

@@ -881,15 +881,29 @@ Returns session info, persona, role, and next task. Use mode:'full' for complete
     },
     {
         name: 'get_findings',
-        description: `Get findings for a project, optionally filtered by category, severity, or status.`,
+        description: `Get findings for a project, optionally filtered by category, severity, or status. Use summary_only=true to reduce token usage by returning only essential fields (id, title, category, severity, status). For just counts, use get_findings_stats instead.`,
         inputSchema: {
             type: 'object',
             properties: {
                 project_id: { type: 'string', description: 'Project UUID' },
                 category: { type: 'string', enum: ['performance', 'security', 'code_quality', 'accessibility', 'documentation', 'architecture', 'testing', 'other'], description: 'Filter by category (optional)' },
                 severity: { type: 'string', enum: ['info', 'low', 'medium', 'high', 'critical'], description: 'Filter by severity (optional)' },
-                status: { type: 'string', enum: ['open', 'addressed', 'dismissed', 'wontfix'], description: 'Filter by status (default: all)' },
-                limit: { type: 'number', description: 'Max number of findings to return (default 50)' },
+                status: { type: 'string', enum: ['open', 'addressed', 'dismissed', 'wontfix'], description: 'Filter by status (default: open)' },
+                limit: { type: 'number', description: 'Max number of findings to return (default 50, max 200)' },
+                offset: { type: 'number', description: 'Number of findings to skip for pagination (default 0)' },
+                search_query: { type: 'string', description: 'Search findings by title' },
+                summary_only: { type: 'boolean', description: 'When true, returns only id, title, category, severity, status (reduces tokens by ~80%). Default: false' },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'get_findings_stats',
+        description: `Get aggregate statistics about findings for a project. Returns total count and breakdowns by status, severity, and category. Much more token-efficient than get_findings when you just need to understand the overall state.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'string', description: 'Project UUID' },
             },
             required: ['project_id'],
         },
@@ -1100,6 +1114,10 @@ Returns subtasks with aggregate completion stats.`,
                     type: 'string',
                     description: 'Session ID from start_work_session (optional, uses current session if not provided)',
                 },
+                current_worktree_path: {
+                    type: ['string', 'null'],
+                    description: 'Report your current git worktree path (e.g., "../project-task-abc123"). Set to null to clear.',
+                },
             },
         },
     },
@@ -1149,7 +1167,7 @@ Returns subtasks with aggregate completion stats.`,
     },
     {
         name: 'validate_task',
-        description: 'Validate a completed task. Include test results in validation_notes.',
+        description: 'Validate a completed task. Include test results in validation_notes. For github-flow/git-flow projects, a PR must exist before approval (add via add_task_reference).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -1165,6 +1183,10 @@ Returns subtasks with aggregate completion stats.`,
                     type: 'boolean',
                     description: 'Whether the task passes validation (true = approved, false = needs more work)',
                 },
+                skip_pr_check: {
+                    type: 'boolean',
+                    description: 'Skip PR existence check (use only for tasks that legitimately do not need a PR)',
+                },
             },
             required: ['task_id', 'approved'],
         },
@@ -1348,6 +1370,10 @@ Returns subtasks with aggregate completion stats.`,
                     type: 'boolean',
                     description: 'When true, converted task blocks all other work until complete',
                 },
+                recurring: {
+                    type: 'boolean',
+                    description: 'When true, requirement resets to pending when a new deployment is requested',
+                },
             },
             required: ['project_id', 'type', 'title'],
         },

package/package.json

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

package/src/api-client.ts

@@ -137,13 +137,16 @@ export class VibescopeApiClient {
 		return this.request('POST', '/api/mcp/sessions/start', params);
 	}
 
-	async heartbeat(sessionId: string): Promise<ApiResponse<{
+	async heartbeat(sessionId: string, options?: {
+		current_worktree_path?: string | null;
+	}): Promise<ApiResponse<{
 		success: boolean;
 		session_id: string;
 		timestamp: string;
 	}>> {
 		return this.request('POST', '/api/mcp/sessions/heartbeat', {
-			session_id: sessionId
+			session_id: sessionId,
+			...options
 		});
 	}
 
@@ -381,6 +384,20 @@ export class VibescopeApiClient {
 	}): Promise<ApiResponse<{
 		success: boolean;
 		task_id: string;
+		git_workflow?: {
+			workflow: string;
+			base_branch: string;
+			suggested_branch: string;
+			worktree_required: boolean;
+		};
+		worktree_setup?: {
+			message: string;
+			commands: string[];
+			worktree_path: string;
+			branch_name: string;
+			cleanup_command: string;
+		};
+		next_step?: string;
 	}>> {
 		return this.request('PATCH', `/api/mcp/tasks/${taskId}`, updates);
 	}
@@ -405,6 +422,7 @@ export class VibescopeApiClient {
 			deployment?: string;
 		};
 		next_action: string;
+		warnings?: string[];
 	}>> {
 		return this.request('POST', `/api/mcp/tasks/${taskId}/complete`, params);
 	}
@@ -642,6 +660,9 @@ export class VibescopeApiClient {
 		severity?: string;
 		status?: string;
 		limit?: number;
+		offset?: number;
+		search_query?: string;
+		summary_only?: boolean;
 	}): Promise<ApiResponse<{
 		findings: Array<{
 			id: string;
@@ -655,6 +676,8 @@ export class VibescopeApiClient {
 			resolution_note?: string;
 			created_at: string;
 		}>;
+		total_count?: number;
+		has_more?: boolean;
 	}>> {
 		return this.proxy('get_findings', {
 			project_id: projectId,
@@ -662,6 +685,17 @@ export class VibescopeApiClient {
 		});
 	}
 
+	async getFindingsStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+		by_status: Record<string, number>;
+		by_severity: Record<string, number>;
+		by_category: Record<string, number>;
+	}>> {
+		return this.proxy('get_findings_stats', {
+			project_id: projectId
+		});
+	}
+
 	async addFinding(projectId: string, params: {
 		title: string;
 		description?: string;
@@ -839,11 +873,13 @@ export class VibescopeApiClient {
 	async validateTask(taskId: string, params: {
 		approved: boolean;
 		validation_notes?: string;
+		skip_pr_check?: boolean;
 	}, sessionId?: string): Promise<ApiResponse<{
 		success: boolean;
 		approved: boolean;
 		task_id: string;
 		message?: string;
+		workflow?: string;
 	}>> {
 		return this.proxy('validate_task', {
 			task_id: taskId,
@@ -858,6 +894,21 @@ export class VibescopeApiClient {
 		success: boolean;
 		activity: string;
 		message: string;
+		git_workflow?: {
+			workflow: string;
+			base_branch: string;
+			worktree_recommended: boolean;
+			note: string;
+		};
+		worktree_setup?: {
+			message: string;
+			commands: string[];
+			worktree_path: string;
+			branch_name: string;
+			cleanup_command: string;
+			report_worktree: string;
+		};
+		next_step?: string;
 	}>> {
 		return this.proxy('start_fallback_activity', {
 			project_id: projectId,
@@ -1591,6 +1642,7 @@ export class VibescopeApiClient {
 		file_path?: string;
 		stage?: string;
 		blocking?: boolean;
+		recurring?: boolean;
 	}): Promise<ApiResponse<{
 		success: boolean;
 		requirement_id: string;
@@ -1730,6 +1782,24 @@ export class VibescopeApiClient {
 			readme_content: readmeContent
 		});
 	}
+
+	// ============================================================================
+	// Help Topics (database-backed)
+	// ============================================================================
+	async getHelpTopic(slug: string): Promise<ApiResponse<{
+		slug: string;
+		title: string;
+		content: string;
+	} | null>> {
+		return this.proxy('get_help_topic', { slug });
+	}
+
+	async getHelpTopics(): Promise<ApiResponse<Array<{
+		slug: string;
+		title: string;
+	}>>> {
+		return this.proxy('get_help_topics', {});
+	}
 }
 
 // Singleton instance

package/src/handlers/__test-setup__.ts

@@ -77,6 +77,7 @@ export const mockApiClient = {
 	// Findings
 	addFinding: vi.fn(),
 	getFindings: vi.fn(),
+	getFindingsStats: vi.fn(),
 	updateFinding: vi.fn(),
 	deleteFinding: vi.fn(),
 
@@ -164,6 +165,10 @@ export const mockApiClient = {
 	claimValidation: vi.fn(),
 	validateTask: vi.fn(),
 
+	// Help Topics
+	getHelpTopic: vi.fn(),
+	getHelpTopics: vi.fn(),
+
 	// Proxy (generic)
 	proxy: vi.fn(),
 };

package/src/handlers/bodies-of-work.ts

@@ -134,24 +134,40 @@ export const updateBodyOfWork: Handler = async (args, ctx) => {
 };
 
 export const getBodyOfWork: Handler = async (args, ctx) => {
-	const { body_of_work_id } = args as { body_of_work_id: string };
+	const { body_of_work_id, summary_only = false } = args as { body_of_work_id: string; summary_only?: boolean };
 
 	validateRequired(body_of_work_id, 'body_of_work_id');
 	validateUUID(body_of_work_id, 'body_of_work_id');
 
 	const apiClient = getApiClient();
 
+	// Response type varies based on summary_only
 	const response = await apiClient.proxy<{
-		id: string;
-		title: string;
-		description?: string;
-		status: string;
-		progress_percentage: number;
-		pre_tasks: unknown[];
-		core_tasks: unknown[];
-		post_tasks: unknown[];
-		total_tasks: number;
-	}>('get_body_of_work', { body_of_work_id });
+		body_of_work: {
+			id: string;
+			title: string;
+			description?: string;
+			status: string;
+			progress_percentage: number;
+		};
+		// Full response includes tasks grouped by phase
+		tasks?: {
+			pre: unknown[];
+			core: unknown[];
+			post: unknown[];
+		};
+		// Summary response includes counts and next task
+		task_counts?: {
+			pre: { total: number; completed: number };
+			core: { total: number; completed: number };
+			post: { total: number; completed: number };
+			total: number;
+			completed: number;
+			in_progress: number;
+		};
+		current_task?: { id: string; title: string } | null;
+		next_task?: { id: string; title: string; priority: number } | null;
+	}>('get_body_of_work', { body_of_work_id, summary_only });
 
 	if (!response.ok) {
 		throw new Error(`Failed to get body of work: ${response.error}`);

package/src/handlers/deployment.ts

@@ -198,7 +198,7 @@ export const cancelDeployment: Handler = async (args, ctx) => {
 };
 
 export const addDeploymentRequirement: Handler = async (args, ctx) => {
-	const { project_id, type, title, description, file_path, stage = 'preparation', blocking = false } = args as {
+	const { project_id, type, title, description, file_path, stage = 'preparation', blocking = false, recurring = false } = args as {
 		project_id: string;
 		type: string;
 		title: string;
@@ -206,6 +206,7 @@ export const addDeploymentRequirement: Handler = async (args, ctx) => {
 		file_path?: string;
 		stage?: string;
 		blocking?: boolean;
+		recurring?: boolean;
 	};
 
 	validateRequired(project_id, 'project_id');
@@ -230,7 +231,8 @@ export const addDeploymentRequirement: Handler = async (args, ctx) => {
 		description,
 		file_path,
 		stage: stage as 'preparation' | 'deployment' | 'verification',
-		blocking
+		blocking,
+		recurring
 	});
 
 	if (!response.ok) {