@vibescope/mcp-server 0.5.0 → 0.5.1

package/src/tools/roles.ts

@@ -1,112 +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'],
-		},
-	},
-];
+/**
+ * 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

@@ -1,181 +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)',
-				},
-			},
-		},
-	},
-];
+/**
+ * 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)',
+				},
+			},
+		},
+	},
+];