@vibescope/mcp-server 0.2.0 → 0.2.2

package/dist/tools.js

@@ -5,7 +5,9 @@ export const tools = [
     {
         name: 'start_work_session',
         description: `CALL THIS FIRST when beginning work on a project.
-Returns session info, persona, role, and next task. Use mode:'full' for complete context.`,
+Returns session info, persona, role, and next_task. Start the next_task IMMEDIATELY without asking the user.
+
+Use mode:'full' for complete context, mode:'lite' (default) for minimal tokens.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -187,6 +189,40 @@ Returns session info, persona, role, and next task. Use mode:'full' for complete
             required: ['project_id'],
         },
     },
+    {
+        name: 'get_body_of_work_costs',
+        description: 'Get cost breakdown by body of work with phase-level details. Returns costs for pre/core/post phases and model breakdown.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                body_of_work_id: {
+                    type: 'string',
+                    description: 'Body of work UUID (optional if project_id provided)',
+                },
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID to get all body of work costs (optional if body_of_work_id provided)',
+                },
+            },
+        },
+    },
+    {
+        name: 'get_sprint_costs',
+        description: 'Get cost breakdown by sprint with velocity metrics. Returns cost per story point and phase breakdown.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sprint_id: {
+                    type: 'string',
+                    description: 'Sprint UUID (optional if project_id provided)',
+                },
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID to get all sprint costs (optional if sprint_id provided)',
+                },
+            },
+        },
+    },
     // Knowledge Base Query Tool
     {
         name: 'query_knowledge_base',
@@ -231,7 +267,7 @@ Returns session info, persona, role, and next task. Use mode:'full' for complete
             properties: {
                 category: {
                     type: 'string',
-                    enum: ['session', 'project', 'tasks', 'milestones', 'progress', 'blockers', 'decisions', 'ideas', 'findings', 'validation', 'deployment', 'fallback', 'requests', 'organizations', 'cost', 'knowledge'],
+                    enum: ['session', 'project', 'tasks', 'milestones', 'progress', 'blockers', 'decisions', 'ideas', 'findings', 'validation', 'deployment', 'fallback', 'bodies_of_work', 'sprints', 'requests', 'organizations', 'cost', 'git_issues', 'knowledge', 'discovery', 'subtasks', 'worktrees', 'roles', 'file_locks'],
                     description: 'Category to list (omit for all categories)',
                 },
             },
@@ -427,7 +463,9 @@ Returns session info, persona, role, and next task. Use mode:'full' for complete
     },
     {
         name: 'get_next_task',
-        description: 'Get highest priority pending task. Skips claimed tasks. Check deployment_blocks_tasks first.',
+        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: {
@@ -483,7 +521,13 @@ Returns session info, persona, role, and next task. Use mode:'full' for complete
     },
     {
         name: 'update_task',
-        description: 'Update task status, progress, or details. Include progress_note with progress_percentage.',
+        description: `Update task status, progress, or details. Include progress_note with progress_percentage.
+
+IMPORTANT: When setting status to "in_progress", you MUST provide git_branch AND worktree_path to enable cleanup tracking.
+Create worktree first: git worktree add ../PROJECT-task-TASKID -b feature/TASKID-description BASE_BRANCH
+Then call: update_task(task_id, status: "in_progress", git_branch: "feature/TASKID-description", worktree_path: "../PROJECT-task-TASKID")
+
+For projects without git branching (trunk-based or none), use skip_worktree_requirement: true.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -519,20 +563,35 @@ Returns session info, persona, role, and next task. Use mode:'full' for complete
                 },
                 git_branch: {
                     type: 'string',
-                    description: 'Git branch associated with this task',
+                    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.',
                 },
                 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 and context counts (validation, blockers, deployment).',
+        description: `Mark task done. Returns next_task which you MUST start immediately without asking the user.
+
+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: {
@@ -1104,6 +1163,46 @@ Returns subtasks with aggregate completion stats.`,
             required: ['parent_task_id'],
         },
     },
+    {
+        name: 'get_stale_worktrees',
+        description: `Get worktrees that need cleanup.
+
+Returns tasks with worktree_path set where:
+- Task is completed or cancelled (worktree should have been cleaned up)
+- Task has been abandoned (no activity for 24+ hours while in_progress)
+
+IMPORTANT: Call this on session start to clean up orphaned worktrees from previous sessions.
+For each stale worktree:
+1. Run: git worktree remove <worktree_path>
+2. Call: clear_worktree_path(task_id)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'clear_worktree_path',
+        description: `Clear the worktree_path from a task after cleanup.
+
+Call this AFTER removing the worktree with git worktree remove.
+This marks the task as cleaned up so it won't appear in get_stale_worktrees.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID',
+                },
+            },
+            required: ['task_id'],
+        },
+    },
     {
         name: 'heartbeat',
         description: `Send heartbeat to maintain 'active' status. Call every 30-60 seconds.`,
@@ -1432,8 +1531,14 @@ Returns subtasks with aggregate completion stats.`,
                 },
                 schedule_type: {
                     type: 'string',
-                    description: 'Schedule type: once (one-time), daily, weekly, or monthly',
-                    enum: ['once', 'daily', 'weekly', 'monthly'],
+                    description: 'Schedule type: once (one-time), hourly, daily, weekly, or monthly',
+                    enum: ['once', 'hourly', 'daily', 'weekly', 'monthly'],
+                },
+                hours_interval: {
+                    type: 'number',
+                    description: 'For hourly schedules, the number of hours between runs (1-24, default: 1)',
+                    minimum: 1,
+                    maximum: 24,
                 },
                 auto_trigger: {
                     type: 'boolean',
@@ -1496,7 +1601,13 @@ Returns subtasks with aggregate completion stats.`,
                 schedule_type: {
                     type: 'string',
                     description: 'New schedule type',
-                    enum: ['once', 'daily', 'weekly', 'monthly'],
+                    enum: ['once', 'hourly', 'daily', 'weekly', 'monthly'],
+                },
+                hours_interval: {
+                    type: 'number',
+                    description: 'For hourly schedules, the number of hours between runs (1-24)',
+                    minimum: 1,
+                    maximum: 24,
                 },
                 auto_trigger: {
                     type: 'boolean',
@@ -1594,6 +1705,7 @@ Returns subtasks with aggregate completion stats.`,
                         'documentation_review',
                         'dependency_audit',
                         'validate_completed_tasks',
+                        'worktree_cleanup',
                     ],
                 },
             },
@@ -2525,4 +2637,568 @@ 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'],
+        },
+    },
+    // ============================================================================
+    // Connector Tools (External Integrations)
+    // ============================================================================
+    {
+        name: 'get_connectors',
+        description: `List connectors for a project. Connectors enable sending events to external services (Slack, Discord, webhooks, etc.).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['webhook', 'slack', 'discord', 'github', 'custom'],
+                    description: 'Filter by connector type (optional)',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['active', 'disabled'],
+                    description: 'Filter by status (optional)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max connectors to return (default: 50)',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Pagination offset (default: 0)',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'get_connector',
+        description: `Get a single connector with full details including configuration (sensitive fields are masked).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                connector_id: {
+                    type: 'string',
+                    description: 'Connector UUID',
+                },
+            },
+            required: ['connector_id'],
+        },
+    },
+    {
+        name: 'add_connector',
+        description: `Add a new connector for external integrations. Supports webhook, Slack, Discord, GitHub, and custom connectors.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Connector name (e.g., "Slack Notifications")',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['webhook', 'slack', 'discord', 'github', 'custom'],
+                    description: 'Connector type',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Optional description',
+                },
+                config: {
+                    type: 'object',
+                    description: 'Type-specific configuration (e.g., { webhook_url: "..." } for Slack)',
+                },
+                events: {
+                    type: 'object',
+                    description: 'Event subscriptions (e.g., { task_completed: true, blocker_added: true })',
+                },
+            },
+            required: ['project_id', 'name', 'type'],
+        },
+    },
+    {
+        name: 'update_connector',
+        description: `Update a connector's configuration, events, or status.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                connector_id: {
+                    type: 'string',
+                    description: 'Connector UUID',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Updated name',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Updated description',
+                },
+                config: {
+                    type: 'object',
+                    description: 'Updated configuration (merged with existing)',
+                },
+                events: {
+                    type: 'object',
+                    description: 'Updated event subscriptions',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['active', 'disabled'],
+                    description: 'Enable or disable the connector',
+                },
+            },
+            required: ['connector_id'],
+        },
+    },
+    {
+        name: 'delete_connector',
+        description: `Delete a connector.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                connector_id: {
+                    type: 'string',
+                    description: 'Connector UUID',
+                },
+            },
+            required: ['connector_id'],
+        },
+    },
+    {
+        name: 'test_connector',
+        description: `Test a connector by sending a test event. Returns success/failure status.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                connector_id: {
+                    type: 'string',
+                    description: 'Connector UUID to test',
+                },
+            },
+            required: ['connector_id'],
+        },
+    },
+    {
+        name: 'get_connector_events',
+        description: `Get event history for a connector or project. Shows delivery status and errors.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                connector_id: {
+                    type: 'string',
+                    description: 'Connector UUID (optional if project_id provided)',
+                },
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID (optional if connector_id provided)',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['pending', 'sent', 'failed', 'retrying'],
+                    description: 'Filter by delivery status (optional)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max events to return (default: 50)',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Pagination offset (default: 0)',
+                },
+            },
+        },
+    },
 ];