@vibescope/mcp-server 0.1.0 → 0.2.0

package/src/handlers/validation.test.ts

@@ -494,4 +494,56 @@ describe('validateTask', () => {
 			validateTask({ task_id: VALID_UUID, approved: false }, ctx)
 		).rejects.toThrow('Failed to validate task');
 	});
+
+	describe('PR requirement', () => {
+		it('should return error when PR is required but not present', async () => {
+			mockApiClient.validateTask.mockResolvedValue({
+				ok: false,
+				error: 'pr_required',
+				data: {
+					message: 'This project uses git-flow workflow which requires a Pull Request before validation approval.',
+					workflow: 'git-flow',
+				},
+			});
+			const ctx = createMockContext();
+
+			const result = await validateTask(
+				{ task_id: VALID_UUID, approved: true },
+				ctx
+			);
+
+			expect(result.result).toMatchObject({
+				error: 'pr_required',
+				workflow: 'git-flow',
+				action_required: expect.stringContaining('add_task_reference'),
+			});
+		});
+
+		it('should pass skip_pr_check to API', async () => {
+			mockApiClient.validateTask.mockResolvedValue({
+				ok: true,
+				data: {
+					success: true,
+					validated_task_id: VALID_UUID,
+					self_validated: false,
+				},
+			});
+			const ctx = createMockContext({ sessionId: 'validator-session' });
+
+			await validateTask(
+				{
+					task_id: VALID_UUID,
+					approved: true,
+					skip_pr_check: true,
+				},
+				ctx
+			);
+
+			expect(mockApiClient.validateTask).toHaveBeenCalledWith(
+				VALID_UUID,
+				{ approved: true, skip_pr_check: true },
+				'validator-session'
+			);
+		});
+	});
 });

package/src/handlers/validation.ts

@@ -47,10 +47,11 @@ export const claimValidation: Handler = async (args, ctx) => {
 };
 
 export const validateTask: Handler = async (args, ctx) => {
-	const { task_id, validation_notes, approved } = args as {
+	const { task_id, validation_notes, approved, skip_pr_check } = args as {
 		task_id: string;
 		validation_notes?: string;
 		approved: boolean;
+		skip_pr_check?: boolean;
 	};
 
 	validateRequired(task_id, 'task_id');
@@ -67,9 +68,21 @@ export const validateTask: Handler = async (args, ctx) => {
 	const response = await apiClient.validateTask(task_id, {
 		approved,
 		validation_notes,
+		skip_pr_check,
 	}, currentSessionId || undefined);
 
 	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")',
+				},
+			};
+		}
 		throw new Error(response.error || 'Failed to validate task');
 	}
 

package/src/index.ts

@@ -1052,8 +1052,8 @@ Returns session info, persona, and next task. Use mode:'full' for complete conte
 				},
 				task_type: {
 					type: 'string',
-					enum: ['frontend', 'backend', 'database', 'mcp', 'testing', 'docs', 'infra', 'other'],
-					description: 'Task category for visual grouping (frontend, backend, database, mcp, testing, docs, infra, other)',
+					enum: ['frontend', 'backend', 'database', 'feature', 'bugfix', 'design', 'mcp', 'testing', 'docs', 'infra', 'other'],
+					description: 'Task category (frontend, backend, database, feature, bugfix, design, mcp, testing, docs, infra, other)',
 				},
 			},
 			required: ['project_id', 'title'],
@@ -1101,8 +1101,8 @@ Returns session info, persona, and next task. Use mode:'full' for complete conte
 				},
 				task_type: {
 					type: 'string',
-					enum: ['frontend', 'backend', 'database', 'mcp', 'testing', 'docs', 'infra', 'other'],
-					description: 'Task category (frontend, backend, database, mcp, testing, docs, infra, other)',
+					enum: ['frontend', 'backend', 'database', 'feature', 'bugfix', 'design', 'mcp', 'testing', 'docs', 'infra', 'other'],
+					description: 'Task category (frontend, backend, database, feature, bugfix, design, mcp, testing, docs, infra, other)',
 				},
 			},
 			required: ['task_id'],
@@ -1817,6 +1817,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.',
+				},
 			},
 		},
 	},
@@ -1866,7 +1870,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: {
@@ -1882,6 +1886,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'],
 		},
@@ -2589,7 +2597,8 @@ Bodies of work allow organizing related tasks with optional auto-deployment on c
 	},
 	{
 		name: 'get_body_of_work',
-		description: `Get a body of work with all its tasks organized by phase.`,
+		description: `Get a body of work with all its tasks organized by phase.
+Use summary_only: true to get task counts and next task instead of full task arrays (saves tokens).`,
 		inputSchema: {
 			type: 'object',
 			properties: {
@@ -2597,6 +2606,10 @@ Bodies of work allow organizing related tasks with optional auto-deployment on c
 					type: 'string',
 					description: 'Body of work UUID',
 				},
+				summary_only: {
+					type: 'boolean',
+					description: 'Return task counts and next task instead of full task arrays (default: false)',
+				},
 			},
 			required: ['body_of_work_id'],
 		},
@@ -2872,7 +2885,8 @@ Sprints start in 'planning' status where tasks can be added with story points.`,
 	{
 		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.`,
+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: {
@@ -2880,6 +2894,10 @@ Includes progress percentage, velocity points, and committed points.`,
 					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'],
 		},

package/src/tools.ts

@@ -884,15 +884,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'],
 		},
@@ -1103,6 +1117,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.',
+				},
 			},
 		},
 	},
@@ -1152,7 +1170,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: {
@@ -1168,6 +1186,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'],
 		},
@@ -1351,6 +1373,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/src/knowledge.ts

@@ -1,230 +0,0 @@
-/**
- * Knowledge Base
- *
- * Embedded help topics for on-demand agent guidance.
- */
-
-export const KNOWLEDGE_BASE: Record<string, string> = {
-	getting_started: `# Getting Started
-1. Call start_work_session(git_url) to initialize
-2. Response includes next_task - start working on it immediately
-3. Use update_task to mark in_progress and track progress
-4. Call complete_task when done - it returns your next task
-5. Use get_help(topic) when you need guidance on specific workflows`,
-
-	tasks: `# Task Workflow
-- Mark task in_progress with update_task before starting
-- Update progress_percentage regularly (every 15-20% progress)
-- Include progress_note to auto-log milestones
-- One task at a time - complete current before starting another
-- complete_task returns next_task and context counts (validation, blockers, deployment)
-- Priority: 1=highest, 5=lowest`,
-
-	validation: `# Task Validation
-Completed tasks need validation before PR merge. PRIORITIZE validation over new tasks.
-
-## Validator Workflow
-
-### 1. Claim Task
-claim_validation(task_id) → Returns worktree_setup with existing branch
-
-### 2. Set Up Worktree (EXISTING branch)
-git fetch origin feature/task-branch
-git worktree add ../PROJECT-task-ID feature/task-branch
-cd ../PROJECT-task-ID
-
-### 3. Run Tests Locally
-pnpm install && pnpm test && pnpm build
-
-### 4. Approve or Reject
-
-**APPROVE** → Validator merges PR:
-validate_task(task_id, approved: true, validation_notes: "...")
-# Response includes merge instructions with PR URL
-gh pr merge <NUMBER> --squash
-git worktree remove ../PROJECT-task-ID
-
-**REJECT** → Create fix task:
-validate_task(task_id, approved: false, validation_notes: "Issues...", create_fix_task: true)
-# Creates fix task with SAME branch/PR
-# Fix agent picks up, pushes fixes to same PR
-git worktree remove ../PROJECT-task-ID
-
-## Key Rules
-- Validators check out EXISTING branches
-- On approval: validator merges immediately
-- On rejection: use create_fix_task: true
-- Always clean up worktree after validation`,
-
-	deployment: `# Deployment Workflow
-1. Ensure all completed tasks are validated first
-2. request_deployment(project_id, environment: "production")
-3. claim_deployment_validation(project_id) - claim for validation
-4. Run: pnpm build && pnpm test
-5. report_validation(project_id, build_passed: true, tests_passed: true)
-6. start_deployment(project_id) - returns project's deployment_instructions
-7. Follow the instructions (e.g., push to main, run deploy command)
-8. complete_deployment(project_id, success: true, summary: "...")`,
-
-	git: `# Git Workflow
-
-Call get_git_workflow(project_id) for project-specific config.
-
-## Workflow Types
-- **none**: No branching strategy
-- **trunk-based**: Commit directly to main, small frequent commits
-- **github-flow**: Feature branches, merge via PR after validation
-- **git-flow**: develop/release/feature branches
-
-## Lifecycle Integration
-
-### 1. Starting a Task
-When you call update_task(status: "in_progress"), the response includes:
-- **branch_name**: Suggested branch (e.g., feature/a1b2c3d4-task-title)
-- **base_branch**: Branch to branch from
-- **steps**: Git commands to create the branch
-- **reminder**: Call to update task with git_branch
-
-### 2. Completing a Task
-When you call complete_task, the response includes:
-- **steps**: Push commands
-- **pr_suggestion**: { title, body_template } - ready-to-use PR content
-- **next_step**: Reminder that merge happens AFTER validation
-
-Add the PR link via add_task_reference(task_id, url, label: "Pull Request").
-
-### 3. Validation Approved
-When validate_task(approved: true) is called, the response includes:
-- **target_branch**: Where to merge
-- **feature_branch**: Branch being merged
-- **steps**: Merge options (UI or command line)
-- **cleanup**: Branch deletion commands
-- **note**: Confirmation it's safe to merge
-
-## Multi-Agent Worktrees (CRITICAL)
-
-When multiple agents share a repository, you MUST use git worktrees to prevent conflicts.
-
-### Why Worktrees?
-- Branch switching in shared repos causes file conflicts between agents
-- Uncommitted changes from one agent block another's work
-- Worktrees provide isolated working directories with shared .git
-
-### Setup (Once Per Task)
-\`\`\`bash
-# From main repo, create worktree for your task
-git worktree add ../worktree-<task-short-id> -b feature/<task-id>-<title>
-
-# Work in the worktree directory
-cd ../worktree-<task-short-id>
-\`\`\`
-
-### Cleanup (After Task Merged)
-\`\`\`bash
-# Remove worktree after PR merged
-git worktree remove ../worktree-<task-short-id>
-git branch -d feature/<task-id>-<title>
-\`\`\`
-
-### Worktree Rules
-- ALWAYS create a worktree before starting work on a task
-- Each agent works in their own worktree directory
-- Never switch branches in the main repo when other agents are active
-- Commit and push frequently to avoid losing work
-
-## Handling Merge Conflicts
-
-When claim_validation detects conflicts (via GitHub API):
-1. Response includes merge_conflict with rebase_instructions
-2. Checkout the feature branch locally
-3. Rebase onto target branch: \`git rebase origin/<target>\`
-4. Resolve conflicts, then: \`git add . && git rebase --continue\`
-5. Force push: \`git push origin <branch> --force-with-lease\`
-6. Re-claim validation to verify PR is now mergeable
-
-## Key Rules
-- Create worktree + branch when starting task (multi-agent environments)
-- Push and create PR when completing task
-- Wait for validation before merging
-- Resolve merge conflicts via rebase before approval
-- Clean up worktree and branch after successful merge`,
-
-	blockers: `# Working with Blockers
-When stuck and need human input:
-1. add_blocker(project_id, description: "What's blocking")
-2. Ask your question to the user
-3. resolve_blocker(blocker_id, resolution_note: "How resolved")
-Only use for genuine blockers requiring decisions - not routine questions.`,
-
-	milestones: `# Task Milestones
-For complex tasks, break into milestones:
-1. add_milestone(task_id, title: "Design schema")
-2. add_milestone(task_id, title: "Implement API")
-3. Update with complete_milestone(milestone_id) as you go
-Dashboard shows progress bar with completed/total.`,
-
-	fallback: `# Fallback Activities
-When no tasks available, get_next_task suggests activities:
-- feature_ideation, code_review, performance_audit
-- security_review, test_coverage, documentation_review
-1. start_fallback_activity(project_id, activity: "code_review")
-2. Do the work, use add_finding for issues, add_idea for improvements
-3. stop_fallback_activity(project_id, summary: "...")`,
-
-	session: `# Session Management
-- start_work_session initializes and returns next_task (lite mode default)
-- Use mode:'full' for complete context when needed
-- heartbeat every 30-60 seconds maintains active status
-- end_work_session releases claimed tasks and returns summary
-- NEVER STOP: After completing a task, immediately start the next one
-- When context grows large: /clear then start_work_session to continue fresh
-- Your progress is saved to the dashboard - nothing is lost on /clear`,
-
-	tokens: `# Token Efficiency
-Be mindful of token costs - every tool call has a cost.
-- Use mode:'lite' (default) - saves ~85% vs full mode
-- Call get_token_usage() to check consumption
-- /compact when context grows large
-- Batch related updates when possible
-- Trust lite mode; only use full mode for initial exploration`,
-
-	sprints: `# Sprints
-Sprints are time-bounded bodies of work with velocity tracking.
-
-## Lifecycle
-1. **planning**: Create sprint, add tasks with story points
-2. **active**: Sprint in progress, working on tasks
-3. **in_review**: Sprint ended, reviewing completion
-4. **retrospective**: Post-sprint reflection
-5. **completed**: Final state, velocity recorded
-
-## Workflow
-1. create_sprint(project_id, title, start_date, end_date, goal)
-2. get_sprint_backlog(project_id) - view available tasks
-3. add_task_to_sprint(sprint_id, task_id, story_points) - add tasks
-4. start_sprint(sprint_id) - locks committed_points
-5. Work on tasks normally (they're assigned to the sprint)
-6. complete_sprint(sprint_id) - calculates final velocity
-
-## Velocity Tracking
-- committed_points: Total story points at sprint start
-- velocity_points: Story points completed by sprint end
-- get_sprint_velocity(project_id) - shows history and average velocity
-
-## Auto-Deployment
-Set auto_deploy_on_completion: true when creating sprint.
-Triggers deployment when sprint completes.`,
-
-	topics: `# Available Help Topics
-- getting_started: Basic workflow overview
-- tasks: Working on tasks, progress tracking
-- validation: Cross-agent task validation
-- deployment: Deployment coordination
-- git: Git workflow configuration
-- blockers: Handling blockers
-- milestones: Breaking down complex tasks
-- fallback: Background activities when idle
-- session: Session management
-- tokens: Token efficiency tips
-- sprints: Time-bounded task groupings with velocity tracking`,
-};