DeepResearch MCP

!DeepResearch Logo * * *

📚 Overview

DeepResearch MCP is a powerful research assistant built on the Model Context Protocol (MCP). It conducts intelligent, iterative research on any topic through web searches, analysis, and comprehensive report generation.

🌟 Key Features

• Intelligent Topic Exploration - Automatically identifies knowledge gaps and generates focused search queries
• Comprehensive Content Extraction - Enhanced web scraping with improved content organization
• Structured Knowledge Processing - Preserves important information while managing token usage
• Scholarly Report Generation - Creates detailed, well-structured reports with executive summaries, analyses, and visualizations
• Complete Bibliography - Properly cites all sources with numbered references
• Adaptive Content Management - Automatically manages content to stay within token limits
• Error Resilience - Recovers from errors and generates partial reports when full processing isn't possible

🛠️ Architecture

┌────────────────────┐     ┌─────────────────┐     ┌────────────────┐
│                    │     │                 │     │                │
│  MCP Server Layer  ├────►│ Research Service├────►│ Search Service │
│  (Tools & Prompts) │     │ (Session Mgmt)  │     │  (Firecrawl)   │
│                    │     │                 │     │                │
└────────────────────┘     └─────────┬───────┘     └────────────────┘
                                     │
                                     ▼
                           ┌─────────────────┐
                           │                 │
                           │  OpenAI Service │
                           │ (Analysis/Rpt)  │
                           │                 │
                           └─────────────────┘

💻 Installation

Prerequisites

• Node.js 18 or higher
• OpenAI API key
• Firecrawl API key

Setup Steps

1. Clone the repository

   git clone <repository-url>
   cd deep-research-mcp
   

2. Install dependencies

   npm install
   

3. Configure environment variables

   cp .env.example .env
   

   Edit the .env file and add your API keys:

   OPENAI_API_KEY=sk-your-openai-api-key
   FIRECRAWL_API_KEY=your-firecrawl-api-key
   

4. Build the project

   npm run build
   

🚀 Usage

Running the MCP Server

Start the server on stdio for MCP client connections:

npm start

Using the Example Client

Run research on a specific topic with a specified depth:

npm run client "Your research topic" 3

Parameters:

• First argument: Research topic or query
• Second argument: Research depth (number of iterations, default: 2)
• Third argument (optional): "complete" to use the complete-research tool (one-step process)

Example:

npm run client "the impact of climate change on coral reefs" 3 complete

Example Output

The DeepResearch MCP will produce a comprehensive report that includes:

• Executive Summary - Concise overview of the research findings
• Introduction - Context and importance of the research topic
• Methodology - Description of the research approach
• Comprehensive Analysis - Detailed examination of the topic
• Comparative Analysis - Visual comparison of key aspects
• Discussion - Interpretation of findings and implications
• Limitations - Constraints and gaps in the research
• Conclusion - Final insights and recommendations
• Bibliography - Complete list of sources with URLs

🔧 MCP Integration

Available MCP Resources

Resource Path	Description
research://state/{sessionId}	Access the current state of a research session
research://findings/{sessionId}	Access the collected findings for a session

Available MCP Tools

Tool Name	Description	Parameters
initialize-research	Start a new research session	query: string, depth: number
execute-research-step	Execute the next research step	sessionId: string
generate-report	Create a final report	sessionId: string, timeout: number (optional)
complete-research	Execute the entire research process	query: string, depth: number, timeout: number (optional)

🖥️ Claude Desktop Integration

DeepResearch MCP can be integrated with Claude Desktop to provide direct research capabilities to Claude.

Configuration Steps

1. Copy the sample configuration

   cp claude_desktop_config_sample.json ~/path/to/claude/desktop/config/directory/claude_desktop_config.json
   

2. Edit the configuration file

   Update the path to point to your installation of deep-research-mcp and add your API keys:

   {
     "mcpServers": {
       "deep-research": {
         "command": "node",
         "args": [
           "/absolute/path/to/your/deep-research-mcp/dist/index.js"
         ],
         "env": {
           "FIRECRAWL_API_KEY": "your-firecrawler-api-key",
           "OPENAI_API_KEY": "your-openai-api-key"
         }
       }
     }
   }
   

3. Restart Claude Desktop

   After saving the configuration, restart Claude Desktop for the changes to take effect.

4. Using with Claude Desktop

   Now you can ask Claude to perform research using commands like:

   Can you research the impact of climate change on coral reefs and provide a detailed report?
   

📋 Sample Client Code

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function main() {
  // Connect to the server
  const transport = new StdioClientTransport({
    command: "node",
    args: ["dist/index.js"]
  });

  const client = new Client({ name: "deep-research-client", version: "1.0.0" });
  await client.connect(transport);

  // Initialize research
  const initResult = await client.callTool({
    name: "initialize-research",
    arguments: {
      query: "The impact of artificial intelligence on healthcare",
      depth: 3
    }
  });
  
  // Parse the response to get sessionId
  const { sessionId } = JSON.parse(initResult.content[0].text);
  
  // Execute steps until complete
  let currentDepth = 0;
  while (currentDepth < 3) {
    const stepResult = await client.callTool({
      name: "execute-research-step",
      arguments: { sessionId }
    });
    
    const stepInfo = JSON.parse(stepResult.content[0].text);
    currentDepth = stepInfo.currentDepth;
    
    console.log(`Completed step ${stepInfo.currentDepth}/${stepInfo.maxDepth}`);
  }
  
  // Generate final report with timeout
  const report = await client.callTool({
    name: "generate-report",
    arguments: { 
      sessionId,
      timeout: 180000 // 3 minutes timeout
    }
  });
  
  console.log("Final Report:");
  console.log(report.content[0].text);
}

main().catch(console.error);

🔍 Troubleshooting

Common Issues

• Token Limit Exceeded: For very large research topics, you may encounter OpenAI token limit errors. Try:

  • Reducing the research depth
  • Using more specific queries
  • Breaking complex topics into smaller sub-topics

• Timeout Errors: For complex research, the process may time out. Solutions:

  • Increase the timeout parameters in tool calls
  • Use the complete-research tool with a longer timeout
  • Process research in smaller chunks

• API Rate Limits: If you encounter rate limit errors from OpenAI or Firecrawl:

  • Implement a delay between research steps
  • Use an API key with higher rate limits
  • Retry with exponential backoff

📝 License

ISC

🙏 Acknowledgements

• Built with Model Context Protocol
• Powered by OpenAI and Firecrawl