@vibescope/mcp-server 0.3.1 → 0.3.4

package/src/handlers/session.ts

@@ -37,6 +37,7 @@ const startWorkSessionSchema = {
 	role: { type: 'string' as const, default: 'developer' }, // Open-ended - any role name accepted
 	hostname: { type: 'string' as const }, // Machine hostname for worktree tracking
 	agent_type: { type: 'string' as const }, // Open-ended - any agent type accepted
+	agent_name: { type: 'string' as const }, // Explicit agent name for cloud/remote agents (skips persona pool)
 };
 
 const heartbeatSchema = {
@@ -54,7 +55,7 @@ const getHelpSchema = {
 };
 
 export const startWorkSession: Handler = 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;
@@ -100,6 +101,7 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		role: role as SessionRole,
 		hostname, // Machine hostname for worktree tracking
 		agent_type: agent_type as AgentType | undefined, // Agent type for onboarding
+		agent_name: agent_name as string | undefined, // Explicit name for cloud/remote agents
 	});
 
 	if (!response.ok) {

package/src/handlers/tasks.ts

@@ -35,6 +35,7 @@ import {
 	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();
@@ -889,9 +890,8 @@ export const searchTasks: Handler = 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, {
@@ -925,9 +925,8 @@ export const searchTasks: Handler = async (args, ctx) => {
 export const getTasksByPriority: Handler = 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, {
@@ -962,9 +961,8 @@ export const getTasksByPriority: Handler = async (args, ctx) => {
 export const getRecentTasks: Handler = 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, {
@@ -1043,11 +1041,11 @@ export const getStaleWorktrees: Handler = async (args, ctx) => {
 	// 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/src/handlers/tool-categories.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { tools } from '../tools.js';
+import { tools } from '../tools/index.js';
 import { TOOL_CATEGORIES } from './discovery.js';
 
 describe('Documentation Generator Prerequisites', () => {

package/src/handlers/types.ts

@@ -45,6 +45,7 @@ export interface SessionState {
 	currentSessionId: string | null;
 	currentPersona: string | null;
 	currentRole: AgentRole | null;
+	currentProjectId: string | null;
 	tokenUsage: TokenUsage;
 }
 
@@ -64,7 +65,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/src/handlers/version.ts

@@ -0,0 +1,63 @@
+/**
+ * Version management handlers
+ */
+
+import { execSync } from 'child_process';
+import type { HandlerRegistry } from './types.js';
+import { success, error } from './types.js';
+import { checkVersion, getLocalVersion } from '../version.js';
+
+const PACKAGE_NAME = '@vibescope/mcp-server';
+
+export const versionHandlers: HandlerRegistry = {
+	check_mcp_version: async (_args, _ctx) => {
+		const info = await checkVersion();
+
+		if (info.error) {
+			return success({
+				current_version: info.current,
+				latest_version: info.latest,
+				update_available: false,
+				warning: info.error,
+			});
+		}
+
+		return success({
+			current_version: info.current,
+			latest_version: info.latest,
+			update_available: info.updateAvailable,
+			message: info.updateAvailable
+				? `Update available! v${info.current} → v${info.latest}. Ask the user if they would like to update using the update_mcp_server tool.`
+				: `Vibescope MCP server is up to date (v${info.current}).`,
+		});
+	},
+
+	update_mcp_server: async (args, _ctx) => {
+		const useGlobal = args.global !== false; // default true
+		const flag = useGlobal ? '-g ' : '';
+		const command = `npm install ${flag}${PACKAGE_NAME}@latest`;
+
+		try {
+			const output = execSync(command, {
+				encoding: 'utf-8',
+				timeout: 60000,
+				stdio: ['pipe', 'pipe', 'pipe'],
+			});
+
+			// Check the new version
+			const newVersion = getLocalVersion();
+
+			return success({
+				updated: true,
+				command_run: command,
+				output: output.trim(),
+				new_version: newVersion,
+				message:
+					'Update complete. The MCP server must be restarted to use the new version. Please ask the user to restart their editor/MCP client, or reconnect the MCP server.',
+			});
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			return error(`Failed to update: ${message}. The user may need to run manually: ${command}`);
+		}
+	},
+};

package/src/index.test.ts

@@ -636,12 +636,12 @@ describe('MCP Server Entry Point', () => {
 	// =========================================================================
 	describe('Tools Registration', () => {
 		it('should export tools array', async () => {
-			const { tools } = await import('./tools.js');
+			const { tools } = await import('./tools/index.js');
 			expect(Array.isArray(tools)).toBe(true);
 		});
 
 		it('should have required tool properties', async () => {
-			const { tools } = await import('./tools.js');
+			const { tools } = await import('./tools/index.js');
 			tools.forEach((tool) => {
 				expect(tool).toHaveProperty('name');
 				expect(tool).toHaveProperty('description');

package/src/index.ts

@@ -33,15 +33,17 @@ import {
 	RateLimiter,
 	extractProjectNameFromGitUrl,
 	isValidStatusTransition,
+	getErrorMessage,
 } from './utils.js';
 import { buildHandlerRegistry, type HandlerContext } from './handlers/index.js';
-import { tools } from './tools.js';
+import { tools } from './tools/index.js';
 import {
 	createTokenUsage,
 	trackTokenUsage as trackTokens,
 	setCurrentModel,
 	type TokenUsage,
 } from './token-tracking.js';
+import { getUpdateWarning } from './version.js';
 
 // ============================================================================
 // Agent Instance Tracking
@@ -59,6 +61,9 @@ let currentPersona: string | null = null;
 // Current role for this agent instance
 let currentRole: 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer' | null = null;
 
+// Current project ID for this agent instance
+let currentProjectId: string | null = null;
+
 // Token usage tracking for this session (using token-tracking module)
 let sessionTokenUsage: TokenUsage = createTokenUsage();
 
@@ -619,12 +624,14 @@ async function handleTool(
 				currentSessionId,
 				currentPersona,
 				currentRole,
+				currentProjectId,
 				tokenUsage: sessionTokenUsage,
 			},
 			updateSession: (updates) => {
 				if (updates.currentSessionId !== undefined) currentSessionId = updates.currentSessionId;
 				if (updates.currentPersona !== undefined) currentPersona = updates.currentPersona;
 				if (updates.currentRole !== undefined) currentRole = updates.currentRole;
+				if (updates.currentProjectId !== undefined) currentProjectId = updates.currentProjectId;
 				if (updates.tokenUsage !== undefined) sessionTokenUsage = updates.tokenUsage;
 			},
 		};
@@ -648,6 +655,13 @@ async function main() {
 		process.exit(1);
 	}
 
+	// Check for updates (non-blocking, with timeout)
+	const updateWarning = await getUpdateWarning();
+
+	const serverInstructions = updateWarning
+		? `${updateWarning}\n\nVibescope MCP server - AI project tracking and coordination tools.`
+		: 'Vibescope MCP server - AI project tracking and coordination tools.';
+
 	const server = new Server(
 		{
 			name: 'vibescope',
@@ -657,6 +671,7 @@ async function main() {
 			capabilities: {
 				tools: {},
 			},
+			instructions: serverInstructions,
 		}
 	);
 
@@ -754,7 +769,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: string | undefined;
 
 			if (errorMessage.includes('violates foreign key constraint')) {

package/src/token-tracking.ts

@@ -5,6 +5,8 @@
  * Extracted from index.ts to enable unit testing.
  */
 
+import { getErrorMessage } from './utils.js';
+
 // ============================================================================
 // Types
 // ============================================================================
@@ -39,8 +41,7 @@ export function estimateTokens(obj: unknown): number {
 		return Math.max(1, Math.ceil(json.length / 4));
 	} 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/src/tools/blockers.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 const blockerTools: Tool[] = [
+	{
+		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/src/tools/bodies-of-work.ts

@@ -0,0 +1,283 @@
+/**
+ * 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 const bodiesOfWorkTools: Tool[] = [
+	{
+		name: 'create_body_of_work',
+		description: `Create a new body of work to group tasks into phases (pre/core/post).
+Bodies of work allow organizing related tasks with optional auto-deployment on completion.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				title: {
+					type: 'string',
+					description: 'Title for the body of work',
+				},
+				description: {
+					type: 'string',
+					description: 'Optional description',
+				},
+				auto_deploy_on_completion: {
+					type: 'boolean',
+					description: 'Automatically request deployment when all tasks complete (default: false)',
+				},
+				deploy_environment: {
+					type: 'string',
+					enum: ['development', 'staging', 'production'],
+					description: 'Target environment for auto-deploy (default: production)',
+				},
+				deploy_version_bump: {
+					type: 'string',
+					enum: ['patch', 'minor', 'major'],
+					description: 'Version bump for auto-deploy (default: minor)',
+				},
+				deploy_trigger: {
+					type: 'string',
+					enum: ['all_completed', 'all_completed_validated'],
+					description: 'When to trigger auto-deploy: all_completed (immediate) or all_completed_validated (requires validation, default)',
+				},
+			},
+			required: ['project_id', 'title'],
+		},
+	},
+	{
+		name: 'update_body_of_work',
+		description: `Update a body of work's settings.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+				title: {
+					type: 'string',
+					description: 'Updated title',
+				},
+				description: {
+					type: 'string',
+					description: 'Updated description',
+				},
+				auto_deploy_on_completion: {
+					type: 'boolean',
+					description: 'Auto-deploy setting',
+				},
+				deploy_environment: {
+					type: 'string',
+					enum: ['development', 'staging', 'production'],
+					description: 'Target environment',
+				},
+				deploy_version_bump: {
+					type: 'string',
+					enum: ['patch', 'minor', 'major'],
+					description: 'Version bump type',
+				},
+				deploy_trigger: {
+					type: 'string',
+					enum: ['all_completed', 'all_completed_validated'],
+					description: 'When to trigger auto-deploy',
+				},
+			},
+			required: ['body_of_work_id'],
+		},
+	},
+	{
+		name: 'get_body_of_work',
+		description: `Get a body of work with all its tasks organized by phase.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+			},
+			required: ['body_of_work_id'],
+		},
+	},
+	{
+		name: 'get_bodies_of_work',
+		description: `List bodies of work for a project with task counts per phase.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				status: {
+					type: 'string',
+					enum: ['draft', 'active', 'completed', 'cancelled'],
+					description: 'Filter by status (optional)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'delete_body_of_work',
+		description: `Delete a body of work. Tasks are preserved but no longer grouped.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+			},
+			required: ['body_of_work_id'],
+		},
+	},
+	{
+		name: 'add_task_to_body_of_work',
+		description: `Add a task to a body of work in a specific phase.
+Phases control execution order: pre tasks run first, then core, then post.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+				task_id: {
+					type: 'string',
+					description: 'Task UUID to add',
+				},
+				phase: {
+					type: 'string',
+					enum: ['pre', 'core', 'post'],
+					description: 'Task phase (default: core)',
+				},
+				order_index: {
+					type: 'number',
+					description: 'Order within phase (auto-assigned if not specified)',
+				},
+			},
+			required: ['body_of_work_id', 'task_id'],
+		},
+	},
+	{
+		name: 'remove_task_from_body_of_work',
+		description: `Remove a task from its body of work. The task is preserved.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID to remove',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	{
+		name: 'activate_body_of_work',
+		description: `Activate a draft body of work to start execution.
+Requires at least one task. Once active, tasks can be worked on following phase order.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+			},
+			required: ['body_of_work_id'],
+		},
+	},
+	{
+		name: 'add_task_dependency',
+		description: `Add a dependency between tasks in a body of work.
+The dependent task cannot start until the dependency is completed. Prevents circular dependencies.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+				task_id: {
+					type: 'string',
+					description: 'Task that depends on another task',
+				},
+				depends_on_task_id: {
+					type: 'string',
+					description: 'Task that must complete first',
+				},
+			},
+			required: ['body_of_work_id', 'task_id', 'depends_on_task_id'],
+		},
+	},
+	{
+		name: 'remove_task_dependency',
+		description: `Remove a dependency between tasks.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+				depends_on_task_id: {
+					type: 'string',
+					description: 'Dependency task UUID',
+				},
+			},
+			required: ['task_id', 'depends_on_task_id'],
+		},
+	},
+	{
+		name: 'get_task_dependencies',
+		description: `Get task dependencies for a body of work or specific task.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID (optional if task_id provided)',
+				},
+				task_id: {
+					type: 'string',
+					description: 'Specific task UUID (optional if body_of_work_id provided)',
+				},
+			},
+		},
+	},
+	{
+		name: 'get_next_body_of_work_task',
+		description: `Get the next available task from a body of work.
+Considers phase order (pre → core → post) and task dependencies.
+Only returns tasks where all dependencies are completed.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				body_of_work_id: {
+					type: 'string',
+					description: 'Body of work UUID',
+				},
+			},
+			required: ['body_of_work_id'],
+		},
+	},
+];