@vibescope/mcp-server 0.2.1 → 0.2.2

package/dist/token-tracking.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Token Tracking Utilities
+ *
+ * Functions for estimating and tracking token usage across MCP tool calls.
+ * Extracted from index.ts to enable unit testing.
+ */
+export interface ModelTokens {
+    input: number;
+    output: number;
+}
+export interface TokenUsage {
+    callCount: number;
+    totalTokens: number;
+    byTool: Record<string, {
+        calls: number;
+        tokens: number;
+    }>;
+    byModel: Record<string, ModelTokens>;
+    currentModel: string | null;
+}
+/**
+ * Estimate tokens from a JSON-serializable object.
+ * Uses a rough heuristic of ~4 characters per token.
+ *
+ * @param obj - Any JSON-serializable object
+ * @returns Estimated token count (always >= 1)
+ */
+export declare function estimateTokens(obj: unknown): number;
+/**
+ * Create a fresh token usage tracker.
+ */
+export declare function createTokenUsage(): TokenUsage;
+/**
+ * Track token usage for a tool call.
+ * Updates the usage object in-place with input/output token estimates.
+ *
+ * @param usage - The token usage object to update
+ * @param toolName - Name of the tool being called
+ * @param args - Input arguments to the tool
+ * @param response - Response from the tool
+ */
+export declare function trackTokenUsage(usage: TokenUsage, toolName: string, args: unknown, response: unknown): void;
+/**
+ * Set the current model for token tracking.
+ * Subsequent calls to trackTokenUsage will be attributed to this model.
+ *
+ * @param usage - The token usage object to update
+ * @param model - Model name (e.g., "opus", "sonnet", "haiku")
+ */
+export declare function setCurrentModel(usage: TokenUsage, model: string | null): void;
+/**
+ * Reset token usage tracking to initial state.
+ *
+ * @param usage - The token usage object to reset
+ */
+export declare function resetTokenUsage(usage: TokenUsage): void;
+/**
+ * Get a summary of token usage for reporting.
+ *
+ * @param usage - The token usage object
+ * @returns Summary object with stats
+ */
+export declare function getTokenUsageSummary(usage: TokenUsage): {
+    total_calls: number;
+    total_tokens: number;
+    average_tokens_per_call: number;
+    by_tool: Record<string, {
+        calls: number;
+        tokens: number;
+        avg: number;
+    }>;
+    by_model: Record<string, ModelTokens>;
+    current_model: string | null;
+};

package/dist/token-tracking.js

@@ -0,0 +1,122 @@
+/**
+ * Token Tracking Utilities
+ *
+ * Functions for estimating and tracking token usage across MCP tool calls.
+ * Extracted from index.ts to enable unit testing.
+ */
+// ============================================================================
+// Token Estimation
+// ============================================================================
+/**
+ * Estimate tokens from a JSON-serializable object.
+ * Uses a rough heuristic of ~4 characters per token.
+ *
+ * @param obj - Any JSON-serializable object
+ * @returns Estimated token count (always >= 1)
+ */
+export function estimateTokens(obj) {
+    try {
+        const json = JSON.stringify(obj);
+        return Math.max(1, Math.ceil(json.length / 4));
+    }
+    catch {
+        // If JSON serialization fails, return a minimal estimate
+        return 1;
+    }
+}
+// ============================================================================
+// Token Usage Tracking
+// ============================================================================
+/**
+ * Create a fresh token usage tracker.
+ */
+export function createTokenUsage() {
+    return {
+        callCount: 0,
+        totalTokens: 0,
+        byTool: {},
+        byModel: {},
+        currentModel: null,
+    };
+}
+/**
+ * Track token usage for a tool call.
+ * Updates the usage object in-place with input/output token estimates.
+ *
+ * @param usage - The token usage object to update
+ * @param toolName - Name of the tool being called
+ * @param args - Input arguments to the tool
+ * @param response - Response from the tool
+ */
+export function trackTokenUsage(usage, toolName, args, response) {
+    const inputTokens = estimateTokens(args);
+    const outputTokens = estimateTokens(response);
+    const totalTokens = inputTokens + outputTokens;
+    usage.callCount++;
+    usage.totalTokens += totalTokens;
+    if (!usage.byTool[toolName]) {
+        usage.byTool[toolName] = { calls: 0, tokens: 0 };
+    }
+    usage.byTool[toolName].calls++;
+    usage.byTool[toolName].tokens += totalTokens;
+    // Track by model if a model is set
+    const model = usage.currentModel;
+    if (model) {
+        if (!usage.byModel[model]) {
+            usage.byModel[model] = { input: 0, output: 0 };
+        }
+        usage.byModel[model].input += inputTokens;
+        usage.byModel[model].output += outputTokens;
+    }
+}
+/**
+ * Set the current model for token tracking.
+ * Subsequent calls to trackTokenUsage will be attributed to this model.
+ *
+ * @param usage - The token usage object to update
+ * @param model - Model name (e.g., "opus", "sonnet", "haiku")
+ */
+export function setCurrentModel(usage, model) {
+    usage.currentModel = model;
+}
+/**
+ * Reset token usage tracking to initial state.
+ *
+ * @param usage - The token usage object to reset
+ */
+export function resetTokenUsage(usage) {
+    usage.callCount = 0;
+    usage.totalTokens = 0;
+    usage.byTool = {};
+    usage.byModel = {};
+    usage.currentModel = null;
+}
+/**
+ * Get a summary of token usage for reporting.
+ *
+ * @param usage - The token usage object
+ * @returns Summary object with stats
+ */
+export function getTokenUsageSummary(usage) {
+    const byTool = {};
+    for (const [tool, stats] of Object.entries(usage.byTool)) {
+        byTool[tool] = {
+            calls: stats.calls,
+            tokens: stats.tokens,
+            avg: stats.calls > 0 ? Math.round(stats.tokens / stats.calls) : 0,
+        };
+    }
+    // Deep copy byModel to prevent mutation
+    const byModel = {};
+    for (const [model, tokens] of Object.entries(usage.byModel)) {
+        byModel[model] = { input: tokens.input, output: tokens.output };
+    }
+    return {
+        total_calls: usage.callCount,
+        total_tokens: usage.totalTokens,
+        average_tokens_per_call: usage.callCount > 0 ? Math.round(usage.totalTokens / usage.callCount) : 0,
+        by_tool: byTool,
+        by_model: byModel,
+        current_model: usage.currentModel,
+    };
+}

package/dist/tools.js

@@ -5,7 +5,9 @@ export const tools = [
     {
         name: 'start_work_session',
         description: `CALL THIS FIRST when beginning work on a project.
-Returns session info, persona, role, and next task. Use mode:'full' for complete context.`,
+Returns session info, persona, role, and next_task. Start the next_task IMMEDIATELY without asking the user.
+
+Use mode:'full' for complete context, mode:'lite' (default) for minimal tokens.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -187,6 +189,40 @@ Returns session info, persona, role, and next task. Use mode:'full' for complete
             required: ['project_id'],
         },
     },
+    {
+        name: 'get_body_of_work_costs',
+        description: 'Get cost breakdown by body of work with phase-level details. Returns costs for pre/core/post phases and model breakdown.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                body_of_work_id: {
+                    type: 'string',
+                    description: 'Body of work UUID (optional if project_id provided)',
+                },
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID to get all body of work costs (optional if body_of_work_id provided)',
+                },
+            },
+        },
+    },
+    {
+        name: 'get_sprint_costs',
+        description: 'Get cost breakdown by sprint with velocity metrics. Returns cost per story point and phase breakdown.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sprint_id: {
+                    type: 'string',
+                    description: 'Sprint UUID (optional if project_id provided)',
+                },
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID to get all sprint costs (optional if sprint_id provided)',
+                },
+            },
+        },
+    },
     // Knowledge Base Query Tool
     {
         name: 'query_knowledge_base',
@@ -231,7 +267,7 @@ Returns session info, persona, role, and next task. Use mode:'full' for complete
             properties: {
                 category: {
                     type: 'string',
-                    enum: ['session', 'project', 'tasks', 'milestones', 'progress', 'blockers', 'decisions', 'ideas', 'findings', 'validation', 'deployment', 'fallback', 'requests', 'organizations', 'cost', 'knowledge'],
+                    enum: ['session', 'project', 'tasks', 'milestones', 'progress', 'blockers', 'decisions', 'ideas', 'findings', 'validation', 'deployment', 'fallback', 'bodies_of_work', 'sprints', 'requests', 'organizations', 'cost', 'git_issues', 'knowledge', 'discovery', 'subtasks', 'worktrees', 'roles', 'file_locks'],
                     description: 'Category to list (omit for all categories)',
                 },
             },
@@ -427,7 +463,9 @@ Returns session info, persona, role, and next task. Use mode:'full' for complete
     },
     {
         name: 'get_next_task',
-        description: 'Get highest priority pending task. Skips claimed tasks. Check deployment_blocks_tasks first.',
+        description: `Get highest priority pending task. Start it IMMEDIATELY by calling update_task(task_id, status: "in_progress").
+
+Do NOT ask the user for permission. Follow the directive in the response.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -483,7 +521,13 @@ Returns session info, persona, role, and next task. Use mode:'full' for complete
     },
     {
         name: 'update_task',
-        description: 'Update task status, progress, or details. Include progress_note with progress_percentage.',
+        description: `Update task status, progress, or details. Include progress_note with progress_percentage.
+
+IMPORTANT: When setting status to "in_progress", you MUST provide git_branch AND worktree_path to enable cleanup tracking.
+Create worktree first: git worktree add ../PROJECT-task-TASKID -b feature/TASKID-description BASE_BRANCH
+Then call: update_task(task_id, status: "in_progress", git_branch: "feature/TASKID-description", worktree_path: "../PROJECT-task-TASKID")
+
+For projects without git branching (trunk-based or none), use skip_worktree_requirement: true.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -519,20 +563,35 @@ Returns session info, persona, role, and next task. Use mode:'full' for complete
                 },
                 git_branch: {
                     type: 'string',
-                    description: 'Git branch associated with this task',
+                    description: 'Git branch associated with this task. REQUIRED when status is "in_progress" (unless skip_worktree_requirement is true)',
+                },
+                worktree_path: {
+                    type: 'string',
+                    description: 'Git worktree path for this task (e.g., "../project-task-abc123"). Store this for cleanup tracking across sessions.',
                 },
                 model_capability: {
                     type: 'string',
                     enum: ['haiku', 'sonnet', 'opus'],
                     description: 'Recommended model capability: haiku (simple tasks), sonnet (standard), opus (complex reasoning)',
                 },
+                skip_worktree_requirement: {
+                    type: 'boolean',
+                    description: 'Skip git_branch requirement for projects without branching workflows (trunk-based or none). Default: false',
+                },
             },
             required: ['task_id'],
         },
     },
     {
         name: 'complete_task',
-        description: 'Mark task done. Returns next_task and context counts (validation, blockers, deployment).',
+        description: `Mark task done. Returns next_task which you MUST start immediately without asking the user.
+
+CRITICAL: After calling this tool, you must:
+1. If next_task is returned → Start it immediately by calling update_task(task_id, status: "in_progress")
+2. If no next_task → Call get_next_task() or start a fallback_activity
+3. NEVER ask the user "What should I do next?" or "Should I continue?"
+
+The auto_continue: true flag in the response means you are expected to continue working autonomously.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -1104,6 +1163,46 @@ Returns subtasks with aggregate completion stats.`,
             required: ['parent_task_id'],
         },
     },
+    {
+        name: 'get_stale_worktrees',
+        description: `Get worktrees that need cleanup.
+
+Returns tasks with worktree_path set where:
+- Task is completed or cancelled (worktree should have been cleaned up)
+- Task has been abandoned (no activity for 24+ hours while in_progress)
+
+IMPORTANT: Call this on session start to clean up orphaned worktrees from previous sessions.
+For each stale worktree:
+1. Run: git worktree remove <worktree_path>
+2. Call: clear_worktree_path(task_id)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'clear_worktree_path',
+        description: `Clear the worktree_path from a task after cleanup.
+
+Call this AFTER removing the worktree with git worktree remove.
+This marks the task as cleaned up so it won't appear in get_stale_worktrees.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Task UUID',
+                },
+            },
+            required: ['task_id'],
+        },
+    },
     {
         name: 'heartbeat',
         description: `Send heartbeat to maintain 'active' status. Call every 30-60 seconds.`,
@@ -1432,8 +1531,14 @@ Returns subtasks with aggregate completion stats.`,
                 },
                 schedule_type: {
                     type: 'string',
-                    description: 'Schedule type: once (one-time), daily, weekly, or monthly',
-                    enum: ['once', 'daily', 'weekly', 'monthly'],
+                    description: 'Schedule type: once (one-time), hourly, daily, weekly, or monthly',
+                    enum: ['once', 'hourly', 'daily', 'weekly', 'monthly'],
+                },
+                hours_interval: {
+                    type: 'number',
+                    description: 'For hourly schedules, the number of hours between runs (1-24, default: 1)',
+                    minimum: 1,
+                    maximum: 24,
                 },
                 auto_trigger: {
                     type: 'boolean',
@@ -1496,7 +1601,13 @@ Returns subtasks with aggregate completion stats.`,
                 schedule_type: {
                     type: 'string',
                     description: 'New schedule type',
-                    enum: ['once', 'daily', 'weekly', 'monthly'],
+                    enum: ['once', 'hourly', 'daily', 'weekly', 'monthly'],
+                },
+                hours_interval: {
+                    type: 'number',
+                    description: 'For hourly schedules, the number of hours between runs (1-24)',
+                    minimum: 1,
+                    maximum: 24,
                 },
                 auto_trigger: {
                     type: 'boolean',
@@ -1594,6 +1705,7 @@ Returns subtasks with aggregate completion stats.`,
                         'documentation_review',
                         'dependency_audit',
                         'validate_completed_tasks',
+                        'worktree_cleanup',
                     ],
                 },
             },
@@ -2912,4 +3024,181 @@ Returns committed vs completed points and average velocity.`,
             required: ['git_issue_id'],
         },
     },
+    // ============================================================================
+    // Connector Tools (External Integrations)
+    // ============================================================================
+    {
+        name: 'get_connectors',
+        description: `List connectors for a project. Connectors enable sending events to external services (Slack, Discord, webhooks, etc.).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['webhook', 'slack', 'discord', 'github', 'custom'],
+                    description: 'Filter by connector type (optional)',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['active', 'disabled'],
+                    description: 'Filter by status (optional)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max connectors to return (default: 50)',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Pagination offset (default: 0)',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'get_connector',
+        description: `Get a single connector with full details including configuration (sensitive fields are masked).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                connector_id: {
+                    type: 'string',
+                    description: 'Connector UUID',
+                },
+            },
+            required: ['connector_id'],
+        },
+    },
+    {
+        name: 'add_connector',
+        description: `Add a new connector for external integrations. Supports webhook, Slack, Discord, GitHub, and custom connectors.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Connector name (e.g., "Slack Notifications")',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['webhook', 'slack', 'discord', 'github', 'custom'],
+                    description: 'Connector type',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Optional description',
+                },
+                config: {
+                    type: 'object',
+                    description: 'Type-specific configuration (e.g., { webhook_url: "..." } for Slack)',
+                },
+                events: {
+                    type: 'object',
+                    description: 'Event subscriptions (e.g., { task_completed: true, blocker_added: true })',
+                },
+            },
+            required: ['project_id', 'name', 'type'],
+        },
+    },
+    {
+        name: 'update_connector',
+        description: `Update a connector's configuration, events, or status.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                connector_id: {
+                    type: 'string',
+                    description: 'Connector UUID',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Updated name',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Updated description',
+                },
+                config: {
+                    type: 'object',
+                    description: 'Updated configuration (merged with existing)',
+                },
+                events: {
+                    type: 'object',
+                    description: 'Updated event subscriptions',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['active', 'disabled'],
+                    description: 'Enable or disable the connector',
+                },
+            },
+            required: ['connector_id'],
+        },
+    },
+    {
+        name: 'delete_connector',
+        description: `Delete a connector.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                connector_id: {
+                    type: 'string',
+                    description: 'Connector UUID',
+                },
+            },
+            required: ['connector_id'],
+        },
+    },
+    {
+        name: 'test_connector',
+        description: `Test a connector by sending a test event. Returns success/failure status.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                connector_id: {
+                    type: 'string',
+                    description: 'Connector UUID to test',
+                },
+            },
+            required: ['connector_id'],
+        },
+    },
+    {
+        name: 'get_connector_events',
+        description: `Get event history for a connector or project. Shows delivery status and errors.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                connector_id: {
+                    type: 'string',
+                    description: 'Connector UUID (optional if project_id provided)',
+                },
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID (optional if connector_id provided)',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['pending', 'sent', 'failed', 'retrying'],
+                    description: 'Filter by delivery status (optional)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max events to return (default: 50)',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Pagination offset (default: 0)',
+                },
+            },
+        },
+    },
 ];

package/dist/utils.d.ts

@@ -55,6 +55,11 @@ export declare const FALLBACK_ACTIVITIES: readonly [{
     readonly title: "Validate completed tasks";
     readonly description: "Review tasks completed by other agents to ensure quality.";
     readonly prompt: "Call get_tasks_awaiting_validation to find completed tasks that need review. Validate each one by checking the implementation and running tests if applicable.";
+}, {
+    readonly activity: "worktree_cleanup";
+    readonly title: "Clean up stale worktrees";
+    readonly description: "Find and remove git worktrees from completed or abandoned tasks.";
+    readonly prompt: "Clean up stale git worktrees to reclaim disk space and prevent confusion:\n\n1. Call get_stale_worktrees(project_id) to find worktrees needing cleanup\n2. For each stale worktree returned:\n   a. Check if the worktree directory exists: ls -la <worktree_path>\n   b. If it exists, remove it: git worktree remove <worktree_path>\n   c. If removal fails (untracked files), use: git worktree remove --force <worktree_path>\n   d. Call clear_worktree_path(task_id) to mark it as cleaned up\n3. Run 'git worktree list' to verify cleanup\n4. Log any issues encountered with add_blocker if worktrees cannot be removed\n\nThis prevents disk bloat from accumulated worktrees and keeps the workspace clean.";
 }];
 export type FallbackActivity = typeof FALLBACK_ACTIVITIES[number];
 /**

package/dist/utils.js

@@ -125,6 +125,23 @@ export const FALLBACK_ACTIVITIES = [
         description: 'Review tasks completed by other agents to ensure quality.',
         prompt: 'Call get_tasks_awaiting_validation to find completed tasks that need review. Validate each one by checking the implementation and running tests if applicable.',
     },
+    {
+        activity: 'worktree_cleanup',
+        title: 'Clean up stale worktrees',
+        description: 'Find and remove git worktrees from completed or abandoned tasks.',
+        prompt: `Clean up stale git worktrees to reclaim disk space and prevent confusion:
+
+1. Call get_stale_worktrees(project_id) to find worktrees needing cleanup
+2. For each stale worktree returned:
+   a. Check if the worktree directory exists: ls -la <worktree_path>
+   b. If it exists, remove it: git worktree remove <worktree_path>
+   c. If removal fails (untracked files), use: git worktree remove --force <worktree_path>
+   d. Call clear_worktree_path(task_id) to mark it as cleaned up
+3. Run 'git worktree list' to verify cleanup
+4. Log any issues encountered with add_blocker if worktrees cannot be removed
+
+This prevents disk bloat from accumulated worktrees and keeps the workspace clean.`,
+    },
 ];
 /**
  * Get a random fallback activity