@codemcp/workflows 3.1.21

package/src/server-helpers.ts

@@ -0,0 +1,225 @@
+/**
+ * Server Helper Functions
+ *
+ * Common utility functions used across the server implementation.
+ * These are pure functions that don't depend on server state.
+ */
+
+import { homedir } from 'node:os';
+import { createLogger } from '@codemcp/workflows-core';
+import { HandlerResult } from './types.js';
+
+const logger = createLogger('ServerHelpers');
+
+/**
+ * Normalize and validate project path
+ * Ensures we have a valid project path, defaulting to home directory if needed
+ */
+export function normalizeProjectPath(projectPath?: string): string {
+  const path = projectPath || process.cwd();
+
+  if (path === '/' || path === '') {
+    const homePath = homedir();
+    logger.info('Invalid project path detected, using home directory', {
+      originalPath: path,
+      normalizedPath: homePath,
+    });
+    return homePath;
+  }
+
+  return path;
+}
+
+/**
+ * Create a standardized success result
+ */
+export function createSuccessResult<T>(
+  data: T,
+  metadata?: Record<string, unknown>
+): HandlerResult<T> {
+  return {
+    success: true,
+    data,
+    metadata,
+  };
+}
+
+/**
+ * Create a standardized error result
+ */
+export function createErrorResult(
+  error: string | Error,
+  metadata?: Record<string, unknown>
+): HandlerResult<never> {
+  const errorMessage = error instanceof Error ? error.message : error;
+
+  return {
+    success: false,
+    error: errorMessage,
+    metadata,
+  };
+}
+
+/**
+ * Safely execute an async operation and return a HandlerResult
+ * This provides consistent error handling across all handlers
+ */
+export async function safeExecute<T>(
+  operation: () => Promise<T>,
+  errorContext?: string
+): Promise<HandlerResult<T>> {
+  try {
+    const result = await operation();
+    return createSuccessResult(result);
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : 'Unknown error';
+    const contextualError = errorContext
+      ? `${errorContext}: ${errorMessage}`
+      : errorMessage;
+
+    logger.error('Operation failed', error as Error, { errorContext });
+    return createErrorResult(contextualError);
+  }
+}
+
+/**
+ * Validate required arguments for tool handlers
+ * Throws an error if any required arguments are missing
+ */
+export function validateRequiredArgs(
+  args: unknown,
+  requiredFields: string[]
+): void {
+  const missingFields = requiredFields.filter(
+    field =>
+      (args as Record<string, unknown>)[field] === undefined ||
+      (args as Record<string, unknown>)[field] === null
+  );
+
+  if (missingFields.length > 0) {
+    throw new Error(`Missing required arguments: ${missingFields.join(', ')}`);
+  }
+}
+
+/**
+ * Check if a conversation exists and provide helpful error if not
+ */
+export function createConversationNotFoundResult(
+  availableWorkflows: string[] = []
+): HandlerResult<never> {
+  if (availableWorkflows.length === 0) {
+    return createErrorResult(
+      'No development conversation has been started for this project and no workflows are available. Please install a workflow first or adjust the VIBE_WORKFLOW_DOMAINS environment variable.',
+      {
+        suggestion:
+          'install_workflow({ source: "waterfall" }) or set VIBE_WORKFLOW_DOMAINS=code,architecture,office',
+        availableWorkflows: [],
+      }
+    );
+  }
+
+  const firstWorkflow = availableWorkflows[0];
+  return createErrorResult(
+    'No development conversation has been started for this project. Please use the start_development tool first to initialize development with a workflow.',
+    {
+      suggestion: `start_development({ workflow: "${firstWorkflow}" })`,
+      availableWorkflows,
+    }
+  );
+}
+
+/**
+ * Extract workflow names for enum generation
+ * Used by server configuration to build Zod schemas
+ */
+export function buildWorkflowEnum(
+  workflowNames: string[]
+): [string, ...string[]] {
+  const allWorkflows = [...workflowNames, 'custom'];
+
+  // Ensure we have at least one element for TypeScript
+  if (allWorkflows.length === 0) {
+    return ['waterfall'];
+  }
+
+  return allWorkflows as [string, ...string[]];
+}
+
+/**
+ * Generate workflow description for tool schemas
+ */
+export function generateWorkflowDescription(
+  workflows: Array<{
+    name: string;
+    displayName: string;
+    description: string;
+    metadata?: {
+      complexity?: 'low' | 'medium' | 'high';
+      bestFor?: string[];
+      useCases?: string[];
+      examples?: string[];
+    };
+  }>
+): string {
+  let description = 'Choose your development workflow:\n\n';
+
+  for (const workflow of workflows) {
+    description += `• **${workflow.name}**: ${workflow.displayName} - ${workflow.description}`;
+
+    // Add enhanced metadata if available
+    if (workflow.metadata) {
+      const meta = workflow.metadata;
+
+      // Add complexity
+      if (meta.complexity) {
+        description += `\n  Complexity: ${meta.complexity}`;
+      }
+
+      // Add best for information
+      if (meta.bestFor && meta.bestFor.length > 0) {
+        description += `\n  Best for: ${meta.bestFor.join(', ')}`;
+      }
+
+      // Add examples
+      if (meta.examples && meta.examples.length > 0) {
+        description += `\n  Examples: ${meta.examples.slice(0, 2).join(', ')}`;
+        if (meta.examples.length > 2) {
+          description += `, and ${meta.examples.length - 2} more`;
+        }
+      }
+    }
+
+    description += '\n';
+  }
+
+  description +=
+    '• **custom**: Use custom workflow from .vibe/workflows in your project\n\n';
+
+  return description;
+}
+
+/**
+ * Log handler execution for debugging
+ */
+export function logHandlerExecution(handlerName: string, args: unknown): void {
+  logger.debug(`Executing ${handlerName} handler`, {
+    handlerName,
+    argsKeys: Object.keys(args || {}),
+  });
+}
+
+/**
+ * Log handler completion for debugging
+ */
+export function logHandlerCompletion(
+  handlerName: string,
+  result: HandlerResult<unknown>
+): void {
+  logger.debug(`Completed ${handlerName} handler`, {
+    handlerName,
+    success: result.success,
+    hasData: !!result.data,
+    hasError: !!result.error,
+  });
+}

package/src/server-implementation.ts

@@ -0,0 +1,277 @@
+/**
+ * Refactored Vibe Feature MCP Server
+ *
+ * Main server orchestrator that brings together all the modular components.
+ * This replaces the monolithic server.ts with a clean, modular architecture.
+ */
+
+import { setMcpServerForLogging, createLogger } from '@codemcp/workflows-core';
+import { ServerConfig } from './types.js';
+import {
+  initializeServerComponents,
+  registerMcpTools,
+  registerMcpResources,
+  ServerComponents,
+} from './server-config.js';
+import { createToolRegistry } from './tool-handlers/index.js';
+import { createResourceRegistry } from './resource-handlers/index.js';
+import { createResponseRenderer } from './response-renderer.js';
+import type {
+  ProceedToPhaseArgs,
+  ProceedToPhaseResult,
+  StartDevelopmentArgs,
+  StartDevelopmentResult,
+  ResumeWorkflowArgs,
+  ResumeWorkflowResult,
+  ResetDevelopmentArgs,
+  ResetDevelopmentResult,
+} from './tool-handlers/index.js';
+
+const logger = createLogger('ResponsibleVibeMCPServer');
+
+/**
+ * Factory function to create a server with real components
+ */
+export async function createResponsibleVibeMCPServer(
+  config: ServerConfig = {}
+): Promise<ResponsibleVibeMCPServer> {
+  const components = await initializeServerComponents(config);
+  return new ResponsibleVibeMCPServer(config, components);
+}
+
+/**
+ * Main server class that orchestrates all components
+ * Can be used both as a standalone process and in-process for testing
+ */
+export class ResponsibleVibeMCPServer {
+  private components: ServerComponents | null = null;
+
+  constructor(
+    private config: ServerConfig,
+    private serverComponents: ServerComponents
+  ) {
+    logger.debug('ResponsibleVibeMCPServer created', {
+      config: JSON.stringify(this.config),
+    });
+  }
+
+  /**
+   * Initialize the server and all its components
+   */
+  async initialize(): Promise<void> {
+    logger.debug('Initializing ResponsibleVibeMCPServer');
+
+    try {
+      // Use injected components
+      this.components = this.serverComponents;
+
+      // Create registries and renderer
+      const toolRegistry = createToolRegistry();
+      const resourceRegistry = createResourceRegistry();
+      const responseRenderer = createResponseRenderer();
+
+      // Update components with registries and renderer
+      this.components.toolRegistry = toolRegistry;
+      this.components.resourceRegistry = resourceRegistry;
+      this.components.responseRenderer = responseRenderer;
+
+      // Register MCP server for logging notifications
+      setMcpServerForLogging(this.components.mcpServer);
+
+      // Register tools and resources with MCP server
+      await registerMcpTools(
+        this.components.mcpServer,
+        toolRegistry,
+        responseRenderer,
+        this.components.context
+      );
+
+      registerMcpResources(
+        this.components.mcpServer,
+        resourceRegistry,
+        responseRenderer,
+        this.components.context
+      );
+    } catch (error) {
+      logger.error(
+        'Failed to initialize ResponsibleVibeMCPServer',
+        error as Error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Get the underlying MCP server instance
+   * This allows for both transport-based and direct testing
+   */
+  public getMcpServer() {
+    if (!this.components) {
+      throw new Error('Server not initialized. Call initialize() first.');
+    }
+    return this.components.mcpServer;
+  }
+
+  /**
+   * Get project path
+   */
+  public getProjectPath(): string {
+    if (!this.components) {
+      throw new Error('Server not initialized. Call initialize() first.');
+    }
+    return this.components.context.projectPath;
+  }
+
+  /**
+   * Get conversation manager (for testing)
+   */
+  public getConversationManager() {
+    if (!this.components) {
+      throw new Error('Server not initialized. Call initialize() first.');
+    }
+    return this.components.context.conversationManager;
+  }
+
+  /**
+   * Get plan manager (for testing)
+   */
+  public getPlanManager() {
+    if (!this.components) {
+      throw new Error('Server not initialized. Call initialize() first.');
+    }
+    return this.components.context.planManager;
+  }
+
+  /**
+   * Direct access to tool handlers for testing
+   */
+  public async handleWhatsNext(args: unknown): Promise<unknown> {
+    if (!this.components) {
+      throw new Error('Server not initialized. Call initialize() first.');
+    }
+
+    const handler = this.components.toolRegistry.get('whats_next');
+    if (!handler) {
+      throw new Error('whats_next handler not found');
+    }
+
+    const result = await handler.handle(args, this.components.context);
+    if (!result.success) {
+      throw new Error(result.error || 'Handler execution failed');
+    }
+
+    return result.data;
+  }
+
+  /**
+   * Direct access to tool handlers for testing
+   */
+  public async handleProceedToPhase(
+    args: ProceedToPhaseArgs
+  ): Promise<ProceedToPhaseResult> {
+    if (!this.components) {
+      throw new Error('Server not initialized. Call initialize() first.');
+    }
+
+    const handler = this.components.toolRegistry.get('proceed_to_phase');
+    if (!handler) {
+      throw new Error('proceed_to_phase handler not found');
+    }
+
+    const result = await handler.handle(args, this.components.context);
+    if (!result.success) {
+      throw new Error(result.error || 'Handler execution failed');
+    }
+
+    return result.data as ProceedToPhaseResult;
+  }
+
+  /**
+   * Direct access to tool handlers for testing
+   */
+  public async handleStartDevelopment(
+    args: StartDevelopmentArgs
+  ): Promise<StartDevelopmentResult> {
+    if (!this.components) {
+      throw new Error('Server not initialized. Call initialize() first.');
+    }
+
+    const handler = this.components.toolRegistry.get('start_development');
+    if (!handler) {
+      throw new Error('start_development handler not found');
+    }
+
+    const result = await handler.handle(args, this.components.context);
+    if (!result.success) {
+      throw new Error(result.error || 'Handler execution failed');
+    }
+
+    return result.data as StartDevelopmentResult;
+  }
+
+  /**
+   * Direct access to tool handlers for testing
+   */
+  public async handleResumeWorkflow(
+    args: ResumeWorkflowArgs
+  ): Promise<ResumeWorkflowResult> {
+    if (!this.components) {
+      throw new Error('Server not initialized. Call initialize() first.');
+    }
+
+    const handler = this.components.toolRegistry.get('resume_workflow');
+    if (!handler) {
+      throw new Error('resume_workflow handler not found');
+    }
+
+    const result = await handler.handle(args, this.components.context);
+    if (!result.success) {
+      throw new Error(result.error || 'Handler execution failed');
+    }
+
+    return result.data as ResumeWorkflowResult;
+  }
+
+  /**
+   * Direct access to tool handlers for testing
+   */
+  public async handleResetDevelopment(
+    args: ResetDevelopmentArgs
+  ): Promise<ResetDevelopmentResult> {
+    if (!this.components) {
+      throw new Error('Server not initialized. Call initialize() first.');
+    }
+
+    const handler = this.components.toolRegistry.get('reset_development');
+    if (!handler) {
+      throw new Error('reset_development handler not found');
+    }
+
+    const result = await handler.handle(args, this.components.context);
+    if (!result.success) {
+      throw new Error(result.error || 'Handler execution failed');
+    }
+
+    return result.data as ResetDevelopmentResult;
+  }
+
+  /**
+   * Cleanup server resources
+   */
+  public async cleanup(): Promise<void> {
+    logger.debug('Cleaning up server resources');
+
+    if (this.components?.database) {
+      await this.components.database.close();
+    }
+
+    logger.info('Server cleanup completed');
+  }
+}
+
+// Export all types and utilities for external use
+export * from './types.js';
+export * from './server-helpers.js';
+export * from './response-renderer.js';
+export * from './tool-handlers/index.js';
+export * from './resource-handlers/index.js';

package/src/server.ts

@@ -0,0 +1,9 @@
+/**
+ * Vibe Feature MCP Server Core
+ */
+
+export {
+  ResponsibleVibeMCPServer,
+  createResponsibleVibeMCPServer,
+} from './server-implementation.js';
+export type { ServerConfig } from './types.js';

package/src/tool-handlers/base-tool-handler.ts

@@ -0,0 +1,141 @@
+/**
+ * Base Tool Handler
+ *
+ * Provides common functionality for all tool handlers including
+ * error handling, logging, and conversation state management.
+ */
+
+import { createLogger } from '@codemcp/workflows-core';
+import { ToolHandler, ServerContext, HandlerResult } from '../types.js';
+import type { ConversationContext } from '@codemcp/workflows-core';
+import {
+  safeExecute,
+  logHandlerExecution,
+  logHandlerCompletion,
+} from '../server-helpers.js';
+
+/**
+ * Abstract base class for tool handlers
+ * Provides common functionality and enforces consistent patterns
+ */
+export abstract class BaseToolHandler<TArgs = unknown, TResult = unknown>
+  implements ToolHandler<TArgs, TResult>
+{
+  protected readonly logger: ReturnType<typeof createLogger>;
+
+  constructor() {
+    this.logger = createLogger(this.constructor.name);
+  }
+
+  /**
+   * Main handler method - implements consistent error handling and logging
+   */
+  async handle(
+    args: TArgs,
+    context: ServerContext
+  ): Promise<HandlerResult<TResult>> {
+    const handlerName = this.constructor.name;
+    logHandlerExecution(handlerName, args);
+
+    const result = await safeExecute(
+      () => this.executeHandler(args, context),
+      `${handlerName} execution failed`
+    );
+
+    logHandlerCompletion(handlerName, result);
+    return result;
+  }
+
+  /**
+   * Abstract method that subclasses must implement
+   * Contains the actual business logic for the tool
+   */
+  protected abstract executeHandler(
+    args: TArgs,
+    context: ServerContext
+  ): Promise<TResult>;
+
+  /**
+   * Helper method to get conversation context with proper error handling
+   */
+  protected async getConversationContext(context: ServerContext) {
+    try {
+      return await context.conversationManager.getConversationContext();
+    } catch (error) {
+      this.logger.info('Conversation not found', { error });
+      throw new Error('CONVERSATION_NOT_FOUND');
+    }
+  }
+
+  /**
+   * Helper method to ensure state machine is loaded for a project
+   */
+  protected ensureStateMachineForProject(
+    context: ServerContext,
+    projectPath: string,
+    workflowName?: string
+  ): void {
+    const stateMachine = context.transitionEngine.getStateMachine(
+      projectPath,
+      workflowName
+    );
+    context.planManager.setStateMachine(stateMachine);
+    context.instructionGenerator.setStateMachine(stateMachine);
+  }
+
+  /**
+   * Helper method to log interactions if logger is available
+   */
+  protected async logInteraction(
+    context: ServerContext,
+    conversationId: string,
+    toolName: string,
+    args: unknown,
+    response: unknown,
+    phase: string
+  ): Promise<void> {
+    if (context.interactionLogger) {
+      await context.interactionLogger.logInteraction(
+        conversationId,
+        toolName,
+        args,
+        response,
+        phase
+      );
+    }
+  }
+}
+
+/**
+ * Base class for tool handlers that require an existing conversation
+ * Automatically handles the conversation-not-found case
+ */
+export abstract class ConversationRequiredToolHandler<
+  TArgs = unknown,
+  TResult = unknown,
+> extends BaseToolHandler<TArgs, TResult> {
+  protected async executeHandler(
+    args: TArgs,
+    context: ServerContext
+  ): Promise<TResult> {
+    let conversationContext;
+
+    try {
+      conversationContext = await this.getConversationContext(context);
+    } catch (_error) {
+      // Return a special error result that the response renderer can handle
+      throw new Error('CONVERSATION_NOT_FOUND');
+    }
+
+    return this.executeWithConversation(args, context, conversationContext);
+  }
+
+  /**
+   * Abstract method for handlers that need conversation context
+   */
+  protected abstract executeWithConversation(
+    args: TArgs,
+    context: ServerContext,
+    conversationContext: ConversationContext
+  ): Promise<TResult>;
+}