@vibescope/mcp-server 0.2.9 → 0.3.0

package/CHANGELOG.md

@@ -1,84 +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
+# 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

@@ -1,194 +1,194 @@
-# @vibescope/mcp-server
-
-MCP server for Vibescope - enables AI agents to track project progress, tasks, blockers, and decisions.
-
-## Installation
-
-### Option 1: npx (Recommended - No Installation)
-
-Use directly in your MCP config without installing:
-
-```json
-{
-  "mcpServers": {
-    "vibescope": {
-      "command": "npx",
-      "args": ["-y", "-p", "@vibescope/mcp-server@latest", "vibescope-mcp"],
-      "env": {
-        "VIBESCOPE_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
-
-### Option 2: Global Install
-
-```bash
-npm install -g @vibescope/mcp-server@latest
-```
-
-Then configure:
-
-```json
-{
-  "mcpServers": {
-    "vibescope": {
-      "command": "vibescope-mcp",
-      "env": {
-        "VIBESCOPE_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
-
-## Quick Start
-
-### Interactive Setup (Recommended)
-
-Run the setup wizard to automatically configure Vibescope for your IDE:
-
-```bash
-npx -p @vibescope/mcp-server vibescope-cli setup
-```
-
-This guides you through:
-1. Selecting your IDE (Claude Code, Claude Desktop, Cursor, or Gemini CLI)
-2. Getting your API key from the Vibescope dashboard
-3. Writing the configuration file
-
-### Claude Code (Manual)
-
-```bash
-claude mcp add vibescope npx @vibescope/mcp-server@latest \
-  --env VIBESCOPE_API_KEY=your_key
-```
-
-### Gemini CLI (Manual)
-
-Add to your `~/.gemini/settings.json` or project-level `.gemini/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "vibescope": {
-      "command": "npx",
-      "args": ["-y", "-p", "@vibescope/mcp-server@latest", "vibescope-mcp"],
-      "env": {
-        "VIBESCOPE_API_KEY": "$VIBESCOPE_API_KEY"
-      },
-      "timeout": 30000,
-      "trust": true
-    }
-  }
-}
-```
-
-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)
-
-MCP tools are invoked **from within your AI conversation**, not via command line.
-
-**WRONG - CLI does not have a 'call' command:**
-```bash
-# 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)
-2. Go to Settings
-3. Generate an API key
-
-## Available Tools
-
-The MCP server provides **140+ tools** for AI agents. Here are the key tools by category:
-
-### Session
-| Tool | Description |
-|------|-------------|
-| `start_work_session` | Initialize session, get persona, role, and next task |
-| `end_work_session` | End session and release claimed tasks |
-| `heartbeat` | Keep session active (call every 30-60s) |
-| `get_help` | Get guidance on workflows |
-| `discover_tools` | List tools by category |
-| `get_tool_info` | Get detailed tool documentation |
-
-### Projects
-| Tool | Description |
-|------|-------------|
-| `create_project` | Create a new project |
-| `update_project` | Update project details and git workflow |
-| `get_project_context` | Get full project context |
-| `get_git_workflow` | Get git branching instructions |
-| `query_knowledge_base` | Query aggregated project knowledge |
-
-### Tasks
-| Tool | Description |
-|------|-------------|
-| `get_tasks` | List tasks, optionally filtered by status |
-| `get_next_task` | Get highest priority pending task |
-| `add_task` | Create a new task |
-| `update_task` | Update task status, progress, or details |
-| `complete_task` | Mark a task as completed |
-| `add_subtask` | Break down tasks into subtasks |
-| `add_task_reference` | Add reference URL (docs, PRs) |
-| `batch_update_tasks` | Update multiple tasks at once |
-
-### Progress & Context
-| Tool | Description |
-|------|-------------|
-| `log_progress` | Log a progress update |
-| `add_blocker` | Flag a blocker needing human input |
-| `resolve_blocker` | Mark a blocker as resolved |
-| `log_decision` | Record an architectural decision |
-| `add_idea` | Record an improvement idea |
-| `add_finding` | Record an audit finding |
-
-### Validation & Deployment
-| Tool | Description |
-|------|-------------|
-| `get_tasks_awaiting_validation` | Get tasks needing review |
-| `claim_validation` | Claim a task for review |
-| `validate_task` | Approve or reject work |
-| `request_deployment` | Request a deployment |
-| `check_deployment_status` | Check deployment state |
-| `complete_deployment` | Mark deployment done |
-
-### Collaboration
-| Tool | Description |
-|------|-------------|
-| `add_milestone` | Track progress on complex tasks |
-| `create_body_of_work` | Group tasks into phases |
-| `create_sprint` | Create time-bounded sprints |
-| `checkout_file` | Prevent file conflicts |
-| `get_pending_requests` | Get human requests |
-| `answer_question` | Answer user questions |
-
-### Additional Categories
-- **Organizations**: Create, manage, and share projects with teams
-- **Cost Tracking**: Monitor spending with alerts and summaries
-- **Git Issues**: Track merge conflicts and push failures
-- **Role Management**: Configure agent roles (developer, validator, deployer)
-- **Scheduled Deployments**: Schedule recurring deployments
-
-Use `discover_tools` to explore all categories and `get_tool_info` for detailed documentation
-
-## Rate Limits
-
-- 60 requests per minute per API key
-- Warning shown when quota drops below 10 requests
+# @vibescope/mcp-server
+
+MCP server for Vibescope - enables AI agents to track project progress, tasks, blockers, and decisions.
+
+## Installation
+
+### Option 1: npx (Recommended - No Installation)
+
+Use directly in your MCP config without installing:
+
+```json
+{
+  "mcpServers": {
+    "vibescope": {
+      "command": "npx",
+      "args": ["-y", "-p", "@vibescope/mcp-server@latest", "vibescope-mcp"],
+      "env": {
+        "VIBESCOPE_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Option 2: Global Install
+
+```bash
+npm install -g @vibescope/mcp-server@latest
+```
+
+Then configure:
+
+```json
+{
+  "mcpServers": {
+    "vibescope": {
+      "command": "vibescope-mcp",
+      "env": {
+        "VIBESCOPE_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Quick Start
+
+### Interactive Setup (Recommended)
+
+Run the setup wizard to automatically configure Vibescope for your IDE:
+
+```bash
+npx -p @vibescope/mcp-server vibescope-cli setup
+```
+
+This guides you through:
+1. Selecting your IDE (Claude Code, Claude Desktop, Cursor, or Gemini CLI)
+2. Getting your API key from the Vibescope dashboard
+3. Writing the configuration file
+
+### Claude Code (Manual)
+
+```bash
+claude mcp add vibescope npx @vibescope/mcp-server@latest \
+  --env VIBESCOPE_API_KEY=your_key
+```
+
+### Gemini CLI (Manual)
+
+Add to your `~/.gemini/settings.json` or project-level `.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "vibescope": {
+      "command": "npx",
+      "args": ["-y", "-p", "@vibescope/mcp-server@latest", "vibescope-mcp"],
+      "env": {
+        "VIBESCOPE_API_KEY": "$VIBESCOPE_API_KEY"
+      },
+      "timeout": 30000,
+      "trust": true
+    }
+  }
+}
+```
+
+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)
+
+MCP tools are invoked **from within your AI conversation**, not via command line.
+
+**WRONG - CLI does not have a 'call' command:**
+```bash
+# 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)
+2. Go to Settings
+3. Generate an API key
+
+## Available Tools
+
+The MCP server provides **140+ tools** for AI agents. Here are the key tools by category:
+
+### Session
+| Tool | Description |
+|------|-------------|
+| `start_work_session` | Initialize session, get persona, role, and next task |
+| `end_work_session` | End session and release claimed tasks |
+| `heartbeat` | Keep session active (call every 30-60s) |
+| `get_help` | Get guidance on workflows |
+| `discover_tools` | List tools by category |
+| `get_tool_info` | Get detailed tool documentation |
+
+### Projects
+| Tool | Description |
+|------|-------------|
+| `create_project` | Create a new project |
+| `update_project` | Update project details and git workflow |
+| `get_project_context` | Get full project context |
+| `get_git_workflow` | Get git branching instructions |
+| `query_knowledge_base` | Query aggregated project knowledge |
+
+### Tasks
+| Tool | Description |
+|------|-------------|
+| `get_tasks` | List tasks, optionally filtered by status |
+| `get_next_task` | Get highest priority pending task |
+| `add_task` | Create a new task |
+| `update_task` | Update task status, progress, or details |
+| `complete_task` | Mark a task as completed |
+| `add_subtask` | Break down tasks into subtasks |
+| `add_task_reference` | Add reference URL (docs, PRs) |
+| `batch_update_tasks` | Update multiple tasks at once |
+
+### Progress & Context
+| Tool | Description |
+|------|-------------|
+| `log_progress` | Log a progress update |
+| `add_blocker` | Flag a blocker needing human input |
+| `resolve_blocker` | Mark a blocker as resolved |
+| `log_decision` | Record an architectural decision |
+| `add_idea` | Record an improvement idea |
+| `add_finding` | Record an audit finding |
+
+### Validation & Deployment
+| Tool | Description |
+|------|-------------|
+| `get_tasks_awaiting_validation` | Get tasks needing review |
+| `claim_validation` | Claim a task for review |
+| `validate_task` | Approve or reject work |
+| `request_deployment` | Request a deployment |
+| `check_deployment_status` | Check deployment state |
+| `complete_deployment` | Mark deployment done |
+
+### Collaboration
+| Tool | Description |
+|------|-------------|
+| `add_milestone` | Track progress on complex tasks |
+| `create_body_of_work` | Group tasks into phases |
+| `create_sprint` | Create time-bounded sprints |
+| `checkout_file` | Prevent file conflicts |
+| `get_pending_requests` | Get human requests |
+| `answer_question` | Answer user questions |
+
+### Additional Categories
+- **Organizations**: Create, manage, and share projects with teams
+- **Cost Tracking**: Monitor spending with alerts and summaries
+- **Git Issues**: Track merge conflicts and push failures
+- **Role Management**: Configure agent roles (developer, validator, deployer)
+- **Scheduled Deployments**: Schedule recurring deployments
+
+Use `discover_tools` to explore all categories and `get_tool_info` for detailed documentation
+
+## Rate Limits
+
+- 60 requests per minute per API key
+- Warning shown when quota drops below 10 requests

package/dist/api-client.d.ts

@@ -142,6 +142,12 @@ export declare class VibescopeApiClient {
         };
         reminders?: string[];
     }>>;
+    signalIdle(sessionId: string): Promise<ApiResponse<{
+        success: boolean;
+        session_id: string;
+        status: string;
+        message: string;
+    }>>;
     listProjects(): Promise<ApiResponse<{
         projects: Array<{
             id: string;
@@ -479,6 +485,7 @@ export declare class VibescopeApiClient {
             validation?: number;
             blockers?: number;
             deployment?: string;
+            worktree_path?: string;
         };
         next_action: string;
         warnings?: string[];
@@ -487,6 +494,34 @@ export declare class VibescopeApiClient {
         success: boolean;
         deleted_id: string;
     }>>;
+    /**
+     * Release a task back to pending status.
+     * Clears session assignment, git branch, and worktree info.
+     */
+    releaseTask(taskId: string, params?: {
+        reason?: string;
+        session_id?: string;
+    }): Promise<ApiResponse<{
+        success: boolean;
+        task_id: string;
+        message: string;
+        reason?: string;
+        hint: string;
+    }>>;
+    /**
+     * Cancel a task with an optional reason.
+     * Task remains visible with cancelled status for historical tracking.
+     */
+    cancelTask(taskId: string, params?: {
+        cancelled_reason?: 'pr_closed' | 'superseded' | 'user_cancelled' | 'validation_failed' | 'obsolete' | 'blocked';
+        cancellation_note?: string;
+        session_id?: string;
+    }): Promise<ApiResponse<{
+        success: boolean;
+        task_id: string;
+        cancelled_reason: string | null;
+        message: string;
+    }>>;
     logProgress(projectId: string, params: {
         summary: string;
         details?: string;
@@ -760,6 +795,7 @@ export declare class VibescopeApiClient {
         approved: boolean;
         validation_notes?: string;
         skip_pr_check?: boolean;
+        pr_checks_passing?: boolean;
     }, sessionId?: string): Promise<ApiResponse<{
         success: boolean;
         approved: boolean;

package/dist/api-client.js

@@ -67,6 +67,11 @@ export class VibescopeApiClient {
             session_id: sessionId
         });
     }
+    async signalIdle(sessionId) {
+        return this.request('POST', '/api/mcp/sessions/idle', {
+            session_id: sessionId
+        });
+    }
     // Project endpoints
     async listProjects() {
         return this.request('GET', '/api/mcp/projects');
@@ -182,6 +187,35 @@ export class VibescopeApiClient {
     async deleteTask(taskId) {
         return this.request('DELETE', `/api/mcp/tasks/${taskId}`);
     }
+    /**
+     * Release a task back to pending status.
+     * Clears session assignment, git branch, and worktree info.
+     */
+    async releaseTask(taskId, params) {
+        return this.proxy('release_task', {
+            task_id: taskId,
+            reason: params?.reason,
+        }, params?.session_id ? {
+            session_id: params.session_id,
+            persona: null,
+            instance_id: '',
+        } : undefined);
+    }
+    /**
+     * Cancel a task with an optional reason.
+     * Task remains visible with cancelled status for historical tracking.
+     */
+    async cancelTask(taskId, params) {
+        return this.proxy('cancel_task', {
+            task_id: taskId,
+            cancelled_reason: params?.cancelled_reason,
+            cancellation_note: params?.cancellation_note,
+        }, params?.session_id ? {
+            session_id: params.session_id,
+            persona: null,
+            instance_id: '',
+        } : undefined);
+    }
     // Progress endpoints
     async logProgress(projectId, params) {
         return this.request('POST', `/api/mcp/projects/${projectId}/progress`, params);

package/dist/cli.d.ts

@@ -27,6 +27,6 @@ export interface VerificationResult {
         session_duration_minutes: number | null;
     };
 }
-export declare function normalizeGitUrl(url: string): string;
+export { normalizeGitUrl } from './utils.js';
 export declare function detectGitUrl(): string | null;
 export declare function verify(gitUrl?: string, projectId?: string): Promise<VerificationResult>;