@vibescope/mcp-server 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to `@vibescope/mcp-server` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Test writing reminders in developer workflow - `update_task(status: "in_progress")` now includes test guidance
+- Test check in validation workflow - `claim_validation` now checks for test file modifications in PR
+- PR link display on completed tasks in dashboard
+- Smart task selection respecting sprints, bodies of work, phases and dependencies
+- `get_project_summary` endpoint for unified project overview
+- `get_file_checkouts_stats` endpoint for aggregate file lock statistics
+- Pagination support for `get_pending_requests`, `get_deployment_requirements`, `get_decisions`, `get_blockers`
+- Offset pagination for `get_git_issues`, `get_file_checkouts`, `get_activity_history`
+- Pagination for scheduled deployments, activity schedules, and stale worktrees
+- New project settings: `require_pr_for_validation`, `auto_merge_on_approval`, `validation_required`, `default_task_priority`, `require_time_estimates`, `fallback_activities_enabled`, `git_delete_branch_on_merge`
+- Stats endpoints for blockers and decisions
+- Automatic semantic version bumping script (`scripts/version-bump.ts`)
+- Version npm scripts: `version:check`, `version:bump`, `version:patch`, `version:minor`, `version:major`
+
+### Changed
+- Worktree naming now includes agent persona and short task description for easier identification
+- Return `unanswered_questions_count` instead of full array in session responses for token efficiency
+
+## [0.2.3] - 2026-01-14
+
+### Fixed
+- Route complete_task through proxy endpoint for proper authentication
+- Surface unanswered questions prominently in start_work_session
+
+### Changed
+- Improved session context type handling for completeTask
+
+## [0.2.2] - 2026-01-13
+
+### Added
+- Token tracking module with unit tests
+- Connector handlers with unit tests
+- Custom connectors support for external integrations
+
+### Changed
+- Refactored duplicate tool definitions from index.ts
+
+## [0.2.1] - 2026-01-12
+
+### Added
+- Unit tests for blockers, decisions, and findings handlers
+- Stats endpoints for blockers, decisions, and findings
+
+### Fixed
+- Security vulnerability in @modelcontextprotocol/sdk (GHSA-8r9q-7v3j-jr4g)
+
+## [0.2.0] - 2026-01-11
+
+### Added
+- Deployment priority feature - active deployments block regular task assignment
+- Background activity history and scheduling
+- Agent creator tracking for tasks, ideas, blockers, decisions
+- Setup CLI package for guided onboarding
+
+### Changed
+- Updated get_next_task tool description to mention deployment blocking
+- Enhanced CLAUDE.md with deployment priority instructions
+
+## [0.1.0] - 2026-01-10
+
+### Added
+- Initial release of MCP server for Vibescope
+- Core tools: tasks, projects, sessions, progress tracking
+- Background activity support (fallback activities)
+- Git workflow integration with worktree support
+- Validation workflow for cross-agent task validation
+- Deployment coordination tools
+
+[Unreleased]: https://github.com/Nonatomic/Vibescope/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/Nonatomic/Vibescope/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/Nonatomic/Vibescope/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/Nonatomic/Vibescope/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/Nonatomic/Vibescope/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/Nonatomic/Vibescope/releases/tag/v0.1.0

package/README.md

@@ -13,7 +13,7 @@ Use directly in your MCP config without installing:
   "mcpServers": {
     "vibescope": {
       "command": "npx",
-      "args": ["-y", "-p", "@vibescope/mcp-server", "vibescope-mcp"],
+      "args": ["-y", "-p", "@vibescope/mcp-server@latest", "vibescope-mcp"],
       "env": {
         "VIBESCOPE_API_KEY": "your-api-key"
       }
@@ -25,7 +25,7 @@ Use directly in your MCP config without installing:
 ### Option 2: Global Install
 
 ```bash
-npm install -g @vibescope/mcp-server
+npm install -g @vibescope/mcp-server@latest
 ```
 
 Then configure:
@@ -43,43 +43,58 @@ Then configure:
 }
 ```
 
-### Option 3: From Source (Development)
+## Quick Start
+
+### Claude Code
 
 ```bash
-# Clone the repo
-git clone https://github.com/Nonatomic/Vibescope.git
-cd Vibescope
+claude mcp add vibescope npx @vibescope/mcp-server@latest \
+  --env VIBESCOPE_API_KEY=your_key
+```
 
-# Install dependencies and build
-pnpm install
-pnpm build
+### Gemini CLI
 
-# Point your MCP config to the built file
-```
+Add to your `~/.gemini/settings.json` or project-level `.gemini/settings.json`:
 
 ```json
 {
   "mcpServers": {
     "vibescope": {
-      "command": "node",
-      "args": ["/path/to/Vibescope/packages/mcp-server/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "-p", "@vibescope/mcp-server@latest", "vibescope-mcp"],
       "env": {
-        "VIBESCOPE_API_KEY": "your-api-key"
-      }
+        "VIBESCOPE_API_KEY": "$VIBESCOPE_API_KEY"
+      },
+      "timeout": 30000,
+      "trust": true
     }
   }
 }
 ```
 
-## Quick Start with Claude Code
+Then set your API key as an environment variable:
+```bash
+export VIBESCOPE_API_KEY=your_key_here
+```
+
+## How to Call MCP Tools (Important for AI Agents)
 
-The easiest way to get started:
+MCP tools are invoked **from within your AI conversation**, not via command line.
 
+**WRONG - CLI does not have a 'call' command:**
 ```bash
-claude mcp add vibescope npx @vibescope/mcp-server \
-  --env VIBESCOPE_API_KEY=your_key
+# This does NOT work
+claude mcp call vibescope start_work_session '{"git_url": "..."}'
 ```
 
+**RIGHT - Call tools within your conversation response:**
+```
+# Invoke as a tool call, same as Read, Edit, or Bash
+mcp__vibescope__start_work_session(git_url: "...", model: "opus")
+```
+
+The CLI commands (`claude mcp`, `gemini mcp`) are only for **server configuration** (`add`, `remove`, `list`), not for calling tools. All tool invocations happen within the AI conversation context.
+
 ## Getting an API Key
 
 1. Sign up at [vibescope.dev](https://vibescope.dev)
@@ -88,7 +103,7 @@ claude mcp add vibescope npx @vibescope/mcp-server \
 
 ## Available Tools
 
-The MCP server provides **130 tools** for AI agents. Here are the key tools by category:
+The MCP server provides **140+ tools** for AI agents. Here are the key tools by category:
 
 ### Session
 | Tool | Description |

package/dist/api-client.d.ts

@@ -31,6 +31,8 @@ export declare class VibescopeApiClient {
         mode?: 'lite' | 'full';
         model?: 'opus' | 'sonnet' | 'haiku';
         role?: 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer';
+        hostname?: string;
+        agent_type?: 'claude' | 'gemini' | 'cursor' | 'windsurf' | 'other';
     }): Promise<ApiResponse<{
         session_started: boolean;
         session_id?: string;
@@ -96,10 +98,34 @@ export declare class VibescopeApiClient {
             example: string;
             note: string;
         };
+        agent_setup?: {
+            agent_type: string;
+            is_new_agent_type: boolean;
+            setup_required: boolean;
+            instructions: string;
+            config_file: string;
+            template_url?: string;
+            steps: string[];
+        };
+        stale_worktrees?: Array<{
+            task_id: string;
+            task_title: string;
+            worktree_path: string;
+            worktree_hostname?: string | null;
+        }>;
+        stale_worktrees_count?: number;
+        cleanup_action?: string;
+        awaiting_validation?: Array<{
+            id: string;
+            title?: string;
+        }>;
+        validation_priority?: boolean;
+        next_action?: string;
         error?: string;
     }>>;
     heartbeat(sessionId: string, options?: {
         current_worktree_path?: string | null;
+        hostname?: string;
     }): Promise<ApiResponse<{
         success: boolean;
         session_id: string;
@@ -192,6 +218,14 @@ export declare class VibescopeApiClient {
         git_auto_tag?: boolean;
         deployment_instructions?: string;
         agent_instructions?: string;
+        git_delete_branch_on_merge?: boolean;
+        require_pr_for_validation?: boolean;
+        auto_merge_on_approval?: boolean;
+        validation_required?: boolean;
+        default_task_priority?: number;
+        require_time_estimates?: boolean;
+        fallback_activities_enabled?: boolean;
+        preferred_fallback_activities?: string[];
     }): Promise<ApiResponse<{
         success: boolean;
         project_id: string;
@@ -283,6 +317,121 @@ export declare class VibescopeApiClient {
             working_agent_session_id?: string;
         };
     }>>;
+    /**
+     * Get a single task by ID with optional subtasks and milestones
+     */
+    getTaskById(taskId: string, params?: {
+        include_subtasks?: boolean;
+        include_milestones?: boolean;
+    }): Promise<ApiResponse<{
+        task: {
+            id: string;
+            title: string;
+            description?: string;
+            priority: number;
+            status: string;
+            progress_percentage?: number;
+            estimated_minutes?: number;
+            started_at?: string;
+            completed_at?: string;
+            git_branch?: string;
+            references?: Array<{
+                url: string;
+                label?: string;
+            }>;
+        };
+        subtasks?: Array<{
+            id: string;
+            title: string;
+            status: string;
+            progress_percentage?: number;
+        }>;
+        milestones?: Array<{
+            id: string;
+            title: string;
+            status: string;
+            order_index: number;
+        }>;
+    }>>;
+    /**
+     * Search tasks by text query with pagination
+     */
+    searchTasks(projectId: string, params: {
+        query: string;
+        status?: string[];
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<{
+        tasks: Array<{
+            id: string;
+            title: string;
+            status: string;
+            priority: number;
+            snippet?: string;
+        }>;
+        total_matches: number;
+        hint?: string;
+    }>>;
+    /**
+     * Get tasks filtered by priority with pagination
+     */
+    getTasksByPriority(projectId: string, params?: {
+        priority?: number;
+        priority_max?: number;
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<{
+        tasks: Array<{
+            id: string;
+            title: string;
+            priority: number;
+            status: string;
+            estimated_minutes?: number;
+        }>;
+        total_count: number;
+    }>>;
+    /**
+     * Get recent tasks (newest or oldest) with pagination
+     */
+    getRecentTasks(projectId: string, params?: {
+        order?: 'newest' | 'oldest';
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<{
+        tasks: Array<{
+            id: string;
+            title: string;
+            status: string;
+            priority: number;
+            created_at: string;
+            age?: string;
+        }>;
+        total_count: number;
+    }>>;
+    /**
+     * Get task statistics for a project
+     */
+    getTaskStats(projectId: string): Promise<ApiResponse<{
+        total: number;
+        by_status: {
+            backlog: number;
+            pending: number;
+            in_progress: number;
+            completed: number;
+            cancelled: number;
+        };
+        by_priority: {
+            1: number;
+            2: number;
+            3: number;
+            4: number;
+            5: number;
+        };
+        awaiting_validation: number;
+        oldest_pending_days: number | null;
+    }>>;
     updateTask(taskId: string, updates: {
         title?: string;
         description?: string;
@@ -394,6 +543,10 @@ export declare class VibescopeApiClient {
     deleteBlocker(blockerId: string): Promise<ApiResponse<{
         success: boolean;
     }>>;
+    getBlockersStats(projectId: string): Promise<ApiResponse<{
+        total: number;
+        by_status: Record<string, number>;
+    }>>;
     getDecisions(projectId: string, options?: {
         limit?: number;
         offset?: number;
@@ -420,6 +573,9 @@ export declare class VibescopeApiClient {
     deleteDecision(decisionId: string): Promise<ApiResponse<{
         success: boolean;
     }>>;
+    getDecisionsStats(projectId: string): Promise<ApiResponse<{
+        total: number;
+    }>>;
     getIdeas(projectId: string, params?: {
         status?: string;
         limit?: number;
@@ -572,13 +728,15 @@ export declare class VibescopeApiClient {
     deleteMilestone(milestoneId: string): Promise<ApiResponse<{
         success: boolean;
     }>>;
-    getPendingRequests(projectId: string, sessionId?: string): Promise<ApiResponse<{
+    getPendingRequests(projectId: string, sessionId?: string, limit?: number, offset?: number): Promise<ApiResponse<{
         requests: Array<{
             id: string;
             request_type: string;
             message: string;
             created_at: string;
         }>;
+        total_count: number;
+        has_more: boolean;
     }>>;
     acknowledgeRequest(requestId: string, sessionId?: string): Promise<ApiResponse<{
         success: boolean;
@@ -645,7 +803,10 @@ export declare class VibescopeApiClient {
         latest_by_type: Record<string, unknown>;
         count: number;
     }>>;
-    getActivitySchedules(projectId: string): Promise<ApiResponse<{
+    getActivitySchedules(projectId: string, params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<{
         schedules: Array<{
             id: string;
             activity_type: string;
@@ -653,8 +814,8 @@ export declare class VibescopeApiClient {
             next_run_at?: string;
             enabled: boolean;
         }>;
-        due_activities: string[];
-        count: number;
+        total_count: number;
+        has_more: boolean;
     }>>;
     addSubtask(parentTaskId: string, params: {
         title: string;
@@ -802,6 +963,27 @@ export declare class VibescopeApiClient {
     }): Promise<ApiResponse<{
         success: boolean;
     }>>;
+    /**
+     * Report actual API token usage for accurate cost tracking.
+     * This records token usage to the session and attributes cost to the current task.
+     */
+    reportTokenUsage(sessionId: string, params: {
+        input_tokens: number;
+        output_tokens: number;
+        model?: 'opus' | 'sonnet' | 'haiku';
+    }): Promise<ApiResponse<{
+        success: boolean;
+        reported: {
+            session_id: string;
+            model: string;
+            input_tokens: number;
+            output_tokens: number;
+            total_tokens: number;
+            estimated_cost_usd: number;
+        };
+        task_attributed: boolean;
+        task_id?: string;
+    }>>;
     listOrganizations(): Promise<ApiResponse<{
         organizations: Array<{
             id: string;
@@ -1009,6 +1191,7 @@ export declare class VibescopeApiClient {
         issue_type?: string;
         branch?: string;
         limit?: number;
+        offset?: number;
     }): Promise<ApiResponse<{
         git_issues: Array<{
             id: string;
@@ -1172,6 +1355,8 @@ export declare class VibescopeApiClient {
     getDeploymentRequirements(projectId: string, params?: {
         status?: string;
         stage?: string;
+        limit?: number;
+        offset?: number;
     }): Promise<ApiResponse<{
         requirements: Array<{
             id: string;
@@ -1181,6 +1366,14 @@ export declare class VibescopeApiClient {
             status: string;
             stage: string;
         }>;
+        total_count: number;
+        has_more: boolean;
+    }>>;
+    getDeploymentRequirementsStats(projectId: string): Promise<ApiResponse<{
+        total: number;
+        by_status: Record<string, number>;
+        by_stage: Record<string, number>;
+        by_type: Record<string, number>;
     }>>;
     completeDeploymentRequirement(requirementId: string): Promise<ApiResponse<{
         success: boolean;
@@ -1198,7 +1391,11 @@ export declare class VibescopeApiClient {
         success: boolean;
         schedule_id: string;
     }>>;
-    getScheduledDeployments(projectId: string, includeDisabled?: boolean): Promise<ApiResponse<{
+    getScheduledDeployments(projectId: string, params?: {
+        includeDisabled?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<{
         schedules: Array<{
             id: string;
             scheduled_at: string;
@@ -1211,8 +1408,8 @@ export declare class VibescopeApiClient {
             git_ref?: string;
             notes?: string;
         }>;
-        count: number;
-        due_count: number;
+        total_count: number;
+        has_more: boolean;
     }>>;
     updateScheduledDeployment(scheduleId: string, updates: {
         scheduled_at?: string;
@@ -1253,6 +1450,51 @@ export declare class VibescopeApiClient {
         success: boolean;
         project_id: string;
     }>>;
+    getProjectSummary(projectId: string): Promise<ApiResponse<{
+        project: {
+            id: string;
+            name: string;
+            description?: string;
+            goal?: string;
+            status: string;
+            git_url?: string;
+            tech_stack?: string[];
+            git_workflow?: string;
+        };
+        tasks: {
+            total: number;
+            by_status: Record<string, number>;
+        };
+        blockers: {
+            total: number;
+            open: number;
+            resolved: number;
+        };
+        findings: {
+            total: number;
+            by_severity: Record<string, number>;
+            by_status: Record<string, number>;
+        };
+        agents: {
+            active_count: number;
+            total_tokens_this_session: number;
+            total_tool_calls: number;
+        };
+        activity: {
+            tasks_completed_today: number;
+            progress_entries_today: number;
+        };
+        deployment: {
+            active: boolean;
+            status: string | null;
+            last_deployment_at: string | null;
+        };
+        planning: {
+            active_sprints: number;
+            active_bodies_of_work: number;
+            pending_deployment_requirements: number;
+        };
+    }>>;
     getHelpTopic(slug: string): Promise<ApiResponse<{
         slug: string;
         title: string;
@@ -1283,6 +1525,7 @@ export declare class VibescopeApiClient {
         status?: string;
         file_path?: string;
         limit?: number;
+        offset?: number;
     }): Promise<ApiResponse<{
         checkouts: Array<{
             id: string;
@@ -1304,22 +1547,38 @@ export declare class VibescopeApiClient {
         checkout_id: string;
         message: string;
     }>>;
-    getStaleWorktrees(projectId: string): Promise<ApiResponse<{
+    getFileCheckoutsStats(projectId: string): Promise<ApiResponse<{
+        total: number;
+        by_status: Record<string, number>;
+    }>>;
+    getStaleWorktrees(projectId: string, params?: {
+        hostname?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<{
         project_id: string;
         project_name: string;
+        hostname_filter: string | null;
         stale_worktrees: Array<{
             task_id: string;
             task_title: string;
             worktree_path: string;
+            worktree_hostname: string | null;
             git_branch: string | null;
             status: string;
             completed_at: string | null;
             updated_at: string;
             pr_url: string | null;
             stale_reason: 'task_finished' | 'potentially_abandoned';
+            can_cleanup_locally: boolean;
         }>;
         count: number;
+        local_count: number;
+        remote_count: number;
+        total_count: number;
+        has_more: boolean;
         cleanup_instructions: string[] | null;
+        remote_worktree_note: string | null;
     }>>;
     clearWorktreePath(taskId: string): Promise<ApiResponse<{
         success: boolean;
@@ -1413,6 +1672,15 @@ export declare class VibescopeApiClient {
         total_count: number;
         has_more: boolean;
     }>>;
+    /**
+     * Confirm that agent setup is complete for a project.
+     * This marks the agent type as onboarded so future sessions don't receive setup instructions.
+     */
+    confirmAgentSetup(projectId: string, agentType: 'claude' | 'gemini' | 'cursor' | 'windsurf' | 'other'): Promise<ApiResponse<{
+        success: boolean;
+        project_id: string;
+        agent_type: string;
+    }>>;
 }
 export declare function getApiClient(): VibescopeApiClient;
 export declare function initApiClient(config: ApiClientConfig): VibescopeApiClient;