MCP HubMCP Hub
ssdeanx

deep-research-mcp-server

by: ssdeanx

MCP Deep Research Server using Gemini creating a Research AI Agent

23created 20/02/2025
Visit
Gemini
AI

📌Overview

Purpose: To provide a lightweight yet powerful tool for conducting deep, iterative research utilizing advanced AI language models and web scraping techniques.

Overview: Deep-research is an AI-powered research assistant designed to navigate complex research tasks effectively. By integrating web scraping and advanced language processing capabilities via Gemini LLMs, it enables users to gather insights and generate reports within a concise and understandable codebase.

Key Features:

  • MCP Integration: Enables seamless functionality within AI agent ecosystems as a Model Context Protocol tool.

  • Iterative Deep Dive: Facilitates in-depth exploration of topics through adaptive query refinement and result processing.

  • Gemini-Powered Queries: Utilizes Gemini LLMs to create intelligent and targeted search queries tailored to user research goals.

  • Depth & Breadth Control: Allows customizable parameters to dictate the thoroughness and scope of research inquiries.

  • Smart Follow-up Questions: Automatically generates relevant follow-up questions to enhance understanding and guide further exploration.

  • Comprehensive Markdown Reports: Produces structured reports summarizing findings in a readily usable Markdown format.

  • Concurrent Processing for Speed: Optimizes research workflows by allowing multiple search queries and results to be processed in parallel.


Deep-research

Your AI-Powered Research Assistant.
Conduct iterative, deep research using search engines, web scraping, and Gemini LLMs, all within a lightweight and understandable codebase.

This tool uses Firecrawl for efficient web data extraction and Gemini for advanced language understanding and report generation.

The goal of this project is to provide the simplest yet most effective implementation of a deep research agent. It is designed to be easily understood, modified, and extended, aiming for a codebase under 500 lines of code (LoC).

Key Features

  • MCP Integration: Seamlessly integrates as a Model Context Protocol (MCP) tool into AI agent ecosystems.
  • Iterative Deep Dive: Explores topics deeply through iterative query refinement and result processing.
  • Gemini-Powered Queries: Uses Gemini LLMs to generate smart, targeted search queries.
  • Depth & Breadth Control: Configurable depth and breadth parameters for precise research scope.
  • Smart Follow-up Questions: Intelligently generates follow-up questions for query refinement.
  • Comprehensive Markdown Reports: Generates detailed, ready-to-use Markdown reports.
  • Concurrent Processing for Speed: Maximizes research efficiency with parallel processing.

Workflow Diagram

flowchart TB
    subgraph Input
        Q[User Query]
        B[Breadth Parameter]
        D[Depth Parameter]
    end

    DR[Deep Research] -->
    SQ[SERP Queries] -->
    PR[Process Results]

    subgraph Results[Results]
        direction TB
        NL((Learnings))
        ND((Directions))
    end

    PR --> NL
    PR --> ND

    DP{depth > 0?}

    RD["Next Direction:
    - Prior Goals
    - New Questions
    - Learnings"]

    MR[Markdown Report]

    %% Main Flow
    Q & B & D --> DR

    %% Results to Decision
    NL & ND --> DP

    %% Circular Flow
    DP -->|Yes| RD
    RD -->|New Context| DR

    %% Final Output
    DP -->|No| MR

    %% Styling
    classDef input fill:#7bed9f,stroke:#2ed573,color:black
    classDef process fill:#70a1ff,stroke:#1e90ff,color:black
    classDef recursive fill:#ffa502,stroke:#ff7f50,color:black
    classDef output fill:#ff4757,stroke:#ff6b81,color:black
    classDef results fill:#a8e6cf,stroke:#3b7a57,color:black

    class Q,B,D input
    class DR,SQ,PR process
    class DP,RD recursive
    class MR output
    class NL,ND results

Persona Agents in open-deep-research

What are Persona Agents?

In deep-research, persona agents guide the behavior of Gemini language models by providing a specific role, skills, personality, communication style, and values. This helps to:

  • Focus the LLM's Output: Ensures responses align with the desired expertise and perspective.
  • Improve Consistency: Maintains a consistent tone and style throughout the process.
  • Enhance Task-Specific Performance: Optimizes outputs for different stages (e.g., query generation, learning extraction, feedback).

Examples of Personas:

  • Expert Research Strategist & Query Generator: Emphasizes strategic thinking and precise query formulation.
  • Expert Research Assistant & Insight Extractor: Focuses on meticulous analysis and factual accuracy.
  • Expert Research Query Refiner & Strategic Advisor: Guides users toward clearer research questions.
  • Professional Doctorate Level Researcher (System Prompt): Sets an expert-level tone for the entire process.

By leveraging persona agents, deep-research achieves targeted, consistent, and high-quality outcomes with Gemini LLMs.

How It Works

Deep research is conducted iteratively: starting with an initial query, the system generates search queries using Gemini LLMs, processes web results via Firecrawl, extracts learnings, and formulates follow-up questions to dig deeper until the desired depth or breadth is reached. The final output is a comprehensive Markdown report summarizing findings and sources.

Features Summary

  • MCP Integration as a tool for AI agent ecosystems.
  • Iterative research approach with query generation and result processing.
  • Gemini-powered intelligent query generation.
  • Configurable depth and breadth parameters.
  • Follow-up question generation for refining research.
  • Detailed Markdown report production.
  • Concurrent processing for efficiency.

Requirements

  • Node.js environment (v22.x recommended)
  • API keys for:
    • Firecrawl API (for web search and content extraction)
    • Gemini API (for advanced LLM access, knowledge cutoff: August 2024)

Setup

Node.js

  1. Clone the repository:

    git clone [your-repo-link-here]
    
  2. Install dependencies:

    npm install
    
  3. Set up environment variables:
    Create a .env.local file in the project root and add your API keys:

    GEMINI_API_KEY="your_gemini_key"
    FIRECRAWL_KEY="your_firecrawl_key"
    # Optional for self-hosted Firecrawl:
    # FIRECRAWL_BASE_URL=http://localhost:3002
    
  4. Build the project:

    npm run build
    

Usage

As MCP Tool

Start the MCP server:

node --env-file .env.local dist/mcp-server.js

Invoke the deep-research tool from any MCP-compatible agent with parameters:

  • query (string, required): Research query.
  • depth (number, optional, 1-5): Research depth.
  • breadth (number, optional, 1-5): Research breadth.
  • existingLearnings (string[], optional): Pre-existing findings.

Example TypeScript invocation:

const mcp = new ModelContextProtocolClient(); // Assuming MCP client is initialized

async function invokeDeepResearchTool() {
  try {
    const result = await mcp.invoke("deep-research", {
      query: "Explain the principles of blockchain technology",
      depth: 2,
      breadth: 4
    });

    if (result.isError) {
      console.error("MCP Tool Error:", result.content[0].text);
    } else {
      console.log("Research Report:\n", result.content[0].text);
      console.log("Sources:\n", result.metadata.sources);
    }
  } catch (error) {
    console.error("MCP Invoke Error:", error);
  }
}

invokeDeepResearchTool();

Standalone CLI Usage

Run directly from the command line:

npm run start "your research query"

Example:

npm run start "what are latest developments in ai research agents"

MCP Inspector Testing

For interactive testing and debugging:

npx @modelcontextprotocol/inspector node --env-file .env.local dist/mcp-server.js

License

MIT License — Free and Open Source.


Recent Improvements (v0.2.0)

Enhanced Research Validation:

  • Input validation: minimum 10 characters + 3 words.
  • Output validation: citation density (1.5+ per 100 words).
  • Recent sources check (3+ references post-2019).
  • Conflict disclosure enforcement.

Gemini Integration Upgrades:

  • Embedded Gemini analysis in the workflow.
  • Integrated Gemini Flash 2.0 for faster processing.
  • Added semantic text splitting for LLM context management.
  • Improved API error handling.

Code Quality Improvements:

  • Added concurrent processing pipeline.
  • Removed redundant academic-validators module.
  • Enhanced type safety across interfaces.
  • Optimized dependencies (30% smaller node_modules).

New Features:

  • Research metrics tracking (sources/learnings ratio).
  • Auto-generated conflict disclosure statements.
  • Recursive research depth control (1-5 levels).
  • MCP tool integration improvements.

Performance:

  • 30% faster research cycles.
  • 40% faster initial research cycles.
  • 60% reduction in API errors.
  • 25% more efficient token usage.

🚀 Let's dive deep into research! 🚀