@codemcp/workflows 3.1.21

package/src/tool-handlers/conduct-review.ts

@@ -0,0 +1,191 @@
+/**
+ * ConductReview Tool Handler
+ *
+ * Handles review requests before phase transitions. Adapts to MCP environment
+ * capabilities - returns automated review results if sampling available,
+ * otherwise returns instructions for LLM to conduct guided review.
+ */
+
+import { ConversationRequiredToolHandler } from './base-tool-handler.js';
+import { validateRequiredArgs } from '../server-helpers.js';
+import type { ConversationContext } from '@codemcp/workflows-core';
+import type { YamlTransition } from '@codemcp/workflows-core';
+import { ServerContext } from '../types.js';
+
+/**
+ * Arguments for the conduct_review tool
+ */
+export interface ConductReviewArgs {
+  target_phase: string;
+}
+
+/**
+ * Response from the conduct_review tool
+ */
+export interface ConductReviewResult {
+  instructions: string;
+  perspectives: Array<{
+    name: string;
+    prompt: string;
+  }>;
+}
+
+/**
+ * ConductReview tool handler implementation
+ */
+export class ConductReviewHandler extends ConversationRequiredToolHandler<
+  ConductReviewArgs,
+  ConductReviewResult
+> {
+  protected async executeWithConversation(
+    args: ConductReviewArgs,
+    context: ServerContext,
+    conversationContext: ConversationContext
+  ): Promise<ConductReviewResult> {
+    // Validate required arguments
+    validateRequiredArgs(args, ['target_phase']);
+
+    const { target_phase } = args;
+    const currentPhase = conversationContext.currentPhase;
+    const conversationId = conversationContext.conversationId;
+
+    this.logger.debug('Processing conduct_review request', {
+      conversationId,
+      currentPhase,
+      targetPhase: target_phase,
+    });
+
+    // Ensure state machine is loaded for this project
+    this.ensureStateMachineForProject(context, conversationContext.projectPath);
+
+    // Get transition configuration from workflow
+    const transition = this.getTransitionConfig(
+      currentPhase,
+      target_phase,
+      conversationContext.workflowName,
+      context
+    );
+
+    if (
+      !transition.review_perspectives ||
+      transition.review_perspectives.length === 0
+    ) {
+      throw new Error(
+        `No review perspectives defined for transition from ${currentPhase} to ${target_phase}`
+      );
+    }
+
+    // Check if MCP environment supports sampling (LLM interaction tools)
+    const hasSamplingCapability = await this.checkSamplingCapability(context);
+
+    if (hasSamplingCapability) {
+      // Conduct automated review using available LLM tools
+      return await this.conductAutomatedReview(
+        transition.review_perspectives,
+        conversationContext
+      );
+    } else {
+      // Generate instructions for LLM to conduct review
+      return await this.generateReviewInstructions(
+        transition.review_perspectives,
+        currentPhase,
+        target_phase
+      );
+    }
+  }
+
+  /**
+   * Get transition configuration from workflow
+   */
+  private getTransitionConfig(
+    currentPhase: string,
+    targetPhase: string,
+    workflowName: string,
+    context: ServerContext
+  ) {
+    const stateMachine = context.workflowManager.loadWorkflowForProject(
+      context.projectPath,
+      workflowName
+    );
+    const currentState = stateMachine.states[currentPhase];
+
+    if (!currentState) {
+      throw new Error(`Invalid current phase: ${currentPhase}`);
+    }
+
+    const transition = currentState.transitions.find(
+      (t: YamlTransition) => t.to === targetPhase
+    );
+    if (!transition) {
+      throw new Error(
+        `No transition found from ${currentPhase} to ${targetPhase}`
+      );
+    }
+
+    return transition;
+  }
+
+  /**
+   * Check if MCP environment supports sampling capabilities
+   */
+  private async checkSamplingCapability(
+    _context: ServerContext
+  ): Promise<boolean> {
+    // For now, assume non-sampling (most common case)
+    // In the future, this could check for specific LLM interaction tools
+    return false;
+  }
+
+  /**
+   * Conduct automated review using LLM tools (when sampling is available)
+   */
+  private async conductAutomatedReview(
+    perspectives: Array<{ perspective: string; prompt: string }>,
+    conversationContext: ConversationContext
+  ): Promise<ConductReviewResult> {
+    // TODO: Implement automated review when sampling tools are available
+    // For now, fall back to guided instructions
+    return this.generateReviewInstructions(
+      perspectives,
+      conversationContext.currentPhase,
+      'target'
+    );
+  }
+
+  /**
+   * Generate instructions for LLM to conduct guided review
+   */
+  private async generateReviewInstructions(
+    perspectives: Array<{ perspective: string; prompt: string }>,
+    currentPhase: string,
+    targetPhase: string
+  ): Promise<ConductReviewResult> {
+    const instructions = `Conduct a review of the ${currentPhase} phase before proceeding to ${targetPhase}.
+
+First, identify the artifacts and decisions from the ${currentPhase} phase by:
+1. Reviewing the plan file to see completed tasks and key decisions
+2. Using git status/diff to see what files were changed (if in a git repository)
+3. Analyzing recent conversation history for important decisions
+
+Then, for each perspective below, analyze these artifacts and provide feedback:
+
+${perspectives
+  .map(
+    (p, i) => `**${i + 1}. ${p.perspective.toUpperCase()} PERSPECTIVE:**
+${p.prompt}
+
+`
+  )
+  .join('')}
+
+After completing all perspective reviews, summarize your findings and ask the user if they're ready to proceed to the ${targetPhase} phase.`;
+
+    return {
+      instructions,
+      perspectives: perspectives.map(p => ({
+        name: p.perspective,
+        prompt: p.prompt,
+      })),
+    };
+  }
+}

package/src/tool-handlers/get-tool-info.ts

@@ -0,0 +1,274 @@
+/**
+ * Get Tool Info Handler
+ *
+ * Provides comprehensive information about the responsible-vibe-mcp development
+ * workflow tools for better tool discoverability and AI integration.
+ */
+
+import { z } from 'zod';
+import { BaseToolHandler } from './base-tool-handler.js';
+import { createLogger } from '@codemcp/workflows-core';
+import { ServerContext } from '../types.js';
+
+const logger = createLogger('GetToolInfoHandler');
+
+/**
+ * Schema for get_tool_info tool arguments
+ */
+const GetToolInfoArgsSchema = z.object({
+  // No input parameters needed
+});
+
+type GetToolInfoArgs = z.infer<typeof GetToolInfoArgsSchema>;
+
+/**
+ * Tool information structure
+ */
+interface ToolInfo {
+  name: string;
+  description: string;
+  parameters: string[];
+  schema?: {
+    required: string[];
+    optional: string[];
+  };
+}
+
+/**
+ * Workflow information structure
+ */
+interface WorkflowInfo {
+  name: string;
+  displayName: string;
+  description: string;
+  phases?: string[];
+}
+
+/**
+ * Complete tool information response
+ */
+interface GetToolInfoResponse {
+  tool_name: string;
+  version: string;
+  purpose: string;
+  description: string;
+
+  available_tools: ToolInfo[];
+  available_workflows: WorkflowInfo[];
+
+  core_concepts: {
+    phase_management: string;
+    plan_file_tracking: string;
+    conversation_context: string;
+    workflow_guidance: string;
+  };
+
+  usage_guidelines: {
+    required_pattern: string;
+    phase_transitions: string;
+    context_requirements: string;
+    plan_file_management: string;
+  };
+
+  workflow_states?: {
+    current_phase?: string;
+    conversation_id?: string;
+    plan_file_path?: string;
+  };
+}
+
+/**
+ * Tool handler for providing comprehensive tool information
+ */
+export class GetToolInfoHandler extends BaseToolHandler<
+  GetToolInfoArgs,
+  GetToolInfoResponse
+> {
+  protected readonly argsSchema = GetToolInfoArgsSchema;
+
+  async executeHandler(
+    _args: GetToolInfoArgs,
+    context: ServerContext
+  ): Promise<GetToolInfoResponse> {
+    logger.info('Generating comprehensive tool information', {
+      projectPath: context.projectPath,
+    });
+
+    // Get available workflows
+    const availableWorkflows =
+      context.workflowManager.getAvailableWorkflowsForProject(
+        context.projectPath
+      );
+
+    // Transform workflows to response format
+    const workflows: WorkflowInfo[] = availableWorkflows.map(workflow => ({
+      name: workflow.name,
+      displayName: workflow.displayName,
+      description: workflow.description,
+      phases: this.extractWorkflowPhases(workflow),
+    }));
+
+    // Define available tools with their information
+    const tools: ToolInfo[] = [
+      {
+        name: 'start_development',
+        description:
+          'Initialize new development project with structured workflow',
+        parameters: ['workflow', 'commit_behaviour'],
+        schema: {
+          required: ['commit_behaviour'],
+          optional: ['workflow'],
+        },
+      },
+      {
+        name: 'whats_next',
+        description:
+          'Get phase-specific instructions and guidance for current development state',
+        parameters: [
+          'context',
+          'user_input',
+          'conversation_summary',
+          'recent_messages',
+        ],
+        schema: {
+          required: ['context', 'user_input'],
+          optional: ['conversation_summary', 'recent_messages'],
+        },
+      },
+      {
+        name: 'proceed_to_phase',
+        description:
+          'Transition to the next development phase when current phase is complete',
+        parameters: ['target_phase', 'reason'],
+        schema: {
+          required: ['target_phase'],
+          optional: ['reason'],
+        },
+      },
+      {
+        name: 'resume_workflow',
+        description:
+          'Continue development after a break or conversation restart',
+        parameters: ['include_system_prompt'],
+        schema: {
+          required: [],
+          optional: ['include_system_prompt'],
+        },
+      },
+      {
+        name: 'reset_development',
+        description:
+          'Start over with a clean slate by deleting all development progress',
+        parameters: ['confirm', 'reason'],
+        schema: {
+          required: ['confirm'],
+          optional: ['reason'],
+        },
+      },
+      {
+        name: 'list_workflows',
+        description:
+          'Get an overview of all available workflows with descriptions',
+        parameters: [],
+        schema: {
+          required: [],
+          optional: [],
+        },
+      },
+      {
+        name: 'get_tool_info',
+        description:
+          'Get comprehensive information about all available tools and workflows',
+        parameters: [],
+        schema: {
+          required: [],
+          optional: [],
+        },
+      },
+    ];
+
+    // Try to get current workflow state if available
+    let workflowState: GetToolInfoResponse['workflow_states'] = undefined;
+    try {
+      const conversationContext =
+        await context.conversationManager.getConversationContext();
+      workflowState = {
+        current_phase: conversationContext.currentPhase,
+        conversation_id: conversationContext.conversationId,
+        plan_file_path: conversationContext.planFilePath,
+      };
+    } catch (error) {
+      // No active conversation - this is fine
+      logger.debug('No active conversation found for workflow state', {
+        error,
+      });
+    }
+
+    // Build the complete response
+    const response: GetToolInfoResponse = {
+      tool_name: 'Responsible Vibe MCP - Development Workflow Management',
+      version: '3.1.6-monorepo', // This should ideally come from package.json
+      purpose:
+        'Structured development workflows with guided phase transitions and conversation state management',
+      description:
+        'A Model Context Protocol server that acts as an intelligent conversation state manager and development guide for LLMs, providing structured workflows for various development tasks including bug fixes, features, architecture documentation, and more.',
+
+      available_tools: tools,
+      available_workflows: workflows,
+
+      core_concepts: {
+        phase_management:
+          'Structured progression through development phases with entrance criteria and transition conditions',
+        plan_file_tracking:
+          'Maintains development state and progress in .vibe/development-plan-*.md files with task tracking',
+        conversation_context:
+          'Stateless operation requiring context in each whats_next() call for proper guidance',
+        workflow_guidance:
+          'Provides phase-specific instructions and recommendations based on current development state',
+      },
+
+      usage_guidelines: {
+        required_pattern:
+          'Always call whats_next() after user interactions to get context-appropriate guidance',
+        phase_transitions:
+          'Only proceed to next phase when entrance criteria are met and current phase tasks are complete',
+        context_requirements:
+          'Provide conversation history and context in whats_next() calls for optimal guidance',
+        plan_file_management:
+          'Update plan file with completed tasks [x] and add new tasks as they are identified',
+      },
+    };
+
+    // Add workflow state if available
+    if (workflowState) {
+      response.workflow_states = workflowState;
+    }
+
+    logger.info('Successfully generated tool information', {
+      toolCount: tools.length,
+      workflowCount: workflows.length,
+      hasWorkflowState: !!workflowState,
+    });
+
+    return response;
+  }
+
+  /**
+   * Extract phase names from a workflow configuration
+   */
+  private extractWorkflowPhases(workflowInfo: unknown): string[] | undefined {
+    if (
+      workflowInfo &&
+      typeof workflowInfo === 'object' &&
+      'states' in workflowInfo &&
+      workflowInfo.states &&
+      typeof workflowInfo.states === 'object'
+    ) {
+      return Object.keys(workflowInfo.states);
+    }
+    return undefined;
+  }
+}
+
+// Export type for external use
+export type { GetToolInfoArgs, GetToolInfoResponse };

package/src/tool-handlers/index.ts

@@ -0,0 +1,117 @@
+/**
+ * Tool Handler Registry
+ *
+ * Central registry for all tool handlers. Provides registration and lookup
+ * functionality for tool handlers used by the MCP server.
+ */
+
+import { createLogger } from '@codemcp/workflows-core';
+import { WhatsNextHandler } from './whats-next.js';
+import { ProceedToPhaseHandler } from './proceed-to-phase.js';
+import { ConductReviewHandler } from './conduct-review.js';
+import { StartDevelopmentHandler } from './start-development.js';
+import { ResumeWorkflowHandler } from './resume-workflow.js';
+import { ResetDevelopmentHandler } from './reset-development.js';
+import { InstallWorkflowHandler } from './install-workflow.js';
+import { ListWorkflowsHandler } from './list-workflows.js';
+import { GetToolInfoHandler } from './get-tool-info.js';
+import { SetupProjectDocsHandler } from './setup-project-docs.js';
+import { NoIdeaHandler } from './no-idea.js';
+import { ToolHandler, ToolRegistry } from '../types.js';
+
+const logger = createLogger('ToolRegistry');
+
+/**
+ * Default implementation of ToolRegistry
+ */
+export class DefaultToolRegistry implements ToolRegistry {
+  private handlers = new Map<string, ToolHandler>();
+
+  register<T extends ToolHandler>(name: string, handler: T): void {
+    logger.debug('Registering tool handler', {
+      name,
+      handlerType: handler.constructor.name,
+    });
+    this.handlers.set(name, handler);
+  }
+
+  get(name: string): ToolHandler | undefined {
+    return this.handlers.get(name);
+  }
+
+  list(): string[] {
+    return Array.from(this.handlers.keys());
+  }
+}
+
+/**
+ * Create and configure the default tool registry with all standard handlers
+ */
+export function createToolRegistry(): ToolRegistry {
+  const registry = new DefaultToolRegistry();
+
+  // Register all standard tool handlers
+  registry.register('whats_next', new WhatsNextHandler());
+  registry.register('proceed_to_phase', new ProceedToPhaseHandler());
+  registry.register('conduct_review', new ConductReviewHandler());
+  registry.register('start_development', new StartDevelopmentHandler());
+  registry.register('resume_workflow', new ResumeWorkflowHandler());
+  registry.register('reset_development', new ResetDevelopmentHandler());
+  registry.register('install_workflow', new InstallWorkflowHandler());
+  registry.register('list_workflows', new ListWorkflowsHandler());
+  registry.register('get_tool_info', new GetToolInfoHandler());
+  registry.register('setup_project_docs', new SetupProjectDocsHandler());
+  registry.register('no_idea', new NoIdeaHandler());
+
+  logger.info('Tool registry created with handlers', {
+    handlers: registry.list(),
+  });
+
+  return registry;
+}
+
+// Export all handler types for external use
+export { WhatsNextHandler } from './whats-next.js';
+export { ProceedToPhaseHandler } from './proceed-to-phase.js';
+export { ConductReviewHandler } from './conduct-review.js';
+export { StartDevelopmentHandler } from './start-development.js';
+export { ResumeWorkflowHandler } from './resume-workflow.js';
+export { ResetDevelopmentHandler } from './reset-development.js';
+export { InstallWorkflowHandler } from './install-workflow.js';
+export { ListWorkflowsHandler } from './list-workflows.js';
+export { GetToolInfoHandler } from './get-tool-info.js';
+export { SetupProjectDocsHandler } from './setup-project-docs.js';
+export { NoIdeaHandler } from './no-idea.js';
+export {
+  BaseToolHandler,
+  ConversationRequiredToolHandler,
+} from './base-tool-handler.js';
+
+// Export argument and result types
+export type { WhatsNextArgs, WhatsNextResult } from './whats-next.js';
+export type {
+  ProceedToPhaseArgs,
+  ProceedToPhaseResult,
+} from './proceed-to-phase.js';
+export type {
+  ConductReviewArgs,
+  ConductReviewResult,
+} from './conduct-review.js';
+export type {
+  StartDevelopmentArgs,
+  StartDevelopmentResult,
+} from './start-development.js';
+export type {
+  ResumeWorkflowArgs,
+  ResumeWorkflowResult,
+} from './resume-workflow.js';
+export type {
+  ResetDevelopmentArgs,
+  ResetDevelopmentResult,
+} from './reset-development.js';
+export type { GetToolInfoArgs, GetToolInfoResponse } from './get-tool-info.js';
+export type {
+  SetupProjectDocsArgs,
+  SetupProjectDocsResult,
+} from './setup-project-docs.js';
+export type { NoIdeaArgs, NoIdeaResponse } from './no-idea.js';