@vibescope/mcp-server 0.3.0 → 0.3.3

package/src/tools/file-checkouts.ts

@@ -0,0 +1,145 @@
+/**
+ * File Checkout Tool Definitions
+ *
+ * Tools for multi-agent file coordination:
+ * - checkout_file
+ * - checkin_file
+ * - get_file_checkouts
+ * - abandon_checkout
+ * - is_file_available
+ * - get_file_checkouts_stats
+ */
+
+import type { Tool } from './types.js';
+
+export const fileCheckoutTools: Tool[] = [
+	{
+		name: 'checkout_file',
+		description: 'Check out a file for editing. Prevents other agents from editing the same file until checked in. ALWAYS checkout files before making changes to prevent conflicts.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				file_path: {
+					type: 'string',
+					description: 'Relative path to the file to checkout (e.g., "src/index.ts")',
+				},
+				reason: {
+					type: 'string',
+					description: 'Optional reason for checkout (e.g., "Fixing bug in login flow")',
+				},
+			},
+			required: ['project_id', 'file_path'],
+		},
+	},
+	{
+		name: 'checkin_file',
+		description: 'Check in a file after editing. Releases the file for other agents to edit. ALWAYS checkin files when done editing.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				checkout_id: {
+					type: 'string',
+					description: 'Checkout UUID (from checkout_file response)',
+				},
+				project_id: {
+					type: 'string',
+					description: 'Project UUID (alternative to checkout_id)',
+				},
+				file_path: {
+					type: 'string',
+					description: 'File path (use with project_id as alternative to checkout_id)',
+				},
+				summary: {
+					type: 'string',
+					description: 'Optional summary of changes made',
+				},
+			},
+		},
+	},
+	{
+		name: 'get_file_checkouts',
+		description: 'Get list of file checkouts for a project. Shows which files are currently checked out and by whom.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				status: {
+					type: 'string',
+					enum: ['checked_out', 'checked_in', 'abandoned'],
+					description: 'Filter by status (default: checked_out)',
+				},
+				include_completed: {
+					type: 'boolean',
+					description: 'Include checked_in and abandoned checkouts (default: false)',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max checkouts to return (default: 50)',
+				},
+				offset: {
+					type: 'number',
+					description: 'Number of checkouts to skip for pagination (default 0)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'abandon_checkout',
+		description: 'Force-release a checkout. Use when the original agent session died or is stuck.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				checkout_id: {
+					type: 'string',
+					description: 'Checkout UUID to abandon',
+				},
+				reason: {
+					type: 'string',
+					description: 'Reason for abandoning (e.g., "Agent session died")',
+				},
+			},
+			required: ['checkout_id'],
+		},
+	},
+	{
+		name: 'is_file_available',
+		description: 'Check if a file is available for checkout. Returns who has it checked out if not available.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				file_path: {
+					type: 'string',
+					description: 'Path to the file to check',
+				},
+			},
+			required: ['project_id', 'file_path'],
+		},
+	},
+	{
+		name: 'get_file_checkouts_stats',
+		description:
+			'Get aggregate statistics about file checkouts for a project. Returns counts by status without the actual checkout data. This is much more token-efficient than get_file_checkouts for understanding the overall state.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+];

package/src/tools/findings.ts

@@ -0,0 +1,101 @@
+/**
+ * Finding Tool Definitions
+ *
+ * Tools for managing audit/review findings:
+ * - add_finding
+ * - get_finding
+ * - get_findings
+ * - get_findings_stats
+ * - update_finding
+ * - delete_finding
+ */
+
+import type { Tool } from './types.js';
+
+export const findingTools: Tool[] = [
+	{
+		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_finding',
+		description: `Get a single finding by ID. More token-efficient than get_findings when you need details for a specific finding.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				finding_id: { type: 'string', description: 'Finding UUID' },
+			},
+			required: ['finding_id'],
+		},
+	},
+	{
+		name: 'get_findings',
+		description: `Get findings for a project, optionally filtered by category, severity, or status. Returns summary fields by default (id, title, category, severity, status). Set summary_only=false for full details. For just counts, use get_findings_stats instead.`,
+		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: open)' },
+				limit: { type: 'number', description: 'Max number of findings to return (default 10, max 200)' },
+				offset: { type: 'number', description: 'Number of findings to skip for pagination (default 0)' },
+				search_query: { type: 'string', description: 'Search findings by title' },
+				summary_only: { type: 'boolean', description: 'When true (default), returns only id, title, category, severity, status. Set to false for full details.' },
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'get_findings_stats',
+		description: `Get aggregate statistics about findings for a project. Returns total count and breakdowns by status, severity, and category. Much more token-efficient than get_findings when you just need to understand the overall state.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: { type: 'string', description: 'Project UUID' },
+			},
+			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'],
+		},
+	},
+];

package/src/tools/git-issues.ts

@@ -0,0 +1,130 @@
+/**
+ * Git Issue Tool Definitions
+ *
+ * Tools for managing git-related issues:
+ * - add_git_issue
+ * - resolve_git_issue
+ * - get_git_issues
+ * - delete_git_issue
+ */
+
+import type { Tool } from './types.js';
+
+export const gitIssueTools: Tool[] = [
+	{
+		name: 'add_git_issue',
+		description: `Record a git-related issue (merge conflict, push failure, etc.). Auto-created by claim_validation when conflicts detected.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				issue_type: {
+					type: 'string',
+					enum: ['merge_conflict', 'push_failed', 'rebase_needed', 'branch_diverged', 'pr_not_mergeable'],
+					description: 'Type of git issue',
+				},
+				branch: {
+					type: 'string',
+					description: 'Branch where the issue occurred',
+				},
+				target_branch: {
+					type: 'string',
+					description: 'Target branch for merge/rebase (optional)',
+				},
+				pr_url: {
+					type: 'string',
+					description: 'Pull request URL if applicable (optional)',
+				},
+				conflicting_files: {
+					type: 'array',
+					items: { type: 'string' },
+					description: 'List of files with conflicts (optional)',
+				},
+				error_message: {
+					type: 'string',
+					description: 'Error message from git operation (optional)',
+				},
+				task_id: {
+					type: 'string',
+					description: 'Related task UUID (optional)',
+				},
+			},
+			required: ['project_id', 'issue_type', 'branch'],
+		},
+	},
+	{
+		name: 'resolve_git_issue',
+		description: `Mark a git issue as resolved.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				git_issue_id: {
+					type: 'string',
+					description: 'Git issue UUID',
+				},
+				resolution_note: {
+					type: 'string',
+					description: 'How the issue was resolved (optional)',
+				},
+				auto_resolved: {
+					type: 'boolean',
+					description: 'Whether this was auto-resolved (e.g., PR became mergeable)',
+				},
+			},
+			required: ['git_issue_id'],
+		},
+	},
+	{
+		name: 'get_git_issues',
+		description: `Get git issues for a project, optionally filtered by status, type, or branch.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				status: {
+					type: 'string',
+					enum: ['open', 'resolved'],
+					description: 'Filter by status (default: open)',
+				},
+				issue_type: {
+					type: 'string',
+					enum: ['merge_conflict', 'push_failed', 'rebase_needed', 'branch_diverged', 'pr_not_mergeable'],
+					description: 'Filter by issue type (optional)',
+				},
+				branch: {
+					type: 'string',
+					description: 'Filter by branch (optional)',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max issues to return (default: 50)',
+				},
+				offset: {
+					type: 'number',
+					description: 'Number of issues to skip for pagination (default 0)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'delete_git_issue',
+		description: `Delete a git issue.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				git_issue_id: {
+					type: 'string',
+					description: 'Git issue UUID',
+				},
+			},
+			required: ['git_issue_id'],
+		},
+	},
+];

package/src/tools/ideas.ts

@@ -0,0 +1,162 @@
+/**
+ * Idea Tool Definitions
+ *
+ * Tools for managing improvement ideas:
+ * - add_idea
+ * - update_idea
+ * - get_idea
+ * - get_ideas
+ * - delete_idea
+ * - convert_idea_to_task
+ */
+
+import type { Tool } from './types.js';
+
+export const ideaTools: Tool[] = [
+	{
+		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_idea',
+		description: `Get a single idea by ID. More token-efficient than get_ideas when you need details for a specific idea.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				idea_id: {
+					type: 'string',
+					description: 'Idea UUID',
+				},
+			},
+			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)',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max number of ideas to return (default 10, max 100)',
+				},
+				offset: {
+					type: 'number',
+					description: 'Number of ideas to skip for pagination (default 0)',
+				},
+				search_query: {
+					type: 'string',
+					description: 'Search ideas by title or description',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		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'],
+		},
+	},
+];

package/src/tools/index.ts

@@ -0,0 +1,131 @@
+/**
+ * MCP Tool Definitions
+ *
+ * This module exports all tool definitions organized by domain.
+ * Each domain file exports an array of Tool objects.
+ */
+
+import type { Tool } from './types.js';
+export type { Tool };
+
+// Domain-specific tool imports
+import { sessionTools } from './session.js';
+import { costTools } from './cost.js';
+import { discoveryTools } from './discovery.js';
+import { worktreeTools } from './worktrees.js';
+import { projectTools } from './project.js';
+import { taskTools } from './tasks.js';
+import { progressTools } from './progress.js';
+import { blockerTools } from './blockers.js';
+import { decisionTools } from './decisions.js';
+import { ideaTools } from './ideas.js';
+import { findingTools } from './findings.js';
+import { validationTools } from './validation.js';
+import { deploymentTools } from './deployment.js';
+import { fallbackTools } from './fallback.js';
+import { requestTools } from './requests.js';
+import { milestoneTools } from './milestones.js';
+import { bodiesOfWorkTools } from './bodies-of-work.js';
+import { organizationTools } from './organizations.js';
+import { fileCheckoutTools } from './file-checkouts.js';
+import { roleTools } from './roles.js';
+import { sprintTools } from './sprints.js';
+import { gitIssueTools } from './git-issues.js';
+import { connectorTools } from './connectors.js';
+import { cloudAgentTools } from './cloud-agents.js';
+
+/**
+ * All MCP tool definitions combined
+ */
+export const tools: Tool[] = [
+	...sessionTools,
+	...costTools,
+	...discoveryTools,
+	...worktreeTools,
+	...projectTools,
+	...taskTools,
+	...progressTools,
+	...blockerTools,
+	...decisionTools,
+	...ideaTools,
+	...findingTools,
+	...validationTools,
+	...deploymentTools,
+	...fallbackTools,
+	...requestTools,
+	...milestoneTools,
+	...bodiesOfWorkTools,
+	...organizationTools,
+	...fileCheckoutTools,
+	...roleTools,
+	...sprintTools,
+	...gitIssueTools,
+	...connectorTools,
+	...cloudAgentTools,
+];
+
+/**
+ * Build the complete tool list from all domain modules
+ * (Backward compatible function - use `tools` export directly)
+ */
+export function buildToolList(): Tool[] {
+	return tools;
+}
+
+/**
+ * Get tool names by domain for categorization
+ */
+export const toolCategories = {
+	session: sessionTools.map((t) => t.name),
+	cost: costTools.map((t) => t.name),
+	discovery: discoveryTools.map((t) => t.name),
+	worktrees: worktreeTools.map((t) => t.name),
+	project: projectTools.map((t) => t.name),
+	tasks: taskTools.map((t) => t.name),
+	progress: progressTools.map((t) => t.name),
+	blockers: blockerTools.map((t) => t.name),
+	decisions: decisionTools.map((t) => t.name),
+	ideas: ideaTools.map((t) => t.name),
+	findings: findingTools.map((t) => t.name),
+	validation: validationTools.map((t) => t.name),
+	deployment: deploymentTools.map((t) => t.name),
+	fallback: fallbackTools.map((t) => t.name),
+	requests: requestTools.map((t) => t.name),
+	milestones: milestoneTools.map((t) => t.name),
+	bodiesOfWork: bodiesOfWorkTools.map((t) => t.name),
+	organizations: organizationTools.map((t) => t.name),
+	fileCheckouts: fileCheckoutTools.map((t) => t.name),
+	roles: roleTools.map((t) => t.name),
+	sprints: sprintTools.map((t) => t.name),
+	gitIssues: gitIssueTools.map((t) => t.name),
+	connectors: connectorTools.map((t) => t.name),
+	cloudAgents: cloudAgentTools.map((t) => t.name),
+} as const;
+
+// Re-export domain tools for selective imports
+export {
+	sessionTools,
+	costTools,
+	discoveryTools,
+	worktreeTools,
+	projectTools,
+	taskTools,
+	progressTools,
+	blockerTools,
+	decisionTools,
+	ideaTools,
+	findingTools,
+	validationTools,
+	deploymentTools,
+	fallbackTools,
+	requestTools,
+	milestoneTools,
+	bodiesOfWorkTools,
+	organizationTools,
+	fileCheckoutTools,
+	roleTools,
+	sprintTools,
+	gitIssueTools,
+	connectorTools,
+	cloudAgentTools,
+};