@vibescope/mcp-server 0.4.4 → 0.4.6

package/src/index.ts

@@ -1,807 +1,807 @@
-#!/usr/bin/env node
-
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import {
-	CallToolRequestSchema,
-	ListToolsRequestSchema,
-	type Tool,
-} from '@modelcontextprotocol/sdk/types.js';
-import { randomUUID } from 'crypto';
-import { initApiClient, getApiClient } from './api-client.js';
-import {
-	ValidationError,
-	validateRequired,
-	validateUUID,
-	validateTaskStatus,
-	validateProjectStatus,
-	validatePriority,
-	validateProgressPercentage,
-	validateEstimatedMinutes,
-	validateEnvironment,
-	VALID_TASK_STATUSES,
-	VALID_PROJECT_STATUSES,
-	VALID_BLOCKER_STATUSES,
-	VALID_DEPLOYMENT_STATUSES,
-	VALID_ENVIRONMENTS,
-} from './validators.js';
-import {
-	AGENT_PERSONAS,
-	FALLBACK_ACTIVITIES,
-	getRandomFallbackActivity,
-	selectPersona,
-	RateLimiter,
-	extractProjectNameFromGitUrl,
-	isValidStatusTransition,
-	getErrorMessage,
-} from './utils.js';
-import { buildHandlerRegistry, type HandlerContext } from './handlers/index.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
-// ============================================================================
-
-// Unique identifier for this agent instance (survives tool calls within same session)
-const INSTANCE_ID = randomUUID();
-
-// Current session ID (set when start_work_session is called)
-let currentSessionId: string | null = null;
-
-// Assigned persona for this agent instance
-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();
-
-// Wrapper function to track token usage with the session's usage object
-function trackTokenUsage(toolName: string, args: unknown, response: unknown): void {
-	trackTokens(sessionTokenUsage, toolName, args, response);
-}
-
-// Global rate limiter instance (60 requests per minute per API key)
-const rateLimiter = new RateLimiter(60, 60000);
-
-// Cleanup expired entries every 5 minutes (store interval ID for cleanup)
-const rateLimiterCleanupInterval = setInterval(() => rateLimiter.cleanup(), 5 * 60 * 1000);
-
-// Cleanup on process exit to prevent memory leaks
-process.on('exit', () => clearInterval(rateLimiterCleanupInterval));
-process.on('SIGINT', () => { clearInterval(rateLimiterCleanupInterval); process.exit(0); });
-process.on('SIGTERM', () => { clearInterval(rateLimiterCleanupInterval); process.exit(0); });
-
-// Build handler registry from modular handlers
-const handlerRegistry = buildHandlerRegistry();
-
-// ============================================================================
-// Embedded Knowledge Base (on-demand help topics)
-// ============================================================================
-
-const KNOWLEDGE_BASE: Record<string, string> = {
-	getting_started: `# Getting Started
-1. Call start_work_session(git_url, model: "your-model-name") to initialize
-   - IMPORTANT: Pass your model for accurate cost tracking (e.g., "opus", "sonnet", "gemini", "gpt-4o")
-   - Check your system prompt for "You are powered by the model named..." to find it
-2. Response includes next_task - start working on it immediately
-3. Use update_task to mark in_progress and track progress
-4. Call complete_task when done - it returns your next task
-5. Use get_help(topic) when you need guidance on specific workflows`,
-
-	tasks: `# Task Workflow
-- Mark task in_progress with update_task before starting
-- Update progress_percentage regularly (every 15-20% progress)
-- Include progress_note to auto-log milestones
-- One task at a time - complete current before starting another
-- complete_task returns next_task and context counts (validation, blockers, deployment)
-- Priority: 1=highest, 5=lowest`,
-
-	validation: `# Task Validation
-Completed tasks need validation before deployment. PRIORITIZE validation over new tasks.
-1. Check: get_tasks_awaiting_validation(project_id)
-2. Claim: claim_validation(task_id) - marks "being reviewed" on dashboard
-3. Review code changes and run tests
-4. Complete: validate_task(task_id, approved: true/false, validation_notes: "...")
-Self-validation allowed when single-agent or to unblock deployment.`,
-
-	deployment: `# Deployment Workflow
-1. Ensure all completed tasks are validated first
-2. request_deployment(project_id, environment: "production")
-3. claim_deployment_validation(project_id) - claim for validation
-4. Run: pnpm build && pnpm test
-5. report_validation(project_id, build_passed: true, tests_passed: true)
-6. start_deployment(project_id) - returns project's deployment_instructions
-7. Follow the instructions (e.g., push to main, run deploy command)
-8. complete_deployment(project_id, success: true, summary: "...")`,
-
-	git: `# Git Workflow
-Call get_git_workflow(project_id) for project-specific config.
-Workflows: none, trunk-based, github-flow, git-flow
-- trunk-based: commit directly to main
-- github-flow: feature branches, merge via PR
-- git-flow: develop/release branches
-Update task git_branch when working on a branch.`,
-
-	blockers: `# Working with Blockers
-When stuck and need human input:
-1. add_blocker(project_id, description: "What's blocking")
-2. Ask your question to the user
-3. resolve_blocker(blocker_id, resolution_note: "How resolved")
-Only use for genuine blockers requiring decisions - not routine questions.`,
-
-	milestones: `# Task Milestones
-For complex tasks, break into milestones:
-1. add_milestone(task_id, title: "Design schema")
-2. add_milestone(task_id, title: "Implement API")
-3. Update with complete_milestone(milestone_id) as you go
-Dashboard shows progress bar with completed/total.`,
-
-	fallback: `# Fallback Activities
-When no tasks available, get_next_task suggests activities:
-- feature_ideation, code_review, performance_audit
-- security_review, test_coverage, documentation_review
-1. start_fallback_activity(project_id, activity: "code_review")
-2. Do the work, use add_finding for issues, add_idea for improvements
-3. stop_fallback_activity(project_id, summary: "...")`,
-
-	session: `# Session Management
-- start_work_session(git_url, model) initializes and returns next_task
-- ALWAYS pass model parameter for cost tracking (e.g., "opus", "sonnet", "gemini", "gpt-4o")
-- Use mode:'lite' (default) or mode:'full' for complete context
-- heartbeat every 30-60 seconds maintains active status
-- end_work_session releases claimed tasks and returns summary
-- NEVER STOP: After completing a task, immediately start the next one
-- When context grows large: /clear then start_work_session to continue fresh
-- Your progress is saved to the dashboard - nothing is lost on /clear`,
-
-	tokens: `# Token Efficiency
-Be mindful of token costs - every tool call has a cost.
-- Use mode:'lite' (default) - saves ~85% vs full mode
-- Call get_token_usage() to check consumption
-- /compact when context grows large
-- Batch related updates when possible
-- Trust lite mode; only use full mode for initial exploration`,
-
-	topics: `# Available Help Topics
-- getting_started: Basic workflow overview
-- tasks: Working on tasks, progress tracking
-- validation: Cross-agent task validation
-- deployment: Deployment coordination
-- git: Git workflow configuration
-- blockers: Handling blockers
-- milestones: Breaking down complex tasks
-- fallback: Background activities when idle
-- session: Session management
-- tokens: Token efficiency tips`,
-};
-
-
-// ============================================================================
-// Types
-// ============================================================================
-
-interface Database {
-	public: {
-		Tables: {
-			api_keys: {
-				Row: {
-					id: string;
-					user_id: string;
-					key_hash: string;
-					name: string;
-					last_used_at: string | null;
-				};
-				Insert: {
-					id?: string;
-					user_id: string;
-					key_hash: string;
-					name: string;
-					last_used_at?: string | null;
-				};
-				Update: {
-					id?: string;
-					user_id?: string;
-					key_hash?: string;
-					name?: string;
-					last_used_at?: string | null;
-				};
-			};
-			projects: {
-				Row: {
-					id: string;
-					user_id: string;
-					name: string;
-					description: string | null;
-					goal: string | null;
-					status: string;
-					git_url: string | null;
-					agent_instructions: string | null;
-					tech_stack: string[] | null;
-					git_workflow: 'none' | 'trunk-based' | 'github-flow' | 'git-flow';
-					git_main_branch: string;
-					git_develop_branch: string | null;
-					git_auto_branch: boolean;
-					git_auto_tag: boolean;
-					created_at: string;
-					updated_at: string;
-				};
-				Insert: {
-					id?: string;
-					user_id: string;
-					name: string;
-					description?: string | null;
-					goal?: string | null;
-					status?: string;
-					git_url?: string | null;
-					agent_instructions?: string | null;
-					tech_stack?: string[] | null;
-					git_workflow?: 'none' | 'trunk-based' | 'github-flow' | 'git-flow';
-					git_main_branch?: string;
-					git_develop_branch?: string | null;
-					git_auto_branch?: boolean;
-					git_auto_tag?: boolean;
-					created_at?: string;
-					updated_at?: string;
-				};
-				Update: {
-					id?: string;
-					user_id?: string;
-					name?: string;
-					description?: string | null;
-					goal?: string | null;
-					status?: string;
-					git_url?: string | null;
-					agent_instructions?: string | null;
-					tech_stack?: string[] | null;
-					git_workflow?: 'none' | 'trunk-based' | 'github-flow' | 'git-flow';
-					git_main_branch?: string;
-					git_develop_branch?: string | null;
-					git_auto_branch?: boolean;
-					git_auto_tag?: boolean;
-					created_at?: string;
-					updated_at?: string;
-				};
-			};
-			tasks: {
-				Row: {
-					id: string;
-					project_id: string;
-					title: string;
-					description: string | null;
-					priority: number;
-					status: string;
-					created_by: string;
-					created_at: string;
-					completed_at: string | null;
-					progress_percentage: number;
-					estimated_minutes: number | null;
-					started_at: string | null;
-					working_agent_session_id: string | null;
-					git_branch: string | null;
-					references: { url: string; label?: string }[] | null;
-				};
-				Insert: {
-					id?: string;
-					project_id: string;
-					title: string;
-					description?: string | null;
-					priority?: number;
-					status?: string;
-					created_by?: string;
-					created_at?: string;
-					completed_at?: string | null;
-					progress_percentage?: number;
-					estimated_minutes?: number | null;
-					started_at?: string | null;
-					working_agent_session_id?: string | null;
-					git_branch?: string | null;
-					references?: { url: string; label?: string }[] | null;
-				};
-				Update: {
-					id?: string;
-					project_id?: string;
-					title?: string;
-					description?: string | null;
-					priority?: number;
-					status?: string;
-					created_by?: string;
-					created_at?: string;
-					completed_at?: string | null;
-					progress_percentage?: number;
-					estimated_minutes?: number | null;
-					started_at?: string | null;
-					working_agent_session_id?: string | null;
-					git_branch?: string | null;
-					references?: { url: string; label?: string }[] | null;
-				};
-			};
-			progress_logs: {
-				Row: {
-					id: string;
-					project_id: string;
-					task_id: string | null;
-					summary: string;
-					details: string | null;
-					created_by: string;
-					created_at: string;
-				};
-				Insert: {
-					id?: string;
-					project_id: string;
-					task_id?: string | null;
-					summary: string;
-					details?: string | null;
-					created_by?: string;
-					created_at?: string;
-				};
-				Update: {
-					id?: string;
-					project_id?: string;
-					task_id?: string | null;
-					summary?: string;
-					details?: string | null;
-					created_by?: string;
-					created_at?: string;
-				};
-			};
-			blockers: {
-				Row: {
-					id: string;
-					project_id: string;
-					description: string;
-					status: string;
-					created_by: string;
-					created_at: string;
-					resolved_at: string | null;
-					resolution_note: string | null;
-				};
-				Insert: {
-					id?: string;
-					project_id: string;
-					description: string;
-					status?: string;
-					created_by?: string;
-					created_at?: string;
-					resolved_at?: string | null;
-					resolution_note?: string | null;
-				};
-				Update: {
-					id?: string;
-					project_id?: string;
-					description?: string;
-					status?: string;
-					created_by?: string;
-					created_at?: string;
-					resolved_at?: string | null;
-					resolution_note?: string | null;
-				};
-			};
-			ideas: {
-				Row: {
-					id: string;
-					project_id: string;
-					title: string;
-					description: string | null;
-					created_by: string;
-					created_at: string;
-				};
-				Insert: {
-					id?: string;
-					project_id: string;
-					title: string;
-					description?: string | null;
-					created_by?: string;
-					created_at?: string;
-				};
-				Update: {
-					id?: string;
-					project_id?: string;
-					title?: string;
-					description?: string | null;
-					created_by?: string;
-					created_at?: string;
-				};
-			};
-			decisions: {
-				Row: {
-					id: string;
-					project_id: string;
-					title: string;
-					description: string;
-					rationale: string | null;
-					alternatives_considered: string[] | null;
-					created_by: string;
-					created_at: string;
-				};
-				Insert: {
-					id?: string;
-					project_id: string;
-					title: string;
-					description: string;
-					rationale?: string | null;
-					alternatives_considered?: string[] | null;
-					created_by?: string;
-					created_at?: string;
-				};
-				Update: {
-					id?: string;
-					project_id?: string;
-					title?: string;
-					description?: string;
-					rationale?: string | null;
-					alternatives_considered?: string[] | null;
-					created_by?: string;
-					created_at?: string;
-				};
-			};
-			agent_sessions: {
-				Row: {
-					id: string;
-					api_key_id: string;
-					project_id: string;
-					last_synced_at: string;
-					agent_name: string | null;
-					agent_version: string | null;
-					instance_id: string | null;
-					current_task_id: string | null;
-					status: string;
-				};
-				Insert: {
-					id?: string;
-					api_key_id: string;
-					project_id: string;
-					last_synced_at?: string;
-					agent_name?: string | null;
-					agent_version?: string | null;
-					instance_id?: string | null;
-					current_task_id?: string | null;
-					status?: string;
-				};
-				Update: {
-					id?: string;
-					api_key_id?: string;
-					project_id?: string;
-					last_synced_at?: string;
-					agent_name?: string | null;
-					agent_version?: string | null;
-					instance_id?: string | null;
-					current_task_id?: string | null;
-					status?: string;
-				};
-			};
-			agent_heartbeats: {
-				Row: {
-					id: string;
-					session_id: string;
-					created_at: string;
-				};
-				Insert: {
-					id?: string;
-					session_id: string;
-					created_at?: string;
-				};
-				Update: {
-					id?: string;
-					session_id?: string;
-					created_at?: string;
-				};
-			};
-			task_milestones: {
-				Row: {
-					id: string;
-					task_id: string;
-					title: string;
-					description: string | null;
-					order_index: number;
-					status: string;
-					created_by: string;
-					created_at: string;
-					completed_at: string | null;
-					created_by_session_id: string | null;
-				};
-				Insert: {
-					id?: string;
-					task_id: string;
-					title: string;
-					description?: string | null;
-					order_index?: number;
-					status?: string;
-					created_by?: string;
-					created_at?: string;
-					completed_at?: string | null;
-					created_by_session_id?: string | null;
-				};
-				Update: {
-					id?: string;
-					task_id?: string;
-					title?: string;
-					description?: string | null;
-					order_index?: number;
-					status?: string;
-					created_by?: string;
-					created_at?: string;
-					completed_at?: string | null;
-					created_by_session_id?: string | null;
-				};
-			};
-		};
-		Views: Record<string, never>;
-		Functions: Record<string, never>;
-		Enums: Record<string, never>;
-	};
-}
-
-interface AuthContext {
-	userId: string;
-	apiKeyId: string;
-	organizationId?: string;
-	scope: 'personal' | 'organization';
-}
-
-interface UserUpdates {
-	tasks: Array<{ id: string; title: string; created_at: string }>;
-	blockers: Array<{ id: string; description: string; created_at: string }>;
-	ideas: Array<{ id: string; title: string; created_at: string }>;
-}
-
-// ============================================================================
-// Configuration
-// ============================================================================
-
-const API_KEY = process.env.VIBESCOPE_API_KEY;
-
-if (!API_KEY) {
-	console.error('Missing required environment variable: VIBESCOPE_API_KEY');
-	process.exit(1);
-}
-
-// Initialize the API client
-initApiClient({ apiKey: API_KEY });
-
-// ============================================================================
-// Authentication
-// ============================================================================
-
-async function validateApiKey(): Promise<AuthContext | null> {
-	const apiClient = getApiClient();
-	const response = await apiClient.validateAuth();
-
-	if (!response.ok || !response.data?.valid) {
-		return null;
-	}
-
-	return {
-		userId: response.data.user_id,
-		apiKeyId: response.data.api_key_id,
-		scope: 'personal', // API handles authorization, scope not needed locally
-	};
-}
-
-// Tool definitions imported from tools.ts
-
-
-// ============================================================================
-// Tool Handlers
-// ============================================================================
-
-async function handleTool(
-	auth: AuthContext,
-	name: string,
-	args: Record<string, unknown>
-): Promise<{ result: unknown; user_updates?: UserUpdates; reminder?: string }> {
-	// Update session on every tool call via API:
-	// - last_synced_at: keeps session alive and visible as "active" on dashboard
-	// - token tracking: synced periodically for cost monitoring
-	// Skip for start_work_session since it handles its own session setup
-	if (currentSessionId && name !== 'start_work_session') {
-		const apiClient = getApiClient();
-		// Fire and forget - don't block tool execution on session sync
-		apiClient.syncSession(currentSessionId).catch(() => {
-			// Silently ignore sync errors - session tracking is non-critical
-		});
-	}
-
-	// Check if handler exists in the modular registry
-	const handler = handlerRegistry[name];
-	if (handler) {
-		// Build handler context
-		const ctx: HandlerContext = {
-			auth,
-			session: {
-				instanceId: INSTANCE_ID,
-				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;
-			},
-		};
-
-		const handlerResult = await handler(args, ctx);
-		return handlerResult as { result: unknown; user_updates?: UserUpdates; reminder?: string };
-	}
-
-	throw new Error(`Unknown tool: ${name}`);
-}
-
-// ============================================================================
-// Server Setup
-// ============================================================================
-
-async function main() {
-	// Validate API key on startup via API
-	const auth = await validateApiKey();
-	if (!auth) {
-		console.error('Invalid API key');
-		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',
-			version: '0.1.0',
-		},
-		{
-			capabilities: {
-				tools: {},
-			},
-			instructions: serverInstructions,
-		}
-	);
-
-	// List available tools
-	server.setRequestHandler(ListToolsRequestSchema, async () => {
-		return { tools };
-	});
-
-	// Get reminder nudge - only for critical workflow reminders to save context
-	function getReminder(toolName: string): string | null {
-		// Most reminders removed to reduce context bloat - instructions are in CLAUDE.md
-		// Only keep critical continuation reminder for complete_task
-		const reminders: Record<string, string> = {
-			'complete_task': 'CONTINUE WORKING: Call get_next_task or start the next_task. If awaiting_validation tasks exist, validate them FIRST before new work. If context is large, run /clear then start_work_session to refresh.',
-			'batch_complete_tasks': 'CONTINUE WORKING: Call get_next_task. If awaiting_validation tasks exist, validate them FIRST before new work.',
-		};
-		return reminders[toolName] ?? null;
-	}
-
-	// Handle tool calls
-	server.setRequestHandler(CallToolRequestSchema, async (request) => {
-		const { name, arguments: args } = request.params;
-
-		// Check rate limit
-		const rateCheck = rateLimiter.check(auth.apiKeyId);
-		if (!rateCheck.allowed) {
-			const resetSeconds = Math.ceil(rateCheck.resetIn / 1000);
-			return {
-				content: [
-					{
-						type: 'text',
-						text: `Rate limit exceeded. Too many requests. Please wait ${resetSeconds} seconds before trying again. (Limit: 60 requests per minute)`,
-					},
-				],
-				isError: true,
-			};
-		}
-
-		try {
-			const toolArgs = (args as Record<string, unknown>) || {};
-			const { result, user_updates } = await handleTool(
-				auth,
-				name,
-				toolArgs
-			);
-
-			// Track token usage for this call (both input args and output result)
-			trackTokenUsage(name, toolArgs, result);
-
-			const content: { type: 'text'; text: string }[] = [
-				{
-					type: 'text',
-					text: JSON.stringify(result, null, 2),
-				},
-			];
-
-			// Include reminder nudge if applicable
-			const reminder = getReminder(name);
-			if (reminder) {
-				content.push({
-					type: 'text',
-					text: `\n--- ${reminder} ---`,
-				});
-			}
-
-			// Include user updates only if there are new items (null means no updates)
-			if (user_updates) {
-				content.push({
-					type: 'text',
-					text: `\n--- New User Updates ---\n${JSON.stringify(user_updates, null, 2)}`,
-				});
-			}
-
-			// Add rate limit warning if getting low
-			if (rateCheck.remaining < 10) {
-				content.push({
-					type: 'text',
-					text: `\n--- Rate Limit Warning: ${rateCheck.remaining} requests remaining this minute ---`,
-				});
-			}
-
-			return { content };
-		} catch (error) {
-			// Handle validation errors with structured output
-			if (error instanceof ValidationError) {
-				return {
-					content: [
-						{
-							type: 'text',
-							text: JSON.stringify(error.toJSON(), null, 2),
-						},
-					],
-					isError: true,
-				};
-			}
-
-			// Handle database errors with better context
-			const errorMessage = getErrorMessage(error);
-			let hint: string | undefined;
-
-			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.';
-			} else if (errorMessage.includes('duplicate key')) {
-				hint = 'A record with this identifier already exists.';
-			} else if (errorMessage.includes('not found') || errorMessage.includes('no rows')) {
-				hint = 'The requested resource was not found. Verify the ID is correct.';
-			}
-
-			return {
-				content: [
-					{
-						type: 'text',
-						text: JSON.stringify({
-							error: 'operation_failed',
-							message: errorMessage,
-							hint,
-						}, null, 2),
-					},
-				],
-				isError: true,
-			};
-		}
-	});
-
-	// Start server
-	const transport = new StdioServerTransport();
-	await server.connect(transport);
-}
-
-main().catch((error) => {
-	console.error('Fatal error:', error);
-	process.exit(1);
-});
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+	CallToolRequestSchema,
+	ListToolsRequestSchema,
+	type Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+import { randomUUID } from 'crypto';
+import { initApiClient, getApiClient } from './api-client.js';
+import {
+	ValidationError,
+	validateRequired,
+	validateUUID,
+	validateTaskStatus,
+	validateProjectStatus,
+	validatePriority,
+	validateProgressPercentage,
+	validateEstimatedMinutes,
+	validateEnvironment,
+	VALID_TASK_STATUSES,
+	VALID_PROJECT_STATUSES,
+	VALID_BLOCKER_STATUSES,
+	VALID_DEPLOYMENT_STATUSES,
+	VALID_ENVIRONMENTS,
+} from './validators.js';
+import {
+	AGENT_PERSONAS,
+	FALLBACK_ACTIVITIES,
+	getRandomFallbackActivity,
+	selectPersona,
+	RateLimiter,
+	extractProjectNameFromGitUrl,
+	isValidStatusTransition,
+	getErrorMessage,
+} from './utils.js';
+import { buildHandlerRegistry, type HandlerContext } from './handlers/index.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
+// ============================================================================
+
+// Unique identifier for this agent instance (survives tool calls within same session)
+const INSTANCE_ID = randomUUID();
+
+// Current session ID (set when start_work_session is called)
+let currentSessionId: string | null = null;
+
+// Assigned persona for this agent instance
+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();
+
+// Wrapper function to track token usage with the session's usage object
+function trackTokenUsage(toolName: string, args: unknown, response: unknown): void {
+	trackTokens(sessionTokenUsage, toolName, args, response);
+}
+
+// Global rate limiter instance (60 requests per minute per API key)
+const rateLimiter = new RateLimiter(60, 60000);
+
+// Cleanup expired entries every 5 minutes (store interval ID for cleanup)
+const rateLimiterCleanupInterval = setInterval(() => rateLimiter.cleanup(), 5 * 60 * 1000);
+
+// Cleanup on process exit to prevent memory leaks
+process.on('exit', () => clearInterval(rateLimiterCleanupInterval));
+process.on('SIGINT', () => { clearInterval(rateLimiterCleanupInterval); process.exit(0); });
+process.on('SIGTERM', () => { clearInterval(rateLimiterCleanupInterval); process.exit(0); });
+
+// Build handler registry from modular handlers
+const handlerRegistry = buildHandlerRegistry();
+
+// ============================================================================
+// Embedded Knowledge Base (on-demand help topics)
+// ============================================================================
+
+const KNOWLEDGE_BASE: Record<string, string> = {
+	getting_started: `# Getting Started
+1. Call start_work_session(git_url, model: "your-model-name") to initialize
+   - IMPORTANT: Pass your model for accurate cost tracking (e.g., "opus", "sonnet", "gemini", "gpt-4o")
+   - Check your system prompt for "You are powered by the model named..." to find it
+2. Response includes next_task - start working on it immediately
+3. Use update_task to mark in_progress and track progress
+4. Call complete_task when done - it returns your next task
+5. Use get_help(topic) when you need guidance on specific workflows`,
+
+	tasks: `# Task Workflow
+- Mark task in_progress with update_task before starting
+- Update progress_percentage regularly (every 15-20% progress)
+- Include progress_note to auto-log milestones
+- One task at a time - complete current before starting another
+- complete_task returns next_task and context counts (validation, blockers, deployment)
+- Priority: 1=highest, 5=lowest`,
+
+	validation: `# Task Validation
+Completed tasks need validation before deployment. PRIORITIZE validation over new tasks.
+1. Check: get_tasks_awaiting_validation(project_id)
+2. Claim: claim_validation(task_id) - marks "being reviewed" on dashboard
+3. Review code changes and run tests
+4. Complete: validate_task(task_id, approved: true/false, validation_notes: "...")
+Self-validation allowed when single-agent or to unblock deployment.`,
+
+	deployment: `# Deployment Workflow
+1. Ensure all completed tasks are validated first
+2. request_deployment(project_id, environment: "production")
+3. claim_deployment_validation(project_id) - claim for validation
+4. Run: pnpm build && pnpm test
+5. report_validation(project_id, build_passed: true, tests_passed: true)
+6. start_deployment(project_id) - returns project's deployment_instructions
+7. Follow the instructions (e.g., push to main, run deploy command)
+8. complete_deployment(project_id, success: true, summary: "...")`,
+
+	git: `# Git Workflow
+Call get_git_workflow(project_id) for project-specific config.
+Workflows: none, trunk-based, github-flow, git-flow
+- trunk-based: commit directly to main
+- github-flow: feature branches, merge via PR
+- git-flow: develop/release branches
+Update task git_branch when working on a branch.`,
+
+	blockers: `# Working with Blockers
+When stuck and need human input:
+1. add_blocker(project_id, description: "What's blocking")
+2. Ask your question to the user
+3. resolve_blocker(blocker_id, resolution_note: "How resolved")
+Only use for genuine blockers requiring decisions - not routine questions.`,
+
+	milestones: `# Task Milestones
+For complex tasks, break into milestones:
+1. add_milestone(task_id, title: "Design schema")
+2. add_milestone(task_id, title: "Implement API")
+3. Update with complete_milestone(milestone_id) as you go
+Dashboard shows progress bar with completed/total.`,
+
+	fallback: `# Fallback Activities
+When no tasks available, get_next_task suggests activities:
+- feature_ideation, code_review, performance_audit
+- security_review, test_coverage, documentation_review
+1. start_fallback_activity(project_id, activity: "code_review")
+2. Do the work, use add_finding for issues, add_idea for improvements
+3. stop_fallback_activity(project_id, summary: "...")`,
+
+	session: `# Session Management
+- start_work_session(git_url, model) initializes and returns next_task
+- ALWAYS pass model parameter for cost tracking (e.g., "opus", "sonnet", "gemini", "gpt-4o")
+- Use mode:'lite' (default) or mode:'full' for complete context
+- heartbeat every 30-60 seconds maintains active status
+- end_work_session releases claimed tasks and returns summary
+- NEVER STOP: After completing a task, immediately start the next one
+- When context grows large: /clear then start_work_session to continue fresh
+- Your progress is saved to the dashboard - nothing is lost on /clear`,
+
+	tokens: `# Token Efficiency
+Be mindful of token costs - every tool call has a cost.
+- Use mode:'lite' (default) - saves ~85% vs full mode
+- Call get_token_usage() to check consumption
+- /compact when context grows large
+- Batch related updates when possible
+- Trust lite mode; only use full mode for initial exploration`,
+
+	topics: `# Available Help Topics
+- getting_started: Basic workflow overview
+- tasks: Working on tasks, progress tracking
+- validation: Cross-agent task validation
+- deployment: Deployment coordination
+- git: Git workflow configuration
+- blockers: Handling blockers
+- milestones: Breaking down complex tasks
+- fallback: Background activities when idle
+- session: Session management
+- tokens: Token efficiency tips`,
+};
+
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface Database {
+	public: {
+		Tables: {
+			api_keys: {
+				Row: {
+					id: string;
+					user_id: string;
+					key_hash: string;
+					name: string;
+					last_used_at: string | null;
+				};
+				Insert: {
+					id?: string;
+					user_id: string;
+					key_hash: string;
+					name: string;
+					last_used_at?: string | null;
+				};
+				Update: {
+					id?: string;
+					user_id?: string;
+					key_hash?: string;
+					name?: string;
+					last_used_at?: string | null;
+				};
+			};
+			projects: {
+				Row: {
+					id: string;
+					user_id: string;
+					name: string;
+					description: string | null;
+					goal: string | null;
+					status: string;
+					git_url: string | null;
+					agent_instructions: string | null;
+					tech_stack: string[] | null;
+					git_workflow: 'none' | 'trunk-based' | 'github-flow' | 'git-flow';
+					git_main_branch: string;
+					git_develop_branch: string | null;
+					git_auto_branch: boolean;
+					git_auto_tag: boolean;
+					created_at: string;
+					updated_at: string;
+				};
+				Insert: {
+					id?: string;
+					user_id: string;
+					name: string;
+					description?: string | null;
+					goal?: string | null;
+					status?: string;
+					git_url?: string | null;
+					agent_instructions?: string | null;
+					tech_stack?: string[] | null;
+					git_workflow?: 'none' | 'trunk-based' | 'github-flow' | 'git-flow';
+					git_main_branch?: string;
+					git_develop_branch?: string | null;
+					git_auto_branch?: boolean;
+					git_auto_tag?: boolean;
+					created_at?: string;
+					updated_at?: string;
+				};
+				Update: {
+					id?: string;
+					user_id?: string;
+					name?: string;
+					description?: string | null;
+					goal?: string | null;
+					status?: string;
+					git_url?: string | null;
+					agent_instructions?: string | null;
+					tech_stack?: string[] | null;
+					git_workflow?: 'none' | 'trunk-based' | 'github-flow' | 'git-flow';
+					git_main_branch?: string;
+					git_develop_branch?: string | null;
+					git_auto_branch?: boolean;
+					git_auto_tag?: boolean;
+					created_at?: string;
+					updated_at?: string;
+				};
+			};
+			tasks: {
+				Row: {
+					id: string;
+					project_id: string;
+					title: string;
+					description: string | null;
+					priority: number;
+					status: string;
+					created_by: string;
+					created_at: string;
+					completed_at: string | null;
+					progress_percentage: number;
+					estimated_minutes: number | null;
+					started_at: string | null;
+					working_agent_session_id: string | null;
+					git_branch: string | null;
+					references: { url: string; label?: string }[] | null;
+				};
+				Insert: {
+					id?: string;
+					project_id: string;
+					title: string;
+					description?: string | null;
+					priority?: number;
+					status?: string;
+					created_by?: string;
+					created_at?: string;
+					completed_at?: string | null;
+					progress_percentage?: number;
+					estimated_minutes?: number | null;
+					started_at?: string | null;
+					working_agent_session_id?: string | null;
+					git_branch?: string | null;
+					references?: { url: string; label?: string }[] | null;
+				};
+				Update: {
+					id?: string;
+					project_id?: string;
+					title?: string;
+					description?: string | null;
+					priority?: number;
+					status?: string;
+					created_by?: string;
+					created_at?: string;
+					completed_at?: string | null;
+					progress_percentage?: number;
+					estimated_minutes?: number | null;
+					started_at?: string | null;
+					working_agent_session_id?: string | null;
+					git_branch?: string | null;
+					references?: { url: string; label?: string }[] | null;
+				};
+			};
+			progress_logs: {
+				Row: {
+					id: string;
+					project_id: string;
+					task_id: string | null;
+					summary: string;
+					details: string | null;
+					created_by: string;
+					created_at: string;
+				};
+				Insert: {
+					id?: string;
+					project_id: string;
+					task_id?: string | null;
+					summary: string;
+					details?: string | null;
+					created_by?: string;
+					created_at?: string;
+				};
+				Update: {
+					id?: string;
+					project_id?: string;
+					task_id?: string | null;
+					summary?: string;
+					details?: string | null;
+					created_by?: string;
+					created_at?: string;
+				};
+			};
+			blockers: {
+				Row: {
+					id: string;
+					project_id: string;
+					description: string;
+					status: string;
+					created_by: string;
+					created_at: string;
+					resolved_at: string | null;
+					resolution_note: string | null;
+				};
+				Insert: {
+					id?: string;
+					project_id: string;
+					description: string;
+					status?: string;
+					created_by?: string;
+					created_at?: string;
+					resolved_at?: string | null;
+					resolution_note?: string | null;
+				};
+				Update: {
+					id?: string;
+					project_id?: string;
+					description?: string;
+					status?: string;
+					created_by?: string;
+					created_at?: string;
+					resolved_at?: string | null;
+					resolution_note?: string | null;
+				};
+			};
+			ideas: {
+				Row: {
+					id: string;
+					project_id: string;
+					title: string;
+					description: string | null;
+					created_by: string;
+					created_at: string;
+				};
+				Insert: {
+					id?: string;
+					project_id: string;
+					title: string;
+					description?: string | null;
+					created_by?: string;
+					created_at?: string;
+				};
+				Update: {
+					id?: string;
+					project_id?: string;
+					title?: string;
+					description?: string | null;
+					created_by?: string;
+					created_at?: string;
+				};
+			};
+			decisions: {
+				Row: {
+					id: string;
+					project_id: string;
+					title: string;
+					description: string;
+					rationale: string | null;
+					alternatives_considered: string[] | null;
+					created_by: string;
+					created_at: string;
+				};
+				Insert: {
+					id?: string;
+					project_id: string;
+					title: string;
+					description: string;
+					rationale?: string | null;
+					alternatives_considered?: string[] | null;
+					created_by?: string;
+					created_at?: string;
+				};
+				Update: {
+					id?: string;
+					project_id?: string;
+					title?: string;
+					description?: string;
+					rationale?: string | null;
+					alternatives_considered?: string[] | null;
+					created_by?: string;
+					created_at?: string;
+				};
+			};
+			agent_sessions: {
+				Row: {
+					id: string;
+					api_key_id: string;
+					project_id: string;
+					last_synced_at: string;
+					agent_name: string | null;
+					agent_version: string | null;
+					instance_id: string | null;
+					current_task_id: string | null;
+					status: string;
+				};
+				Insert: {
+					id?: string;
+					api_key_id: string;
+					project_id: string;
+					last_synced_at?: string;
+					agent_name?: string | null;
+					agent_version?: string | null;
+					instance_id?: string | null;
+					current_task_id?: string | null;
+					status?: string;
+				};
+				Update: {
+					id?: string;
+					api_key_id?: string;
+					project_id?: string;
+					last_synced_at?: string;
+					agent_name?: string | null;
+					agent_version?: string | null;
+					instance_id?: string | null;
+					current_task_id?: string | null;
+					status?: string;
+				};
+			};
+			agent_heartbeats: {
+				Row: {
+					id: string;
+					session_id: string;
+					created_at: string;
+				};
+				Insert: {
+					id?: string;
+					session_id: string;
+					created_at?: string;
+				};
+				Update: {
+					id?: string;
+					session_id?: string;
+					created_at?: string;
+				};
+			};
+			task_milestones: {
+				Row: {
+					id: string;
+					task_id: string;
+					title: string;
+					description: string | null;
+					order_index: number;
+					status: string;
+					created_by: string;
+					created_at: string;
+					completed_at: string | null;
+					created_by_session_id: string | null;
+				};
+				Insert: {
+					id?: string;
+					task_id: string;
+					title: string;
+					description?: string | null;
+					order_index?: number;
+					status?: string;
+					created_by?: string;
+					created_at?: string;
+					completed_at?: string | null;
+					created_by_session_id?: string | null;
+				};
+				Update: {
+					id?: string;
+					task_id?: string;
+					title?: string;
+					description?: string | null;
+					order_index?: number;
+					status?: string;
+					created_by?: string;
+					created_at?: string;
+					completed_at?: string | null;
+					created_by_session_id?: string | null;
+				};
+			};
+		};
+		Views: Record<string, never>;
+		Functions: Record<string, never>;
+		Enums: Record<string, never>;
+	};
+}
+
+interface AuthContext {
+	userId: string;
+	apiKeyId: string;
+	organizationId?: string;
+	scope: 'personal' | 'organization';
+}
+
+interface UserUpdates {
+	tasks: Array<{ id: string; title: string; created_at: string }>;
+	blockers: Array<{ id: string; description: string; created_at: string }>;
+	ideas: Array<{ id: string; title: string; created_at: string }>;
+}
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+const API_KEY = process.env.VIBESCOPE_API_KEY;
+
+if (!API_KEY) {
+	console.error('Missing required environment variable: VIBESCOPE_API_KEY');
+	process.exit(1);
+}
+
+// Initialize the API client
+initApiClient({ apiKey: API_KEY });
+
+// ============================================================================
+// Authentication
+// ============================================================================
+
+async function validateApiKey(): Promise<AuthContext | null> {
+	const apiClient = getApiClient();
+	const response = await apiClient.validateAuth();
+
+	if (!response.ok || !response.data?.valid) {
+		return null;
+	}
+
+	return {
+		userId: response.data.user_id,
+		apiKeyId: response.data.api_key_id,
+		scope: 'personal', // API handles authorization, scope not needed locally
+	};
+}
+
+// Tool definitions imported from tools.ts
+
+
+// ============================================================================
+// Tool Handlers
+// ============================================================================
+
+async function handleTool(
+	auth: AuthContext,
+	name: string,
+	args: Record<string, unknown>
+): Promise<{ result: unknown; user_updates?: UserUpdates; reminder?: string }> {
+	// Update session on every tool call via API:
+	// - last_synced_at: keeps session alive and visible as "active" on dashboard
+	// - token tracking: synced periodically for cost monitoring
+	// Skip for start_work_session since it handles its own session setup
+	if (currentSessionId && name !== 'start_work_session') {
+		const apiClient = getApiClient();
+		// Fire and forget - don't block tool execution on session sync
+		apiClient.syncSession(currentSessionId).catch(() => {
+			// Silently ignore sync errors - session tracking is non-critical
+		});
+	}
+
+	// Check if handler exists in the modular registry
+	const handler = handlerRegistry[name];
+	if (handler) {
+		// Build handler context
+		const ctx: HandlerContext = {
+			auth,
+			session: {
+				instanceId: INSTANCE_ID,
+				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;
+			},
+		};
+
+		const handlerResult = await handler(args, ctx);
+		return handlerResult as { result: unknown; user_updates?: UserUpdates; reminder?: string };
+	}
+
+	throw new Error(`Unknown tool: ${name}`);
+}
+
+// ============================================================================
+// Server Setup
+// ============================================================================
+
+async function main() {
+	// Validate API key on startup via API
+	const auth = await validateApiKey();
+	if (!auth) {
+		console.error('Invalid API key');
+		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',
+			version: '0.1.0',
+		},
+		{
+			capabilities: {
+				tools: {},
+			},
+			instructions: serverInstructions,
+		}
+	);
+
+	// List available tools
+	server.setRequestHandler(ListToolsRequestSchema, async () => {
+		return { tools };
+	});
+
+	// Get reminder nudge - only for critical workflow reminders to save context
+	function getReminder(toolName: string): string | null {
+		// Most reminders removed to reduce context bloat - instructions are in CLAUDE.md
+		// Only keep critical continuation reminder for complete_task
+		const reminders: Record<string, string> = {
+			'complete_task': 'CONTINUE WORKING: Call get_next_task or start the next_task. If awaiting_validation tasks exist, validate them FIRST before new work. If context is large, run /clear then start_work_session to refresh.',
+			'batch_complete_tasks': 'CONTINUE WORKING: Call get_next_task. If awaiting_validation tasks exist, validate them FIRST before new work.',
+		};
+		return reminders[toolName] ?? null;
+	}
+
+	// Handle tool calls
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const { name, arguments: args } = request.params;
+
+		// Check rate limit
+		const rateCheck = rateLimiter.check(auth.apiKeyId);
+		if (!rateCheck.allowed) {
+			const resetSeconds = Math.ceil(rateCheck.resetIn / 1000);
+			return {
+				content: [
+					{
+						type: 'text',
+						text: `Rate limit exceeded. Too many requests. Please wait ${resetSeconds} seconds before trying again. (Limit: 60 requests per minute)`,
+					},
+				],
+				isError: true,
+			};
+		}
+
+		try {
+			const toolArgs = (args as Record<string, unknown>) || {};
+			const { result, user_updates } = await handleTool(
+				auth,
+				name,
+				toolArgs
+			);
+
+			// Track token usage for this call (both input args and output result)
+			trackTokenUsage(name, toolArgs, result);
+
+			const content: { type: 'text'; text: string }[] = [
+				{
+					type: 'text',
+					text: JSON.stringify(result, null, 2),
+				},
+			];
+
+			// Include reminder nudge if applicable
+			const reminder = getReminder(name);
+			if (reminder) {
+				content.push({
+					type: 'text',
+					text: `\n--- ${reminder} ---`,
+				});
+			}
+
+			// Include user updates only if there are new items (null means no updates)
+			if (user_updates) {
+				content.push({
+					type: 'text',
+					text: `\n--- New User Updates ---\n${JSON.stringify(user_updates, null, 2)}`,
+				});
+			}
+
+			// Add rate limit warning if getting low
+			if (rateCheck.remaining < 10) {
+				content.push({
+					type: 'text',
+					text: `\n--- Rate Limit Warning: ${rateCheck.remaining} requests remaining this minute ---`,
+				});
+			}
+
+			return { content };
+		} catch (error) {
+			// Handle validation errors with structured output
+			if (error instanceof ValidationError) {
+				return {
+					content: [
+						{
+							type: 'text',
+							text: JSON.stringify(error.toJSON(), null, 2),
+						},
+					],
+					isError: true,
+				};
+			}
+
+			// Handle database errors with better context
+			const errorMessage = getErrorMessage(error);
+			let hint: string | undefined;
+
+			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.';
+			} else if (errorMessage.includes('duplicate key')) {
+				hint = 'A record with this identifier already exists.';
+			} else if (errorMessage.includes('not found') || errorMessage.includes('no rows')) {
+				hint = 'The requested resource was not found. Verify the ID is correct.';
+			}
+
+			return {
+				content: [
+					{
+						type: 'text',
+						text: JSON.stringify({
+							error: 'operation_failed',
+							message: errorMessage,
+							hint,
+						}, null, 2),
+					},
+				],
+				isError: true,
+			};
+		}
+	});
+
+	// Start server
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+
+main().catch((error) => {
+	console.error('Fatal error:', error);
+	process.exit(1);
+});