@vibescope/mcp-server 0.0.1 → 0.2.0

package/dist/knowledge.js

@@ -18,12 +18,40 @@ export const KNOWLEDGE_BASE = {
 - complete_task returns next_task and context counts (validation, blockers, deployment)
 - Priority: 1=highest, 5=lowest`,
     validation: `# Task Validation
-Completed tasks need validation before deployment. PRIORITIZE validation over new tasks.
-1. Check: get_tasks_awaiting_validation(project_id)
-2. Claim: claim_validation(task_id) - marks "being reviewed" on dashboard
-3. Review code changes and run tests
-4. Complete: validate_task(task_id, approved: true/false, validation_notes: "...")
-Self-validation allowed when single-agent or to unblock deployment.`,
+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")
@@ -68,11 +96,53 @@ When validate_task(approved: true) is called, the response includes:
 - **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 branch when starting task (github-flow/git-flow)
+- Create worktree + branch when starting task (multi-agent environments)
 - Push and create PR when completing task
 - Wait for validation before merging
-- Clean up branch after successful merge`,
+- 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")
@@ -107,6 +177,32 @@ Be mindful of token costs - every tool call has a cost.
 - /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
@@ -117,5 +213,6 @@ Be mindful of token costs - every tool call has a cost.
 - milestones: Breaking down complex tasks
 - fallback: Background activities when idle
 - session: Session management
-- tokens: Token efficiency tips`,
+- tokens: Token efficiency tips
+- sprints: Time-bounded task groupings with velocity tracking`,
 };

package/dist/tools.js

@@ -417,6 +417,10 @@ Returns session info, persona, role, and next task. Use mode:'full' for complete
                     type: 'boolean',
                     description: 'Include subtasks in results (default false). Use get_subtasks for subtasks of a specific task.',
                 },
+                include_metadata: {
+                    type: 'boolean',
+                    description: 'When true, returns all task fields (description, progress, timestamps, etc.). When false (default), returns only id/title/priority/status to save tokens.',
+                },
             },
             required: ['project_id'],
         },
@@ -877,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'],
         },
@@ -1096,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.',
+                },
             },
         },
     },
@@ -1145,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: {
@@ -1161,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'],
         },
@@ -1344,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/dist/validators.d.ts

@@ -33,3 +33,24 @@ export declare function validatePriority(priority: number | undefined): void;
 export declare function validateProgressPercentage(percentage: number | undefined): void;
 export declare function validateEstimatedMinutes(minutes: number | undefined): void;
 export declare function validateEnvironment(environment: string | undefined): void;
+export declare function validateEnum<T extends readonly string[]>(value: string | undefined, validValues: T, fieldName: string): void;
+export type FieldType = 'string' | 'number' | 'boolean' | 'array' | 'object';
+export interface FieldSchema {
+    type: FieldType;
+    required?: boolean;
+    validate?: (value: unknown, fieldName: string) => void;
+    default?: unknown;
+}
+export type ArgSchema = Record<string, FieldSchema>;
+export type InferArgs<T extends ArgSchema> = {
+    [K in keyof T]: T[K]['required'] extends true ? T[K]['type'] extends 'string' ? string : T[K]['type'] extends 'number' ? number : T[K]['type'] extends 'boolean' ? boolean : T[K]['type'] extends 'array' ? unknown[] : T[K]['type'] extends 'object' ? Record<string, unknown> : unknown : T[K]['type'] extends 'string' ? string | undefined : T[K]['type'] extends 'number' ? number | undefined : T[K]['type'] extends 'boolean' ? boolean | undefined : T[K]['type'] extends 'array' ? unknown[] | undefined : T[K]['type'] extends 'object' ? Record<string, unknown> | undefined : unknown | undefined;
+};
+export declare function parseArgs<T extends ArgSchema>(args: Record<string, unknown>, schema: T): InferArgs<T>;
+export declare function uuidValidator(value: unknown, fieldName: string): void;
+export declare function taskStatusValidator(value: unknown, _fieldName: string): void;
+export declare function projectStatusValidator(value: unknown, _fieldName: string): void;
+export declare function priorityValidator(value: unknown, _fieldName: string): void;
+export declare function progressValidator(value: unknown, _fieldName: string): void;
+export declare function minutesValidator(value: unknown, _fieldName: string): void;
+export declare function environmentValidator(value: unknown, _fieldName: string): void;
+export declare function createEnumValidator<T extends readonly string[]>(validValues: T): (value: unknown, fieldName: string) => void;

package/dist/validators.js

@@ -109,3 +109,94 @@ export function validateEnvironment(environment) {
         });
     }
 }
+export function validateEnum(value, validValues, fieldName) {
+    if (!value)
+        return;
+    if (!validValues.includes(value)) {
+        throw new ValidationError(`Invalid ${fieldName}: "${value}"`, {
+            field: fieldName,
+            validValues: validValues,
+            hint: `${fieldName} must be one of: ${validValues.join(', ')}`,
+        });
+    }
+}
+function checkType(value, type) {
+    if (value === undefined || value === null)
+        return true;
+    switch (type) {
+        case 'string': return typeof value === 'string';
+        case 'number': return typeof value === 'number';
+        case 'boolean': return typeof value === 'boolean';
+        case 'array': return Array.isArray(value);
+        case 'object': return typeof value === 'object' && value !== null && !Array.isArray(value);
+        default: return true;
+    }
+}
+export function parseArgs(args, schema) {
+    const result = {};
+    for (const [fieldName, fieldSchema] of Object.entries(schema)) {
+        let value = args[fieldName];
+        if (value === undefined && fieldSchema.default !== undefined) {
+            value = fieldSchema.default;
+        }
+        if (fieldSchema.required && (value === undefined || value === null || value === '')) {
+            throw new ValidationError(`Missing required field: ${fieldName}`, {
+                field: fieldName,
+                hint: `Please provide a value for "${fieldName}"`,
+            });
+        }
+        if (value !== undefined && value !== null && !checkType(value, fieldSchema.type)) {
+            throw new ValidationError(`Invalid type for ${fieldName}: expected ${fieldSchema.type}, got ${typeof value}`, {
+                field: fieldName,
+                hint: `The "${fieldName}" field must be a ${fieldSchema.type}`,
+            });
+        }
+        if (fieldSchema.validate && value !== undefined && value !== null) {
+            fieldSchema.validate(value, fieldName);
+        }
+        result[fieldName] = value;
+    }
+    return result;
+}
+export function uuidValidator(value, fieldName) {
+    if (typeof value !== 'string')
+        return;
+    validateUUID(value, fieldName);
+}
+export function taskStatusValidator(value, _fieldName) {
+    if (typeof value !== 'string')
+        return;
+    validateTaskStatus(value);
+}
+export function projectStatusValidator(value, _fieldName) {
+    if (typeof value !== 'string')
+        return;
+    validateProjectStatus(value);
+}
+export function priorityValidator(value, _fieldName) {
+    if (typeof value !== 'number')
+        return;
+    validatePriority(value);
+}
+export function progressValidator(value, _fieldName) {
+    if (typeof value !== 'number')
+        return;
+    validateProgressPercentage(value);
+}
+export function minutesValidator(value, _fieldName) {
+    if (typeof value !== 'number')
+        return;
+    validateEstimatedMinutes(value);
+}
+export function environmentValidator(value, _fieldName) {
+    if (typeof value !== 'string')
+        return;
+    validateEnvironment(value);
+}
+export function createEnumValidator(validValues) {
+    return (value, fieldName) => {
+        if (typeof value !== 'string')
+            return;
+        validateEnum(value, validValues, fieldName);
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibescope/mcp-server",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "MCP server for Vibescope - AI project tracking tools",
   "type": "module",
   "main": "dist/index.js",
@@ -38,7 +38,6 @@
     "vitest": "^4.0.17"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.2",
-    "@supabase/supabase-js": "^2.90.1"
+    "@modelcontextprotocol/sdk": "^1.25.2"
   }
 }