Vibe Coder MCP

Instructions

Implementation Reference

• src/tools/research-manager/index.ts:132-270 (handler)

  Main handler function that executes the research tool: creates background job, calls Perplexity via helper for initial research, enhances with LLM using structured prompt, saves Markdown report to file.

  export const performResearch: ToolExecutor = async (
    params: Record<string, unknown>,
    config: OpenRouterConfig,
    context?: ToolExecutionContext // Add context parameter
  ): Promise<CallToolResult> => {
    // ---> Step 2.5(RM).2: Inject Dependencies & Get Session ID <---
    const sessionId = context?.sessionId || 'unknown-session';
    if (sessionId === 'unknown-session') {
        logger.warn({ tool: 'performResearch' }, 'Executing tool without a valid sessionId. SSE progress updates will not be sent.');
    }
  
    // We can safely access 'query' because executeTool validated it
    const query = params.query as string;
  
    // ---> Step 2.5(RM).3: Create Job & Return Job ID <---
    const jobId = jobManager.createJob('research', params); // Use original tool name 'research'
    logger.info({ jobId, tool: 'research', sessionId }, 'Starting background job.');
  
    // Return immediately
    const initialResponse = formatBackgroundJobInitiationResponse(
      jobId,
      'Research',
      `Your research request for query "${query.substring(0, 50)}..." has been submitted. You can retrieve the result using the job ID.`
    );
  
    // ---> Step 2.5(RM).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(RM).7: Update Final Result/Error Handling (Try Block Start) <---
      try {
        // ---> Step 2.5(RM).6: Add Progress Updates (Initial) <---
        jobManager.updateJobStatus(jobId, JobStatus.RUNNING, 'Starting research process...');
        sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, 'Starting research process...');
        logs.push(`[${new Date().toISOString()}] Starting research for: ${query.substring(0, 50)}...`);
  
        // Ensure directories are initialized before writing
        await initDirectories();
  
      // Generate a filename for storing research (using the potentially configured RESEARCH_DIR)
        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
        const sanitizedQuery = query.substring(0, 30).toLowerCase().replace(/[^a-z0-9]+/g, '-');
        const filename = `${timestamp}-${sanitizedQuery}-research.md`;
        filePath = path.join(RESEARCH_DIR, filename); // Assign to outer scope variable
  
        // ---> Step 2.5(RM).6: Add Progress Updates (Perplexity Call Start) <---
        logger.info({ jobId }, `Performing initial research query via Perplexity: ${query.substring(0, 50)}...`);
        jobManager.updateJobStatus(jobId, JobStatus.RUNNING, 'Performing initial research query via Perplexity...');
        sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, 'Performing initial research query via Perplexity...');
        logs.push(`[${new Date().toISOString()}] Calling Perplexity for initial research.`);
  
        // Use Perplexity model for research via centralized helper
        const researchResult = await performResearchQuery(query, config);
  
        // ---> Step 2.5(RM).6: Add Progress Updates (Perplexity Call End / LLM Call Start) <---
        logger.info({ jobId }, "Research Manager: Initial research complete. Enhancing results using direct LLM call...");
        jobManager.updateJobStatus(jobId, JobStatus.RUNNING, 'Initial research complete. Enhancing results via LLM...');
        sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, 'Initial research complete. Enhancing results via LLM...');
        logs.push(`[${new Date().toISOString()}] Perplexity research complete. Calling LLM for enhancement.`);
  
        const enhancementPrompt = `Synthesize and structure the following initial research findings based on the original query.\n\nOriginal Query: ${query}\n\nInitial Research Findings:\n${researchResult}`;
  
      const enhancedResearch = await performFormatAwareLlmCallWithCentralizedConfig(
        enhancementPrompt,
        RESEARCH_SYSTEM_PROMPT, // System prompt guides the structuring
        'research_enhancement', // Define a logical task name for potential mapping
        'markdown', // Explicitly specify markdown format
        undefined, // No schema for markdown
        0.4 // Slightly higher temp for synthesis might be okay
      );
  
      // ---> Step 2.5(RM).6: Add Progress Updates (LLM Call End) <---
      logger.info({ jobId }, "Research Manager: Enhancement completed.");
      jobManager.updateJobStatus(jobId, JobStatus.RUNNING, 'Processing enhanced research...');
      sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, 'Processing enhanced research...');
      logs.push(`[${new Date().toISOString()}] LLM enhancement complete.`);
  
      // Basic validation
      if (!enhancedResearch || typeof enhancedResearch !== 'string' || !enhancedResearch.trim().startsWith('# Research Report:')) {
        logger.warn({ jobId, markdown: enhancedResearch?.substring(0, 100) }, 'Research enhancement returned empty or potentially invalid Markdown format.');
        logs.push(`[${new Date().toISOString()}] Validation Error: LLM output invalid format.`);
        throw new ToolExecutionError('Research enhancement returned empty or invalid Markdown content.');
      }
  
      // Format the research (already should be formatted by LLM, just add timestamp)
      const formattedResult = `${enhancedResearch}\n\n_Generated: ${new Date().toLocaleString()}_`;
  
      // ---> Step 2.5(RM).6: Add Progress Updates (Saving File) <---
      logger.info({ jobId }, `Saving research to ${filePath}...`);
      jobManager.updateJobStatus(jobId, JobStatus.RUNNING, `Saving research to file...`);
      sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, `Saving research to file...`);
      logs.push(`[${new Date().toISOString()}] Saving research to ${filePath}.`);
  
      // Save the result
      await fs.writeFile(filePath, formattedResult, 'utf8');
      logger.info({ jobId }, `Research result saved to ${filePath}`);
      logs.push(`[${new Date().toISOString()}] Research saved successfully.`);
      sseNotifier.sendProgress(sessionId, jobId, JobStatus.RUNNING, `Research saved successfully.`);
  
      // ---> Step 2.5(RM).7: Update Final Result/Error Handling (Set Success Result) <---
      const finalResult: CallToolResult = {
        // Include file path in success message
        content: [{ type: "text", text: `Research completed successfully and saved to: ${filePath}\n\n${formattedResult}` }],
        isError: false
      };
      jobManager.setJobResult(jobId, finalResult);
      // Optional explicit SSE: sseNotifier.sendProgress(sessionId, jobId, JobStatus.COMPLETED, 'Research completed successfully.');
  
      // ---> Step 2.5(RM).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: 'research', query }, `Research Manager Error: ${errorMsg}`);
        logs.push(`[${new Date().toISOString()}] Error: ${errorMsg}`);
  
        let appError: AppError;
        const cause = error instanceof Error ? error : undefined;
        if (error instanceof AppError) {
           appError = error; // Use existing AppError
        } else {
           appError = new ToolExecutionError(`Failed to perform research for query "${query}": ${errorMsg}`, { query, 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/research-manager/index.ts:275-285 (schema)

  Input schema definition for the research tool (query: string min 3 chars) and full ToolDefinition.

  const researchInputSchemaShape = {
    query: z.string().min(3, { message: "Query must be at least 3 characters long." }).describe("The research query or topic to investigate")
  };
  
  // Tool definition for the research tool, using the raw shape
  const researchToolDefinition: ToolDefinition = {
    name: "research-manager", // Align with mcp-config.json and hybrid-matcher expectations
    description: "Performs comprehensive research on any technical topic including frameworks, libraries, packages, tools, and best practices using Perplexity Sonar.",
    inputSchema: researchInputSchemaShape, // Use the raw shape here
    executor: performResearch // Reference the adapted function
  };

• src/tools/research-manager/index.ts:288-293 (registration)

  Registration of the 'research-manager' tool with the central tool registry.

  if (!isToolRegistered(researchToolDefinition.name)) {
    registerTool(researchToolDefinition);
    logger.debug(`Tool "${researchToolDefinition.name}" registered successfully`);
  } else {
    logger.debug(`Tool "${researchToolDefinition.name}" already registered, skipping`);
  }

• src/tools/research-manager/index.ts:60-122 (helper)

  System prompt used for LLM to structure and enhance the initial Perplexity research into a comprehensive Markdown report.

  const RESEARCH_SYSTEM_PROMPT = `
  # ROLE & GOAL
  You are an expert AI Research Specialist. Your goal is to synthesize initial research findings and the original user query into a comprehensive, well-structured, and insightful research report in Markdown format.
  
  # CORE TASK
  Process the initial research findings (provided as context) related to the user's original 'query'. Enhance, structure, and synthesize this information into a high-quality research report.
  
  # INPUT HANDLING
  - The user prompt will contain the original 'query' and the initial research findings (likely from Perplexity) under a heading like 'Incorporate this information:'.
  - Your task is *not* to perform new research, but to *refine, structure, and deepen* the provided information based on the original query.
  
  # RESEARCH CONTEXT INTEGRATION (Your Input IS the Context)
  - Treat the provided research findings as your primary source material.
  - Analyze the findings for key themes, data points, conflicting information, and gaps.
  - Synthesize the information logically, adding depth and interpretation where possible. Do not simply reformat the input.
  - If the initial research seems incomplete based on the original query, explicitly state the limitations or areas needing further investigation in the 'Limitations' section.
  
  # OUTPUT FORMAT & STRUCTURE (Strict Markdown)
  - Your entire response **MUST** be valid Markdown.
  - Start **directly** with the main title: '# Research Report: [Topic from Original Query]'
  - Use the following sections with the specified Markdown heading levels. Include all sections, even if brief.
  
    ## 1. Executive Summary
    - Provide a brief (2-4 sentence) overview of the key findings and conclusions based *only* on the provided research content.
  
    ## 2. Key Findings
    - List the most important discoveries or data points from the research as bullet points.
    - Directly synthesize information from the provided research context.
  
    ## 3. Detailed Analysis
    - Elaborate on the key findings.
    - Organize the information logically using subheadings (###).
    - Discuss different facets of the topic, incorporating various points from the research.
    - Compare and contrast different viewpoints or data points if present in the research.
  
    ## 4. Practical Applications / Implications
    - Discuss the real-world relevance or potential uses of the researched information.
    - How can this information be applied? What are the consequences?
  
    ## 5. Limitations and Caveats
    - Acknowledge any limitations mentioned in the research findings.
    - Identify potential gaps or areas where the provided research seems incomplete relative to the original query.
    - Mention any conflicting information found in the research.
  
    ## 6. Conclusion & Recommendations (Optional)
    - Summarize the main takeaways.
    - If appropriate based *only* on the provided research, suggest potential next steps or areas for further investigation.
  
  # QUALITY ATTRIBUTES
  - **Synthesized:** Do not just regurgitate the input; organize, connect, and add analytical value.
  - **Structured:** Strictly adhere to the specified Markdown format and sections.
  - **Accurate:** Faithfully represent the information provided in the research context.
  - **Comprehensive (within context):** Cover the key aspects present in the provided research relative to the query.
  - **Clear & Concise:** Use precise language.
  - **Objective:** Present the information neutrally, clearly separating findings from interpretation.
  
  # CONSTRAINTS (Do NOT Do the Following)
  - **NO Conversational Filler:** Start directly with the '# Research Report: ...' title.
  - **NO New Research:** Do not attempt to access external websites or knowledge beyond the provided research context. Your task is synthesis and structuring.
  - **NO Hallucination:** Do not invent findings or data not present in the input.
  - **NO Process Commentary:** Do not mention Perplexity, Gemini, or the synthesis process itself.
  - **Strict Formatting:** Use \`##\` for main sections and \`###\` for subheadings within the Detailed Analysis. Use bullet points for Key Findings.
  `;

• src/utils/researchHelper.ts:14-93 (helper)

  Core helper function that performs the actual Perplexity API call for the initial research query.

  export async function performResearchQuery(query: string, config: OpenRouterConfig): Promise<string> {
    const logicalTaskName = 'research_query';
    logger.debug({ query, model: config.perplexityModel }, "Performing Perplexity research query"); // Keep original log for context
  
    // Check for API key first
    if (!config.apiKey) {
      throw new ConfigurationError("OpenRouter API key (OPENROUTER_API_KEY) is not configured.");
    }
  
    // Select the model using the utility function
    const defaultModel = config.perplexityModel || "perplexity/sonar"; // Use configured perplexity model as default
    const modelToUse = selectModelForTask(config, logicalTaskName, defaultModel);
  
    try {
      const response = await axios.post(
        `${config.baseUrl}/chat/completions`,
        {
          model: modelToUse, // Use the dynamically selected model
          messages: [
            { role: "system", content: "You are a sophisticated AI research assistant using Perplexity Sonar Deep Research. Provide comprehensive, accurate, and up-to-date information. Research the user's query thoroughly." },
            { role: "user", content: query }
          ],
          max_tokens: 8000, // Increased from 4000 to handle larger research responses
          temperature: 0.1
        },
        {
          headers: {
            "Content-Type": "application/json",
            "Authorization": `Bearer ${config.apiKey}`,
            "HTTP-Referer": "https://vibe-coder-mcp.local" // Optional
          },
          timeout: 90000 // Increased timeout for potentially deeper research (90s)
        }
      );
  
      if (response.data?.choices?.[0]?.message?.content) {
        logger.debug({ query, modelUsed: modelToUse }, "Research query successful");
        return response.data.choices[0].message.content.trim();
      } else {
        logger.warn({ query, responseData: response.data, modelUsed: modelToUse }, "Received empty or unexpected response structure from research call");
        // Throw specific ParsingError
        throw new ParsingError(
          "Invalid API response structure received from research call",
          { query, responseData: response.data, modelUsed: modelToUse }
        );
      }
    } catch (error) {
      logger.error({ err: error, query, modelUsed: modelToUse }, "Research API call failed");
  
      if (axios.isAxiosError(error)) {
        const axiosError = error as AxiosError;
        const status = axiosError.response?.status;
        const responseData = axiosError.response?.data;
        const apiMessage = `Research API Error: Status ${status || 'N/A'}. ${axiosError.message}`;
        // Throw specific ApiError
        throw new ApiError(
          apiMessage,
          status,
          { query, modelUsed: modelToUse, responseData },
          axiosError // Pass original AxiosError
        );
      } else if (error instanceof AppError) {
          // Re-throw known AppErrors (like ParsingError from above)
          throw error;
      } else if (error instanceof Error) {
        // Wrap other standard errors
         throw new AppError(
           `Research failed: ${error.message}`,
           { query, modelUsed: modelToUse },
           error // Pass original Error
         );
      } else {
        // Handle cases where a non-Error was thrown
        throw new AppError(
          `Unknown error during research.`,
          { query, modelUsed: modelToUse, thrownValue: String(error) }
        );
      }
    }
  }