@vibescope/mcp-server 0.3.0 → 0.3.3

package/dist/tools/tasks.js

@@ -0,0 +1,539 @@
+/**
+ * Task Tool Definitions
+ *
+ * Tools for task CRUD and management:
+ * - get_task
+ * - search_tasks
+ * - get_tasks_by_priority
+ * - get_recent_tasks
+ * - get_task_stats
+ * - get_next_task
+ * - add_task
+ * - update_task
+ * - complete_task
+ * - delete_task
+ * - cancel_task
+ * - release_task
+ * - add_task_reference
+ * - remove_task_reference
+ * - batch_update_tasks
+ * - batch_complete_tasks
+ * - add_subtask
+ * - get_subtasks
+ * - get_stale_worktrees
+ * - clear_worktree_path
+ */
+export const taskTools = [
+    {
+        name: 'get_task',
+        description: `Get a single task by ID with optional subtasks and milestones.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID',
+                },
+                include_subtasks: {
+                    type: 'boolean',
+                    description: 'Include subtasks array (default: false)',
+                },
+                include_milestones: {
+                    type: 'boolean',
+                    description: 'Include milestones array (default: false)',
+                },
+            },
+            required: ['task_id'],
+        },
+    },
+    {
+        name: 'search_tasks',
+        description: `Search tasks by text query. Supports pagination with offset. Use for finding specific tasks by title or description.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Search query (min 2 chars). Searches title and description.',
+                },
+                status: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'] },
+                    description: 'Filter by status (optional, array)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results per page (1-20, default: 10)',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Number of results to skip for pagination (default: 0)',
+                },
+            },
+            required: ['project_id', 'query'],
+        },
+    },
+    {
+        name: 'get_tasks_by_priority',
+        description: `Get tasks filtered by priority. Supports pagination with offset. Use for finding high-priority or low-priority tasks.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                priority: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 5,
+                    description: 'Exact priority to match (1=highest, 5=lowest)',
+                },
+                priority_max: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 5,
+                    description: 'Max priority (for range, e.g., priority=1, priority_max=2 gets P1 and P2)',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'],
+                    description: 'Filter by status (default: pending)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results per page (1-20, default: 10)',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Number of results to skip for pagination (default: 0)',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'get_recent_tasks',
+        description: `Get tasks ordered by creation date. Supports pagination with offset. Use to find oldest pending tasks or newest additions.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                order: {
+                    type: 'string',
+                    enum: ['newest', 'oldest'],
+                    description: 'Sort order (default: newest)',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'],
+                    description: 'Filter by status (optional)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results per page (1-20, default: 10)',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Number of results to skip for pagination (default: 0)',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'get_task_stats',
+        description: `Get aggregate task statistics for a project. Returns counts by status and priority, no task data. Most token-efficient way to understand project state.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'get_next_task',
+        description: `Get highest priority pending task. Start it IMMEDIATELY by calling update_task(task_id, status: "in_progress").
+
+Do NOT ask the user for permission. Follow the directive in the response.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'add_task',
+        description: `Add a new task. Priority 1=highest, 5=lowest. Include estimated_minutes. Use blocking=true for deployment finalization tasks that must complete before other work.
+
+WHEN TO USE: If the user gives you work directly (e.g., "implement feature X", "fix this bug") that isn't already tracked as a task in Vibescope, you MUST create a task first using this tool. This ensures:
+- The work is visible on the dashboard
+- Progress can be tracked
+- Other agents won't duplicate the work
+- The human can see what you're working on`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                title: {
+                    type: 'string',
+                    description: 'Task title',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Detailed description',
+                },
+                priority: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 5,
+                    description: 'Priority 1-5 (1 = highest)',
+                },
+                estimated_minutes: {
+                    type: 'number',
+                    minimum: 1,
+                    description: 'Estimated time to complete in minutes',
+                },
+                blocking: {
+                    type: 'boolean',
+                    description: 'When true, this task blocks all other work until complete (used for deployment finalization)',
+                },
+                model_capability: {
+                    type: 'string',
+                    enum: ['haiku', 'sonnet', 'opus'],
+                    description: 'Recommended model capability: haiku (simple tasks), sonnet (standard), opus (complex reasoning)',
+                },
+            },
+            required: ['project_id', 'title'],
+        },
+    },
+    {
+        name: 'update_task',
+        description: `Update task status, progress, or details. Include progress_note with progress_percentage.
+
+CRITICAL - WORKTREE REQUIRED: For projects using github-flow or git-flow, you MUST use a git worktree to isolate your work. This prevents conflicts with other agents working on the same repository.
+
+When setting status to "in_progress":
+1. Create worktree FIRST: git worktree add ../PROJECT-PERSONA-task-desc -b feature/TASKID-description BASE_BRANCH
+2. cd into the worktree directory
+3. THEN call update_task with git_branch AND worktree_path
+
+Example: update_task(task_id, status: "in_progress", git_branch: "feature/abc123-add-login", worktree_path: "../MyProject-Edge-add-login")
+
+For projects without git branching (trunk-based or none), use skip_worktree_requirement: true.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID',
+                },
+                title: { type: 'string', description: 'New task title' },
+                description: { type: 'string', description: 'New task description' },
+                priority: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 5,
+                    description: 'Task priority (1=highest, 5=lowest)',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'],
+                    description: 'Task status',
+                },
+                progress_percentage: {
+                    type: 'number',
+                    minimum: 0,
+                    maximum: 100,
+                    description: '0-100 completion percentage',
+                },
+                progress_note: {
+                    type: 'string',
+                    description: 'Brief note (auto-logged)',
+                },
+                estimated_minutes: {
+                    type: 'number',
+                    minimum: 1,
+                    description: 'Revised time estimate',
+                },
+                git_branch: {
+                    type: 'string',
+                    description: 'Git branch associated with this task. REQUIRED when status is "in_progress" (unless skip_worktree_requirement is true)',
+                },
+                worktree_path: {
+                    type: 'string',
+                    description: 'Git worktree path for this task (e.g., "../project-task-abc123"). Store this for cleanup tracking across sessions.',
+                },
+                worktree_hostname: {
+                    type: 'string',
+                    description: 'Machine hostname where worktree was created (os.hostname()). Required with worktree_path to enable machine-aware cleanup.',
+                },
+                model_capability: {
+                    type: 'string',
+                    enum: ['haiku', 'sonnet', 'opus'],
+                    description: 'Recommended model capability: haiku (simple tasks), sonnet (standard), opus (complex reasoning)',
+                },
+                skip_worktree_requirement: {
+                    type: 'boolean',
+                    description: 'Skip git_branch requirement for projects without branching workflows (trunk-based or none). Default: false',
+                },
+            },
+            required: ['task_id'],
+        },
+    },
+    {
+        name: 'complete_task',
+        description: `Mark task done. Returns next_task which you MUST start immediately without asking the user.
+
+CRITICAL: Before calling complete_task on branching workflows (github-flow, git-flow):
+1. Create your PR targeting the correct branch (develop for git-flow, main for github-flow)
+2. Call add_task_reference(task_id, pr_url) to link the PR to your task
+3. THEN call complete_task - validators CANNOT approve tasks without a PR reference
+
+CRITICAL: After calling this tool, you must:
+1. If next_task is returned → Start it immediately by calling update_task(task_id, status: "in_progress")
+2. If no next_task → Call get_next_task() or start a fallback_activity
+3. NEVER ask the user "What should I do next?" or "Should I continue?"
+
+The auto_continue: true flag in the response means you are expected to continue working autonomously.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID',
+                },
+                summary: {
+                    type: 'string',
+                    description: 'Brief summary of what was done. This is stored on the task as completion_summary and displayed when reviewing completed tasks.',
+                },
+            },
+            required: ['task_id'],
+        },
+    },
+    {
+        name: 'delete_task',
+        description: `Delete a task.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID',
+                },
+            },
+            required: ['task_id'],
+        },
+    },
+    {
+        name: 'cancel_task',
+        description: `Cancel a task with an optional reason. Use this when a task should be marked as cancelled rather than deleted (e.g., PR was closed, work was superseded). The task remains visible with a cancelled status for historical tracking.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID',
+                },
+                cancelled_reason: {
+                    type: 'string',
+                    description: 'Reason for cancellation',
+                    enum: ['pr_closed', 'superseded', 'user_cancelled', 'validation_failed', 'obsolete', 'blocked'],
+                },
+                cancellation_note: {
+                    type: 'string',
+                    description: 'Optional note explaining the cancellation (logged to progress)',
+                },
+            },
+            required: ['task_id'],
+        },
+    },
+    {
+        name: 'release_task',
+        description: `Release a claimed task back to pending status. Use when you need to give up a task you've started but cannot complete (e.g., context limits reached, conflicts with other work, user requested different approach). The task becomes available for other agents to claim.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID',
+                },
+                reason: {
+                    type: 'string',
+                    description: 'Optional reason for releasing the task (logged to progress)',
+                },
+            },
+            required: ['task_id'],
+        },
+    },
+    {
+        name: 'add_task_reference',
+        description: 'Add a reference URL to a task (docs, PRs, issues).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID',
+                },
+                url: {
+                    type: 'string',
+                    description: 'URL to add as reference',
+                },
+                label: {
+                    type: 'string',
+                    description: 'Optional label/title for the reference',
+                },
+            },
+            required: ['task_id', 'url'],
+        },
+    },
+    {
+        name: 'remove_task_reference',
+        description: `Remove a reference link from a task by URL.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID',
+                },
+                url: {
+                    type: 'string',
+                    description: 'URL of the reference to remove',
+                },
+            },
+            required: ['task_id', 'url'],
+        },
+    },
+    {
+        name: 'batch_update_tasks',
+        description: 'Update multiple tasks at once. Include progress_note with progress_percentage.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                updates: {
+                    type: 'array',
+                    description: 'Array of task updates to apply',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            task_id: { type: 'string', description: 'Task UUID' },
+                            status: { type: 'string', enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'] },
+                            progress_percentage: { type: 'number', minimum: 0, maximum: 100 },
+                            progress_note: { type: 'string', description: 'Brief note about what was achieved' },
+                            priority: { type: 'number', minimum: 1, maximum: 5 },
+                        },
+                        required: ['task_id'],
+                    },
+                },
+            },
+            required: ['updates'],
+        },
+    },
+    {
+        name: 'batch_complete_tasks',
+        description: `Mark multiple tasks as completed at once.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                completions: {
+                    type: 'array',
+                    description: 'Array of task completions',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            task_id: { type: 'string', description: 'Task UUID' },
+                            summary: { type: 'string', description: 'Optional completion summary' },
+                        },
+                        required: ['task_id'],
+                    },
+                },
+            },
+            required: ['completions'],
+        },
+    },
+    {
+        name: 'add_subtask',
+        description: `Add a subtask to break down a larger task into smaller workable pieces.
+Subtasks can be claimed and worked on independently by any agent.
+Subtasks inherit the project from their parent task.
+Max depth is 1 (subtasks cannot have their own subtasks).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                parent_task_id: {
+                    type: 'string',
+                    description: 'UUID of the parent task to add subtask to',
+                },
+                title: {
+                    type: 'string',
+                    description: 'Subtask title',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Detailed description (optional)',
+                },
+                priority: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 5,
+                    description: 'Priority 1-5 (1 = highest). Defaults to parent task priority.',
+                },
+                estimated_minutes: {
+                    type: 'number',
+                    minimum: 1,
+                    description: 'Estimated time to complete in minutes',
+                },
+            },
+            required: ['parent_task_id', 'title'],
+        },
+    },
+    {
+        name: 'get_subtasks',
+        description: `Get subtasks for a parent task with pagination.
+Returns subtasks with aggregate completion stats.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                parent_task_id: {
+                    type: 'string',
+                    description: 'UUID of the parent task',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'],
+                    description: 'Filter by status (optional)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max subtasks to return (default: 20, max: 50)',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Number of subtasks to skip (default: 0)',
+                },
+            },
+            required: ['parent_task_id'],
+        },
+    },
+];

package/dist/tools/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tool Definition Types
+ *
+ * Re-export the Tool type from the MCP SDK for use in domain-specific tool files.
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+export type { Tool };

package/dist/tools/types.js

@@ -0,0 +1,6 @@
+/**
+ * Tool Definition Types
+ *
+ * Re-export the Tool type from the MCP SDK for use in domain-specific tool files.
+ */
+export {};

package/dist/tools/validation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Validation Tool Definitions
+ *
+ * Tools for task validation workflow:
+ * - get_tasks_awaiting_validation
+ * - claim_validation
+ * - validate_task
+ */
+import type { Tool } from './types.js';
+export declare const validationTools: Tool[];

package/dist/tools/validation.js

@@ -0,0 +1,72 @@
+/**
+ * Validation Tool Definitions
+ *
+ * Tools for task validation workflow:
+ * - get_tasks_awaiting_validation
+ * - claim_validation
+ * - validate_task
+ */
+export const validationTools = [
+    {
+        name: 'get_tasks_awaiting_validation',
+        description: `Get completed tasks not yet validated.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'claim_validation',
+        description: 'Claim a completed task for review. Shows "being reviewed" on dashboard.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID to claim for review',
+                },
+            },
+            required: ['task_id'],
+        },
+    },
+    {
+        name: 'validate_task',
+        description: 'Validate a completed task. Include test results in validation_notes. For github-flow/git-flow projects, a PR must exist and checks must pass before approval.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID to validate',
+                },
+                validation_notes: {
+                    type: 'string',
+                    description: 'Notes about the validation (what was checked, any issues found)',
+                },
+                approved: {
+                    type: 'boolean',
+                    description: 'Whether the task passes validation (true = approved, false = needs more work)',
+                },
+                pr_checks_passing: {
+                    type: 'boolean',
+                    description: 'REQUIRED when approving tasks with PRs. Confirm you verified PR checks are passing via `gh pr view <PR_NUMBER> --json statusCheckRollup`. Set to true only if all required checks pass.',
+                },
+                skip_pr_check: {
+                    type: 'boolean',
+                    description: 'Skip PR existence check (use only for tasks that legitimately do not need a PR)',
+                },
+                create_fix_task: {
+                    type: 'boolean',
+                    description: 'When rejecting (approved: false), create a new fix task linked to the original. The fix task will contain the rejection reason and be assigned the same git branch.',
+                },
+            },
+            required: ['task_id', 'approved'],
+        },
+    },
+];

package/dist/tools/worktrees.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Git Worktree Tool Definitions
+ *
+ * Tools for managing git worktrees:
+ * - get_stale_worktrees: Get worktrees that need cleanup
+ * - clear_worktree_path: Clear worktree_path from a task after cleanup
+ */
+import type { Tool } from './types.js';
+export declare const worktreeTools: Tool[];