@vibescope/mcp-server 0.0.1

package/src/index.ts

@@ -0,0 +1,3205 @@
+#!/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 { createClient } from '@supabase/supabase-js';
+import { randomUUID } from 'crypto';
+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,
+} from './utils.js';
+import { hashApiKey } from './cli.js';
+import { buildHandlerRegistry, type HandlerContext } from './handlers/index.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;
+
+// Token usage tracking for this session
+interface ModelTokens {
+	input: number;
+	output: number;
+}
+interface TokenUsage {
+	callCount: number;
+	totalTokens: number;
+	byTool: Record<string, { calls: number; tokens: number }>;
+	byModel: Record<string, ModelTokens>;
+	currentModel: string | null;
+}
+let sessionTokenUsage: TokenUsage = {
+	callCount: 0,
+	totalTokens: 0,
+	byTool: {},
+	byModel: {},
+	currentModel: null,
+};
+
+// Estimate tokens from JSON (rough: ~4 chars per token)
+function estimateTokens(obj: unknown): number {
+	return Math.ceil(JSON.stringify(obj).length / 4);
+}
+
+// Track token usage for a tool call (input = args, output = response)
+function trackTokenUsage(toolName: string, args: unknown, response: unknown): void {
+	const inputTokens = estimateTokens(args);
+	const outputTokens = estimateTokens(response);
+	const totalTokens = inputTokens + outputTokens;
+
+	sessionTokenUsage.callCount++;
+	sessionTokenUsage.totalTokens += totalTokens;
+
+	if (!sessionTokenUsage.byTool[toolName]) {
+		sessionTokenUsage.byTool[toolName] = { calls: 0, tokens: 0 };
+	}
+	sessionTokenUsage.byTool[toolName].calls++;
+	sessionTokenUsage.byTool[toolName].tokens += totalTokens;
+
+	// Track by model if a model is set
+	const model = sessionTokenUsage.currentModel;
+	if (model) {
+		if (!sessionTokenUsage.byModel[model]) {
+			sessionTokenUsage.byModel[model] = { input: 0, output: 0 };
+		}
+		sessionTokenUsage.byModel[model].input += inputTokens;
+		sessionTokenUsage.byModel[model].output += outputTokens;
+	}
+}
+
+// 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: "opus"|"sonnet"|"haiku") to initialize
+   - IMPORTANT: Pass your model for accurate cost tracking
+   - 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 ("opus", "sonnet", "haiku") for cost tracking
+- 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
+// ============================================================================
+
+// Default Supabase URL for Vibescope production instance
+const DEFAULT_SUPABASE_URL = 'https://uuneucmuubpgswvfijwd.supabase.co';
+
+const SUPABASE_URL = process.env.SUPABASE_URL || process.env.PUBLIC_SUPABASE_URL || DEFAULT_SUPABASE_URL;
+const SUPABASE_SERVICE_KEY = process.env.SUPABASE_SERVICE_KEY;
+const API_KEY = process.env.VIBESCOPE_API_KEY;
+
+if (!SUPABASE_SERVICE_KEY) {
+	console.error('Missing required environment variable: SUPABASE_SERVICE_KEY');
+	process.exit(1);
+}
+
+if (!API_KEY) {
+	console.error('Missing required environment variable: VIBESCOPE_API_KEY');
+	process.exit(1);
+}
+
+// ============================================================================
+// Database Client
+// ============================================================================
+
+// Using untyped client for MCP server - data validation happens at runtime
+const supabase = createClient(SUPABASE_URL, SUPABASE_SERVICE_KEY);
+
+// ============================================================================
+// Authentication
+// ============================================================================
+
+async function validateApiKey(apiKey: string): Promise<AuthContext | null> {
+	const keyHash = hashApiKey(apiKey);
+
+	const { data, error } = await supabase
+		.from('api_keys')
+		.select('id, user_id, organization_id, scope, is_valid')
+		.eq('key_hash', keyHash)
+		.single();
+
+	if (error || !data) {
+		return null;
+	}
+
+	// Check if key has been invalidated (e.g., user left org)
+	if (data.is_valid === false) {
+		return null;
+	}
+
+	// For org-scoped keys, verify user is still a member
+	if (data.scope === 'organization' && data.organization_id) {
+		const { data: member } = await supabase
+			.from('organization_members')
+			.select('role')
+			.eq('organization_id', data.organization_id)
+			.eq('user_id', data.user_id)
+			.single();
+
+		if (!member) {
+			// User is no longer a member, invalidate the key
+			await supabase
+				.from('api_keys')
+				.update({ is_valid: false })
+				.eq('id', data.id);
+			return null;
+		}
+	}
+
+	// Update last_used_at
+	await supabase
+		.from('api_keys')
+		.update({ last_used_at: new Date().toISOString() })
+		.eq('id', data.id);
+
+	return {
+		userId: data.user_id,
+		apiKeyId: data.id,
+		organizationId: data.organization_id || undefined,
+		scope: data.scope || 'personal',
+	};
+}
+
+// ============================================================================
+// Session Status Checking (Multi-Agent Coordination)
+// ============================================================================
+
+/**
+ * Check if an agent session is active or stale.
+ * A session is considered stale if:
+ * - It doesn't exist (orphaned reference)
+ * - Its status is 'disconnected'
+ * - Its last_synced_at is older than 5 minutes
+ */
+async function checkSessionStatus(
+	sessionId: string
+): Promise<{ exists: boolean; isActive: boolean; agentName?: string }> {
+	const { data: session } = await supabase
+		.from('agent_sessions')
+		.select('id, status, last_synced_at, agent_name, instance_id')
+		.eq('id', sessionId)
+		.single();
+
+	if (!session) {
+		return { exists: false, isActive: false };
+	}
+
+	const lastSync = new Date(session.last_synced_at).getTime();
+	const fiveMinutesAgo = Date.now() - 5 * 60 * 1000;
+	const isActive = session.status !== 'disconnected' && lastSync > fiveMinutesAgo;
+
+	return {
+		exists: true,
+		isActive,
+		agentName: session.agent_name || `Agent ${session.instance_id?.slice(0, 8) || sessionId.slice(0, 8)}`,
+	};
+}
+
+// ============================================================================
+// User Updates Tracking
+// ============================================================================
+
+async function getUserUpdates(
+	auth: AuthContext,
+	projectId: string
+): Promise<UserUpdates | undefined> {
+	// Get session's last_synced_at - prefer currentSessionId for accuracy
+	let lastSyncedAt: string;
+
+	if (currentSessionId) {
+		const { data: session } = await supabase
+			.from('agent_sessions')
+			.select('last_synced_at')
+			.eq('id', currentSessionId)
+			.single();
+		lastSyncedAt = session?.last_synced_at || new Date(0).toISOString();
+	} else {
+		const { data: session } = await supabase
+			.from('agent_sessions')
+			.select('last_synced_at')
+			.eq('api_key_id', auth.apiKeyId)
+			.eq('project_id', projectId)
+			.single();
+		lastSyncedAt = session?.last_synced_at || new Date(0).toISOString();
+	}
+
+	// Fetch user-created items since last sync (limit to 5 each for context efficiency)
+	const [tasksResult, blockersResult, ideasResult] = await Promise.all([
+		supabase
+			.from('tasks')
+			.select('id, title, created_at')
+			.eq('project_id', projectId)
+			.eq('created_by', 'user')
+			.gt('created_at', lastSyncedAt)
+			.order('created_at', { ascending: false })
+			.limit(5),
+		supabase
+			.from('blockers')
+			.select('id, description, created_at')
+			.eq('project_id', projectId)
+			.eq('created_by', 'user')
+			.gt('created_at', lastSyncedAt)
+			.order('created_at', { ascending: false })
+			.limit(5),
+		supabase
+			.from('ideas')
+			.select('id, title, created_at')
+			.eq('project_id', projectId)
+			.eq('created_by', 'user')
+			.gt('created_at', lastSyncedAt)
+			.order('created_at', { ascending: false })
+			.limit(5),
+	]);
+
+	const tasks = tasksResult.data || [];
+	const blockers = blockersResult.data || [];
+	const ideas = ideasResult.data || [];
+
+	// Return undefined if no new updates (saves context window space)
+	if (tasks.length === 0 && blockers.length === 0 && ideas.length === 0) {
+		return undefined;
+	}
+
+	return { tasks, blockers, ideas };
+}
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+const tools: Tool[] = [
+	{
+		name: 'start_work_session',
+		description: `CALL THIS FIRST when beginning work on a project.
+Returns session info, persona, and next task. Use mode:'full' for complete context.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				git_url: {
+					type: 'string',
+					description: 'Git repository URL. Used to find project if project_id not provided.',
+				},
+				mode: {
+					type: 'string',
+					enum: ['lite', 'full'],
+					description: 'Response mode: lite (default, minimal tokens) or full (complete context)',
+				},
+				model: {
+					type: 'string',
+					enum: ['opus', 'sonnet', 'haiku'],
+					description: 'Claude model being used (for accurate cost tracking). E.g., "opus", "sonnet", "haiku".',
+				},
+			},
+		},
+	},
+	{
+		name: 'get_help',
+		description: 'Get guidance on a specific topic. Use when unsure about workflows.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				topic: {
+					type: 'string',
+					enum: ['getting_started', 'tasks', 'validation', 'deployment', 'git', 'blockers', 'milestones', 'fallback', 'session', 'tokens', 'topics'],
+					description: 'Help topic. Use "topics" to list all available.',
+				},
+			},
+			required: ['topic'],
+		},
+	},
+	{
+		name: 'get_token_usage',
+		description: 'Get token usage stats for this session. Monitor efficiency.',
+		inputSchema: {
+			type: 'object',
+			properties: {},
+		},
+	},
+	// Cost monitoring tools
+	{
+		name: 'get_cost_summary',
+		description: 'Get cost summary (daily/weekly/monthly) for a project.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				period: {
+					type: 'string',
+					enum: ['daily', 'weekly', 'monthly'],
+					description: 'Summary period (default: daily)',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max records to return (default: 30)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'get_cost_alerts',
+		description: 'Get cost alerts for the current user.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Filter by project (optional)',
+				},
+			},
+		},
+	},
+	{
+		name: 'add_cost_alert',
+		description: 'Add a cost alert threshold.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID (null for all projects)',
+				},
+				threshold_amount: {
+					type: 'number',
+					description: 'Amount in USD that triggers the alert',
+				},
+				threshold_period: {
+					type: 'string',
+					enum: ['daily', 'weekly', 'monthly'],
+					description: 'Period for the threshold',
+				},
+				alert_type: {
+					type: 'string',
+					enum: ['warning', 'critical'],
+					description: 'Alert severity (default: warning)',
+				},
+			},
+			required: ['threshold_amount', 'threshold_period'],
+		},
+	},
+	{
+		name: 'update_cost_alert',
+		description: 'Update a cost alert.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				alert_id: {
+					type: 'string',
+					description: 'Alert UUID',
+				},
+				threshold_amount: {
+					type: 'number',
+					description: 'New threshold amount in USD',
+				},
+				threshold_period: {
+					type: 'string',
+					enum: ['daily', 'weekly', 'monthly'],
+					description: 'New period',
+				},
+				alert_type: {
+					type: 'string',
+					enum: ['warning', 'critical'],
+					description: 'New alert type',
+				},
+				enabled: {
+					type: 'boolean',
+					description: 'Enable or disable the alert',
+				},
+			},
+			required: ['alert_id'],
+		},
+	},
+	{
+		name: 'delete_cost_alert',
+		description: 'Delete a cost alert.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				alert_id: {
+					type: 'string',
+					description: 'Alert UUID to delete',
+				},
+			},
+			required: ['alert_id'],
+		},
+	},
+	{
+		name: 'get_task_costs',
+		description: 'Get cost breakdown by task for a project.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max tasks to return (default: 20)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'discover_tools',
+		description: 'List tools by category. Use get_tool_info for details.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				category: {
+					type: 'string',
+					enum: ['session', 'project', 'tasks', 'milestones', 'progress', 'blockers', 'decisions', 'ideas', 'findings', 'validation', 'deployment', 'fallback', 'requests', 'organizations', 'cost'],
+					description: 'Category to list (omit for all categories)',
+				},
+			},
+		},
+	},
+	{
+		name: 'get_tool_info',
+		description: 'Get detailed tool documentation.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				tool_name: {
+					type: 'string',
+					description: 'Tool name',
+				},
+			},
+			required: ['tool_name'],
+		},
+	},
+	{
+		name: 'get_project_context',
+		description: 'Get full project context: goals, instructions, tasks, blockers, decisions.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID. If not provided, will list all projects.',
+				},
+				git_url: {
+					type: 'string',
+					description: 'Git repository URL. Used to find project if project_id not provided.',
+				},
+			},
+		},
+	},
+	{
+		name: 'get_git_workflow',
+		description: 'Get git workflow config and branching instructions for the project.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				task_id: {
+					type: 'string',
+					description: 'Optional task ID to include branch naming suggestion',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'create_project',
+		description: 'Create a new project to track in Vibescope.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				name: {
+					type: 'string',
+					description: 'Project display name',
+				},
+				description: {
+					type: 'string',
+					description: 'Brief project description',
+				},
+				goal: {
+					type: 'string',
+					description: 'What does "done" look like for this project?',
+				},
+				git_url: {
+					type: 'string',
+					description: 'Git repository URL (if available)',
+				},
+				tech_stack: {
+					type: 'array',
+					items: { type: 'string' },
+					description: 'Technologies used (e.g., ["TypeScript", "React", "PostgreSQL"])',
+				},
+			},
+			required: ['name'],
+		},
+	},
+	{
+		name: 'update_project',
+		description: 'Update project details (name, description, goal, settings).',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				name: { type: 'string' },
+				description: { type: 'string' },
+				goal: { type: 'string' },
+				git_url: { type: 'string' },
+				tech_stack: {
+					type: 'array',
+					items: { type: 'string' },
+				},
+				status: {
+					type: 'string',
+					enum: ['active', 'paused', 'completed', 'archived'],
+				},
+				git_workflow: {
+					type: 'string',
+					enum: ['none', 'trunk-based', 'github-flow', 'git-flow'],
+					description: 'Git workflow: none (no branching), trunk-based (commit to main), github-flow (feature branches + PR), git-flow (develop/release branches)',
+				},
+				git_main_branch: {
+					type: 'string',
+					description: 'Main branch name (default: main)',
+				},
+				git_develop_branch: {
+					type: 'string',
+					description: 'Development branch name (used with git-flow)',
+				},
+				git_auto_branch: {
+					type: 'boolean',
+					description: 'Automatically create feature branches for new tasks',
+				},
+				git_auto_tag: {
+					type: 'boolean',
+					description: 'Automatically tag deployments on main branch',
+				},
+				deployment_instructions: {
+					type: 'string',
+					description: 'Instructions for how to deploy (e.g., "Push to main for Vercel auto-deploy", "Run fly deploy")',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'update_project_readme',
+		description: 'Sync README content to the dashboard.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				readme_content: {
+					type: 'string',
+					description: 'README content in markdown format',
+				},
+			},
+			required: ['project_id', 'readme_content'],
+		},
+	},
+	{
+		name: 'get_tasks',
+		description: 'Get tasks for a project, optionally filtered by status. By default returns only root tasks (not subtasks).',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				status: {
+					type: 'string',
+					enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'],
+					description: 'Filter by status (optional)',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max number of tasks to return (default 50)',
+				},
+				include_subtasks: {
+					type: 'boolean',
+					description: 'Include subtasks in results (default false). Use get_subtasks for subtasks of a specific task.',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'get_next_task',
+		description: 'Get highest priority pending task. Skips claimed tasks. Check deployment_blocks_tasks first.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'add_task',
+		description: 'Add a new task. Priority 1=highest, 5=lowest. Include estimated_minutes. Use blocking=true for deployment finalization tasks that must complete before other work.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				title: {
+					type: 'string',
+					description: 'Task title',
+				},
+				description: {
+					type: 'string',
+					description: 'Detailed description',
+				},
+				priority: {
+					type: 'number',
+					minimum: 1,
+					maximum: 5,
+					description: 'Priority 1-5 (1 = highest)',
+				},
+				estimated_minutes: {
+					type: 'number',
+					minimum: 1,
+					description: 'Estimated time to complete in minutes',
+				},
+				blocking: {
+					type: 'boolean',
+					description: 'When true, this task blocks all other work until complete (used for deployment finalization)',
+				},
+			},
+			required: ['project_id', 'title'],
+		},
+	},
+	{
+		name: 'update_task',
+		description: 'Update task status, progress, or details. Include progress_note with progress_percentage.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+				title: { type: 'string' },
+				description: { type: 'string' },
+				priority: {
+					type: 'number',
+					minimum: 1,
+					maximum: 5,
+				},
+				status: {
+					type: 'string',
+					enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'],
+				},
+				progress_percentage: {
+					type: 'number',
+					minimum: 0,
+					maximum: 100,
+					description: '0-100 completion percentage',
+				},
+				progress_note: {
+					type: 'string',
+					description: 'Brief note (auto-logged)',
+				},
+				estimated_minutes: {
+					type: 'number',
+					minimum: 1,
+					description: 'Revised time estimate',
+				},
+				git_branch: {
+					type: 'string',
+					description: 'Git branch associated with this task',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	{
+		name: 'complete_task',
+		description: 'Mark task done. Returns next_task and context counts (validation, blockers, deployment).',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+				summary: {
+					type: 'string',
+					description: 'Brief summary of what was done',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	{
+		name: 'log_progress',
+		description: `Log progress update. Record significant milestones or observations.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				task_id: {
+					type: 'string',
+					description: 'Task UUID (optional, links progress to specific task)',
+				},
+				summary: {
+					type: 'string',
+					description: 'Brief summary of progress',
+				},
+				details: {
+					type: 'string',
+					description: 'Detailed notes (optional)',
+				},
+			},
+			required: ['project_id', 'summary'],
+		},
+	},
+	{
+		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_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)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'log_decision',
+		description: `Record an architectural or technical decision with rationale.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				title: {
+					type: 'string',
+					description: 'Decision title (e.g., "Use PostgreSQL for database")',
+				},
+				description: {
+					type: 'string',
+					description: 'What was decided',
+				},
+				rationale: {
+					type: 'string',
+					description: 'Why this decision was made',
+				},
+				alternatives_considered: {
+					type: 'array',
+					items: { type: 'string' },
+					description: 'Other options that were considered',
+				},
+			},
+			required: ['project_id', 'title', 'description'],
+		},
+	},
+	{
+		name: 'get_decisions',
+		description: `Get recorded decisions for a project.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'add_idea',
+		description: `Record an idea for improvements or features. Starts as 'raw', can progress to 'shipped'.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				title: {
+					type: 'string',
+					description: 'Idea title',
+				},
+				description: {
+					type: 'string',
+					description: 'Detailed description',
+				},
+				status: {
+					type: 'string',
+					enum: ['raw', 'exploring', 'planned', 'in_development', 'shipped'],
+					description: 'Development stage (default: raw)',
+				},
+			},
+			required: ['project_id', 'title'],
+		},
+	},
+	{
+		name: 'update_idea',
+		description: `Update an idea's status or details.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				idea_id: {
+					type: 'string',
+					description: 'Idea UUID',
+				},
+				title: {
+					type: 'string',
+					description: 'Updated title',
+				},
+				description: {
+					type: 'string',
+					description: 'Updated description',
+				},
+				status: {
+					type: 'string',
+					enum: ['raw', 'exploring', 'planned', 'in_development', 'shipped'],
+					description: 'New development stage',
+				},
+				doc_url: {
+					type: 'string',
+					description: 'URL to feature documentation/specification',
+				},
+			},
+			required: ['idea_id'],
+		},
+	},
+	{
+		name: 'get_ideas',
+		description: `Get recorded ideas for a project, optionally filtered by status.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				status: {
+					type: 'string',
+					enum: ['raw', 'exploring', 'planned', 'in_development', 'shipped'],
+					description: 'Filter by status (optional)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'delete_task',
+		description: `Delete a task.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	{
+		name: 'add_task_reference',
+		description: 'Add a reference URL to a task (docs, PRs, issues).',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+				url: {
+					type: 'string',
+					description: 'URL to add as reference',
+				},
+				label: {
+					type: 'string',
+					description: 'Optional label/title for the reference',
+				},
+			},
+			required: ['task_id', 'url'],
+		},
+	},
+	{
+		name: 'remove_task_reference',
+		description: `Remove a reference link from a task by URL.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+				url: {
+					type: 'string',
+					description: 'URL of the reference to remove',
+				},
+			},
+			required: ['task_id', 'url'],
+		},
+	},
+	{
+		name: 'delete_idea',
+		description: `Delete an idea.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				idea_id: {
+					type: 'string',
+					description: 'Idea UUID',
+				},
+			},
+			required: ['idea_id'],
+		},
+	},
+	{
+		name: 'convert_idea_to_task',
+		description: `Convert an idea to a task. Creates a task from the idea's title and description, links them, and optionally updates the idea status to 'in_development'. Useful for planned ideas that are ready for implementation.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				idea_id: {
+					type: 'string',
+					description: 'Idea UUID to convert',
+				},
+				priority: {
+					type: 'number',
+					minimum: 1,
+					maximum: 5,
+					description: 'Task priority 1-5 (default: 3, 1 = highest)',
+				},
+				estimated_minutes: {
+					type: 'number',
+					minimum: 1,
+					description: 'Estimated time to complete in minutes',
+				},
+				update_status: {
+					type: 'boolean',
+					description: "Update idea status to 'in_development' (default: true)",
+				},
+			},
+			required: ['idea_id'],
+		},
+	},
+	// Findings (knowledge base)
+	{
+		name: 'add_finding',
+		description: 'Record a finding from an audit/review (performance, security, code quality, etc).',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: { type: 'string', description: 'Project UUID' },
+				category: { type: 'string', enum: ['performance', 'security', 'code_quality', 'accessibility', 'documentation', 'architecture', 'testing', 'other'], description: 'Category of the finding (default: other)' },
+				title: { type: 'string', description: 'Brief title describing the finding' },
+				description: { type: 'string', description: 'Detailed description of the finding, including impact and suggested fix' },
+				severity: { type: 'string', enum: ['info', 'low', 'medium', 'high', 'critical'], description: 'Severity level (default: info)' },
+				file_path: { type: 'string', description: 'File path where the issue was found (optional)' },
+				line_number: { type: 'number', description: 'Line number in the file (optional)' },
+				related_task_id: { type: 'string', description: 'ID of related task if this finding came from a task (optional)' },
+			},
+			required: ['project_id', 'title'],
+		},
+	},
+	{
+		name: 'get_findings',
+		description: `Get findings for a project, optionally filtered by category, severity, or status.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: { type: 'string', description: 'Project UUID' },
+				category: { type: 'string', enum: ['performance', 'security', 'code_quality', 'accessibility', 'documentation', 'architecture', 'testing', 'other'], description: 'Filter by category (optional)' },
+				severity: { type: 'string', enum: ['info', 'low', 'medium', 'high', 'critical'], description: 'Filter by severity (optional)' },
+				status: { type: 'string', enum: ['open', 'addressed', 'dismissed', 'wontfix'], description: 'Filter by status (default: all)' },
+				limit: { type: 'number', description: 'Max number of findings to return (default 50)' },
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'update_finding',
+		description: `Update a finding's status or details. Use to mark findings as addressed or dismissed.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				finding_id: { type: 'string', description: 'Finding UUID' },
+				status: { type: 'string', enum: ['open', 'addressed', 'dismissed', 'wontfix'], description: 'New status' },
+				resolution_note: { type: 'string', description: 'Note explaining how the finding was addressed or why it was dismissed' },
+				title: { type: 'string', description: 'Updated title' },
+				description: { type: 'string', description: 'Updated description' },
+				severity: { type: 'string', enum: ['info', 'low', 'medium', 'high', 'critical'], description: 'Updated severity' },
+			},
+			required: ['finding_id'],
+		},
+	},
+	{
+		name: 'delete_finding',
+		description: `Delete a finding.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				finding_id: { type: 'string', description: 'Finding UUID' },
+			},
+			required: ['finding_id'],
+		},
+	},
+	{
+		name: 'delete_blocker',
+		description: `Delete a blocker.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				blocker_id: {
+					type: 'string',
+					description: 'Blocker UUID',
+				},
+			},
+			required: ['blocker_id'],
+		},
+	},
+	{
+		name: 'delete_decision',
+		description: `Delete a decision.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				decision_id: {
+					type: 'string',
+					description: 'Decision UUID',
+				},
+			},
+			required: ['decision_id'],
+		},
+	},
+	{
+		name: 'get_activity_feed',
+		description: `Get combined activity feed (tasks, progress, blockers, decisions) in chronological order.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				types: {
+					type: 'array',
+					items: {
+						type: 'string',
+						enum: ['task', 'progress', 'blocker', 'decision'],
+					},
+					description: 'Filter by activity types (default: all)',
+				},
+				created_by: {
+					type: 'string',
+					enum: ['agent', 'user'],
+					description: 'Filter by creator (default: all)',
+				},
+				since: {
+					type: 'string',
+					description: 'ISO date string - only return activity after this time',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max number of items to return (default 50, max 200)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'batch_update_tasks',
+		description: 'Update multiple tasks at once. Include progress_note with progress_percentage.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				updates: {
+					type: 'array',
+					description: 'Array of task updates to apply',
+					items: {
+						type: 'object',
+						properties: {
+							task_id: { type: 'string', description: 'Task UUID' },
+							status: { type: 'string', enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'] },
+							progress_percentage: { type: 'number', minimum: 0, maximum: 100 },
+							progress_note: { type: 'string', description: 'Brief note about what was achieved' },
+							priority: { type: 'number', minimum: 1, maximum: 5 },
+						},
+						required: ['task_id'],
+					},
+				},
+			},
+			required: ['updates'],
+		},
+	},
+	{
+		name: 'batch_complete_tasks',
+		description: `Mark multiple tasks as completed at once.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				completions: {
+					type: 'array',
+					description: 'Array of task completions',
+					items: {
+						type: 'object',
+						properties: {
+							task_id: { type: 'string', description: 'Task UUID' },
+							summary: { type: 'string', description: 'Optional completion summary' },
+						},
+						required: ['task_id'],
+					},
+				},
+			},
+			required: ['completions'],
+		},
+	},
+	// =========================================================================
+	// Subtask Tools
+	// =========================================================================
+	{
+		name: 'add_subtask',
+		description: `Add a subtask to break down a larger task into smaller workable pieces.
+Subtasks can be claimed and worked on independently by any agent.
+Subtasks inherit the project from their parent task.
+Max depth is 1 (subtasks cannot have their own subtasks).`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				parent_task_id: {
+					type: 'string',
+					description: 'UUID of the parent task to add subtask to',
+				},
+				title: {
+					type: 'string',
+					description: 'Subtask title',
+				},
+				description: {
+					type: 'string',
+					description: 'Detailed description (optional)',
+				},
+				priority: {
+					type: 'number',
+					minimum: 1,
+					maximum: 5,
+					description: 'Priority 1-5 (1 = highest). Defaults to parent task priority.',
+				},
+				estimated_minutes: {
+					type: 'number',
+					minimum: 1,
+					description: 'Estimated time to complete in minutes',
+				},
+			},
+			required: ['parent_task_id', 'title'],
+		},
+	},
+	{
+		name: 'get_subtasks',
+		description: `Get subtasks for a parent task.
+Returns subtasks with aggregate completion stats.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				parent_task_id: {
+					type: 'string',
+					description: 'UUID of the parent task',
+				},
+				status: {
+					type: 'string',
+					enum: ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'],
+					description: 'Filter by status (optional)',
+				},
+			},
+			required: ['parent_task_id'],
+		},
+	},
+	{
+		name: 'heartbeat',
+		description: `Send heartbeat to maintain 'active' status. Call every 30-60 seconds.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				session_id: {
+					type: 'string',
+					description: 'Session ID from start_work_session (optional, uses current session if not provided)',
+				},
+			},
+		},
+	},
+	{
+		name: 'end_work_session',
+		description: `End session and release claimed tasks. Returns session summary.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				session_id: {
+					type: 'string',
+					description: 'Session ID to end (optional, uses current session if not provided)',
+				},
+			},
+		},
+	},
+	// =========================================================================
+	// Task Validation Tools
+	// =========================================================================
+	{
+		name: 'get_tasks_awaiting_validation',
+		description: `Get completed tasks not yet validated.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'claim_validation',
+		description: 'Claim a completed task for review. Shows "being reviewed" on dashboard.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID to claim for review',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	{
+		name: 'validate_task',
+		description: 'Validate a completed task. Include test results in validation_notes.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID to validate',
+				},
+				validation_notes: {
+					type: 'string',
+					description: 'Notes about the validation (what was checked, any issues found)',
+				},
+				approved: {
+					type: 'boolean',
+					description: 'Whether the task passes validation (true = approved, false = needs more work)',
+				},
+			},
+			required: ['task_id', 'approved'],
+		},
+	},
+	// =========================================================================
+	// Deployment Coordination Tools
+	// =========================================================================
+	{
+		name: 'request_deployment',
+		description: 'Request a deployment. Requires validation first. One active deployment per project.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				environment: {
+					type: 'string',
+					enum: ['development', 'staging', 'production'],
+					description: 'Target environment (default: production)',
+				},
+				version_bump: {
+					type: 'string',
+					enum: ['patch', 'minor', 'major'],
+					description: 'Version bump: major/minor/patch (default: patch)',
+				},
+				notes: {
+					type: 'string',
+					description: 'Optional notes about this deployment',
+				},
+				git_ref: {
+					type: 'string',
+					description: 'Git branch or commit being deployed',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'claim_deployment_validation',
+		description: `Claim pending deployment for validation. Run build+tests, then call report_validation.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'report_validation',
+		description: `Report build/test results. If passed, status->'ready'. If failed, creates investigation task.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				build_passed: {
+					type: 'boolean',
+					description: 'Whether the build succeeded',
+				},
+				tests_passed: {
+					type: 'boolean',
+					description: 'Whether the tests passed',
+				},
+				error_message: {
+					type: 'string',
+					description: 'Error details if validation failed',
+				},
+			},
+			required: ['project_id', 'build_passed', 'tests_passed'],
+		},
+	},
+	{
+		name: 'check_deployment_status',
+		description: `Get active deployment status and details.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'start_deployment',
+		description: `Start deployment (requires 'ready' status). Sets status to 'deploying'.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'complete_deployment',
+		description: `Mark deployment as complete (success or failure).`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				success: {
+					type: 'boolean',
+					description: 'Whether the deployment succeeded',
+				},
+				summary: {
+					type: 'string',
+					description: 'Summary of what was deployed or why it failed',
+				},
+			},
+			required: ['project_id', 'success'],
+		},
+	},
+	{
+		name: 'cancel_deployment',
+		description: `Cancel active deployment. Sets status to 'failed'.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				reason: {
+					type: 'string',
+					description: 'Reason for cancellation',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'add_deployment_requirement',
+		description: `Add a pre-deployment requirement (migration, env var, config change). These are shown as a checklist before deployment.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				type: {
+					type: 'string',
+					description: 'Type of requirement',
+					enum: ['migration', 'env_var', 'config', 'manual', 'breaking_change', 'agent_task'],
+				},
+				title: {
+					type: 'string',
+					description: 'Brief description (e.g., "Run migration: 20250114_token_tracking.sql")',
+				},
+				description: {
+					type: 'string',
+					description: 'Optional detailed instructions',
+				},
+				file_path: {
+					type: 'string',
+					description: 'Optional file path reference',
+				},
+				stage: {
+					type: 'string',
+					description: 'Deployment stage: preparation (default), deployment, or verification',
+					enum: ['preparation', 'deployment', 'verification'],
+				},
+				blocking: {
+					type: 'boolean',
+					description: 'When true, converted task blocks all other work until complete',
+				},
+			},
+			required: ['project_id', 'type', 'title'],
+		},
+	},
+	{
+		name: 'complete_deployment_requirement',
+		description: `Mark a deployment requirement as completed.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				requirement_id: {
+					type: 'string',
+					description: 'Requirement UUID',
+				},
+			},
+			required: ['requirement_id'],
+		},
+	},
+	{
+		name: 'get_deployment_requirements',
+		description: `Get pending deployment requirements for a project.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				status: {
+					type: 'string',
+					description: 'Filter by status (default: pending)',
+					enum: ['pending', 'completed', 'converted_to_task', 'all'],
+				},
+				stage: {
+					type: 'string',
+					description: 'Filter by stage (optional)',
+					enum: ['preparation', 'deployment', 'verification', 'all'],
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'schedule_deployment',
+		description: `Schedule a deployment for a specific time. Supports one-time and recurring schedules with auto-trigger or manual trigger modes.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				scheduled_at: {
+					type: 'string',
+					description: 'ISO 8601 datetime for when the deployment should be triggered',
+				},
+				schedule_type: {
+					type: 'string',
+					description: 'Schedule type: once (one-time), daily, weekly, or monthly',
+					enum: ['once', 'daily', 'weekly', 'monthly'],
+				},
+				auto_trigger: {
+					type: 'boolean',
+					description: 'Whether agents should automatically trigger this deployment when due (default: true)',
+				},
+				environment: {
+					type: 'string',
+					description: 'Target environment (default: production)',
+					enum: ['development', 'staging', 'production'],
+				},
+				version_bump: {
+					type: 'string',
+					description: 'Version bump: patch, minor, or major (default: patch)',
+					enum: ['patch', 'minor', 'major'],
+				},
+				notes: {
+					type: 'string',
+					description: 'Optional notes about this scheduled deployment',
+				},
+				git_ref: {
+					type: 'string',
+					description: 'Optional git branch or commit to deploy',
+				},
+			},
+			required: ['project_id', 'scheduled_at'],
+		},
+	},
+	{
+		name: 'get_scheduled_deployments',
+		description: `Get scheduled deployments for a project.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				include_disabled: {
+					type: 'boolean',
+					description: 'Include disabled schedules (default: false)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'update_scheduled_deployment',
+		description: `Update a scheduled deployment's configuration.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				schedule_id: {
+					type: 'string',
+					description: 'Schedule UUID',
+				},
+				scheduled_at: {
+					type: 'string',
+					description: 'New scheduled time (ISO 8601)',
+				},
+				schedule_type: {
+					type: 'string',
+					description: 'New schedule type',
+					enum: ['once', 'daily', 'weekly', 'monthly'],
+				},
+				auto_trigger: {
+					type: 'boolean',
+					description: 'Whether to auto-trigger',
+				},
+				enabled: {
+					type: 'boolean',
+					description: 'Enable or disable the schedule',
+				},
+				environment: {
+					type: 'string',
+					description: 'Target environment',
+					enum: ['development', 'staging', 'production'],
+				},
+				version_bump: {
+					type: 'string',
+					description: 'Version bump type',
+					enum: ['patch', 'minor', 'major'],
+				},
+				notes: {
+					type: 'string',
+					description: 'Notes about this deployment',
+				},
+				git_ref: {
+					type: 'string',
+					description: 'Git branch or commit to deploy',
+				},
+			},
+			required: ['schedule_id'],
+		},
+	},
+	{
+		name: 'delete_scheduled_deployment',
+		description: `Delete a scheduled deployment.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				schedule_id: {
+					type: 'string',
+					description: 'Schedule UUID',
+				},
+			},
+			required: ['schedule_id'],
+		},
+	},
+	{
+		name: 'trigger_scheduled_deployment',
+		description: `Manually trigger a scheduled deployment. Creates a new deployment and updates the schedule.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				schedule_id: {
+					type: 'string',
+					description: 'Schedule UUID',
+				},
+			},
+			required: ['schedule_id'],
+		},
+	},
+	{
+		name: 'check_due_deployments',
+		description: `Check for scheduled deployments that are due. Returns schedules where: enabled AND auto_trigger AND scheduled_at <= NOW().`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'start_fallback_activity',
+		description: `Start a background activity when no tasks available.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				activity: {
+					type: 'string',
+					description: 'The fallback activity type (e.g., code_review, security_review)',
+					enum: [
+						'feature_ideation',
+						'code_review',
+						'performance_audit',
+						'ux_review',
+						'cost_analysis',
+						'security_review',
+						'test_coverage',
+						'documentation_review',
+						'dependency_audit',
+						'validate_completed_tasks',
+					],
+				},
+			},
+			required: ['project_id', 'activity'],
+		},
+	},
+	{
+		name: 'stop_fallback_activity',
+		description: `Stop current fallback activity. Auto-clears when starting a regular task.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				summary: {
+					type: 'string',
+					description: 'Optional summary of what was accomplished during this activity',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'get_activity_history',
+		description: `Get background activity completion history.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				activity_type: {
+					type: 'string',
+					description: 'Optional: filter to a specific activity type',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max number of history entries to return (default 50)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'get_activity_schedules',
+		description: `Get background activity schedules.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	// =========================================================================
+	// Agent Request Tools
+	// =========================================================================
+	{
+		name: 'get_pending_requests',
+		description: `Get unacknowledged user requests for this agent/project.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'acknowledge_request',
+		description: `Mark a user request as handled.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				request_id: {
+					type: 'string',
+					description: 'Request UUID to acknowledge',
+				},
+			},
+			required: ['request_id'],
+		},
+	},
+	{
+		name: 'answer_question',
+		description: `Answer a question from the user. Use this when the user has asked a question via the dashboard.
+The answer will be displayed to the user and the question marked as answered.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				request_id: {
+					type: 'string',
+					description: 'Request UUID of the question to answer',
+				},
+				answer: {
+					type: 'string',
+					description: 'Your answer to the user\'s question',
+				},
+			},
+			required: ['request_id', 'answer'],
+		},
+	},
+	// ============================================================================
+	// Milestone Tools
+	// ============================================================================
+	{
+		name: 'add_milestone',
+		description: `Add a milestone to a task.
+Milestones help break down large tasks into smaller trackable steps.
+Use this to show progress on complex tasks and help gauge completion.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID to add milestone to',
+				},
+				title: {
+					type: 'string',
+					description: 'Milestone title (brief description of what needs to be done)',
+				},
+				description: {
+					type: 'string',
+					description: 'Optional detailed description',
+				},
+				order_index: {
+					type: 'number',
+					minimum: 0,
+					description: 'Order of this milestone (0-based, defaults to end of list)',
+				},
+			},
+			required: ['task_id', 'title'],
+		},
+	},
+	{
+		name: 'update_milestone',
+		description: `Update a milestone's title, description, status, or order.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				milestone_id: {
+					type: 'string',
+					description: 'Milestone UUID',
+				},
+				title: {
+					type: 'string',
+					description: 'Updated title',
+				},
+				description: {
+					type: 'string',
+					description: 'Updated description',
+				},
+				status: {
+					type: 'string',
+					enum: ['pending', 'in_progress', 'completed'],
+					description: 'Milestone status',
+				},
+				order_index: {
+					type: 'number',
+					minimum: 0,
+					description: 'Updated order',
+				},
+			},
+			required: ['milestone_id'],
+		},
+	},
+	{
+		name: 'complete_milestone',
+		description: `Mark a milestone as completed. This is a convenience wrapper for update_milestone with status=completed.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				milestone_id: {
+					type: 'string',
+					description: 'Milestone UUID',
+				},
+			},
+			required: ['milestone_id'],
+		},
+	},
+	{
+		name: 'delete_milestone',
+		description: `Delete a milestone from a task.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				milestone_id: {
+					type: 'string',
+					description: 'Milestone UUID',
+				},
+			},
+			required: ['milestone_id'],
+		},
+	},
+	{
+		name: 'get_milestones',
+		description: `Get all milestones for a task, ordered by order_index.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	// ============================================================================
+	// Bodies of Work Tools
+	// ============================================================================
+	{
+		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'],
+		},
+	},
+	// ============================================================================
+	// Organization Tools
+	// ============================================================================
+	{
+		name: 'list_organizations',
+		description: 'List organizations the current user belongs to.',
+		inputSchema: {
+			type: 'object',
+			properties: {},
+		},
+	},
+	{
+		name: 'create_organization',
+		description: 'Create a new organization. You become the owner.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				name: {
+					type: 'string',
+					description: 'Organization display name',
+				},
+				description: {
+					type: 'string',
+					description: 'Brief description of the organization',
+				},
+				slug: {
+					type: 'string',
+					description: 'URL-friendly identifier (auto-generated from name if not provided)',
+				},
+			},
+			required: ['name'],
+		},
+	},
+	{
+		name: 'update_organization',
+		description: 'Update organization details. Requires admin role.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				organization_id: {
+					type: 'string',
+					description: 'Organization UUID',
+				},
+				name: {
+					type: 'string',
+					description: 'New organization name',
+				},
+				description: {
+					type: 'string',
+					description: 'New description',
+				},
+				logo_url: {
+					type: 'string',
+					description: 'URL to organization logo',
+				},
+			},
+			required: ['organization_id'],
+		},
+	},
+	{
+		name: 'delete_organization',
+		description: 'Delete an organization. Requires owner role. Removes all shares.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				organization_id: {
+					type: 'string',
+					description: 'Organization UUID',
+				},
+			},
+			required: ['organization_id'],
+		},
+	},
+	{
+		name: 'list_org_members',
+		description: 'List members of an organization.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				organization_id: {
+					type: 'string',
+					description: 'Organization UUID',
+				},
+			},
+			required: ['organization_id'],
+		},
+	},
+	{
+		name: 'invite_member',
+		description: 'Invite a user to an organization by email. Requires admin role.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				organization_id: {
+					type: 'string',
+					description: 'Organization UUID',
+				},
+				email: {
+					type: 'string',
+					description: 'Email address to invite',
+				},
+				role: {
+					type: 'string',
+					enum: ['admin', 'member', 'viewer'],
+					description: 'Role to assign (default: member)',
+				},
+			},
+			required: ['organization_id', 'email'],
+		},
+	},
+	{
+		name: 'update_member_role',
+		description: 'Change a member\'s role. Requires admin role. Cannot change owner.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				organization_id: {
+					type: 'string',
+					description: 'Organization UUID',
+				},
+				user_id: {
+					type: 'string',
+					description: 'User UUID to update',
+				},
+				role: {
+					type: 'string',
+					enum: ['admin', 'member', 'viewer'],
+					description: 'New role to assign',
+				},
+			},
+			required: ['organization_id', 'user_id', 'role'],
+		},
+	},
+	{
+		name: 'remove_member',
+		description: 'Remove a member from an organization. Requires admin role.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				organization_id: {
+					type: 'string',
+					description: 'Organization UUID',
+				},
+				user_id: {
+					type: 'string',
+					description: 'User UUID to remove',
+				},
+			},
+			required: ['organization_id', 'user_id'],
+		},
+	},
+	{
+		name: 'leave_organization',
+		description: 'Leave an organization. Owner cannot leave without transferring ownership.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				organization_id: {
+					type: 'string',
+					description: 'Organization UUID',
+				},
+			},
+			required: ['organization_id'],
+		},
+	},
+	{
+		name: 'share_project_with_org',
+		description: 'Share a project with an organization. You must own the project.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				organization_id: {
+					type: 'string',
+					description: 'Organization UUID to share with',
+				},
+				permission: {
+					type: 'string',
+					enum: ['read', 'write', 'admin'],
+					description: 'Permission level (default: read)',
+				},
+			},
+			required: ['project_id', 'organization_id'],
+		},
+	},
+	{
+		name: 'update_project_share',
+		description: 'Update the permission level for a project share.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				organization_id: {
+					type: 'string',
+					description: 'Organization UUID',
+				},
+				permission: {
+					type: 'string',
+					enum: ['read', 'write', 'admin'],
+					description: 'New permission level',
+				},
+			},
+			required: ['project_id', 'organization_id', 'permission'],
+		},
+	},
+	{
+		name: 'unshare_project',
+		description: 'Remove a project share from an organization.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				organization_id: {
+					type: 'string',
+					description: 'Organization UUID',
+				},
+			},
+			required: ['project_id', 'organization_id'],
+		},
+	},
+	{
+		name: 'list_project_shares',
+		description: 'List all organizations a project is shared with.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+];
+
+// ============================================================================
+// 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:
+	// - last_synced_at: keeps session alive and visible as "active" on dashboard
+	// - tool_call_count: incremented for token efficiency tracking
+	// - last_tool_at: timestamp of last tool call
+	// Skip for start_work_session since it handles its own session setup
+	if (currentSessionId && name !== 'start_work_session') {
+		const now = new Date().toISOString();
+		await supabase.rpc('increment_tool_call_count', {
+			p_session_id: currentSessionId,
+			p_timestamp: now
+		}).then(({ error }) => {
+			// Fallback to direct update if RPC doesn't exist (pre-migration)
+			if (error) {
+				return supabase
+					.from('agent_sessions')
+					.update({ last_synced_at: now })
+					.eq('id', currentSessionId);
+			}
+		});
+	}
+
+	// Check if handler exists in the modular registry
+	const handler = handlerRegistry[name];
+	if (handler) {
+		// Build handler context
+		const ctx: HandlerContext = {
+			supabase,
+			auth,
+			session: {
+				instanceId: INSTANCE_ID,
+				currentSessionId,
+				currentPersona,
+				tokenUsage: sessionTokenUsage,
+			},
+			updateSession: (updates) => {
+				if (updates.currentSessionId !== undefined) currentSessionId = updates.currentSessionId;
+				if (updates.currentPersona !== undefined) currentPersona = updates.currentPersona;
+				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
+	const auth = await validateApiKey(API_KEY!);
+	if (!auth) {
+		console.error('Invalid API key');
+		process.exit(1);
+	}
+
+	const server = new Server(
+		{
+			name: 'vibescope',
+			version: '0.1.0',
+		},
+		{
+			capabilities: {
+				tools: {},
+			},
+		}
+	);
+
+	// 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 = error instanceof Error ? error.message : 'Unknown 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);
+});