<p align="center">
  <img src="assets/logo.png" width="140" alt="Deep Research MCP Logo" />
</p>

<h1 align="center">Deep Research MCP Server</h1>
<p align="center"><b>Non-generic MCP for real research. Search → Scrape → Synthesize → Fact-check → Remember.</b></p>

<p align="center">
  <a href="https://github.com/SECRET4422/mcp-deep-research-server/actions"><img src="https://img.shields.io/github/actions/workflow/status/SECRET4422/mcp-deep-research-server/ci.yml?branch=main&label=CI&logo=github" alt="CI" /></a>
  <a href="https://www.npmjs.com/package/mcp-deep-research-server"><img src="https://img.shields.io/npm/v/mcp-deep-research-server?logo=npm&color=red" alt="npm" /></a>
  <a href="https://www.npmjs.com/package/mcp-deep-research-server"><img src="https://img.shields.io/npm/dm/mcp-deep-research-server?logo=npm" alt="downloads" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/SECRET4422/mcp-deep-research-server" alt="MIT" /></a>
  <a href="https://github.com/SECRET4422/mcp-deep-research-server/stargazers"><img src="https://img.shields.io/github/stars/SECRET4422/mcp-deep-research-server?style=flat&logo=github" alt="stars" /></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-black?logo=anthropic" alt="MCP" /></a>
  <a href="skills/deep-research/SKILL.md"><img src="https://img.shields.io/badge/Agent%20Skill-Compatible-8a2be2" alt="Agent Skill" /></a>
  <img src="https://img.shields.io/badge/No%20API%20Key%20Needed-2ea44f" alt="No API Key" />
</p>

---

### Why not generic?

| Generic MCP (boring) | This MCP (pro) |
|---|---|
| `echo`, `fetch` | **Orchestrated deep research** |
| Returns raw HTML | **Cheerio + Turndown → clean markdown** + headings, links, meta |
| No memory | **Persistent memory** in `~/.mcp-deep-research/` |
| One page at a time | **Parallel 3-worker scraper**, 10min cache |
| No reasoning | **Fact-check with stance scoring**, contradiction detection |

### Architecture

```mermaid
graph LR
    A[User: deep_research topic] --> B[search_web DDG HTML]
    B --> C[Parallel Scrape x3-8]
    C --> D[cheerio clean + turndown md]
    D --> E[extract_insights heuristic]
    E --> F[Synthesize Report + Citations]
    F --> G[memory_save + history]
    F --> H[Return to Claude]
    
    I[compare_sources] --> C
    J[fact_check_claim] --> B
    K[memory_search] --> G
```

### Tools (8)

| Tool | What it does | Params |
|------|--------------|--------|
| `search_web` | DuckDuckGo HTML search, no API key, UDDG decode | `query, count 1-10, timeFilter` |
| `scrape_page` | Fetch + main-content heuristic + markdown | `url, format=markdown|text|full, extractMainOnly` |
| `extract_insights` | Entities, stats regex, key-point scoring, reading time | `content, goal?` |
| `deep_research` | **Power tool** — search → parallel scrape → synthesize report | `topic, depth=quick|standard|deep, maxSources, saveMemory` |
| `compare_sources` | 2-5 URLs → consensus vs unique vs contradictions | `urls[], focus?` |
| `fact_check_claim` | Searches support + `debunked OR false`, heuristic verdict | `claim, searchDepth` |
| `memory_save` | Save finding to JSON, survives restarts | `key, value, tags[], source?` |
| `memory_search` | Fuzzy search in persistent memory | `query, tags[], limit` |

**Resources:**
- `research://memory` — all saved findings
- `research://history` — last 100 actions
- `research://stats` — cache size, uptime

**Prompts:**
- `deep-dive-research` — full research workflow
- `fact-check` — fact-checker squad
- `compare-narratives` — bias & comparison table

### Quickstart & Installation

#### ⚡ 1-Click Auto Setup for Claude Desktop (Recommended)
Run this single command in your terminal:
```bash
npx mcp-deep-research-server --install
```
> That's it! It automatically detects your OS, writes the config to your `claude_desktop_config.json`, and configures the 8 research tools. Just restart Claude Desktop.

---

#### 🛠️ Manual / Other Clients Setup

**Run via npx:**
```bash
npx mcp-deep-research-server
```

**Or build from source:**
```bash
git clone https://github.com/SECRET4422/mcp-deep-research-server.git
cd mcp-deep-research-server
npm install
npm run build
```

---

#### 🤖 Agent Skill (Claude Code / Antigravity / Agent Frameworks)
This repository includes an open-standard [Agent Skill](skills/deep-research/SKILL.md) that teaches AI coding assistants when and how to autonomously run deep research workflows.
- Import via skill directory: `skills/deep-research/`
- Spec compliant with Claude Code, Cursor, and Google Antigravity agents.

### Test (smoke)

```bash
npm run test:mcp
# or
npm run inspect # opens http://localhost:6274
```

Manually tested:
```
[search] Dehradun → 3 results ✓
[deep_research] What is MCP → 3 sources in 2.1s ✓
tools/list → 8 tools ✓
```

### Add to Claude Desktop

Edit config:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "deep-research": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-deep-research-server/build/index.js"]
    }
  }
}
```

Restart Claude Desktop.

### Add to Cursor / Windsurf / VS Code

`.cursor/mcp.json` or `mcp.json`:

```json
{
  "mcpServers": {
    "deep-research": {
      "command": "node",
      "args": ["./build/index.js"],
      "cwd": "/path/to/mcp-deep-research-server"
    }
  }
}
```

### Example Prompts

**Deep Research:**
> Use deep_research to research "Best LLM fine-tuning in 2026, depth deep" then compare LoRA vs QLoRA

**Fact Check:**
> Fact check claim: "Bun is faster than Node" using fact_check_claim

**Compare:**
> Compare these 3 URLs about MCP architecture focusing on security:
> https://modelcontextprotocol.io/docs/getting-started/intro
> https://www.anthropic.com/news/model-context-protocol
> https://en.wikipedia.org/wiki/Model_Context_Protocol

See `examples/claude-example.md` for more.

### Data Storage

All in `~/.mcp-deep-research/`:
- `memory.json` — persistent findings
- `history.json` — audit log (100 max)
- `cache/` — reserved

No DB, no external calls except search/scrape.

### Pro Features in v1.1.0

- ✅ Logo + pro README + badges
- ✅ GitHub Actions CI (Node 18/20/22) + Release workflow
- ✅ Issue templates, PR template, CONTRIBUTING, SECURITY
- ✅ `.editorconfig`, smoke test script
- ✅ Optimized `package.json` for npm publishing
- ✅ CHANGELOG tracked

### Roadmap

- [ ] Tavily / Brave API fallback if keys present
- [ ] PDF parsing via `pdf-parse`
- [ ] YouTube transcript tool
- [ ] Vector search on memory (embeddings)
- [x] SSRF protection — private/internal IP blocklist for `scrape_page`
- [ ] Smithery registry

### Dev

```bash
npm run dev     # tsx watch
npm run build
npm run lint
```

Guidelines in `CONTRIBUTING.md`.

### License

MIT © Prabhakar Pal — See LICENSE

> Built with 🧠 for Dehradun → World. Not a generic MCP.