@vibescope/mcp-server 0.3.0 → 0.3.3

package/src/tools/roles.ts

@@ -0,0 +1,112 @@
+/**
+ * Role Tool Definitions
+ *
+ * Tools for managing agent roles:
+ * - get_role_settings
+ * - update_role_settings
+ * - set_session_role
+ * - get_agents_by_role
+ */
+
+import type { Tool } from './types.js';
+
+export const roleTools: Tool[] = [
+	{
+		name: 'get_role_settings',
+		description: 'Get role configuration for a project. Shows available roles and their settings.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'update_role_settings',
+		description: 'Update role settings for a project. Configure which roles are enabled and their behavior.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				role: {
+					type: 'string',
+					description: 'Role to configure (e.g., "developer", "validator", "deployer"). Custom roles accepted.',
+				},
+				enabled: {
+					type: 'boolean',
+					description: 'Enable or disable this role',
+				},
+				display_name: {
+					type: 'string',
+					description: 'Custom display name for this role',
+				},
+				description: {
+					type: 'string',
+					description: 'Description of what this role does',
+				},
+				priority_filter: {
+					type: 'array',
+					items: { type: 'number' },
+					description: 'Only show tasks with these priorities (1-5)',
+				},
+				fallback_activities: {
+					type: 'array',
+					items: { type: 'string' },
+					description: 'Preferred fallback activities for this role',
+				},
+				auto_assign_validation: {
+					type: 'boolean',
+					description: 'Auto-assign validation tasks to agents with this role',
+				},
+				auto_assign_deployment: {
+					type: 'boolean',
+					description: 'Auto-assign deployment tasks to agents with this role',
+				},
+			},
+			required: ['project_id', 'role'],
+		},
+	},
+	{
+		name: 'set_session_role',
+		description: 'Set the role for your current session. Changes task filtering and fallback activity suggestions.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				role: {
+					type: 'string',
+					description: 'Role to assign to this session (e.g., "developer", "validator", "deployer"). Custom roles accepted.',
+				},
+				role_config: {
+					type: 'object',
+					description: 'Custom configuration for specialist role (optional)',
+				},
+			},
+			required: ['role'],
+		},
+	},
+	{
+		name: 'get_agents_by_role',
+		description: 'Get active agents grouped by their assigned roles. See who is working on what.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				counts_only: {
+					type: 'boolean',
+					description: 'When true (default), returns only counts per role to save tokens. Set to false for full agent details.',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+];

package/src/tools/session.ts

@@ -0,0 +1,181 @@
+/**
+ * Session Tool Definitions
+ *
+ * Tools for managing agent work sessions:
+ * - start_work_session
+ * - confirm_agent_setup
+ * - get_help
+ * - get_token_usage
+ * - report_token_usage
+ * - heartbeat
+ * - end_work_session
+ * - signal_idle
+ */
+
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const sessionTools: Tool[] = [
+	{
+		name: 'start_work_session',
+		description: `CALL THIS FIRST when beginning work on a project.
+Returns session info, persona, role, and next_task. Start the next_task IMMEDIATELY without asking the user.
+
+IMPORTANT: If the user gives you direct work that isn't tracked as a task (e.g., "add feature X", "fix bug Y"), you MUST call add_task() first to create a task before starting work. This ensures all work is tracked and visible on the dashboard.
+
+Use mode:'full' for complete context, mode:'lite' (default) for minimal tokens.`,
+		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',
+					description: 'Model being used for cost tracking. E.g., "opus", "sonnet", "haiku" for Claude, "gemini" for Gemini, "gpt-4o" for OpenAI.',
+				},
+				role: {
+					type: 'string',
+					description: 'Agent role (e.g., "developer", "validator", "deployer", "reviewer", "maintainer"). Custom roles accepted.',
+				},
+				hostname: {
+					type: 'string',
+					description: 'Machine hostname for worktree tracking. Pass os.hostname() to filter stale worktrees to only those created on this machine.',
+				},
+				agent_type: {
+					type: 'string',
+					description: 'Agent type (e.g., "claude", "gemini", "cursor", "windsurf"). Custom agent types accepted.',
+				},
+				agent_name: {
+					type: 'string',
+					description: 'Explicit agent name (for cloud/remote agents). If provided, uses this name instead of selecting from persona pool. Cloud agents should pass their spawner-assigned name.',
+				},
+			},
+		},
+	},
+	{
+		name: 'confirm_agent_setup',
+		description: `Confirm that agent setup is complete for this project. Call this after creating your agent's configuration file (e.g., .claude/CLAUDE.md, .gemini/GEMINI.md).
+
+This marks your agent type as fully onboarded to the project, so you won't receive setup instructions again.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				agent_type: {
+					type: 'string',
+					description: 'Agent type that completed setup (e.g., "claude", "gemini", "cursor"). Custom agent types accepted.',
+				},
+			},
+			required: ['project_id', 'agent_type'],
+		},
+	},
+	{
+		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', 'roles', 'knowledge', '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: {},
+		},
+	},
+	{
+		name: 'report_token_usage',
+		description: `Report actual Claude API token usage for accurate cost tracking.
+
+IMPORTANT: MCP can only estimate tokens from tool I/O (~1-5% of actual usage). Call this tool after each API response to report actual usage from the Claude API response headers.
+
+The Claude API response includes 'usage.input_tokens' and 'usage.output_tokens' - pass those values here for accurate cost attribution.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				input_tokens: {
+					type: 'number',
+					description: 'Input tokens from Claude API response (usage.input_tokens)',
+				},
+				output_tokens: {
+					type: 'number',
+					description: 'Output tokens from Claude API response (usage.output_tokens)',
+				},
+				model: {
+					type: 'string',
+					description: 'Model used for this API call (optional, uses session model if not provided)',
+				},
+			},
+			required: ['input_tokens', 'output_tokens'],
+		},
+	},
+	{
+		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)',
+				},
+				current_worktree_path: {
+					type: ['string', 'null'],
+					description: 'Report your current git worktree path (e.g., "../project-task-abc123"). Set to null to clear.',
+				},
+				hostname: {
+					type: 'string',
+					description: 'Machine hostname (os.hostname()). Updates session hostname for worktree tracking.',
+				},
+			},
+		},
+	},
+	{
+		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)',
+				},
+			},
+		},
+	},
+	{
+		name: 'signal_idle',
+		description: `Signal that agent is idle (no more tasks). Call this when complete_task returns no next_task or when there's no work available. This provides real-time visibility on the dashboard instead of waiting for heartbeat timeout.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				session_id: {
+					type: 'string',
+					description: 'Session ID (optional, uses current session if not provided)',
+				},
+			},
+		},
+	},
+];

package/src/tools/sprints.ts

@@ -0,0 +1,298 @@
+/**
+ * Sprint Tool Definitions
+ *
+ * Tools for managing sprints with velocity tracking:
+ * - create_sprint
+ * - update_sprint
+ * - get_sprint
+ * - get_sprints
+ * - delete_sprint
+ * - start_sprint
+ * - complete_sprint
+ * - add_task_to_sprint
+ * - remove_task_from_sprint
+ * - get_sprint_backlog
+ * - get_sprint_velocity
+ */
+
+import type { Tool } from './types.js';
+
+export const sprintTools: Tool[] = [
+	{
+		name: 'create_sprint',
+		description: `Create a new sprint. Sprints are time-bounded bodies of work with velocity tracking.
+Sprints start in 'planning' status where tasks can be added with story points.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				title: {
+					type: 'string',
+					description: 'Sprint title (e.g., "Sprint 5" or "Q1 Release")',
+				},
+				goal: {
+					type: 'string',
+					description: 'Sprint goal statement',
+				},
+				start_date: {
+					type: 'string',
+					description: 'Start date (YYYY-MM-DD)',
+				},
+				end_date: {
+					type: 'string',
+					description: 'End date (YYYY-MM-DD)',
+				},
+				auto_deploy_on_completion: {
+					type: 'boolean',
+					description: 'Automatically request deployment when sprint completes (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)',
+				},
+			},
+			required: ['project_id', 'title', 'start_date', 'end_date'],
+		},
+	},
+	{
+		name: 'update_sprint',
+		description: `Update a sprint's details. Can update title, goal, dates, and deployment settings.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				sprint_id: {
+					type: 'string',
+					description: 'Sprint UUID',
+				},
+				title: {
+					type: 'string',
+					description: 'New sprint title',
+				},
+				goal: {
+					type: 'string',
+					description: 'New sprint goal',
+				},
+				start_date: {
+					type: 'string',
+					description: 'New start date (YYYY-MM-DD)',
+				},
+				end_date: {
+					type: 'string',
+					description: 'New end date (YYYY-MM-DD)',
+				},
+				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',
+				},
+			},
+			required: ['sprint_id'],
+		},
+	},
+	{
+		name: 'get_sprint',
+		description: `Get a sprint with all its tasks organized by phase (pre/core/post).
+Includes progress percentage, velocity points, and committed points.
+Use summary_only: true to get task counts and next task instead of full task arrays (saves tokens).`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				sprint_id: {
+					type: 'string',
+					description: 'Sprint UUID',
+				},
+				summary_only: {
+					type: 'boolean',
+					description: 'Return task counts and next task instead of full task arrays (default: false)',
+				},
+			},
+			required: ['sprint_id'],
+		},
+	},
+	{
+		name: 'get_sprints',
+		description: `List sprints for a project with velocity metrics.
+Returns sprints sorted by sprint_number descending (most recent first).`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				status: {
+					type: 'string',
+					enum: ['planning', 'active', 'in_review', 'retrospective', 'completed', 'cancelled'],
+					description: 'Filter by sprint status (optional)',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max sprints to return (default: 20, max: 100)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'delete_sprint',
+		description: `Delete a sprint. Tasks are preserved but no longer grouped.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				sprint_id: {
+					type: 'string',
+					description: 'Sprint UUID',
+				},
+			},
+			required: ['sprint_id'],
+		},
+	},
+	{
+		name: 'start_sprint',
+		description: `Start a sprint. Transitions from 'planning' to 'active' status.
+Locks the committed_points at the current total story points.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				sprint_id: {
+					type: 'string',
+					description: 'Sprint UUID',
+				},
+			},
+			required: ['sprint_id'],
+		},
+	},
+	{
+		name: 'complete_sprint',
+		description: `Complete a sprint. Handles retrospective phase and auto-deployment if configured.
+Status flow: active → in_review → retrospective → completed`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				sprint_id: {
+					type: 'string',
+					description: 'Sprint UUID',
+				},
+				retrospective_notes: {
+					type: 'string',
+					description: 'Sprint retrospective notes',
+				},
+				skip_retrospective: {
+					type: 'boolean',
+					description: 'Skip retrospective phase and go directly to completed (default: false)',
+				},
+			},
+			required: ['sprint_id'],
+		},
+	},
+	{
+		name: 'add_task_to_sprint',
+		description: `Add a task to a sprint with optional story points.
+Tasks can be added during 'planning' status. Story points contribute to committed_points.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				sprint_id: {
+					type: 'string',
+					description: 'Sprint UUID',
+				},
+				task_id: {
+					type: 'string',
+					description: 'Task UUID to add',
+				},
+				story_points: {
+					type: 'number',
+					description: 'Story point estimate (optional, must be non-negative integer)',
+				},
+				phase: {
+					type: 'string',
+					enum: ['pre', 'core', 'post'],
+					description: 'Task phase (default: core)',
+				},
+			},
+			required: ['sprint_id', 'task_id'],
+		},
+	},
+	{
+		name: 'remove_task_from_sprint',
+		description: `Remove a task from a sprint. Task is preserved but returns to backlog.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				sprint_id: {
+					type: 'string',
+					description: 'Sprint UUID',
+				},
+				task_id: {
+					type: 'string',
+					description: 'Task UUID to remove',
+				},
+			},
+			required: ['sprint_id', 'task_id'],
+		},
+	},
+	{
+		name: 'get_sprint_backlog',
+		description: `Get tasks from backlog/pending that can be added to a sprint with pagination.
+Returns tasks not already assigned to any body of work or sprint.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				sprint_id: {
+					type: 'string',
+					description: 'Sprint UUID to exclude already-added tasks (optional)',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max tasks to return (default: 20, max: 50)',
+				},
+				offset: {
+					type: 'number',
+					description: 'Number of tasks to skip (default: 0)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'get_sprint_velocity',
+		description: `Get velocity metrics for completed sprints.
+Returns committed vs completed points and average velocity.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				limit: {
+					type: 'number',
+					description: 'Number of sprints to analyze (default: 10, max: 50)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+];