@vibescope/mcp-server 0.1.0 → 0.2.0

package/src/handlers/discovery.ts

@@ -4,10 +4,30 @@
  * 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';
 
+// 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
 const TOOL_CATEGORIES: Record<string, { description: string; tools: Array<{ name: string; brief: string }> }> = {
 	session: {
@@ -194,745 +214,6 @@ const TOOL_CATEGORIES: Record<string, { description: string; tools: Array<{ name
 	},
 };
 
-// Detailed tool info (fetched on-demand)
-const TOOL_INFO: Record<string, string> = {
-	start_work_session: `# start_work_session
-Initialize agent session and get assigned work.
-
-**Parameters:**
-- project_id (optional): Project UUID
-- git_url (optional): Git URL to find project
-- mode: 'lite' (default) or 'full' for complete context
-
-**Returns:** session_id, persona, project info, next_task
-
-**Example:** start_work_session(git_url: "https://github.com/org/repo")`,
-
-	get_help: `# get_help
-Get workflow guidance on specific topics.
-
-**Parameters:**
-- topic (required): One of: getting_started, tasks, validation, deployment, git, blockers, milestones, fallback, session, tokens, topics
-
-**Example:** get_help(topic: "deployment")`,
-
-	get_token_usage: `# get_token_usage
-Get token usage statistics for current session.
-
-**Returns:** total calls, total tokens, breakdown by tool, averages`,
-
-	heartbeat: `# heartbeat
-Send heartbeat to maintain active status. Call every 30-60 seconds.
-
-**Parameters:**
-- session_id (optional): Uses current session if not provided`,
-
-	end_work_session: `# end_work_session
-End session and release claimed tasks.
-
-**Parameters:**
-- session_id (optional): Uses current session if not provided
-
-**Returns:** Session summary with tasks completed, time spent`,
-
-	get_project_context: `# get_project_context
-Get full project context including goals, instructions, tasks, blockers, decisions.
-
-**Parameters:**
-- project_id (optional): Project UUID
-- git_url (optional): Git URL to find project
-
-Without params, lists all projects.`,
-
-	get_git_workflow: `# get_git_workflow
-Get git workflow config and branching instructions.
-
-**Parameters:**
-- project_id (required): Project UUID
-- task_id (optional): Include branch naming suggestion
-
-**Returns:** workflow type, branch names, auto-settings`,
-
-	create_project: `# create_project
-Create a new project to track.
-
-**Parameters:**
-- name (required): Project display name
-- description: Brief description
-- goal: What "done" looks like
-- git_url: Repository URL
-- tech_stack: Array of technologies`,
-
-	update_project: `# update_project
-Update project settings.
-
-**Parameters:**
-- project_id (required): Project UUID
-- name, description, goal, git_url, tech_stack, status
-- git_workflow: none, trunk-based, github-flow, git-flow
-- git_main_branch, git_develop_branch, git_auto_branch, git_auto_tag`,
-
-	update_project_readme: `# update_project_readme
-Sync README content to the dashboard.
-
-**Parameters:**
-- project_id (required): Project UUID
-- readme_content (required): Markdown content`,
-
-	get_tasks: `# get_tasks
-Get tasks for a project.
-
-**Parameters:**
-- project_id (required): Project UUID
-- status (optional): pending, in_progress, completed, cancelled
-- limit (optional): Max tasks (default 50)`,
-
-	get_next_task: `# get_next_task
-Get highest priority pending task not claimed by another agent.
-
-**Parameters:**
-- project_id (required): Project UUID
-
-**Returns:** task or null, may suggest fallback activity`,
-
-	add_task: `# add_task
-Create a new task.
-
-**Parameters:**
-- project_id (required): Project UUID
-- title (required): Task title
-- description: Detailed description
-- priority: 1-5 (1=highest, default 3)
-- estimated_minutes: Time estimate`,
-
-	update_task: `# update_task
-Update task status, progress, or details.
-
-**Parameters:**
-- task_id (required): Task UUID
-- status: pending, in_progress, completed, cancelled
-- progress_percentage: 0-100
-- progress_note: Brief note (auto-logged)
-- title, description, priority, estimated_minutes, git_branch
-
-**Best practice:** Include progress_note with progress_percentage`,
-
-	complete_task: `# complete_task
-Mark task as done.
-
-**Parameters:**
-- task_id (required): Task UUID
-- summary: What was done
-
-**Returns:** next_task, validation_count, blockers_count, deployment_priority`,
-
-	delete_task: `# delete_task
-Delete a task.
-
-**Parameters:**
-- task_id (required): Task UUID`,
-
-	batch_update_tasks: `# batch_update_tasks
-Update multiple tasks at once.
-
-**Parameters:**
-- updates (required): Array of {task_id, status?, progress_percentage?, progress_note?, priority?}`,
-
-	batch_complete_tasks: `# batch_complete_tasks
-Complete multiple tasks at once.
-
-**Parameters:**
-- completions (required): Array of {task_id, summary?}`,
-
-	add_task_reference: `# add_task_reference
-Add a reference URL to a task.
-
-**Parameters:**
-- task_id (required): Task UUID
-- url (required): Reference URL
-- label (optional): Display label`,
-
-	remove_task_reference: `# remove_task_reference
-Remove a reference URL from a task.
-
-**Parameters:**
-- task_id (required): Task UUID
-- url (required): URL to remove`,
-
-	add_milestone: `# add_milestone
-Add a milestone/step to a task.
-
-**Parameters:**
-- task_id (required): Task UUID
-- title (required): Milestone title
-- description (optional): Details
-- order_index (optional): Position (0-based)`,
-
-	update_milestone: `# update_milestone
-Update a milestone.
-
-**Parameters:**
-- milestone_id (required): Milestone UUID
-- title, description, status (pending/in_progress/completed), order_index`,
-
-	complete_milestone: `# complete_milestone
-Mark milestone as completed.
-
-**Parameters:**
-- milestone_id (required): Milestone UUID`,
-
-	delete_milestone: `# delete_milestone
-Delete a milestone.
-
-**Parameters:**
-- milestone_id (required): Milestone UUID`,
-
-	get_milestones: `# get_milestones
-Get all milestones for a task.
-
-**Parameters:**
-- task_id (required): Task UUID`,
-
-	log_progress: `# log_progress
-Record a progress update.
-
-**Parameters:**
-- project_id (required): Project UUID
-- summary (required): Brief summary
-- task_id (optional): Link to task
-- details (optional): Extended notes`,
-
-	get_activity_feed: `# get_activity_feed
-Get combined activity feed.
-
-**Parameters:**
-- project_id (required): Project UUID
-- types (optional): Array of task, progress, blocker, decision
-- created_by (optional): agent or user
-- since (optional): ISO date string
-- limit (optional): Max items (default 50)`,
-
-	add_blocker: `# add_blocker
-Record a blocker preventing progress.
-
-**Parameters:**
-- project_id (required): Project UUID
-- description (required): What is blocking`,
-
-	resolve_blocker: `# resolve_blocker
-Mark a blocker as resolved.
-
-**Parameters:**
-- blocker_id (required): Blocker UUID
-- resolution_note (optional): How it was resolved`,
-
-	get_blockers: `# get_blockers
-Get blockers for a project.
-
-**Parameters:**
-- project_id (required): Project UUID
-- status (optional): open or resolved (default: open)`,
-
-	delete_blocker: `# delete_blocker
-Delete a blocker.
-
-**Parameters:**
-- blocker_id (required): Blocker UUID`,
-
-	log_decision: `# log_decision
-Record an architectural decision.
-
-**Parameters:**
-- project_id (required): Project UUID
-- title (required): Decision title
-- description (required): What was decided
-- rationale (optional): Why
-- alternatives_considered (optional): Array of alternatives`,
-
-	get_decisions: `# get_decisions
-Get recorded decisions.
-
-**Parameters:**
-- project_id (required): Project UUID`,
-
-	delete_decision: `# delete_decision
-Delete a decision.
-
-**Parameters:**
-- decision_id (required): Decision UUID`,
-
-	add_idea: `# add_idea
-Record an improvement idea.
-
-**Parameters:**
-- project_id (required): Project UUID
-- title (required): Idea title
-- description (optional): Details
-- status (optional): raw, exploring, planned, in_development, shipped`,
-
-	update_idea: `# update_idea
-Update an idea.
-
-**Parameters:**
-- idea_id (required): Idea UUID
-- title, description, status, doc_url`,
-
-	get_ideas: `# get_ideas
-Get recorded ideas.
-
-**Parameters:**
-- project_id (required): Project UUID
-- status (optional): Filter by status`,
-
-	delete_idea: `# delete_idea
-Delete an idea.
-
-**Parameters:**
-- idea_id (required): Idea UUID`,
-
-	convert_idea_to_task: `# convert_idea_to_task
-Convert an idea to a task. Creates a new task from the idea's title and description.
-
-**Parameters:**
-- idea_id (required): Idea UUID to convert
-- priority (optional): Task priority 1-5 (default: 3)
-- estimated_minutes (optional): Estimated time
-- update_status (optional): Update idea to 'in_development' (default: true)
-
-**Returns:**
-- task_id: Created task UUID
-- Links idea and task together`,
-
-	add_finding: `# add_finding
-Record an audit/review finding.
-
-**Parameters:**
-- project_id (required): Project UUID
-- title (required): Finding title
-- category: performance, security, code_quality, accessibility, documentation, architecture, testing, other
-- description: Details with impact and suggested fix
-- severity: info, low, medium, high, critical
-- file_path, line_number, related_task_id (optional)`,
-
-	get_findings: `# get_findings
-Get audit findings.
-
-**Parameters:**
-- project_id (required): Project UUID
-- category, severity, status (optional filters)
-- limit (optional): Max items`,
-
-	update_finding: `# update_finding
-Update a finding.
-
-**Parameters:**
-- finding_id (required): Finding UUID
-- status: open, addressed, dismissed, wontfix
-- resolution_note, title, description, severity`,
-
-	delete_finding: `# delete_finding
-Delete a finding.
-
-**Parameters:**
-- finding_id (required): Finding UUID`,
-
-	get_tasks_awaiting_validation: `# get_tasks_awaiting_validation
-Get completed tasks needing validation.
-
-**Parameters:**
-- project_id (required): Project UUID
-
-**Returns:** Tasks with reviewing status (who's reviewing, when started)`,
-
-	claim_validation: `# claim_validation
-Claim a completed task for review. Shows "being reviewed" on dashboard.
-
-**Parameters:**
-- task_id (required): Task UUID to claim
-
-**Note:** Claim before reviewing to prevent duplicate work.`,
-
-	validate_task: `# validate_task
-Validate a completed task.
-
-**Parameters:**
-- task_id (required): Task UUID
-- approved (required): true/false
-- validation_notes: What was checked, issues found`,
-
-	request_deployment: `# request_deployment
-Request a deployment.
-
-**Parameters:**
-- project_id (required): Project UUID
-- environment: development, staging, production
-- version_bump: patch, minor, major
-- notes, git_ref (optional)`,
-
-	claim_deployment_validation: `# claim_deployment_validation
-Claim pending deployment for validation.
-
-**Parameters:**
-- project_id (required): Project UUID
-
-Next: Run build+tests, then call report_validation`,
-
-	report_validation: `# report_validation
-Report build/test results.
-
-**Parameters:**
-- project_id (required): Project UUID
-- build_passed (required): boolean
-- tests_passed (required): boolean
-- error_message (if failed)`,
-
-	check_deployment_status: `# check_deployment_status
-Get active deployment status.
-
-**Parameters:**
-- project_id (required): Project UUID`,
-
-	start_deployment: `# start_deployment
-Start deployment (requires 'ready' status).
-
-**Parameters:**
-- project_id (required): Project UUID`,
-
-	complete_deployment: `# complete_deployment
-Mark deployment complete.
-
-**Parameters:**
-- project_id (required): Project UUID
-- success (required): boolean
-- summary: What was deployed or why failed`,
-
-	cancel_deployment: `# cancel_deployment
-Cancel active deployment.
-
-**Parameters:**
-- project_id (required): Project UUID
-- reason (optional): Why cancelled`,
-
-	schedule_deployment: `# schedule_deployment
-Schedule a deployment for a specific time.
-
-**Parameters:**
-- project_id (required): Project UUID
-- scheduled_at (required): ISO 8601 datetime
-- schedule_type (optional): once, daily, weekly, monthly (default: once)
-- auto_trigger (optional): Whether agents auto-trigger (default: true)
-- environment (optional): development, staging, production (default: production)
-- version_bump (optional): patch, minor, major (default: patch)
-- notes (optional): Notes about the deployment
-- git_ref (optional): Git branch or commit
-
-**Example:** schedule_deployment(project_id, scheduled_at: "2025-01-15T10:00:00Z", schedule_type: "weekly")`,
-
-	get_scheduled_deployments: `# get_scheduled_deployments
-List scheduled deployments for a project.
-
-**Parameters:**
-- project_id (required): Project UUID
-- include_disabled (optional): Include disabled schedules (default: false)`,
-
-	update_scheduled_deployment: `# update_scheduled_deployment
-Update a scheduled deployment's configuration.
-
-**Parameters:**
-- schedule_id (required): Schedule UUID
-- scheduled_at (optional): New scheduled time
-- schedule_type (optional): once, daily, weekly, monthly
-- auto_trigger (optional): Whether to auto-trigger
-- enabled (optional): Enable or disable
-- environment, version_bump, notes, git_ref (optional)`,
-
-	delete_scheduled_deployment: `# delete_scheduled_deployment
-Delete a scheduled deployment.
-
-**Parameters:**
-- schedule_id (required): Schedule UUID`,
-
-	trigger_scheduled_deployment: `# trigger_scheduled_deployment
-Manually trigger a scheduled deployment.
-
-Creates a new deployment using the schedule's configuration.
-Updates schedule: last_triggered_at, trigger_count, next scheduled_at (for recurring).
-
-**Parameters:**
-- schedule_id (required): Schedule UUID`,
-
-	check_due_deployments: `# check_due_deployments
-Check for scheduled deployments that are due.
-
-Returns schedules where: enabled AND auto_trigger AND scheduled_at <= NOW()
-
-Use this to find deployments to trigger when working on a project.
-
-**Parameters:**
-- project_id (required): Project UUID`,
-
-	start_fallback_activity: `# start_fallback_activity
-Start background activity when no tasks.
-
-**Parameters:**
-- project_id (required): Project UUID
-- activity (required): feature_ideation, code_review, performance_audit, ux_review, cost_analysis, security_review, test_coverage, documentation_review, dependency_audit, validate_completed_tasks`,
-
-	stop_fallback_activity: `# stop_fallback_activity
-Stop current fallback activity.
-
-**Parameters:**
-- project_id (required): Project UUID
-- summary (optional): What was accomplished`,
-
-	get_activity_history: `# get_activity_history
-Get background activity history.
-
-**Parameters:**
-- project_id (required): Project UUID
-- activity_type (optional): Filter by type
-- limit (optional): Max items`,
-
-	get_activity_schedules: `# get_activity_schedules
-Get activity schedules.
-
-**Parameters:**
-- project_id (required): Project UUID`,
-
-	get_pending_requests: `# get_pending_requests
-Get unacknowledged user requests.
-
-**Parameters:**
-- project_id (required): Project UUID`,
-
-	acknowledge_request: `# acknowledge_request
-Mark a request as handled.
-
-**Parameters:**
-- request_id (required): Request UUID`,
-
-	answer_question: `# answer_question
-Answer a user question from dashboard.
-
-**Parameters:**
-- request_id (required): Request UUID
-- answer (required): Your answer`,
-
-	discover_tools: `# discover_tools
-List available tools by category.
-
-**Parameters:**
-- category (optional): Filter to specific category
-
-Without category, returns all categories with tool counts.
-With category, returns tools in that category with brief descriptions.`,
-
-	get_tool_info: `# get_tool_info
-Get detailed info for a specific tool.
-
-**Parameters:**
-- tool_name (required): Name of the tool
-
-Returns: full documentation, parameters, examples, best practices.`,
-
-	// Organization tools
-	list_organizations: `# list_organizations
-List organizations the current user belongs to.
-
-**Parameters:** None
-
-**Returns:** Array of organizations with role and joined_at`,
-
-	create_organization: `# create_organization
-Create a new organization. You become the owner.
-
-**Parameters:**
-- name (required): Organization display name
-- description (optional): Brief description
-- slug (optional): URL-friendly identifier (auto-generated if not provided)
-
-**Example:** create_organization(name: "Acme Corp", description: "Our development team")`,
-
-	update_organization: `# update_organization
-Update organization details. Requires admin role.
-
-**Parameters:**
-- organization_id (required): Organization UUID
-- name, description, logo_url (optional updates)`,
-
-	delete_organization: `# delete_organization
-Delete an organization. Requires owner role. Removes all shares.
-
-**Parameters:**
-- organization_id (required): Organization UUID
-
-**Warning:** This will remove all project shares with this organization.`,
-
-	list_org_members: `# list_org_members
-List members of an organization.
-
-**Parameters:**
-- organization_id (required): Organization UUID
-
-**Returns:** Array of members with role and joined_at`,
-
-	invite_member: `# invite_member
-Invite a user to an organization by email. Requires admin role.
-
-**Parameters:**
-- organization_id (required): Organization UUID
-- email (required): Email address to invite
-- role (optional): admin, member, or viewer (default: member)
-
-**Returns:** Invite details with token`,
-
-	update_member_role: `# update_member_role
-Change a member's role. Requires admin role.
-
-**Parameters:**
-- organization_id (required): Organization UUID
-- user_id (required): User UUID to update
-- role (required): admin, member, or viewer
-
-**Note:** Cannot change your own role or the owner's role.`,
-
-	remove_member: `# remove_member
-Remove a member from an organization. Requires admin role.
-
-**Parameters:**
-- organization_id (required): Organization UUID
-- user_id (required): User UUID to remove
-
-**Note:** Cannot remove the owner. Their org-scoped API keys are invalidated.`,
-
-	leave_organization: `# leave_organization
-Leave an organization.
-
-**Parameters:**
-- organization_id (required): Organization UUID
-
-**Note:** Owner cannot leave. Must transfer ownership or delete organization.`,
-
-	share_project_with_org: `# share_project_with_org
-Share a project with an organization. You must own the project.
-
-**Parameters:**
-- project_id (required): Project UUID
-- organization_id (required): Organization UUID to share with
-- permission (optional): read, write, or admin (default: read)
-
-**Permission levels:**
-- read: View project and tasks
-- write: Add/update tasks, log progress
-- admin: All write permissions plus deployments`,
-
-	update_project_share: `# update_project_share
-Update the permission level for a project share.
-
-**Parameters:**
-- project_id (required): Project UUID
-- organization_id (required): Organization UUID
-- permission (required): read, write, or admin`,
-
-	unshare_project: `# unshare_project
-Remove a project share from an organization.
-
-**Parameters:**
-- project_id (required): Project UUID
-- organization_id (required): Organization UUID
-
-**Note:** Org members will lose access immediately.`,
-
-	list_project_shares: `# list_project_shares
-List all organizations a project is shared with.
-
-**Parameters:**
-- project_id (required): Project UUID
-
-**Returns:** Array of shares with organization info and permission level`,
-
-	// Cost monitoring tools
-	get_cost_summary: `# get_cost_summary
-Get cost summary (daily/weekly/monthly) for a project.
-
-**Parameters:**
-- project_id (required): Project UUID
-- period: 'daily' | 'weekly' | 'monthly' (default: daily)
-- limit: Max records to return (default: 30)
-
-**Returns:** Cost summary with totals and breakdown by model`,
-
-	get_cost_alerts: `# get_cost_alerts
-Get cost alerts for the current user.
-
-**Parameters:**
-- project_id (optional): Filter by project
-
-**Returns:** Array of configured cost alerts`,
-
-	add_cost_alert: `# add_cost_alert
-Add a cost threshold alert.
-
-**Parameters:**
-- project_id (optional): Specific project or null for all
-- threshold_amount (required): Amount in USD
-- threshold_period (required): 'daily' | 'weekly' | 'monthly'
-- alert_type: 'warning' | 'critical' (default: warning)
-
-**Example:** add_cost_alert(threshold_amount: 50, threshold_period: "daily", alert_type: "warning")`,
-
-	update_cost_alert: `# update_cost_alert
-Update an existing cost alert.
-
-**Parameters:**
-- alert_id (required): Alert UUID
-- threshold_amount: New amount in USD
-- threshold_period: New period
-- alert_type: New alert type
-- enabled: Enable/disable the alert`,
-
-	delete_cost_alert: `# delete_cost_alert
-Delete a cost alert.
-
-**Parameters:**
-- alert_id (required): Alert UUID to delete`,
-
-	get_task_costs: `# get_task_costs
-Get cost breakdown by task for a project.
-
-**Parameters:**
-- project_id (required): Project UUID
-- limit: Max tasks to return (default: 20)
-
-**Returns:** Tasks sorted by estimated cost with model breakdown`,
-
-	// Knowledge base tools
-	query_knowledge_base: `# query_knowledge_base
-Query aggregated project knowledge in a single call. Reduces token usage by combining multiple data sources.
-
-**Parameters:**
-- project_id (required): Project UUID
-- scope: 'summary' (default) or 'detailed' (includes rationales, descriptions)
-- categories: Array of categories to include (default: all)
-  - findings: Audit findings (security, performance, code quality)
-  - qa: Questions and answers
-  - decisions: Architectural decisions
-  - completed_tasks: Tasks with completion summaries
-  - blockers: Resolved blockers with resolution notes
-  - progress: Recent progress logs
-- limit: Max items per category (default: 5, max: 20)
-- search_query: Optional text search across all knowledge
-
-**Returns:**
-- project: name, goal, tech_stack
-- stats: counts for each category, findings by severity
-- Category data based on selection
-
-**Token savings:** Replaces up to 6 separate tool calls (get_findings, get_decisions, get_tasks, get_blockers, etc.) with one call.
-
-**Example:** query_knowledge_base(project_id, categories: ["findings", "decisions"], limit: 10)`,
-};
-
 export const discoverTools: Handler = async (args) => {
 	const { category } = args as { category?: string };
 
@@ -979,7 +260,9 @@ export const getToolInfo: Handler = async (args) => {
 		return { result: { error: 'tool_name is required' } };
 	}
 
-	const info = TOOL_INFO[tool_name];
+	// Lazy-load tool documentation
+	const toolDocs = await getToolDocs();
+	const info = toolDocs[tool_name];
 	if (!info) {
 		return {
 			result: {