@vibescope/mcp-server 0.5.0 → 0.5.2

package/src/handlers/discovery.ts

@@ -1,433 +1,433 @@
-/**
- * Discovery Handlers
- *
- * Handles tool discovery and documentation:
- * - discover_tools
- * - get_tool_info
- *
- * Note: Tool documentation is lazy-loaded from tool-docs.ts to save tokens.
- * This saves ~8,000 tokens per schema load.
- */
-
-import type { Handler, HandlerRegistry } from './types.js';
-import { parseArgs } from '../validators.js';
-
-// Argument schemas for type-safe parsing
-const discoverToolsSchema = {
-	category: { type: 'string' as const },
-};
-
-const getToolInfoSchema = {
-	tool_name: { type: 'string' as const, required: true as const },
-};
-
-// Lazy-loaded tool documentation cache
-let toolInfoCache: Record<string, string> | null = null;
-
-/**
- * Lazy-load tool documentation.
- * Only loads the TOOL_INFO module when get_tool_info is called.
- */
-async function getToolDocs(): Promise<Record<string, string>> {
-	if (toolInfoCache) {
-		return toolInfoCache;
-	}
-
-	const { TOOL_INFO } = await import('./tool-docs.js');
-	toolInfoCache = TOOL_INFO;
-	return toolInfoCache;
-}
-
-// Tool categories with brief descriptions (exported for documentation generation)
-export const TOOL_CATEGORIES: Record<string, { description: string; tools: Array<{ name: string; brief: string }> }> = {
-	session: {
-		description: 'Session lifecycle and monitoring',
-		tools: [
-			{ name: 'start_work_session', brief: 'Initialize session, get next task' },
-			{ name: 'get_help', brief: 'Get workflow guidance' },
-			{ name: 'get_token_usage', brief: 'View token stats' },
-			{ name: 'report_token_usage', brief: 'Report actual Claude API usage' },
-			{ name: 'heartbeat', brief: 'Maintain active status' },
-			{ name: 'signal_idle', brief: 'Signal agent is idle' },
-			{ name: 'end_work_session', brief: 'End session, release tasks' },
-			{ name: 'confirm_agent_setup', brief: 'Mark agent setup as complete' },
-		],
-	},
-	project: {
-		description: 'Project CRUD and configuration',
-		tools: [
-			{ name: 'get_project_context', brief: 'Full project info' },
-			{ name: 'get_project_summary', brief: 'Unified stats overview' },
-			{ name: 'get_git_workflow', brief: 'Git branching config' },
-			{ name: 'create_project', brief: 'Create new project' },
-			{ name: 'update_project', brief: 'Modify project settings' },
-			{ name: 'update_project_readme', brief: 'Sync README to dashboard' },
-		],
-	},
-	tasks: {
-		description: 'Task management and tracking',
-		tools: [
-			{ name: 'get_task', brief: 'Get single task by ID' },
-			{ name: 'search_tasks', brief: 'Text search tasks' },
-			{ name: 'get_tasks_by_priority', brief: 'Filter tasks by priority' },
-			{ name: 'get_recent_tasks', brief: 'Get oldest/newest tasks' },
-			{ name: 'get_task_stats', brief: 'Get aggregate task counts' },
-			{ name: 'get_next_task', brief: 'Get highest priority task' },
-			{ name: 'add_task', brief: 'Create new task' },
-			{ name: 'update_task', brief: 'Update task status/progress' },
-			{ name: 'complete_task', brief: 'Mark task done' },
-			{ name: 'delete_task', brief: 'Remove a task' },
-			{ name: 'cancel_task', brief: 'Cancel task with reason' },
-			{ name: 'release_task', brief: 'Unclaim task to pending' },
-			{ name: 'batch_update_tasks', brief: 'Update multiple tasks' },
-			{ name: 'batch_complete_tasks', brief: 'Complete multiple tasks' },
-			{ name: 'add_task_reference', brief: 'Add URL to task' },
-			{ name: 'remove_task_reference', brief: 'Remove URL from task' },
-		],
-	},
-	milestones: {
-		description: 'Task breakdown into steps',
-		tools: [
-			{ name: 'add_milestone', brief: 'Add step to task' },
-			{ name: 'update_milestone', brief: 'Update milestone' },
-			{ name: 'complete_milestone', brief: 'Mark step done' },
-			{ name: 'delete_milestone', brief: 'Remove milestone' },
-			{ name: 'get_milestones', brief: 'List task milestones' },
-		],
-	},
-	progress: {
-		description: 'Progress logging and activity',
-		tools: [
-			{ name: 'log_progress', brief: 'Record progress update' },
-			{ name: 'get_activity_feed', brief: 'Combined activity feed' },
-		],
-	},
-	blockers: {
-		description: 'Blocker management',
-		tools: [
-			{ name: 'add_blocker', brief: 'Record a blocker' },
-			{ name: 'resolve_blocker', brief: 'Mark resolved' },
-			{ name: 'get_blocker', brief: 'Get single blocker' },
-			{ name: 'get_blockers', brief: 'List blockers' },
-			{ name: 'get_blockers_stats', brief: 'Get blocker statistics' },
-			{ name: 'delete_blocker', brief: 'Remove blocker' },
-		],
-	},
-	decisions: {
-		description: 'Architectural decisions',
-		tools: [
-			{ name: 'log_decision', brief: 'Record decision' },
-			{ name: 'get_decision', brief: 'Get single decision' },
-			{ name: 'get_decisions', brief: 'List decisions' },
-			{ name: 'get_decisions_stats', brief: 'Get decision statistics' },
-			{ name: 'delete_decision', brief: 'Remove decision' },
-		],
-	},
-	ideas: {
-		description: 'Feature ideas tracking',
-		tools: [
-			{ name: 'add_idea', brief: 'Record an idea' },
-			{ name: 'update_idea', brief: 'Update idea status' },
-			{ name: 'get_idea', brief: 'Get single idea' },
-			{ name: 'get_ideas', brief: 'List ideas' },
-			{ name: 'delete_idea', brief: 'Remove idea' },
-			{ name: 'convert_idea_to_task', brief: 'Convert idea to task' },
-		],
-	},
-	findings: {
-		description: 'Audit findings/knowledge base',
-		tools: [
-			{ name: 'add_finding', brief: 'Record audit finding' },
-			{ name: 'get_finding', brief: 'Get single finding' },
-			{ name: 'get_findings', brief: 'List findings' },
-			{ name: 'get_findings_stats', brief: 'Get findings statistics' },
-			{ name: 'update_finding', brief: 'Update finding status' },
-			{ name: 'delete_finding', brief: 'Remove finding' },
-		],
-	},
-	validation: {
-		description: 'Cross-agent task validation',
-		tools: [
-			{ name: 'get_tasks_awaiting_validation', brief: 'Unvalidated tasks' },
-			{ name: 'claim_validation', brief: 'Claim task for review' },
-			{ name: 'validate_task', brief: 'Approve/reject task' },
-		],
-	},
-	deployment: {
-		description: 'Deployment coordination',
-		tools: [
-			{ name: 'request_deployment', brief: 'Request deploy' },
-			{ name: 'claim_deployment_validation', brief: 'Claim for validation' },
-			{ name: 'report_validation', brief: 'Report build/test results' },
-			{ name: 'check_deployment_status', brief: 'Get deploy status' },
-			{ name: 'start_deployment', brief: 'Begin deployment' },
-			{ name: 'complete_deployment', brief: 'Mark deploy done' },
-			{ name: 'cancel_deployment', brief: 'Cancel deployment' },
-			{ name: 'add_deployment_requirement', brief: 'Add pre-deploy step' },
-			{ name: 'complete_deployment_requirement', brief: 'Mark step done' },
-			{ name: 'get_deployment_requirements', brief: 'List pre-deploy steps' },
-			{ name: 'get_deployment_requirements_stats', brief: 'Get requirements statistics' },
-			{ name: 'reorder_deployment_requirements', brief: 'Reorder steps within a stage' },
-			{ name: 'schedule_deployment', brief: 'Schedule future deployment' },
-			{ name: 'get_scheduled_deployments', brief: 'List scheduled deployments' },
-			{ name: 'update_scheduled_deployment', brief: 'Update schedule config' },
-			{ name: 'delete_scheduled_deployment', brief: 'Delete schedule' },
-			{ name: 'trigger_scheduled_deployment', brief: 'Manual trigger' },
-			{ name: 'check_due_deployments', brief: 'Check due schedules' },
-		],
-	},
-	fallback: {
-		description: 'Background activities when idle',
-		tools: [
-			{ name: 'start_fallback_activity', brief: 'Start background work' },
-			{ name: 'stop_fallback_activity', brief: 'Stop background work' },
-			{ name: 'get_activity_history', brief: 'Activity history' },
-			{ name: 'get_activity_schedules', brief: 'Activity schedules' },
-		],
-	},
-	bodies_of_work: {
-		description: 'Group tasks into bodies of work',
-		tools: [
-			{ name: 'create_body_of_work', brief: 'Create task group' },
-			{ name: 'update_body_of_work', brief: 'Update settings' },
-			{ name: 'get_body_of_work', brief: 'Get with tasks' },
-			{ name: 'get_bodies_of_work', brief: 'List bodies of work' },
-			{ name: 'delete_body_of_work', brief: 'Remove body of work' },
-			{ name: 'add_task_to_body_of_work', brief: 'Add task to group' },
-			{ name: 'remove_task_from_body_of_work', brief: 'Remove from group' },
-			{ name: 'activate_body_of_work', brief: 'Activate for work' },
-			{ name: 'add_task_dependency', brief: 'Add task dependency' },
-			{ name: 'remove_task_dependency', brief: 'Remove task dependency' },
-			{ name: 'get_task_dependencies', brief: 'List task dependencies' },
-			{ name: 'get_next_body_of_work_task', brief: 'Get next available task' },
-		],
-	},
-	sprints: {
-		description: 'Time-bounded sprints with velocity tracking',
-		tools: [
-			{ name: 'create_sprint', brief: 'Create new sprint' },
-			{ name: 'update_sprint', brief: 'Update sprint details' },
-			{ name: 'get_sprint', brief: 'Get sprint with tasks' },
-			{ name: 'get_sprints', brief: 'List project sprints' },
-			{ name: 'delete_sprint', brief: 'Delete sprint' },
-			{ name: 'start_sprint', brief: 'Start sprint' },
-			{ name: 'complete_sprint', brief: 'Complete sprint' },
-			{ name: 'add_task_to_sprint', brief: 'Add task to sprint' },
-			{ name: 'remove_task_from_sprint', brief: 'Remove from sprint' },
-			{ name: 'get_sprint_backlog', brief: 'Get available tasks (paginated)' },
-			{ name: 'get_sprint_velocity', brief: 'Velocity metrics' },
-		],
-	},
-	requests: {
-		description: 'User request handling',
-		tools: [
-			{ name: 'get_pending_requests', brief: 'Unhandled requests' },
-			{ name: 'acknowledge_request', brief: 'Mark handled' },
-			{ name: 'answer_question', brief: 'Answer user question' },
-		],
-	},
-	organizations: {
-		description: 'Organization and team management',
-		tools: [
-			// REMOVED: list_organizations - use dashboard
-			{ name: 'create_organization', brief: 'Create new org' },
-			{ name: 'update_organization', brief: 'Update org settings' },
-			{ name: 'delete_organization', brief: 'Delete org' },
-			// REMOVED: list_org_members - use dashboard
-			{ name: 'invite_member', brief: 'Invite by email' },
-			{ name: 'update_member_role', brief: 'Change member role' },
-			{ name: 'remove_member', brief: 'Remove from org' },
-			{ name: 'leave_organization', brief: 'Leave an org' },
-			{ name: 'share_project_with_org', brief: 'Share project' },
-			{ name: 'update_project_share', brief: 'Update share perms' },
-			{ name: 'unshare_project', brief: 'Remove share' },
-			// REMOVED: list_project_shares - use dashboard
-		],
-	},
-	cost: {
-		description: 'Cost monitoring and alerts',
-		tools: [
-			{ name: 'get_cost_summary', brief: 'Cost by period (paginated)' },
-			// REMOVED: get_cost_alerts - use dashboard
-			{ name: 'add_cost_alert', brief: 'Add threshold alert' },
-			{ name: 'update_cost_alert', brief: 'Update alert config' },
-			{ name: 'delete_cost_alert', brief: 'Remove alert' },
-			// REMOVED: get_task_costs - use get_cost_summary
-			// REMOVED: get_body_of_work_costs - use get_cost_summary
-			// REMOVED: get_sprint_costs - use get_cost_summary
-		],
-	},
-	git_issues: {
-		description: 'Git conflict and issue tracking',
-		tools: [
-			{ name: 'add_git_issue', brief: 'Record git issue' },
-			{ name: 'resolve_git_issue', brief: 'Mark resolved' },
-			{ name: 'get_git_issues', brief: 'List git issues' },
-			{ name: 'delete_git_issue', brief: 'Delete git issue' },
-		],
-	},
-	knowledge: {
-		description: 'Queryable knowledge base from project data',
-		tools: [
-			{ name: 'query_knowledge_base', brief: 'Aggregated project knowledge in one call' },
-		],
-	},
-	discovery: {
-		description: 'Tool discovery and documentation',
-		tools: [
-			{ name: 'discover_tools', brief: 'List tools by category' },
-			{ name: 'get_tool_info', brief: 'Get detailed tool docs' },
-		],
-	},
-	subtasks: {
-		description: 'Break tasks into smaller pieces',
-		tools: [
-			{ name: 'add_subtask', brief: 'Add subtask to task' },
-			{ name: 'get_subtasks', brief: 'List task subtasks (paginated)' },
-		],
-	},
-	worktrees: {
-		description: 'Git worktree management',
-		tools: [
-			{ name: 'get_stale_worktrees', brief: 'Find orphaned worktrees' },
-			{ name: 'clear_worktree_path', brief: 'Clear worktree from task' },
-		],
-	},
-	roles: {
-		description: 'Agent role management',
-		tools: [
-			{ name: 'get_role_settings', brief: 'Get project role settings' },
-			{ name: 'update_role_settings', brief: 'Configure role behavior' },
-			{ name: 'set_session_role', brief: 'Set session role' },
-			{ name: 'get_agents_by_role', brief: 'List agents by role' },
-		],
-	},
-	file_locks: {
-		description: 'File checkout/locking for multi-agent',
-		tools: [
-			{ name: 'checkout_file', brief: 'Lock file for editing' },
-			{ name: 'checkin_file', brief: 'Release file lock' },
-			{ name: 'get_file_checkouts', brief: 'List file locks' },
-			{ name: 'get_file_checkouts_stats', brief: 'Lock statistics' },
-			{ name: 'abandon_checkout', brief: 'Force-release lock' },
-			{ name: 'is_file_available', brief: 'Check if file is free' },
-		],
-	},
-	connectors: {
-		description: 'External integration connectors',
-		tools: [
-			{ name: 'get_connectors', brief: 'List project connectors' },
-			{ name: 'get_connector', brief: 'Get connector details' },
-			{ name: 'add_connector', brief: 'Create new connector' },
-			{ name: 'update_connector', brief: 'Update connector config' },
-			{ name: 'delete_connector', brief: 'Remove connector' },
-			{ name: 'test_connector', brief: 'Send test event' },
-			{ name: 'get_connector_events', brief: 'Event history' },
-		],
-	},
-	cloud_agents: {
-		description: 'Cloud agent management and cleanup',
-		tools: [
-			{ name: 'update_agent_status', brief: 'Update agent dashboard status message' },
-			{ name: 'cleanup_stale_cloud_agents', brief: 'Clean up stale cloud agents' },
-			{ name: 'list_cloud_agents', brief: 'List cloud agents for project' },
-		],
-	},
-	chat: {
-		description: 'Project-wide chat channel for agent and user communication',
-		tools: [
-			{ name: 'send_project_message', brief: 'Send a message to the project chat' },
-			{ name: 'get_project_messages', brief: 'Read recent project chat messages' },
-			{ name: 'post_progress', brief: 'Post a structured progress update (info/milestone/blocker/question)' },
-		],
-	},
-	version: {
-		description: 'MCP server version management and updates',
-		tools: [
-			{ name: 'check_mcp_version', brief: 'Check for MCP server updates' },
-			{ name: 'update_mcp_server', brief: 'Self-update the MCP server' },
-		],
-	},
-	persona_templates: {
-		description: 'Persona templates — behavioral archetypes that shape agent behavior',
-		tools: [
-			{ name: 'get_persona_templates', brief: 'List available persona templates for a project' },
-		],
-	},
-	features: {
-		description: 'Feature specs — flesh out ideas into full specs before breaking into tasks',
-		tools: [
-			{ name: 'add_feature', brief: 'Create a draft feature spec' },
-			{ name: 'update_feature', brief: 'Update feature details or status' },
-			{ name: 'get_feature', brief: 'Get a single feature by ID' },
-			{ name: 'get_features', brief: 'List features for a project' },
-			{ name: 'delete_feature', brief: 'Delete a feature' },
-			{ name: 'link_idea_to_feature', brief: 'Link an idea to a feature' },
-		],
-	},
-};
-
-export const discoverTools: Handler = async (args) => {
-	const { category } = parseArgs(args, discoverToolsSchema);
-
-	if (category) {
-		// Return tools in specific category
-		const cat = TOOL_CATEGORIES[category];
-		if (!cat) {
-			return {
-				result: {
-					error: `Unknown category: ${category}`,
-					available: Object.keys(TOOL_CATEGORIES),
-				},
-			};
-		}
-		return {
-			result: {
-				category,
-				description: cat.description,
-				tools: cat.tools,
-			},
-		};
-	}
-
-	// Return all categories with tool counts
-	const categories = Object.entries(TOOL_CATEGORIES).map(([name, cat]) => ({
-		name,
-		description: cat.description,
-		tool_count: cat.tools.length,
-	}));
-
-	return {
-		result: {
-			categories,
-			total_tools: categories.reduce((sum, c) => sum + c.tool_count, 0),
-			usage: 'Call discover_tools(category) to list tools, get_tool_info(tool_name) for details',
-		},
-	};
-};
-
-export const getToolInfo: Handler = async (args) => {
-	const { tool_name } = parseArgs(args, getToolInfoSchema);
-
-	// Lazy-load tool documentation
-	const toolDocs = await getToolDocs();
-	const info = toolDocs[tool_name];
-	if (!info) {
-		return {
-			result: {
-				error: `Unknown tool: ${tool_name}`,
-				hint: 'Use discover_tools() to list available tools',
-			},
-		};
-	}
-
-	return { result: { tool: tool_name, info } };
-};
-
-/**
- * Discovery handlers registry
- */
-export const discoveryHandlers: HandlerRegistry = {
-	discover_tools: discoverTools,
-	get_tool_info: getToolInfo,
-};
+/**
+ * Discovery Handlers
+ *
+ * Handles tool discovery and documentation:
+ * - discover_tools
+ * - get_tool_info
+ *
+ * Note: Tool documentation is lazy-loaded from tool-docs.ts to save tokens.
+ * This saves ~8,000 tokens per schema load.
+ */
+
+import type { Handler, HandlerRegistry } from './types.js';
+import { parseArgs } from '../validators.js';
+
+// Argument schemas for type-safe parsing
+const discoverToolsSchema = {
+	category: { type: 'string' as const },
+};
+
+const getToolInfoSchema = {
+	tool_name: { type: 'string' as const, required: true as const },
+};
+
+// Lazy-loaded tool documentation cache
+let toolInfoCache: Record<string, string> | null = null;
+
+/**
+ * Lazy-load tool documentation.
+ * Only loads the TOOL_INFO module when get_tool_info is called.
+ */
+async function getToolDocs(): Promise<Record<string, string>> {
+	if (toolInfoCache) {
+		return toolInfoCache;
+	}
+
+	const { TOOL_INFO } = await import('./tool-docs.js');
+	toolInfoCache = TOOL_INFO;
+	return toolInfoCache;
+}
+
+// Tool categories with brief descriptions (exported for documentation generation)
+export const TOOL_CATEGORIES: Record<string, { description: string; tools: Array<{ name: string; brief: string }> }> = {
+	session: {
+		description: 'Session lifecycle and monitoring',
+		tools: [
+			{ name: 'start_work_session', brief: 'Initialize session, get next task' },
+			{ name: 'get_help', brief: 'Get workflow guidance' },
+			{ name: 'get_token_usage', brief: 'View token stats' },
+			{ name: 'report_token_usage', brief: 'Report actual Claude API usage' },
+			{ name: 'heartbeat', brief: 'Maintain active status' },
+			{ name: 'signal_idle', brief: 'Signal agent is idle' },
+			{ name: 'end_work_session', brief: 'End session, release tasks' },
+			{ name: 'confirm_agent_setup', brief: 'Mark agent setup as complete' },
+		],
+	},
+	project: {
+		description: 'Project CRUD and configuration',
+		tools: [
+			{ name: 'get_project_context', brief: 'Full project info' },
+			{ name: 'get_project_summary', brief: 'Unified stats overview' },
+			{ name: 'get_git_workflow', brief: 'Git branching config' },
+			{ name: 'create_project', brief: 'Create new project' },
+			{ name: 'update_project', brief: 'Modify project settings' },
+			{ name: 'update_project_readme', brief: 'Sync README to dashboard' },
+		],
+	},
+	tasks: {
+		description: 'Task management and tracking',
+		tools: [
+			{ name: 'get_task', brief: 'Get single task by ID' },
+			{ name: 'search_tasks', brief: 'Text search tasks' },
+			{ name: 'get_tasks_by_priority', brief: 'Filter tasks by priority' },
+			{ name: 'get_recent_tasks', brief: 'Get oldest/newest tasks' },
+			{ name: 'get_task_stats', brief: 'Get aggregate task counts' },
+			{ name: 'get_next_task', brief: 'Get highest priority task' },
+			{ name: 'add_task', brief: 'Create new task' },
+			{ name: 'update_task', brief: 'Update task status/progress' },
+			{ name: 'complete_task', brief: 'Mark task done' },
+			{ name: 'delete_task', brief: 'Remove a task' },
+			{ name: 'cancel_task', brief: 'Cancel task with reason' },
+			{ name: 'release_task', brief: 'Unclaim task to pending' },
+			{ name: 'batch_update_tasks', brief: 'Update multiple tasks' },
+			{ name: 'batch_complete_tasks', brief: 'Complete multiple tasks' },
+			{ name: 'add_task_reference', brief: 'Add URL to task' },
+			{ name: 'remove_task_reference', brief: 'Remove URL from task' },
+		],
+	},
+	milestones: {
+		description: 'Task breakdown into steps',
+		tools: [
+			{ name: 'add_milestone', brief: 'Add step to task' },
+			{ name: 'update_milestone', brief: 'Update milestone' },
+			{ name: 'complete_milestone', brief: 'Mark step done' },
+			{ name: 'delete_milestone', brief: 'Remove milestone' },
+			{ name: 'get_milestones', brief: 'List task milestones' },
+		],
+	},
+	progress: {
+		description: 'Progress logging and activity',
+		tools: [
+			{ name: 'log_progress', brief: 'Record progress update' },
+			{ name: 'get_activity_feed', brief: 'Combined activity feed' },
+		],
+	},
+	blockers: {
+		description: 'Blocker management',
+		tools: [
+			{ name: 'add_blocker', brief: 'Record a blocker' },
+			{ name: 'resolve_blocker', brief: 'Mark resolved' },
+			{ name: 'get_blocker', brief: 'Get single blocker' },
+			{ name: 'get_blockers', brief: 'List blockers' },
+			{ name: 'get_blockers_stats', brief: 'Get blocker statistics' },
+			{ name: 'delete_blocker', brief: 'Remove blocker' },
+		],
+	},
+	decisions: {
+		description: 'Architectural decisions',
+		tools: [
+			{ name: 'log_decision', brief: 'Record decision' },
+			{ name: 'get_decision', brief: 'Get single decision' },
+			{ name: 'get_decisions', brief: 'List decisions' },
+			{ name: 'get_decisions_stats', brief: 'Get decision statistics' },
+			{ name: 'delete_decision', brief: 'Remove decision' },
+		],
+	},
+	ideas: {
+		description: 'Feature ideas tracking',
+		tools: [
+			{ name: 'add_idea', brief: 'Record an idea' },
+			{ name: 'update_idea', brief: 'Update idea status' },
+			{ name: 'get_idea', brief: 'Get single idea' },
+			{ name: 'get_ideas', brief: 'List ideas' },
+			{ name: 'delete_idea', brief: 'Remove idea' },
+			{ name: 'convert_idea_to_task', brief: 'Convert idea to task' },
+		],
+	},
+	findings: {
+		description: 'Audit findings/knowledge base',
+		tools: [
+			{ name: 'add_finding', brief: 'Record audit finding' },
+			{ name: 'get_finding', brief: 'Get single finding' },
+			{ name: 'get_findings', brief: 'List findings' },
+			{ name: 'get_findings_stats', brief: 'Get findings statistics' },
+			{ name: 'update_finding', brief: 'Update finding status' },
+			{ name: 'delete_finding', brief: 'Remove finding' },
+		],
+	},
+	validation: {
+		description: 'Cross-agent task validation',
+		tools: [
+			{ name: 'get_tasks_awaiting_validation', brief: 'Unvalidated tasks' },
+			{ name: 'claim_validation', brief: 'Claim task for review' },
+			{ name: 'validate_task', brief: 'Approve/reject task' },
+		],
+	},
+	deployment: {
+		description: 'Deployment coordination',
+		tools: [
+			{ name: 'request_deployment', brief: 'Request deploy' },
+			{ name: 'claim_deployment_validation', brief: 'Claim for validation' },
+			{ name: 'report_validation', brief: 'Report build/test results' },
+			{ name: 'check_deployment_status', brief: 'Get deploy status' },
+			{ name: 'start_deployment', brief: 'Begin deployment' },
+			{ name: 'complete_deployment', brief: 'Mark deploy done' },
+			{ name: 'cancel_deployment', brief: 'Cancel deployment' },
+			{ name: 'add_deployment_requirement', brief: 'Add pre-deploy step' },
+			{ name: 'complete_deployment_requirement', brief: 'Mark step done' },
+			{ name: 'get_deployment_requirements', brief: 'List pre-deploy steps' },
+			{ name: 'get_deployment_requirements_stats', brief: 'Get requirements statistics' },
+			{ name: 'reorder_deployment_requirements', brief: 'Reorder steps within a stage' },
+			{ name: 'schedule_deployment', brief: 'Schedule future deployment' },
+			{ name: 'get_scheduled_deployments', brief: 'List scheduled deployments' },
+			{ name: 'update_scheduled_deployment', brief: 'Update schedule config' },
+			{ name: 'delete_scheduled_deployment', brief: 'Delete schedule' },
+			{ name: 'trigger_scheduled_deployment', brief: 'Manual trigger' },
+			{ name: 'check_due_deployments', brief: 'Check due schedules' },
+		],
+	},
+	fallback: {
+		description: 'Background activities when idle',
+		tools: [
+			{ name: 'start_fallback_activity', brief: 'Start background work' },
+			{ name: 'stop_fallback_activity', brief: 'Stop background work' },
+			{ name: 'get_activity_history', brief: 'Activity history' },
+			{ name: 'get_activity_schedules', brief: 'Activity schedules' },
+		],
+	},
+	bodies_of_work: {
+		description: 'Group tasks into bodies of work',
+		tools: [
+			{ name: 'create_body_of_work', brief: 'Create task group' },
+			{ name: 'update_body_of_work', brief: 'Update settings' },
+			{ name: 'get_body_of_work', brief: 'Get with tasks' },
+			{ name: 'get_bodies_of_work', brief: 'List bodies of work' },
+			{ name: 'delete_body_of_work', brief: 'Remove body of work' },
+			{ name: 'add_task_to_body_of_work', brief: 'Add task to group' },
+			{ name: 'remove_task_from_body_of_work', brief: 'Remove from group' },
+			{ name: 'activate_body_of_work', brief: 'Activate for work' },
+			{ name: 'add_task_dependency', brief: 'Add task dependency' },
+			{ name: 'remove_task_dependency', brief: 'Remove task dependency' },
+			{ name: 'get_task_dependencies', brief: 'List task dependencies' },
+			{ name: 'get_next_body_of_work_task', brief: 'Get next available task' },
+		],
+	},
+	sprints: {
+		description: 'Time-bounded sprints with velocity tracking',
+		tools: [
+			{ name: 'create_sprint', brief: 'Create new sprint' },
+			{ name: 'update_sprint', brief: 'Update sprint details' },
+			{ name: 'get_sprint', brief: 'Get sprint with tasks' },
+			{ name: 'get_sprints', brief: 'List project sprints' },
+			{ name: 'delete_sprint', brief: 'Delete sprint' },
+			{ name: 'start_sprint', brief: 'Start sprint' },
+			{ name: 'complete_sprint', brief: 'Complete sprint' },
+			{ name: 'add_task_to_sprint', brief: 'Add task to sprint' },
+			{ name: 'remove_task_from_sprint', brief: 'Remove from sprint' },
+			{ name: 'get_sprint_backlog', brief: 'Get available tasks (paginated)' },
+			{ name: 'get_sprint_velocity', brief: 'Velocity metrics' },
+		],
+	},
+	requests: {
+		description: 'User request handling',
+		tools: [
+			{ name: 'get_pending_requests', brief: 'Unhandled requests' },
+			{ name: 'acknowledge_request', brief: 'Mark handled' },
+			{ name: 'answer_question', brief: 'Answer user question' },
+		],
+	},
+	organizations: {
+		description: 'Organization and team management',
+		tools: [
+			// REMOVED: list_organizations - use dashboard
+			{ name: 'create_organization', brief: 'Create new org' },
+			{ name: 'update_organization', brief: 'Update org settings' },
+			{ name: 'delete_organization', brief: 'Delete org' },
+			// REMOVED: list_org_members - use dashboard
+			{ name: 'invite_member', brief: 'Invite by email' },
+			{ name: 'update_member_role', brief: 'Change member role' },
+			{ name: 'remove_member', brief: 'Remove from org' },
+			{ name: 'leave_organization', brief: 'Leave an org' },
+			{ name: 'share_project_with_org', brief: 'Share project' },
+			{ name: 'update_project_share', brief: 'Update share perms' },
+			{ name: 'unshare_project', brief: 'Remove share' },
+			// REMOVED: list_project_shares - use dashboard
+		],
+	},
+	cost: {
+		description: 'Cost monitoring and alerts',
+		tools: [
+			{ name: 'get_cost_summary', brief: 'Cost by period (paginated)' },
+			// REMOVED: get_cost_alerts - use dashboard
+			{ name: 'add_cost_alert', brief: 'Add threshold alert' },
+			{ name: 'update_cost_alert', brief: 'Update alert config' },
+			{ name: 'delete_cost_alert', brief: 'Remove alert' },
+			// REMOVED: get_task_costs - use get_cost_summary
+			// REMOVED: get_body_of_work_costs - use get_cost_summary
+			// REMOVED: get_sprint_costs - use get_cost_summary
+		],
+	},
+	git_issues: {
+		description: 'Git conflict and issue tracking',
+		tools: [
+			{ name: 'add_git_issue', brief: 'Record git issue' },
+			{ name: 'resolve_git_issue', brief: 'Mark resolved' },
+			{ name: 'get_git_issues', brief: 'List git issues' },
+			{ name: 'delete_git_issue', brief: 'Delete git issue' },
+		],
+	},
+	knowledge: {
+		description: 'Queryable knowledge base from project data',
+		tools: [
+			{ name: 'query_knowledge_base', brief: 'Aggregated project knowledge in one call' },
+		],
+	},
+	discovery: {
+		description: 'Tool discovery and documentation',
+		tools: [
+			{ name: 'discover_tools', brief: 'List tools by category' },
+			{ name: 'get_tool_info', brief: 'Get detailed tool docs' },
+		],
+	},
+	subtasks: {
+		description: 'Break tasks into smaller pieces',
+		tools: [
+			{ name: 'add_subtask', brief: 'Add subtask to task' },
+			{ name: 'get_subtasks', brief: 'List task subtasks (paginated)' },
+		],
+	},
+	worktrees: {
+		description: 'Git worktree management',
+		tools: [
+			{ name: 'get_stale_worktrees', brief: 'Find orphaned worktrees' },
+			{ name: 'clear_worktree_path', brief: 'Clear worktree from task' },
+		],
+	},
+	roles: {
+		description: 'Agent role management',
+		tools: [
+			{ name: 'get_role_settings', brief: 'Get project role settings' },
+			{ name: 'update_role_settings', brief: 'Configure role behavior' },
+			{ name: 'set_session_role', brief: 'Set session role' },
+			{ name: 'get_agents_by_role', brief: 'List agents by role' },
+		],
+	},
+	file_locks: {
+		description: 'File checkout/locking for multi-agent',
+		tools: [
+			{ name: 'checkout_file', brief: 'Lock file for editing' },
+			{ name: 'checkin_file', brief: 'Release file lock' },
+			{ name: 'get_file_checkouts', brief: 'List file locks' },
+			{ name: 'get_file_checkouts_stats', brief: 'Lock statistics' },
+			{ name: 'abandon_checkout', brief: 'Force-release lock' },
+			{ name: 'is_file_available', brief: 'Check if file is free' },
+		],
+	},
+	connectors: {
+		description: 'External integration connectors',
+		tools: [
+			{ name: 'get_connectors', brief: 'List project connectors' },
+			{ name: 'get_connector', brief: 'Get connector details' },
+			{ name: 'add_connector', brief: 'Create new connector' },
+			{ name: 'update_connector', brief: 'Update connector config' },
+			{ name: 'delete_connector', brief: 'Remove connector' },
+			{ name: 'test_connector', brief: 'Send test event' },
+			{ name: 'get_connector_events', brief: 'Event history' },
+		],
+	},
+	cloud_agents: {
+		description: 'Cloud agent management and cleanup',
+		tools: [
+			{ name: 'update_agent_status', brief: 'Update agent dashboard status message' },
+			{ name: 'cleanup_stale_cloud_agents', brief: 'Clean up stale cloud agents' },
+			{ name: 'list_cloud_agents', brief: 'List cloud agents for project' },
+		],
+	},
+	chat: {
+		description: 'Project-wide chat channel for agent and user communication',
+		tools: [
+			{ name: 'send_project_message', brief: 'Send a message to the project chat' },
+			{ name: 'get_project_messages', brief: 'Read recent project chat messages' },
+			{ name: 'post_progress', brief: 'Post a structured progress update (info/milestone/blocker/question)' },
+		],
+	},
+	version: {
+		description: 'MCP server version management and updates',
+		tools: [
+			{ name: 'check_mcp_version', brief: 'Check for MCP server updates' },
+			{ name: 'update_mcp_server', brief: 'Self-update the MCP server' },
+		],
+	},
+	persona_templates: {
+		description: 'Persona templates — behavioral archetypes that shape agent behavior',
+		tools: [
+			{ name: 'get_persona_templates', brief: 'List available persona templates for a project' },
+		],
+	},
+	features: {
+		description: 'Feature specs — flesh out ideas into full specs before breaking into tasks',
+		tools: [
+			{ name: 'add_feature', brief: 'Create a draft feature spec' },
+			{ name: 'update_feature', brief: 'Update feature details or status' },
+			{ name: 'get_feature', brief: 'Get a single feature by ID' },
+			{ name: 'get_features', brief: 'List features for a project' },
+			{ name: 'delete_feature', brief: 'Delete a feature' },
+			{ name: 'link_idea_to_feature', brief: 'Link an idea to a feature' },
+		],
+	},
+};
+
+export const discoverTools: Handler = async (args) => {
+	const { category } = parseArgs(args, discoverToolsSchema);
+
+	if (category) {
+		// Return tools in specific category
+		const cat = TOOL_CATEGORIES[category];
+		if (!cat) {
+			return {
+				result: {
+					error: `Unknown category: ${category}`,
+					available: Object.keys(TOOL_CATEGORIES),
+				},
+			};
+		}
+		return {
+			result: {
+				category,
+				description: cat.description,
+				tools: cat.tools,
+			},
+		};
+	}
+
+	// Return all categories with tool counts
+	const categories = Object.entries(TOOL_CATEGORIES).map(([name, cat]) => ({
+		name,
+		description: cat.description,
+		tool_count: cat.tools.length,
+	}));
+
+	return {
+		result: {
+			categories,
+			total_tools: categories.reduce((sum, c) => sum + c.tool_count, 0),
+			usage: 'Call discover_tools(category) to list tools, get_tool_info(tool_name) for details',
+		},
+	};
+};
+
+export const getToolInfo: Handler = async (args) => {
+	const { tool_name } = parseArgs(args, getToolInfoSchema);
+
+	// Lazy-load tool documentation
+	const toolDocs = await getToolDocs();
+	const info = toolDocs[tool_name];
+	if (!info) {
+		return {
+			result: {
+				error: `Unknown tool: ${tool_name}`,
+				hint: 'Use discover_tools() to list available tools',
+			},
+		};
+	}
+
+	return { result: { tool: tool_name, info } };
+};
+
+/**
+ * Discovery handlers registry
+ */
+export const discoveryHandlers: HandlerRegistry = {
+	discover_tools: discoverTools,
+	get_tool_info: getToolInfo,
+};