@vibescope/mcp-server 0.4.5 → 0.4.7

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/project.d.ts

@@ -96,6 +96,7 @@ export interface ProjectMethods {
         require_time_estimates?: boolean;
         fallback_activities_enabled?: boolean;
         preferred_fallback_activities?: string[];
+        allow_agent_task_creation?: boolean;
     }): Promise<ApiResponse<{
         success: boolean;
         project_id: string;

package/dist/api-client.d.ts

@@ -27,7 +27,9 @@ export declare class VibescopeApiClient {
     private retryConfig;
     constructor(config: ApiClientConfig);
     private request;
-    validateAuth(): Promise<ApiResponse<{
+    validateAuth(options?: {
+        timeoutMs?: number;
+    }): Promise<ApiResponse<{
         valid: boolean;
         user_id: string;
         api_key_id: string;
@@ -245,6 +247,7 @@ export declare class VibescopeApiClient {
         require_time_estimates?: boolean;
         fallback_activities_enabled?: boolean;
         preferred_fallback_activities?: string[];
+        allow_agent_task_creation?: boolean;
     }): Promise<ApiResponse<{
         success: boolean;
         project_id: string;

package/dist/api-client.js

@@ -47,21 +47,30 @@ export class VibescopeApiClient {
             retryStatusCodes: config.retry?.retryStatusCodes ?? DEFAULT_RETRY_STATUS_CODES,
         };
     }
-    async request(method, path, body) {
+    async request(method, path, body, options) {
         const url = `${this.baseUrl}${path}`;
         const { maxRetries, baseDelayMs, maxDelayMs, retryStatusCodes } = this.retryConfig;
         let lastError = null;
         let lastResponse = null;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            let timeoutId;
             try {
-                const response = await fetch(url, {
+                const fetchOptions = {
                     method,
                     headers: {
                         'Content-Type': 'application/json',
                         'X-API-Key': this.apiKey
                     },
-                    body: body ? JSON.stringify(body) : undefined
-                });
+                    body: body ? JSON.stringify(body) : undefined,
+                };
+                if (options?.timeoutMs) {
+                    const controller = new AbortController();
+                    timeoutId = setTimeout(() => controller.abort(), options.timeoutMs);
+                    fetchOptions.signal = controller.signal;
+                }
+                const response = await fetch(url, fetchOptions);
+                if (timeoutId)
+                    clearTimeout(timeoutId);
                 // Check if we should retry this status code
                 if (retryStatusCodes.includes(response.status) && attempt < maxRetries) {
                     lastResponse = response;
@@ -94,7 +103,15 @@ export class VibescopeApiClient {
                 };
             }
             catch (err) {
-                lastError = err instanceof Error ? err : new Error('Network error');
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                // Detect AbortError from timeout
+                if (err instanceof Error && err.name === 'AbortError' && options?.timeoutMs) {
+                    lastError = new Error(`Request timed out after ${options.timeoutMs}ms`);
+                }
+                else {
+                    lastError = err instanceof Error ? err : new Error('Network error');
+                }
                 // Retry on network errors (connection failures, timeouts)
                 if (attempt < maxRetries) {
                     const delay = calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs);
@@ -130,10 +147,10 @@ export class VibescopeApiClient {
         };
     }
     // Auth endpoints
-    async validateAuth() {
+    async validateAuth(options) {
         return this.request('POST', '/api/mcp/auth/validate', {
             api_key: this.apiKey
-        });
+        }, options);
     }
     // Session endpoints
     async startSession(params) {