ameeralns/DeepResearchMCP

## 📚 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
bash
git clone
cd deep-research-mcp
2. Install dependencies
bash
npm install
3. Configure environment variables
bash
cp .env.example .env
Edit the .env file and add your API keys:
OPENAIAPIKEY=sk-your-openai-api-key
FIRECRAWLAPIKEY=your-firecrawl-api-key
4. Build the project
bash
npm run build
## 🚀 Usage
### Running the MCP Server
Start the server on stdio for MCP client connections:
bash
npm start
### Using the Example Client
Run research on a specific topic with a specified depth:
bash
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:
bash
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 |