deepResearch

Instructions

Implementation Reference

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

  Main handler (execute method) for the deepResearch tool. Validates input (topic), checks Exa API key config, calls conductDeepResearch(), 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 DeepResearchInput;
      
      // 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 deep research for topic: ${input.topic}`);
  
      // Conduct research
      const result = await this.conductDeepResearch(input.topic, config.research.exaKey);
      
      this.logOperation('Deep research completed successfully');
  
      return this.createSuccessResponse(result.result);
  
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      this.logOperation(`Deep research failed: ${errorMessage}`);
      return this.createErrorResponse(`Research failed: ${errorMessage}`);
    }
  }

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

  Private method that creates an Exa deep research task using 'exa-research-pro' model, then polls for completion using pollTaskWithFallback (from base class).

  private async conductDeepResearch(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 deep research task');
  const task = await research.create({
        instructions: topic,
        model: RESEARCH_CONFIG.DEEP_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.DEEP_RESEARCH.MAX_ATTEMPTS,
        RESEARCH_CONFIG.DEEP_RESEARCH.POLL_INTERVAL_MS,
        RESEARCH_CONFIG.DEEP_RESEARCH.TIMEOUT_MS
      );
      
      return this.formatResponse(result);
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Failed to conduct deep research with Exa.ai.';
      throw new Error(`Exa.ai deep research failed: ${errorMessage}`);
    }
  }

• src/tools/deepResearch.ts:13-15 (schema)

  Input type definition for deepResearch tool - accepts a single 'topic' string.

  interface DeepResearchInput {
    topic: string;
  }

• src/tools/deepResearch.ts:21-30 (schema)

  JSON Schema input validation for the deepResearch tool. Requires a single 'topic' string property.

  readonly inputSchema = {
    type: 'object' as const,
    properties: {
      topic: {
        type: 'string' as const,
        description: 'The research topic or problem you want to investigate comprehensively. Be as detailed as possible about what you want to learn, including technical requirements, architectural considerations, performance needs, security concerns, or strategic implications you want analyzed in depth.'
      }
    },
    required: ['topic']
  };

• src/server.ts:61-67 (registration)

  Registration of DeepResearchTool in the MCP server's setupTools method. The tool is instantiated and added to the tools map, making it available via ListToolsRequestSchema and CallToolRequestSchema handlers.

  const toolInstances = [
    new AskAboutFileTool(),
    new RunAndExtractTool(),
    new AskFollowUpTool(),
    new ResearchTopicTool(),
    new DeepResearchTool()
  ];