@vibescope/mcp-server 0.2.3 → 0.2.5

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

@@ -1,138 +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 with Claude Code
-
-The easiest way to get started:
-
-```bash
-claude mcp add vibescope npx @vibescope/mcp-server@latest \
-  --env VIBESCOPE_API_KEY=your_key
-```
-
-## 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