@vibescope/mcp-server 0.3.0 → 0.3.3

package/dist/handlers/cloud-agents.js

@@ -0,0 +1,91 @@
+/**
+ * Cloud Agents Handlers
+ *
+ * Handles cloud agent management:
+ * - cleanup_stale_cloud_agents
+ * - list_cloud_agents
+ */
+import { success, error } from './types.js';
+import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
+import { getApiClient } from '../api-client.js';
+// Argument schemas
+const cleanupStaleAgentsSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    stale_minutes: { type: 'number', default: 5 },
+    include_running: { type: 'boolean', default: false },
+    dry_run: { type: 'boolean', default: false },
+};
+const listCloudAgentsSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    status: {
+        type: 'string',
+        default: 'all',
+        validate: createEnumValidator(['starting', 'running', 'stopped', 'failed', 'all'])
+    },
+};
+/**
+ * Clean up stale cloud agents that failed to start or lost connection.
+ * Only operates on agents in the specified project (security scoped).
+ */
+export const cleanupStaleCloudAgents = async (args, ctx) => {
+    const { project_id, stale_minutes, include_running, dry_run } = parseArgs(args, cleanupStaleAgentsSchema);
+    // Ensure user has an active session with this project (security check)
+    if (ctx.session.currentProjectId && ctx.session.currentProjectId !== project_id) {
+        return error('Cannot cleanup agents for a different project than your current session');
+    }
+    const apiClient = getApiClient();
+    // Call the cleanup endpoint via fetch (since it's a new endpoint not in the client)
+    const response = await apiClient.proxy('cleanup_stale_cloud_agents', {
+        project_id,
+        staleMinutes: stale_minutes,
+        includeRunning: include_running,
+        dryRun: dry_run,
+    });
+    if (!response.ok) {
+        return error(response.error || 'Failed to cleanup stale agents');
+    }
+    const data = response.data;
+    if (dry_run) {
+        return success({
+            dryRun: true,
+            wouldClean: data.wouldClean || 0,
+            agents: data.agents,
+            message: `Found ${data.wouldClean || 0} stale agents that would be cleaned up`
+        });
+    }
+    return success({
+        cleaned: data.cleaned,
+        failed: data.failed || 0,
+        agents: data.agents,
+        message: `Cleaned up ${data.cleaned} stale agents`
+    });
+};
+/**
+ * List cloud agents for a project with optional status filter.
+ */
+export const listCloudAgents = async (args, ctx) => {
+    const { project_id, status } = parseArgs(args, listCloudAgentsSchema);
+    // Ensure user has an active session with this project (security check)
+    if (ctx.session.currentProjectId && ctx.session.currentProjectId !== project_id) {
+        return error('Cannot list agents for a different project than your current session');
+    }
+    const apiClient = getApiClient();
+    const response = await apiClient.proxy('list_cloud_agents', {
+        project_id,
+        status: status === 'all' ? undefined : status,
+    });
+    if (!response.ok) {
+        return error(response.error || 'Failed to list cloud agents');
+    }
+    return success({
+        agents: response.data.agents,
+        count: response.data.agents.length
+    });
+};
+/**
+ * Cloud agents handlers registry
+ */
+export const cloudAgentHandlers = {
+    cleanup_stale_cloud_agents: cleanupStaleCloudAgents,
+    list_cloud_agents: listCloudAgents,
+};

package/dist/handlers/discovery.js

@@ -316,6 +316,13 @@ export const TOOL_CATEGORIES = {
             { name: 'get_connector_events', brief: 'Event history' },
         ],
     },
+    cloud_agents: {
+        description: 'Cloud agent management and cleanup',
+        tools: [
+            { name: 'cleanup_stale_cloud_agents', brief: 'Clean up stale cloud agents' },
+            { name: 'list_cloud_agents', brief: 'List cloud agents for project' },
+        ],
+    },
 };
 export const discoverTools = async (args) => {
     const { category } = parseArgs(args, discoverToolsSchema);

package/dist/handlers/index.d.ts

@@ -27,6 +27,7 @@ export * from './sprints.js';
 export * from './file-checkouts.js';
 export * from './roles.js';
 export * from './connectors.js';
+export * from './cloud-agents.js';
 import type { HandlerRegistry } from './types.js';
 /**
  * Build the complete handler registry from all modules

package/dist/handlers/index.js

@@ -27,6 +27,7 @@ export * from './sprints.js';
 export * from './file-checkouts.js';
 export * from './roles.js';
 export * from './connectors.js';
+export * from './cloud-agents.js';
 import { milestoneHandlers } from './milestones.js';
 import { sessionHandlers } from './session.js';
 import { ideaHandlers } from './ideas.js';
@@ -49,6 +50,7 @@ import { sprintHandlers } from './sprints.js';
 import { fileCheckoutHandlers } from './file-checkouts.js';
 import { roleHandlers } from './roles.js';
 import { connectorHandlers } from './connectors.js';
+import { cloudAgentHandlers } from './cloud-agents.js';
 /**
  * Build the complete handler registry from all modules
  */
@@ -76,5 +78,6 @@ export function buildHandlerRegistry() {
         ...fileCheckoutHandlers,
         ...roleHandlers,
         ...connectorHandlers,
+        ...cloudAgentHandlers,
     };
 }

package/dist/handlers/session.js

@@ -26,6 +26,7 @@ const startWorkSessionSchema = {
     role: { type: 'string', default: 'developer' }, // Open-ended - any role name accepted
     hostname: { type: 'string' }, // Machine hostname for worktree tracking
     agent_type: { type: 'string' }, // Open-ended - any agent type accepted
+    agent_name: { type: 'string' }, // Explicit agent name for cloud/remote agents (skips persona pool)
 };
 const heartbeatSchema = {
     session_id: { type: 'string' },
@@ -39,7 +40,7 @@ const getHelpSchema = {
     topic: { type: 'string', required: true },
 };
 export const startWorkSession = async (args, ctx) => {
-    const { project_id, git_url, mode, model, role, hostname: providedHostname, agent_type } = parseArgs(args, startWorkSessionSchema);
+    const { project_id, git_url, mode, model, role, hostname: providedHostname, agent_type, agent_name } = parseArgs(args, startWorkSessionSchema);
     // Use auto-detected hostname if not provided - enables machine-aware worktree filtering
     const hostname = providedHostname || MACHINE_HOSTNAME;
     // Normalize git_url and track if it was changed - helps agents understand URL matching
@@ -78,6 +79,7 @@ export const startWorkSession = async (args, ctx) => {
         role: role,
         hostname, // Machine hostname for worktree tracking
         agent_type: agent_type, // Agent type for onboarding
+        agent_name: agent_name, // Explicit name for cloud/remote agents
     });
     if (!response.ok) {
         // Include additional error details if available

package/dist/handlers/tasks.js

@@ -24,6 +24,7 @@
 import os from 'os';
 import { parseArgs, uuidValidator, taskStatusValidator, priorityValidator, progressValidator, minutesValidator, createEnumValidator, ValidationError, } from '../validators.js';
 import { getApiClient } from '../api-client.js';
+import { capPagination, PAGINATION_LIMITS } from '../utils.js';
 // Auto-detect machine hostname for worktree tracking
 const MACHINE_HOSTNAME = os.hostname();
 // Valid task types
@@ -715,9 +716,8 @@ export const searchTasks = async (args, ctx) => {
             },
         };
     }
-    // Cap limit at 20, safe offset
-    const cappedLimit = Math.min(limit ?? 10, 20);
-    const safeOffset = Math.max(0, offset ?? 0);
+    // Cap pagination to safe values
+    const { cappedLimit, safeOffset } = capPagination(limit ?? 10, offset, PAGINATION_LIMITS.TASK_LIMIT);
     const api = getApiClient();
     const response = await api.searchTasks(project_id, {
         query,
@@ -745,9 +745,8 @@ export const searchTasks = async (args, ctx) => {
  */
 export const getTasksByPriority = async (args, ctx) => {
     const { project_id, priority, priority_max, status, limit, offset } = parseArgs(args, getTasksByPrioritySchema);
-    // Cap limit at 20, safe offset
-    const cappedLimit = Math.min(limit ?? 10, 20);
-    const safeOffset = Math.max(0, offset ?? 0);
+    // Cap pagination to safe values
+    const { cappedLimit, safeOffset } = capPagination(limit ?? 10, offset, PAGINATION_LIMITS.TASK_LIMIT);
     const api = getApiClient();
     const response = await api.getTasksByPriority(project_id, {
         priority,
@@ -776,9 +775,8 @@ export const getTasksByPriority = async (args, ctx) => {
  */
 export const getRecentTasks = async (args, ctx) => {
     const { project_id, order, status, limit, offset } = parseArgs(args, getRecentTasksSchema);
-    // Cap limit at 20, safe offset
-    const cappedLimit = Math.min(limit ?? 10, 20);
-    const safeOffset = Math.max(0, offset ?? 0);
+    // Cap pagination to safe values
+    const { cappedLimit, safeOffset } = capPagination(limit ?? 10, offset, PAGINATION_LIMITS.TASK_LIMIT);
     const api = getApiClient();
     const response = await api.getRecentTasks(project_id, {
         order: order,
@@ -843,10 +841,10 @@ export const getStaleWorktrees = async (args, ctx) => {
     const { project_id, hostname: providedHostname, limit, offset } = parseArgs(args, getStaleWorktreesSchema);
     // Use auto-detected hostname if not provided - filters to only worktrees on THIS machine
     const hostname = providedHostname || MACHINE_HOSTNAME;
-    // Cap limit to prevent context bloating
-    const cappedLimit = Math.min(limit ?? 20, 50);
+    // Cap pagination to safe values
+    const { cappedLimit, safeOffset } = capPagination(limit, offset, PAGINATION_LIMITS.DEFAULT_MAX_LIMIT);
     const api = getApiClient();
-    const response = await api.getStaleWorktrees(project_id, { hostname, limit: cappedLimit, offset });
+    const response = await api.getStaleWorktrees(project_id, { hostname, limit: cappedLimit, offset: safeOffset });
     if (!response.ok) {
         return { result: { error: response.error || 'Failed to get stale worktrees' }, isError: true };
     }

package/dist/handlers/types.d.ts

@@ -44,6 +44,7 @@ export interface SessionState {
     currentSessionId: string | null;
     currentPersona: string | null;
     currentRole: AgentRole | null;
+    currentProjectId: string | null;
     tokenUsage: TokenUsage;
 }
 /**
@@ -73,7 +74,7 @@ export interface HandlerContext {
     auth: AuthContext;
     session: SessionState;
     /** Update session state (for handlers that modify session) */
-    updateSession: (updates: Partial<Pick<SessionState, 'currentSessionId' | 'currentPersona' | 'currentRole' | 'tokenUsage'>>) => void;
+    updateSession: (updates: Partial<Pick<SessionState, 'currentSessionId' | 'currentPersona' | 'currentRole' | 'currentProjectId' | 'tokenUsage'>>) => void;
     /** Get user updates since last sync (for session handlers) */
     getUserUpdates?: (projectId: string) => Promise<UserUpdates | undefined>;
     /** Select an available persona for the agent */

package/dist/handlers/validation.js

@@ -21,6 +21,7 @@ const validateTaskSchema = {
     approved: { type: 'boolean', required: true },
     validation_notes: { type: 'string' },
     skip_pr_check: { type: 'boolean' },
+    // Note: pr_checks_passing may arrive as string from some MCP clients, handled in validateTask
     pr_checks_passing: { type: 'boolean' },
 };
 export const getTasksAwaitingValidation = async (args, _ctx) => {
@@ -79,12 +80,15 @@ export const validateTask = async (args, ctx) => {
     const { task_id, approved, validation_notes, skip_pr_check, pr_checks_passing } = parseArgs(args, validateTaskSchema);
     const { session } = ctx;
     const currentSessionId = session.currentSessionId;
+    // Ensure pr_checks_passing is a proper boolean (MCP may send as string)
+    // Cast to unknown first to satisfy TypeScript
+    const checksPassingBool = pr_checks_passing === true || pr_checks_passing === 'true';
     const apiClient = getApiClient();
     const response = await apiClient.validateTask(task_id, {
         approved,
         validation_notes,
         skip_pr_check,
-        pr_checks_passing,
+        pr_checks_passing: pr_checks_passing !== undefined ? checksPassingBool : undefined,
     }, currentSessionId || undefined);
     if (!response.ok) {
         // Handle PR required error specially

package/dist/index.js

@@ -5,9 +5,9 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { randomUUID } from 'crypto';
 import { initApiClient, getApiClient } from './api-client.js';
 import { ValidationError, } from './validators.js';
-import { RateLimiter, } from './utils.js';
+import { RateLimiter, getErrorMessage, } from './utils.js';
 import { buildHandlerRegistry } from './handlers/index.js';
-import { tools } from './tools.js';
+import { tools } from './tools/index.js';
 import { createTokenUsage, trackTokenUsage as trackTokens, } from './token-tracking.js';
 // ============================================================================
 // Agent Instance Tracking
@@ -20,6 +20,8 @@ let currentSessionId = null;
 let currentPersona = null;
 // Current role for this agent instance
 let currentRole = null;
+// Current project ID for this agent instance
+let currentProjectId = null;
 // Token usage tracking for this session (using token-tracking module)
 let sessionTokenUsage = createTokenUsage();
 // Wrapper function to track token usage with the session's usage object
@@ -177,6 +179,7 @@ async function handleTool(auth, name, args) {
                 currentSessionId,
                 currentPersona,
                 currentRole,
+                currentProjectId,
                 tokenUsage: sessionTokenUsage,
             },
             updateSession: (updates) => {
@@ -186,6 +189,8 @@ async function handleTool(auth, name, args) {
                     currentPersona = updates.currentPersona;
                 if (updates.currentRole !== undefined)
                     currentRole = updates.currentRole;
+                if (updates.currentProjectId !== undefined)
+                    currentProjectId = updates.currentProjectId;
                 if (updates.tokenUsage !== undefined)
                     sessionTokenUsage = updates.tokenUsage;
             },
@@ -293,7 +298,7 @@ async function main() {
                 };
             }
             // Handle database errors with better context
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            const errorMessage = getErrorMessage(error);
             let hint;
             if (errorMessage.includes('violates foreign key constraint')) {
                 hint = 'The referenced ID does not exist. Check that the project_id, task_id, or other IDs are correct.';

package/dist/token-tracking.js

@@ -4,6 +4,7 @@
  * Functions for estimating and tracking token usage across MCP tool calls.
  * Extracted from index.ts to enable unit testing.
  */
+import { getErrorMessage } from './utils.js';
 // ============================================================================
 // Token Estimation
 // ============================================================================
@@ -21,8 +22,7 @@ export function estimateTokens(obj) {
     }
     catch (error) {
         // Log warning when serialization fails (e.g., circular references, BigInt)
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        console.warn(`[Vibescope] Token estimation failed: ${errorMessage}. Returning minimal estimate of 1 token.`);
+        console.warn(`[Vibescope] Token estimation failed: ${getErrorMessage(error)}. Returning minimal estimate of 1 token.`);
         return 1;
     }
 }

package/dist/tools/blockers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Blocker Tool Definitions
+ *
+ * Tools for managing blockers:
+ * - add_blocker
+ * - resolve_blocker
+ * - get_blocker
+ * - get_blockers
+ * - get_blockers_stats
+ * - delete_blocker
+ */
+import type { Tool } from './types.js';
+export declare const blockerTools: Tool[];

package/dist/tools/blockers.js

@@ -0,0 +1,119 @@
+/**
+ * Blocker Tool Definitions
+ *
+ * Tools for managing blockers:
+ * - add_blocker
+ * - resolve_blocker
+ * - get_blocker
+ * - get_blockers
+ * - get_blockers_stats
+ * - delete_blocker
+ */
+export const blockerTools = [
+    {
+        name: 'add_blocker',
+        description: `Record a blocker preventing progress.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                description: {
+                    type: 'string',
+                    description: 'What is blocking progress?',
+                },
+            },
+            required: ['project_id', 'description'],
+        },
+    },
+    {
+        name: 'resolve_blocker',
+        description: `Mark a blocker as resolved.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                blocker_id: {
+                    type: 'string',
+                    description: 'Blocker UUID',
+                },
+                resolution_note: {
+                    type: 'string',
+                    description: 'How was it resolved?',
+                },
+            },
+            required: ['blocker_id'],
+        },
+    },
+    {
+        name: 'get_blocker',
+        description: `Get a single blocker by ID. More token-efficient than get_blockers when you need details for a specific blocker.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                blocker_id: {
+                    type: 'string',
+                    description: 'Blocker UUID',
+                },
+            },
+            required: ['blocker_id'],
+        },
+    },
+    {
+        name: 'get_blockers',
+        description: `Get blockers for a project, optionally filtered by status.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['open', 'resolved'],
+                    description: 'Filter by status (default: open)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max number of blockers to return (default 10, max 200)',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Number of blockers to skip for pagination (default 0)',
+                },
+                search_query: {
+                    type: 'string',
+                    description: 'Search blockers by description',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'get_blockers_stats',
+        description: `Get aggregate statistics about blockers for a project. Returns total count and breakdown by status. Much more token-efficient than get_blockers when you just need to understand the overall state.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'string', description: 'Project UUID' },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'delete_blocker',
+        description: `Delete a blocker.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                blocker_id: {
+                    type: 'string',
+                    description: 'Blocker UUID',
+                },
+            },
+            required: ['blocker_id'],
+        },
+    },
+];

package/dist/tools/bodies-of-work.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Bodies of Work Tool Definitions
+ *
+ * Tools for managing grouped task collections:
+ * - create_body_of_work
+ * - update_body_of_work
+ * - get_body_of_work
+ * - get_bodies_of_work
+ * - delete_body_of_work
+ * - add_task_to_body_of_work
+ * - remove_task_from_body_of_work
+ * - activate_body_of_work
+ * - add_task_dependency
+ * - remove_task_dependency
+ * - get_task_dependencies
+ * - get_next_body_of_work_task
+ */
+import type { Tool } from './types.js';
+export declare const bodiesOfWorkTools: Tool[];