@vibescope/mcp-server 0.2.0 → 0.2.2

package/README.md

@@ -88,24 +88,77 @@ claude mcp add vibescope npx @vibescope/mcp-server \
 
 ## Available Tools
 
-The MCP server provides these tools for AI agents:
+The MCP server provides **130 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;
@@ -209,6 +226,7 @@ export declare class VibescopeApiClient {
         estimated_minutes?: number;
         blocking?: boolean;
         session_id?: string;
+        task_type?: string;
     }): Promise<ApiResponse<{
         success: boolean;
         task_id: string;
@@ -274,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;
@@ -375,7 +394,11 @@ export declare class VibescopeApiClient {
     deleteBlocker(blockerId: string): Promise<ApiResponse<{
         success: boolean;
     }>>;
-    getDecisions(projectId: string): Promise<ApiResponse<{
+    getDecisions(projectId: string, options?: {
+        limit?: number;
+        offset?: number;
+        search_query?: string;
+    }): Promise<ApiResponse<{
         decisions: Array<{
             id: string;
             title: string;
@@ -662,6 +685,8 @@ export declare class VibescopeApiClient {
     getActivityFeed(projectId: string, params?: {
         limit?: number;
         since?: string;
+        types?: string[];
+        created_by?: string;
     }): Promise<ApiResponse<{
         activities: Array<{
             type: string;
@@ -730,6 +755,7 @@ export declare class VibescopeApiClient {
         success: boolean;
     }>>;
     queryKnowledgeBase(projectId: string, params?: {
+        scope?: 'summary' | 'detailed';
         categories?: string[];
         limit?: number;
         search_query?: string;
@@ -739,22 +765,35 @@ export declare class VibescopeApiClient {
             title: string;
             category: string;
             severity: string;
+            description?: string;
         }>;
         decisions?: Array<{
             id: string;
             title: string;
             description: string;
+            rationale?: string;
         }>;
         completed_tasks?: Array<{
             id: string;
             title: string;
             completed_at: string;
+            summary?: string;
         }>;
         resolved_blockers?: Array<{
             id: string;
             description: string;
             resolution_note?: string;
         }>;
+        progress?: Array<{
+            id: string;
+            summary: string;
+            details?: string;
+        }>;
+        qa?: Array<{
+            id: string;
+            question: string;
+            answer: string;
+        }>;
     }>>;
     syncSession(sessionId: string, params?: {
         total_tokens?: number;
@@ -1036,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;
@@ -1095,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<{
@@ -1106,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;
@@ -1119,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;
@@ -1163,6 +1262,157 @@ export declare class VibescopeApiClient {
         slug: string;
         title: string;
     }>>>;
+    checkoutFile(projectId: string, filePath: string, reason?: string, sessionId?: string): Promise<ApiResponse<{
+        success: boolean;
+        checkout_id: string;
+        file_path: string;
+        already_checked_out?: boolean;
+        message: string;
+    }>>;
+    checkinFile(params: {
+        checkout_id?: string;
+        project_id?: string;
+        file_path?: string;
+        summary?: string;
+    }, sessionId?: string): Promise<ApiResponse<{
+        success: boolean;
+        checkout_id: string;
+        message: string;
+    }>>;
+    getFileCheckouts(projectId: string, options?: {
+        status?: string;
+        file_path?: string;
+        limit?: number;
+    }): Promise<ApiResponse<{
+        checkouts: Array<{
+            id: string;
+            file_path: string;
+            status: string;
+            checked_out_at: string;
+            checkout_reason?: string;
+            checked_in_at?: string;
+            checkin_summary?: string;
+            checked_out_by?: string;
+        }>;
+    }>>;
+    abandonCheckout(params: {
+        checkout_id?: string;
+        project_id?: string;
+        file_path?: string;
+    }): Promise<ApiResponse<{
+        success: boolean;
+        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

@@ -28,7 +28,8 @@ export class VibescopeApiClient {
                 return {
                     ok: false,
                     status: response.status,
-                    error: data.error || `HTTP ${response.status}`
+                    error: data.error || `HTTP ${response.status}`,
+                    data // Include full response data for additional error context
                 };
             }
             return {
@@ -171,8 +172,8 @@ export class VibescopeApiClient {
     // ============================================================================
     // Decision endpoints
     // ============================================================================
-    async getDecisions(projectId) {
-        return this.proxy('get_decisions', { project_id: projectId });
+    async getDecisions(projectId, options) {
+        return this.proxy('get_decisions', { project_id: projectId, ...options });
     }
     async logDecision(projectId, params, sessionId) {
         return this.proxy('log_decision', {
@@ -615,6 +616,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', {});
     }
@@ -694,6 +701,78 @@ export class VibescopeApiClient {
     async getHelpTopics() {
         return this.proxy('get_help_topics', {});
     }
+    // ============================================================================
+    // File Checkout endpoints (multi-agent coordination)
+    // ============================================================================
+    async checkoutFile(projectId, filePath, reason, sessionId) {
+        return this.proxy('checkout_file', {
+            project_id: projectId,
+            file_path: filePath,
+            reason
+        }, sessionId ? {
+            session_id: sessionId,
+            persona: null,
+            instance_id: ''
+        } : undefined);
+    }
+    async checkinFile(params, sessionId) {
+        return this.proxy('checkin_file', params, sessionId ? {
+            session_id: sessionId,
+            persona: null,
+            instance_id: ''
+        } : undefined);
+    }
+    async getFileCheckouts(projectId, options) {
+        return this.proxy('get_file_checkouts', {
+            project_id: projectId,
+            ...options
+        });
+    }
+    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