@vibescope/mcp-server 0.2.1 → 0.2.3

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,40 +43,12 @@ Then configure:
 }
 ```
 
-### Option 3: From Source (Development)
-
-```bash
-# Clone the repo
-git clone https://github.com/Nonatomic/Vibescope.git
-cd Vibescope
-
-# Install dependencies and build
-pnpm install
-pnpm build
-
-# Point your MCP config to the built file
-```
-
-```json
-{
-  "mcpServers": {
-    "vibescope": {
-      "command": "node",
-      "args": ["/path/to/Vibescope/packages/mcp-server/dist/index.js"],
-      "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 \
+claude mcp add vibescope npx @vibescope/mcp-server@latest \
   --env VIBESCOPE_API_KEY=your_key
 ```
 
@@ -88,24 +60,77 @@ claude mcp add vibescope npx @vibescope/mcp-server \
 
 ## Available Tools
 
-The MCP server provides these tools for AI agents:
+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 |
 |------|-------------|
-| `start_work_session` | Initialize a work session for a project |
-| `get_project_context` | Get full project context including tasks, blockers, and user updates |
 | `get_tasks` | List tasks, optionally filtered by status |
-| `get_next_task` | Get the highest priority pending task |
+| `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 or technical decision |
+| `log_decision` | Record an architectural decision |
 | `add_idea` | Record an improvement idea |
-| `create_project` | Create a new project |
-| `update_project` | Update project details |
+| `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
 

package/dist/api-client.d.ts

@@ -69,6 +69,23 @@ export declare class VibescopeApiClient {
             priority: number;
             estimated_minutes?: number;
         } | null;
+        pending_requests?: Array<{
+            id: string;
+            request_type: string;
+            message: string;
+            created_at: string;
+        }>;
+        pending_requests_count?: number;
+        URGENT_QUESTIONS?: {
+            count: number;
+            oldest_waiting_minutes: number;
+            action_required: string;
+            requests: Array<{
+                id: string;
+                message: string;
+                waiting_minutes: number;
+            }>;
+        };
         directive?: string;
         blockers_count?: number;
         validation_count?: number;
@@ -275,6 +292,7 @@ export declare class VibescopeApiClient {
         progress_note?: string;
         estimated_minutes?: number;
         git_branch?: string;
+        worktree_path?: string;
         session_id?: string;
     }): Promise<ApiResponse<{
         success: boolean;
@@ -1057,6 +1075,63 @@ export declare class VibescopeApiClient {
             output_tokens: number;
         }>;
     }>>;
+    getBodyOfWorkCosts(params: {
+        body_of_work_id?: string;
+        project_id?: string;
+    }): Promise<ApiResponse<{
+        bodies_of_work: Array<{
+            body_of_work_id: string;
+            title: string;
+            project_id: string;
+            status: string;
+            task_count: number;
+            total_cost_usd: number;
+            total_tokens: number;
+            pre_phase_cost_usd: number;
+            core_phase_cost_usd: number;
+            post_phase_cost_usd: number;
+            model_breakdown: Record<string, {
+                input: number;
+                output: number;
+            }>;
+        }>;
+        count: number;
+        totals: {
+            total_cost_usd: number;
+            total_tokens: number;
+            total_tasks: number;
+        };
+    }>>;
+    getSprintCosts(params: {
+        sprint_id?: string;
+        project_id?: string;
+    }): Promise<ApiResponse<{
+        sprints: Array<{
+            sprint_id: string;
+            title: string;
+            project_id: string;
+            status: string;
+            sprint_number: number;
+            task_count: number;
+            total_cost_usd: number;
+            total_tokens: number;
+            cost_per_story_point: number | null;
+            committed_points: number;
+            velocity_points: number;
+            model_breakdown: Record<string, {
+                input: number;
+                output: number;
+            }>;
+        }>;
+        count: number;
+        totals: {
+            total_cost_usd: number;
+            total_tokens: number;
+            total_tasks: number;
+            total_velocity_points: number;
+            avg_cost_per_point: number | null;
+        };
+    }>>;
     getTokenUsage(): Promise<ApiResponse<{
         session_tokens: number;
         estimated_cost: number;
@@ -1116,6 +1191,7 @@ export declare class VibescopeApiClient {
         environment?: string;
         version_bump?: string;
         auto_trigger?: boolean;
+        hours_interval?: number;
         notes?: string;
         git_ref?: string;
     }): Promise<ApiResponse<{
@@ -1127,6 +1203,7 @@ export declare class VibescopeApiClient {
             id: string;
             scheduled_at: string;
             schedule_type: string;
+            hours_interval: number;
             environment: string;
             version_bump: string;
             auto_trigger: boolean;
@@ -1140,6 +1217,7 @@ export declare class VibescopeApiClient {
     updateScheduledDeployment(scheduleId: string, updates: {
         scheduled_at?: string;
         schedule_type?: string;
+        hours_interval?: number;
         environment?: string;
         version_bump?: string;
         auto_trigger?: boolean;
@@ -1226,6 +1304,115 @@ export declare class VibescopeApiClient {
         checkout_id: string;
         message: string;
     }>>;
+    getStaleWorktrees(projectId: string): Promise<ApiResponse<{
+        project_id: string;
+        project_name: string;
+        stale_worktrees: Array<{
+            task_id: string;
+            task_title: string;
+            worktree_path: string;
+            git_branch: string | null;
+            status: string;
+            completed_at: string | null;
+            updated_at: string;
+            pr_url: string | null;
+            stale_reason: 'task_finished' | 'potentially_abandoned';
+        }>;
+        count: number;
+        cleanup_instructions: string[] | null;
+    }>>;
+    clearWorktreePath(taskId: string): Promise<ApiResponse<{
+        success: boolean;
+        task_id: string;
+    }>>;
+    getConnectors(projectId: string, params?: {
+        type?: string;
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<{
+        connectors: Array<{
+            id: string;
+            name: string;
+            type: string;
+            description?: string;
+            status: string;
+            events: Record<string, boolean>;
+            events_sent: number;
+            last_triggered_at?: string;
+            last_error?: string;
+            last_error_at?: string;
+            created_at: string;
+        }>;
+        total_count: number;
+        has_more: boolean;
+    }>>;
+    getConnector(connectorId: string): Promise<ApiResponse<{
+        connector: {
+            id: string;
+            name: string;
+            type: string;
+            description?: string;
+            config: Record<string, unknown>;
+            events: Record<string, boolean>;
+            status: string;
+            events_sent: number;
+            last_triggered_at?: string;
+            last_error?: string;
+            last_error_at?: string;
+            created_at: string;
+        };
+    }>>;
+    addConnector(projectId: string, params: {
+        name: string;
+        type: string;
+        description?: string;
+        config?: Record<string, unknown>;
+        events?: Record<string, boolean>;
+    }): Promise<ApiResponse<{
+        success: boolean;
+        connector_id: string;
+    }>>;
+    updateConnector(connectorId: string, updates: {
+        name?: string;
+        description?: string;
+        config?: Record<string, unknown>;
+        events?: Record<string, boolean>;
+        status?: string;
+    }): Promise<ApiResponse<{
+        success: boolean;
+        connector_id: string;
+    }>>;
+    deleteConnector(connectorId: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+    testConnector(connectorId: string): Promise<ApiResponse<{
+        success: boolean;
+        event_id: string;
+        status?: number;
+        error?: string;
+    }>>;
+    getConnectorEvents(params: {
+        connector_id?: string;
+        project_id?: string;
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<{
+        events: Array<{
+            id: string;
+            connector_id: string;
+            event_type: string;
+            status: string;
+            response_status?: number;
+            error_message?: string;
+            attempts: number;
+            created_at: string;
+            sent_at?: string;
+        }>;
+        total_count: number;
+        has_more: boolean;
+    }>>;
 }
 export declare function getApiClient(): VibescopeApiClient;
 export declare function initApiClient(config: ApiClientConfig): VibescopeApiClient;

package/dist/api-client.js

@@ -118,7 +118,11 @@ export class VibescopeApiClient {
         return this.request('PATCH', `/api/mcp/tasks/${taskId}`, updates);
     }
     async completeTask(taskId, params) {
-        return this.request('POST', `/api/mcp/tasks/${taskId}/complete`, params);
+        // Use proxy endpoint for consistency - direct endpoint had routing issues on Vercel
+        return this.proxy('complete_task', {
+            task_id: taskId,
+            summary: params.summary,
+        }, params.session_id ? { session_id: params.session_id, persona: null, instance_id: '' } : undefined);
     }
     async deleteTask(taskId) {
         return this.request('DELETE', `/api/mcp/tasks/${taskId}`);
@@ -616,6 +620,12 @@ export class VibescopeApiClient {
             limit
         });
     }
+    async getBodyOfWorkCosts(params) {
+        return this.proxy('get_body_of_work_costs', params);
+    }
+    async getSprintCosts(params) {
+        return this.proxy('get_sprint_costs', params);
+    }
     async getTokenUsage() {
         return this.proxy('get_token_usage', {});
     }
@@ -725,6 +735,48 @@ export class VibescopeApiClient {
     async abandonCheckout(params) {
         return this.proxy('abandon_checkout', params);
     }
+    // ============================================================================
+    // Worktree Management
+    // ============================================================================
+    async getStaleWorktrees(projectId) {
+        return this.request('GET', `/api/mcp/worktrees/stale?project_id=${projectId}`);
+    }
+    async clearWorktreePath(taskId) {
+        return this.request('PATCH', `/api/mcp/tasks/${taskId}`, { worktree_path: null });
+    }
+    // ============================================================================
+    // Connector endpoints
+    // ============================================================================
+    async getConnectors(projectId, params) {
+        return this.proxy('get_connectors', {
+            project_id: projectId,
+            ...params
+        });
+    }
+    async getConnector(connectorId) {
+        return this.proxy('get_connector', { connector_id: connectorId });
+    }
+    async addConnector(projectId, params) {
+        return this.proxy('add_connector', {
+            project_id: projectId,
+            ...params
+        });
+    }
+    async updateConnector(connectorId, updates) {
+        return this.proxy('update_connector', {
+            connector_id: connectorId,
+            ...updates
+        });
+    }
+    async deleteConnector(connectorId) {
+        return this.proxy('delete_connector', { connector_id: connectorId });
+    }
+    async testConnector(connectorId) {
+        return this.proxy('test_connector', { connector_id: connectorId });
+    }
+    async getConnectorEvents(params) {
+        return this.proxy('get_connector_events', params);
+    }
 }
 // Singleton instance
 let apiClient = null;

package/dist/handlers/blockers.js

@@ -7,6 +7,7 @@
  * - get_blockers
  * - delete_blocker
  */
+import { success, error } from './types.js';
 import { parseArgs, uuidValidator, createEnumValidator, VALID_BLOCKER_STATUSES, } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 // Argument schemas for type-safe parsing
@@ -33,18 +34,18 @@ export const addBlocker = async (args, ctx) => {
     const apiClient = getApiClient();
     const response = await apiClient.addBlocker(project_id, description, ctx.session.currentSessionId || undefined);
     if (!response.ok) {
-        throw new Error(response.error || 'Failed to add blocker');
+        return error(response.error || 'Failed to add blocker');
     }
-    return { result: response.data };
+    return success(response.data);
 };
 export const resolveBlocker = async (args, _ctx) => {
     const { blocker_id, resolution_note } = parseArgs(args, resolveBlockerSchema);
     const apiClient = getApiClient();
     const response = await apiClient.resolveBlocker(blocker_id, resolution_note);
     if (!response.ok) {
-        throw new Error(response.error || 'Failed to resolve blocker');
+        return error(response.error || 'Failed to resolve blocker');
     }
-    return { result: response.data };
+    return success(response.data);
 };
 export const getBlockers = async (args, _ctx) => {
     const { project_id, status, limit, offset, search_query } = parseArgs(args, getBlockersSchema);
@@ -56,18 +57,18 @@ export const getBlockers = async (args, _ctx) => {
         search_query
     });
     if (!response.ok) {
-        throw new Error(response.error || 'Failed to fetch blockers');
+        return error(response.error || 'Failed to fetch blockers');
     }
-    return { result: response.data };
+    return success(response.data);
 };
 export const deleteBlocker = async (args, _ctx) => {
     const { blocker_id } = parseArgs(args, deleteBlockerSchema);
     const apiClient = getApiClient();
     const response = await apiClient.deleteBlocker(blocker_id);
     if (!response.ok) {
-        throw new Error(response.error || 'Failed to delete blocker');
+        return error(response.error || 'Failed to delete blocker');
     }
-    return { result: response.data };
+    return success(response.data);
 };
 /**
  * Blockers handlers registry

package/dist/handlers/bodies-of-work.js

@@ -105,7 +105,7 @@ export const createBodyOfWork = async (args, ctx) => {
         instance_id: session.instanceId
     });
     if (!response.ok) {
-        throw new Error(`Failed to create body of work: ${response.error}`);
+        return { result: { error: response.error || 'Failed to create body of work' }, isError: true };
     }
     return {
         result: {
@@ -135,7 +135,7 @@ export const updateBodyOfWork = async (args, ctx) => {
         deploy_trigger
     });
     if (!response.ok) {
-        throw new Error(`Failed to update body of work: ${response.error}`);
+        return { result: { error: response.error || 'Failed to update body of work' }, isError: true };
     }
     return { result: { success: true, body_of_work_id } };
 };
@@ -145,7 +145,7 @@ export const getBodyOfWork = async (args, ctx) => {
     // Response type varies based on summary_only
     const response = await apiClient.proxy('get_body_of_work', { body_of_work_id, summary_only });
     if (!response.ok) {
-        throw new Error(`Failed to get body of work: ${response.error}`);
+        return { result: { error: response.error || 'Failed to get body of work' }, isError: true };
     }
     return { result: response.data };
 };
@@ -160,7 +160,7 @@ export const getBodiesOfWork = async (args, ctx) => {
         search_query
     });
     if (!response.ok) {
-        throw new Error(`Failed to fetch bodies of work: ${response.error}`);
+        return { result: { error: response.error || 'Failed to fetch bodies of work' }, isError: true };
     }
     return { result: response.data };
 };
@@ -171,7 +171,7 @@ export const deleteBodyOfWork = async (args, ctx) => {
         body_of_work_id
     });
     if (!response.ok) {
-        throw new Error(`Failed to delete body of work: ${response.error}`);
+        return { result: { error: response.error || 'Failed to delete body of work' }, isError: true };
     }
     return { result: { success: true, message: 'Body of work deleted. Tasks are preserved.' } };
 };
@@ -185,7 +185,7 @@ export const addTaskToBodyOfWork = async (args, ctx) => {
         order_index
     });
     if (!response.ok) {
-        throw new Error(`Failed to add task to body of work: ${response.error}`);
+        return { result: { error: response.error || 'Failed to add task to body of work' }, isError: true };
     }
     return { result: response.data };
 };
@@ -194,7 +194,7 @@ export const removeTaskFromBodyOfWork = async (args, ctx) => {
     const apiClient = getApiClient();
     const response = await apiClient.proxy('remove_task_from_body_of_work', { task_id });
     if (!response.ok) {
-        throw new Error(`Failed to remove task from body of work: ${response.error}`);
+        return { result: { error: response.error || 'Failed to remove task from body of work' }, isError: true };
     }
     return { result: response.data };
 };
@@ -203,14 +203,14 @@ export const activateBodyOfWork = async (args, ctx) => {
     const apiClient = getApiClient();
     const response = await apiClient.proxy('activate_body_of_work', { body_of_work_id });
     if (!response.ok) {
-        throw new Error(`Failed to activate body of work: ${response.error}`);
+        return { result: { error: response.error || 'Failed to activate body of work' }, isError: true };
     }
     return { result: response.data };
 };
 export const addTaskDependency = async (args, ctx) => {
     const { body_of_work_id, task_id, depends_on_task_id } = parseArgs(args, addTaskDependencySchema);
     if (task_id === depends_on_task_id) {
-        throw new Error('A task cannot depend on itself');
+        return { result: { error: 'A task cannot depend on itself' }, isError: true };
     }
     const apiClient = getApiClient();
     const response = await apiClient.proxy('add_task_dependency', {
@@ -219,7 +219,7 @@ export const addTaskDependency = async (args, ctx) => {
         depends_on_task_id
     });
     if (!response.ok) {
-        throw new Error(`Failed to add task dependency: ${response.error}`);
+        return { result: { error: response.error || 'Failed to add task dependency' }, isError: true };
     }
     return { result: response.data };
 };
@@ -231,14 +231,14 @@ export const removeTaskDependency = async (args, ctx) => {
         depends_on_task_id
     });
     if (!response.ok) {
-        throw new Error(`Failed to remove task dependency: ${response.error}`);
+        return { result: { error: response.error || 'Failed to remove task dependency' }, isError: true };
     }
     return { result: response.data };
 };
 export const getTaskDependencies = async (args, ctx) => {
     const { body_of_work_id, task_id } = parseArgs(args, getTaskDependenciesSchema);
     if (!body_of_work_id && !task_id) {
-        throw new Error('Either body_of_work_id or task_id is required');
+        return { result: { error: 'Either body_of_work_id or task_id is required' }, isError: true };
     }
     const apiClient = getApiClient();
     const response = await apiClient.proxy('get_task_dependencies', {
@@ -246,7 +246,7 @@ export const getTaskDependencies = async (args, ctx) => {
         task_id
     });
     if (!response.ok) {
-        throw new Error(`Failed to fetch task dependencies: ${response.error}`);
+        return { result: { error: response.error || 'Failed to fetch task dependencies' }, isError: true };
     }
     return { result: response.data };
 };
@@ -255,7 +255,7 @@ export const getNextBodyOfWorkTask = async (args, ctx) => {
     const apiClient = getApiClient();
     const response = await apiClient.proxy('get_next_body_of_work_task', { body_of_work_id });
     if (!response.ok) {
-        throw new Error(`Failed to get next body of work task: ${response.error}`);
+        return { result: { error: response.error || 'Failed to get next body of work task' }, isError: true };
     }
     return { result: response.data };
 };

package/dist/handlers/connectors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Connectors Handlers
+ *
+ * Handles external integration management:
+ * - get_connectors
+ * - get_connector
+ * - add_connector
+ * - update_connector
+ * - delete_connector
+ * - test_connector
+ * - get_connector_events
+ */
+import type { Handler, HandlerRegistry } from './types.js';
+/**
+ * Get all connectors for a project
+ */
+export declare const getConnectors: Handler;
+/**
+ * Get a single connector with full details
+ */
+export declare const getConnector: Handler;
+/**
+ * Add a new connector
+ */
+export declare const addConnector: Handler;
+/**
+ * Update a connector
+ */
+export declare const updateConnector: Handler;
+/**
+ * Delete a connector
+ */
+export declare const deleteConnector: Handler;
+/**
+ * Test a connector by sending a test event
+ */
+export declare const testConnector: Handler;
+/**
+ * Get connector event history
+ */
+export declare const getConnectorEvents: Handler;
+/**
+ * Connectors handlers registry
+ */
+export declare const connectorHandlers: HandlerRegistry;