Vibe Coder MCP

Instructions

Implementation Reference

• src/tools/prd-generator/index.ts:172-364 (handler)

  The primary handler/executor for the 'generate-prd' tool (registered as 'prd-generator'). It orchestrates background job creation, pre-generation research via Perplexity, LLM-based PRD markdown generation with strict system prompt, file saving, progress updates via SSE, and comprehensive error handling.
  export const generatePRD: ToolExecutor = async ( params: Record<string, unknown>, // More type-safe than 'any' config: OpenRouterConfig, context?: ToolExecutionContext // Add context parameter ): Promise<CallToolResult> => { // Return CallToolResult // ---> Step 2.5(PRD).2: Inject Dependencies & Get Session ID <--- const sessionId = context?.sessionId || 'unknown-session'; if (sessionId === 'unknown-session') { logger.warn({ tool: 'generatePRD' }, 'Executing tool without a valid sessionId. SSE progress updates will not be sent.'); } // Log the config received by the executor logger.debug({ configReceived: true, hasLlmMapping: Boolean(config.llm_mapping), mappingKeys: config.llm_mapping ? Object.keys(config.llm_mapping) : [] }, 'generatePRD executor received config'); const productDescription = params.productDescription as string; // Assert type after validation // ---> Step 2.5(PRD).3: Create Job & Return Job ID <--- const jobId = jobManager.createJob('generate-prd', params); logger.info({ jobId, tool: 'generatePRD', sessionId }, 'Starting background job.'); // Use the shared service to format the initial response const initialResponse = formatBackgroundJobInitiationResponse( jobId, 'generate-prd', // Internal tool name 'PRD Generator' // User-friendly display name ); // ---> Step 2.5(PRD).4: Wrap Logic in Async Block <--- setImmediate(async () => { const logs: string[] = []; // Keep logs specific to this job execution let filePath: string = ''; // Define filePath in outer scope for catch block // ---> Step 2.5(PRD).7: Update Final Result/Error Handling (Try Block Start) <--- try { // ---> Step 2.5(PRD).6: Add Progress Updates (Initial) <--- jobManager.updateJobStatus(jobId, JobStatus.RUNNING, 'Starting PRD generation process...'); sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, 'Starting PRD generation process...'); logs.push(`[${new Date().toISOString()}] Starting PRD generation for: ${productDescription.substring(0, 50)}...`); // Ensure directories are initialized before writing const prdDir = await initDirectories(context); // Generate a filename for storing the PRD const timestamp = new Date().toISOString().replace(/[:.]/g, '-'); const sanitizedName = productDescription.substring(0, 60).toLowerCase().replace(/[^a-z0-9]+/g, '-'); const filename = `${timestamp}-${sanitizedName}-prd.md`; filePath = path.join(prdDir, filename); // Assign to outer scope variable // ---> Step 2.5(PRD).6: Add Progress Updates (Research Start) <--- logger.info({ jobId, inputs: { productDescription: productDescription.substring(0, 50) } }, "PRD Generator: Starting pre-generation research..."); jobManager.updateJobStatus(jobId, JobStatus.RUNNING, 'Performing pre-generation research...'); sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, 'Performing pre-generation research...'); logs.push(`[${new Date().toISOString()}] Starting pre-generation research.`); let researchContext = ''; try { // Define relevant research queries const query1 = `Market analysis and competitive landscape for: ${productDescription}`; const query2 = `User needs, demographics, and expectations for: ${productDescription}`; const query3 = `Industry standards, best practices, and common feature sets for products like: ${productDescription}`; // Execute research queries in parallel using Perplexity const researchResults = await Promise.allSettled([ performResearchQuery(query1, config), // Uses config.perplexityModel (perplexity/sonar-deep-research) performResearchQuery(query2, config), performResearchQuery(query3, config) ]); // Process research results researchContext = "## Pre-Generation Research Context (From Perplexity Sonar Deep Research):\n\n"; // Add results that were fulfilled researchResults.forEach((result, index) => { const queryLabels = ["Market Analysis", "User Needs & Expectations", "Industry Standards & Best Practices"]; if (result.status === "fulfilled") { researchContext += `### ${queryLabels[index]}:\n${result.value.trim()}\n\n`; } else { logger.warn({ error: result.reason }, `Research query ${index + 1} failed`); researchContext += `### ${queryLabels[index]}:\n*Research on this topic failed.*\n\n`; } }); // ---> Step 2.5(PRD).6: Add Progress Updates (Research End) <--- logger.info({ jobId }, "PRD Generator: Pre-generation research completed."); jobManager.updateJobStatus(jobId, JobStatus.RUNNING, 'Research complete. Starting main PRD generation...'); sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, 'Research complete. Starting main PRD generation...'); logs.push(`[${new Date().toISOString()}] Pre-generation research completed.`); } catch (researchError) { logger.error({ jobId, err: researchError }, "PRD Generator: Error during research aggregation"); logs.push(`[${new Date().toISOString()}] Error during research aggregation: ${researchError instanceof Error ? researchError.message : String(researchError)}`); // Include error in context but continue researchContext = "## Pre-Generation Research Context:\n*Error occurred during research phase.*\n\n"; sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, 'Warning: Error during research phase. Continuing generation...'); } // Create the main generation prompt with combined research and inputs const mainGenerationPrompt = `Create a comprehensive PRD for the following product:\n\n${productDescription}\n\n${researchContext}`; // ---> Step 2.5(PRD).6: Add Progress Updates (LLM Call Start) <--- logger.info({ jobId }, "PRD Generator: Starting main generation using direct LLM call..."); jobManager.updateJobStatus(jobId, JobStatus.RUNNING, 'Generating PRD content via LLM...'); sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, 'Generating PRD content via LLM...'); logs.push(`[${new Date().toISOString()}] Calling LLM for main PRD generation.`); const prdMarkdown = await performFormatAwareLlmCallWithCentralizedConfig( mainGenerationPrompt, PRD_SYSTEM_PROMPT, // Pass the system prompt 'prd_generation', // Logical task name 'markdown', // Explicitly specify markdown format undefined, // No schema for markdown 0.3 // Slightly higher temp might be okay for PRD text ); // ---> Step 2.5(PRD).6: Add Progress Updates (LLM Call End) <--- logger.info({ jobId }, "PRD Generator: Main generation completed."); jobManager.updateJobStatus(jobId, JobStatus.RUNNING, 'Processing LLM response...'); sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, 'Processing LLM response...'); logs.push(`[${new Date().toISOString()}] Received response from LLM.`); // Basic validation: Check if the output looks like Markdown and contains expected elements if (!prdMarkdown || typeof prdMarkdown !== 'string' || !prdMarkdown.trim().startsWith('# PRD:')) { logger.warn({ jobId, markdown: prdMarkdown?.substring(0, 100) }, 'PRD generation returned empty or potentially invalid Markdown format.'); logs.push(`[${new Date().toISOString()}] Validation Error: LLM output invalid format.`); throw new ToolExecutionError('PRD generation returned empty or invalid Markdown content.'); } // Format the PRD (already should be formatted by LLM, just add timestamp) const formattedResult = `${prdMarkdown}\n\n_Generated: ${new Date().toLocaleString()}_`; // ---> Step 2.5(PRD).6: Add Progress Updates (Saving File) <--- logger.info({ jobId }, `Saving PRD to ${filePath}...`); jobManager.updateJobStatus(jobId, JobStatus.RUNNING, `Saving PRD to file...`); sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, `Saving PRD to file...`); logs.push(`[${new Date().toISOString()}] Saving PRD to ${filePath}.`); // Save the result try { await fs.writeFile(filePath, formattedResult, 'utf8'); logger.info({ jobId }, `PRD generated and saved to ${filePath}`); logs.push(`[${new Date().toISOString()}] PRD saved successfully.`); } catch (fileError) { const errorDetails = fileError instanceof Error ? fileError.message : String(fileError); logger.error({ err: fileError, jobId, filePath }, `Failed to write PRD file: ${errorDetails}`); logs.push(`[${new Date().toISOString()}] File write error: ${errorDetails} for path: ${filePath}`); throw new AppError(`Failed to save PRD file to ${filePath}: ${errorDetails}`, { code: 'FILE_WRITE_ERROR', filePath }, fileError as Error); } sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, `PRD saved successfully.`); // ---> Step 2.5(PRD).7: Update Final Result/Error Handling (Set Success Result) <--- const finalResult: CallToolResult = { // Include file path in success message content: [{ type: "text", text: `PRD generated successfully and saved to: ${filePath}\n\n${formattedResult}` }], isError: false }; jobManager.setJobResult(jobId, finalResult); // Optional explicit SSE: sseNotifier.sendProgress(sessionId, jobId, JobStatus.COMPLETED, 'PRD generation completed successfully.'); // ---> Step 2.5(PRD).7: Update Final Result/Error Handling (Catch Block) <--- } catch (error) { const errorMsg = error instanceof Error ? error.message : String(error); logger.error({ err: error, jobId, tool: 'generate-prd', params }, `PRD Generator Error: ${errorMsg}`); logs.push(`[${new Date().toISOString()}] Error: ${errorMsg}`); // Handle specific errors from direct call or research let appError: AppError; const cause = error instanceof Error ? error : undefined; if (error instanceof AppError) { appError = error; } else { appError = new ToolExecutionError(`Failed to generate PRD: ${errorMsg}`, { params, filePath }, cause); } const mcpError = new McpError(ErrorCode.InternalError, appError.message, appError.context); const errorResult: CallToolResult = { content: [{ type: 'text', text: `Error during background job ${jobId}: ${mcpError.message}\n\nLogs:\n${logs.join('\n')}` }], isError: true, errorDetails: mcpError }; // Store error result in Job Manager jobManager.setJobResult(jobId, errorResult); // Send final failed status via SSE (optional if jobManager handles it) sseNotifier.sendProgress(sessionId, jobId, JobStatus.FAILED, `Job failed: ${mcpError.message}`); } }); // ---> END OF setImmediate WRAPPER <--- return initialResponse; // Return the initial response with Job ID };
• src/tools/prd-generator/index.ts:161-163 (schema)

  Zod input schema definition for the PRD generator tool, validating the required 'productDescription' parameter.
  const prdInputSchemaShape = { productDescription: z.string().min(10, { message: "Product description must be at least 10 characters." }).describe("Description of the product to create a PRD for") };
• src/tools/prd-generator/index.ts:369-377 (registration)

  Tool definition object and registration call to the central tool registry, which enables dynamic MCP server registration in src/server.ts.
  const prdToolDefinition: ToolDefinition = { name: "prd-generator", description: "Creates comprehensive product requirements documents based on a product description and research.", inputSchema: prdInputSchemaShape, // Use the raw shape executor: generatePRD // Reference the adapted function }; // Register the tool with the central registry registerTool(prdToolDefinition);
• src/tools/prd-generator/index.ts:79-158 (helper)

  Exported system prompt used by the LLM for generating structured PRD markdown, including strict format requirements and research integration instructions.
  // PRD-specific system prompt (Exported for testing) export const PRD_SYSTEM_PROMPT = ` # ROLE & GOAL You are an expert Product Manager and Technical Writer AI assistant. Your goal is to generate a comprehensive, clear, and well-structured Product Requirements Document (PRD) in Markdown format based on the provided inputs. # CORE TASK Generate a detailed PRD based on the user's product description and the research context provided. # INPUT HANDLING - The primary input is the user's 'productDescription'. Analyze it carefully to understand the core concept, features, and goals. - You will also receive 'Pre-Generation Research Context'. # RESEARCH CONTEXT INTEGRATION - **CRITICAL:** Carefully review the '## Pre-Generation Research Context (From Perplexity Sonar Deep Research)' section provided in the user prompt. - This section contains insights on: Market Analysis, User Needs & Expectations, and Industry Standards & Best Practices. - **Integrate** these insights strategically into the relevant PRD sections. For example: - Use 'Market Analysis' to inform the 'Goals' and 'Competitive Landscape' (if included). - Use 'User Needs & Expectations' and 'Personas' (if available in research) to define the 'Target Audience' and justify features. - Use 'Industry Standards & Best Practices' to guide 'Features & Functionality', 'Technical Considerations', and 'Non-Functional Requirements'. - **Synthesize**, don't just copy. Weave the research findings naturally into the PRD narrative. - If research context is missing or indicates failure for a topic, note this appropriately (e.g., "Market research was inconclusive, but based on the description..."). # OUTPUT FORMAT & STRUCTURE (Strict Markdown) - Your entire response **MUST** be valid Markdown. - Start **directly** with the main title: '# PRD: [Inferred Product Name]' - Use the following sections with the specified Markdown heading levels. Include all mandatory sections; optional sections can be added if relevant information is available from the description or research. ## 1. Introduction / Overview (Mandatory) - Purpose of the product. - High-level summary. ## 2. Goals (Mandatory) - Business goals (e.g., increase market share, user engagement). Use research context if applicable. - Product goals (e.g., solve specific user problems, achieve specific functionality). ## 3. Target Audience (Mandatory) - Describe the primary user groups. - Incorporate insights on demographics, needs, and pain points from the research context. Use persona descriptions if research provided them. ## 4. Features & Functionality (Mandatory) - Use subheadings (###) for major features or epics. - For each feature, use the User Story format: - **User Story:** As a [user type/persona], I want to [perform action] so that [I get benefit]. - **Description:** Further details about the story. - **Acceptance Criteria:** - GIVEN [context] WHEN [action] THEN [outcome] - (Provide multiple specific, testable criteria) ## 5. Design & UX Considerations (Mandatory) - High-level look-and-feel, usability goals. Informed by research on expectations. ## 6. Technical Considerations (Mandatory) - Non-functional requirements (performance, scalability, security - informed by research). - Potential technology constraints or suggestions based on research context. ## 7. Success Metrics (Mandatory) - Key Performance Indicators (KPIs) to measure success (e.g., user adoption rate, task completion time). Informed by industry standards research. ## 8. Open Issues / Questions (Mandatory) - List any ambiguities or areas needing further clarification. ## 9. Out-of-Scope / Future Considerations (Mandatory) - Features explicitly not included in this version. - Potential future enhancements. # QUALITY ATTRIBUTES - **Comprehensive:** Cover all aspects implied by the description and research. - **Clear & Concise:** Use unambiguous language. - **Structured:** Strictly adhere to the specified Markdown format and sections. - **Actionable:** Requirements should be clear enough for design and development teams. - **Accurate:** Reflect the product description and research context faithfully. - **Modern:** Incorporate current best practices identified in research. # CONSTRAINTS (Do NOT Do the Following) - **NO Conversational Filler:** Do not include greetings, apologies, self-references ("Here is the PRD...", "I have generated..."). Start directly with the '# PRD: ...' title. - **NO Markdown Violations:** Ensure all formatting is correct Markdown. Do not use unsupported syntax. - **NO External Knowledge:** Base the PRD *only* on the provided product description and research context. Do not invent unrelated features or use external data. - **NO Process Commentary:** Do not mention the research process or the models used (Perplexity/Gemini) within the PRD output itself. - **Strict Formatting:** Adhere strictly to the section structure and Markdown heading levels specified. `;
• src/tools/prd-generator/index.ts:57-76 (helper)

  Helper function to initialize and ensure the PRD output directory exists, with fallback for backward compatibility.
  export async function initDirectories(context?: ToolExecutionContext): Promise<string> { try { const toolDir = await ensureToolOutputDirectory('prd-generator'); logger.debug(`Ensured PRD directory exists: ${toolDir}`); return toolDir; } catch (error) { logger.error({ err: error }, `Failed to ensure base output directory exists for prd-generator.`); // Fallback to original implementation for backward compatibility const baseOutputDir = getBaseOutputDir(context); try { await fs.ensureDir(baseOutputDir); const toolDir = path.join(baseOutputDir, 'prd-generator'); await fs.ensureDir(toolDir); logger.debug(`Ensured PRD directory exists (fallback): ${toolDir}`); return toolDir; } catch (fallbackError) { logger.error({ err: fallbackError, path: baseOutputDir }, `Fallback directory creation also failed.`); throw fallbackError; } }