@vibescope/mcp-server 0.2.4 → 0.2.5

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,181 +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
-
-### Claude Code
-
-```bash
-claude mcp add vibescope npx @vibescope/mcp-server@latest \
-  --env VIBESCOPE_API_KEY=your_key
-```
-
-### Gemini CLI
-
-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/cli.d.ts

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
 /**
- * Vibescope CLI - Enforcement verification tool
+ * Vibescope CLI - Setup wizard and enforcement verification tool
  *
- * Used by Claude Code Stop hook to verify agent compliance with Vibescope tracking.
- * Exit codes:
+ * Commands:
+ *   setup   - Interactive wizard to configure Vibescope for your IDE
+ *   verify  - Check agent compliance with Vibescope tracking (used by hooks)
+ *
+ * Exit codes (for verify command):
  *   0 = Compliant (allow exit)
  *   1 = Non-compliant (block exit, loop back)
  *   2 = Error (allow exit with warning)

package/dist/cli.js

@@ -1,14 +1,18 @@
 #!/usr/bin/env node
 /**
- * Vibescope CLI - Enforcement verification tool
+ * Vibescope CLI - Setup wizard and enforcement verification tool
  *
- * Used by Claude Code Stop hook to verify agent compliance with Vibescope tracking.
- * Exit codes:
+ * Commands:
+ *   setup   - Interactive wizard to configure Vibescope for your IDE
+ *   verify  - Check agent compliance with Vibescope tracking (used by hooks)
+ *
+ * Exit codes (for verify command):
  *   0 = Compliant (allow exit)
  *   1 = Non-compliant (block exit, loop back)
  *   2 = Error (allow exit with warning)
  */
 import { execSync } from 'child_process';
+import { runSetup } from './setup.js';
 // ============================================================================
 // Configuration (read at runtime for testability)
 // ============================================================================
@@ -89,7 +93,12 @@ export async function verify(gitUrl, projectId) {
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
-    if (command === 'verify') {
+    if (command === 'setup') {
+        // Run interactive setup wizard
+        await runSetup();
+        process.exit(0);
+    }
+    else if (command === 'verify') {
         // Parse --git-url and --project-id flags
         let gitUrl;
         let projectId;
@@ -116,28 +125,37 @@ async function main() {
     }
     else if (command === 'help' || command === '--help' || command === '-h') {
         console.log(`
-Vibescope CLI - Enforcement verification tool
+Vibescope CLI - Setup wizard and enforcement verification tool
 
 Usage:
-  vibescope-cli verify [options]    Check Vibescope compliance before exit
+  vibescope-cli setup                 Interactive setup wizard for your IDE
+  vibescope-cli verify [options]      Check Vibescope compliance before exit
+
+Setup:
+  Configures Vibescope MCP integration for:
+  - Claude Code (CLI)
+  - Claude Desktop
+  - Cursor
+  - Gemini CLI
 
-Options:
+Verify Options:
   --git-url <url>       Git repository URL (auto-detected if not provided)
   --project-id <id>     Vibescope project UUID
 
-Exit Codes:
+Exit Codes (verify):
   0  Compliant - agent can exit
   1  Non-compliant - agent should continue work
   2  Error - allow exit with warning
 
 Environment Variables:
-  VIBESCOPE_API_KEY       Required - Your Vibescope API key
+  VIBESCOPE_API_KEY       Required for verify - Your Vibescope API key
   VIBESCOPE_API_URL       Optional - API URL (default: https://vibescope.dev)
 `);
         process.exit(0);
     }
     else {
-        console.error('Usage: vibescope-cli verify [--git-url <url>] [--project-id <id>]');
+        console.error('Usage: vibescope-cli setup');
+        console.error('       vibescope-cli verify [--git-url <url>] [--project-id <id>]');
         console.error('       vibescope-cli --help');
         process.exit(2);
     }