researchTopic

Instructions

Implementation Reference

• src/tools/researchTopic.ts:32-69 (handler)

  The execute() method of ResearchTopicTool - validates input, checks API key config, calls conductQuickResearch(), and returns the result.

  async execute(args: any): Promise<MCPToolResponse> {
    try {
      // Validate input
      const validationError = this.validateRequiredFields(args, ['topic']);
      if (validationError) {
        return this.createErrorResponse(validationError);
      }
  
      const input = args as ResearchTopicInput;
      
      // Validate topic is not empty
      if (!input.topic.trim()) {
        return this.createErrorResponse('Topic cannot be empty');
      }
  
      // Get configuration
      const config = ConfigurationManager.getConfig();
      if (!config.research.exaKey) {
        return this.createErrorResponse(
          'Exa.ai API key is not configured. Please set the exaKey in your configuration or EXA_KEY environment variable.'
        );
      }
  
      this.logOperation(`Starting quick research for topic: ${input.topic}`);
  
      // Conduct research
      const result = await this.conductQuickResearch(input.topic, config.research.exaKey);
      
      this.logOperation('Quick research completed successfully');
  
      return this.createSuccessResponse(result.result);
  
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      this.logOperation(`Research failed: ${errorMessage}`);
      return this.createErrorResponse(`Research failed: ${errorMessage}`);
    }
  }

• src/tools/researchTopic.ts:71-110 (handler)

  The private conductQuickResearch() method - creates an Exa research task with the topic, polls for completion, and formats the response.

  private async conductQuickResearch(topic: string, exaKey: string): Promise<ExaResponse> {
    const client = new Exa(exaKey);
  
    try {
      const schema = {
        type: 'object' as const,
        properties: {
          result: { type: 'string' as const }
        },
        required: ['result'],
        description: 'Schema with just the result in markdown.'
      };
  
      if (!client?.research || typeof (client as any).research.create !== 'function') {
        throw new Error('Exa.js research client missing create() method');
      }
      const research: any = (client as any).research;
  
      this.logOperation('Creating Exa research task');
  const task = await research.create({
        instructions: topic,
        model: RESEARCH_CONFIG.QUICK_RESEARCH.MODEL,
        output: { schema },
      });
  
      this.logOperation(`Task created with ID: ${task.id}. Polling for results...`);
      const result = await this.pollTaskWithFallback(
        client, 
        task.id, 
        RESEARCH_CONFIG.QUICK_RESEARCH.MAX_ATTEMPTS,
        RESEARCH_CONFIG.QUICK_RESEARCH.POLL_INTERVAL_MS,
        RESEARCH_CONFIG.QUICK_RESEARCH.TIMEOUT_MS
      );
      
      return this.formatResponse(result);
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Failed to conduct research with Exa.ai.';
      throw new Error(`Exa.ai research failed: ${errorMessage}`);
    }
  }

• src/server.ts:60-66 (registration)

  Registration of ResearchTopicTool in setupTools() - instantiates and stores in the tools map.

  private setupTools(): void {
    const toolInstances = [
      new AskAboutFileTool(),
      new RunAndExtractTool(),
      new AskFollowUpTool(),
      new ResearchTopicTool(),
      new DeepResearchTool()

• src/tools/researchTopic.ts:13-30 (schema)

  ResearchTopicInput interface and inputSchema definition - defines the 'topic' string parameter (required).

  interface ResearchTopicInput {
    topic: string;
  }
  
  export class ResearchTopicTool extends BaseResearchTool {
    readonly name = 'researchTopic';
    readonly description = 'Conduct quick, focused web research on software development topics using Exa.ai\'s powerful research capabilities for current information and practical implementation guidance.';
  
    readonly inputSchema = {
      type: 'object' as const,
      properties: {
        topic: {
          type: 'string' as const,
          description: 'The research topic or problem you want to investigate. Be as detailed as possible about what you want to learn, any specific aspects to focus on, timeframes, geographical scope, or particular angles of interest.'
        }
      },
      required: ['topic']
    };

• src/tools/baseResearch.ts:10-80 (helper)

  BaseResearchTool abstract class - provides pollTask(), formatResponse(), and pollTaskWithFallback() helper methods used by ResearchTopicTool.

  export abstract class BaseResearchTool extends BaseMCPTool {
    /**
     * Poll an Exa research task until completion or timeout
     */
    protected async pollTask(client: Exa, taskId: string, maxAttempts: number, pollIntervalMs: number, timeoutMs: number): Promise<ExaTask> {
      let attempts = 0;
      const research: any = (client as any).research;
      if (!research || typeof research.get !== 'function') {
        throw new Error('Exa research client does not expose get() to fetch task status.');
      }
  
      while (attempts < maxAttempts) {
        const task = await research.get(taskId);
        
        if (task.status === 'completed') {
          this.logOperation('Research task completed');
          return task;
        }
        
        if (task.status === 'failed') {
          throw new Error('Research task failed');
        }
        
        if (task.status === 'running' || task.status === 'pending') {
          this.logOperation(`Task status: ${task.status}... (${attempts * pollIntervalMs / 1000}s elapsed)`);
          await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
          attempts++;
        } else {
          // Unexpected status
          throw new Error(`Unexpected task status: ${task.status}`);
        }
      }
      
      // Timeout after configured duration
      throw new Error(`Research task timed out after ${timeoutMs / 1000} seconds`);
    }
  
    /**
     * Format the Exa task result into a standardized response
     */
    protected formatResponse(result: ExaTask): ExaResponse {
      if (!result?.data?.result) {
        throw new Error('Malformed response from Exa.ai - missing result data');
      }
      return {
        result: result.data.result,
        raw: result,
      };
    }
  
    /**
     * Check if the Exa client has a built-in pollTask method and use it, 
     * otherwise fall back to our implementation
     */
    protected async pollTaskWithFallback(
      client: Exa, 
      taskId: string, 
      maxAttempts: number, 
      pollIntervalMs: number, 
      timeoutMs: number
    ): Promise<ExaTask> {
    // Prefer SDK-provided poller; else fall back to local polling using get()
      const research: any = (client as any).research;
      if (research) {
        if (typeof research.pollUntilFinished === 'function') {
          return await research.pollUntilFinished(taskId);
        }
      }
      return await this.pollTask(client, taskId, maxAttempts, pollIntervalMs, timeoutMs);
    }
  }