{"id":"aeae89d9-c306-49dc-9164-faec27363609","slug":"deep-research-mcp-server","kind":"mcp","name":"deep-research-mcp-server","summary":"MCP Deep Research Server using Gemini creating a Research AI Agent","owner":"ssdeanx","repoUrl":"https://github.com/ssdeanx/deep-research-mcp-server","license":"MIT","licenseTier":"permissive","trust":"community","stars":69,"match":null,"fewStars":false,"format":"mcp","createdAt":null,"addedAt":"2026-10-14T03:46:01.114Z","logoUrl":"https://avatars.githubusercontent.com/u/192780881?u=048f441aeee5de5306f847110f942acb9f1510b4&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra"],"tags":["ai","ai-agents","ai-research","ai-research-assistant","ai-researcher","airesearch","research","research-and-development"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T04:21:06.736Z","sample":false,"url":"https://conduits.dev/tools/deep-research-mcp-server","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Deep Research MCP Server\n\n[![Node.js](https://img.shields.io/badge/node.js-v22.x-green?style=flat-square&logo=node.js)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-%5E5.9.2-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)\n[![Gemini API](https://img.shields.io/badge/Gemini_2.5-Flash-purple?style=flat-square&logo=google-gemini)](https://makersuite.google.com/app/apikey)\n[![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-lightgrey?style=flat-square)](https://github.com/modelcontextprotocol)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)\n\n**Your AI-Powered Research Assistant.** Conduct iterative, deep research using Google Gemini 2.5 Flash with Google Search Grounding and URL context. No web-scraping dependency is required.\n\n---\n\n## Table of Contents\n\n* [Features](#features)\n* [Why This Project](#why-this-project)\n* [Workflow Diagram](#workflow-diagram)\n* [Persona Agents](#persona-agents)\n* [How It Works](#how-it-works)\n* [Project Structure](#project-structure)\n* [Requirements](#requirements)\n* [Setup](#setup)\n* [Usage](#usage)\n  * [As MCP Tool](#as-mcp-tool)\n  * [Standalone CLI Usage](#standalone-cli-usage)\n  * [MCP Inspector Testing](#mcp-inspector-testing)\n* [Configuration](#configuration)\n* [Quickstart](#quickstart)\n* [Example Output](#example-output)\n* [Support](#support)\n* [Contributing](#contributing)\n* [Roadmap](#roadmap)\n* [License](#license)\n\nThe goal of this project is to provide the *simplest* yet *most effective* implementation of a deep research agent.  It's designed to be easily understood, modified, and extended, aiming for a codebase under 500 lines of code (LoC).\n\n**Key Features:**\n\n* **MCP Integration:** Runs as a Model Context Protocol (MCP) server/tool for seamless agent integration.\n* **Gemini 2.5 Flash Pipeline:** Long-context reasoning, structured JSON outputs, and tool use (Google Search Grounding, Code Execution, Functions) via env flags.\n* **Iterative Deep Dive:** Query refinement + result analysis with learned context carried forward.\n* **Depth & Breadth Control:** Tune exploration scope precisely.\n* **Semantic/Recursive Splitting:** Token-aware chunking for robust summarization and analysis.\n* **Batching + Caching:** Concurrency-limited batched model calls with LRU caches across prompts/results.\n* **Professional Reports:** Generates structured Markdown (Abstract, ToC, Intro, Body, Methodology, Limitations, Key Learnings, References).\n\n## Why This Project\n\n* **Gemini-first, modern pipeline:** Built around Gemini 2.5 Flash with optional tools (Search Grounding, Code Execution, Functions).\n* **Minimal, understandable core:** Plain TypeScript; easy to audit and extend.\n* **Deterministic outputs:** Zod-validated JSON and consistent report scaffolding.\n* **Agent-ready:** Clean MCP server entry; works with Inspector and MCP-aware clients.\n\n## Workflow Diagram\n\n```mermaid\nflowchart TB\n    subgraph Input\n        Q[User Query]\n        B[Breadth Parameter]\n        D[Depth Parameter]\n    end\n\n    DR[Deep Research] -->\n    SQ[SERP Queries] -->\n    PR[Process Results]\n\n    subgraph Results[Results]\n        direction TB\n        NL((Learnings))\n        ND((Directions))\n    end\n\n    PR --> NL\n    PR --> ND\n\n    DP{depth > 0?}\n\n    RD[\"Next Direction:\n    - Prior Goals\n    - New Questions\n    - Learnings\"]\n\n    MR[Markdown Report]\n\n    %% Main Flow\n    Q & B & D --> DR\n\n    %% Results to Decision\n    NL & ND --> DP\n\n    %% Circular Flow\n    DP -->|Yes| RD\n    RD -->|New Context| DR\n\n    %% Final Output\n    DP -->|No| MR\n\n    %% Styling\n    classDef input fill:#7bed9f,stroke:#2ed573,color:black\n    classDef process fill:#70a1ff,stroke:#1e90ff,color:black\n    classDef recursive fill:#ffa502,stroke:#ff7f50,color:black\n    classDef output fill:#ff4757,stroke:#ff6b81,color:black\n    classDef results fill:#a8e6cf,stroke:#3b7a57,color:black\n\n    class Q,B,D input\n    class DR,SQ,PR process\n    class DP,RD recursive\n    class MR output\n    class NL,ND results\n```\n\n## Persona Agents\n\n**What are Persona Agents?**\n\nIn `deep-research`, we utilize the concept of \"persona agents\" to guide the behavior of the Gemini language models.  Instead of simply prompting the LLM with a task, we imbue it with a specific **role, skills, personality, communication style, and values.** This approach helps to:\n\n* **Focus the LLM's Output:** By defining a clear persona, we encourage the LLM to generate responses that are aligned with the desired expertise and perspective.\n* **Improve Consistency:** Personas help maintain a consistent tone and style throughout the research process.\n* **Enhance Task-Specific Performance:**  Tailoring the persona to the specific task (e.g., query generation, learning extraction, feedback) optimizes the LLM's output for that stage of the research.\n\n**Examples of Personas in use:**\n\n* **Expert Research Strategist & Query Generator:**  Used for generating search queries, this persona emphasizes strategic thinking, comprehensive coverage, and precision in query formulation.\n* **Expert Research Assistant & Insight Extractor:**  When processing web page content, this persona focuses on meticulous analysis, factual accuracy, and extracting key learnings relevant to the research query.\n* **Expert Research Query Refiner & Strategic Advisor:**  For generating follow-up questions, this persona embodies strategic thinking, user intent understanding, and the ability to guide users towards clearer and more effective research questions.\n* **Professional Doctorate Level Researcher (System Prompt):**  This overarching persona, applied to the main system prompt, sets the tone for the entire research process, emphasizing expert-level analysis, logical structure, and in-depth investigation.\n\nBy leveraging persona agents, `deep-research` aims to achieve more targeted, consistent, and high-quality research outcomes from the Gemini language models.\n\n## How It Works\n\nCore modules:\n\n* `src/deep-research.ts` — orchestrates queries, batching, analysis, and synthesis\n  * `generateSerpQueries()` uses Gemini to propose SERP-style queries from your prompt and prior learnings\n  * `processSerpResult()` splits content, batches Gemini calls with tools enabled, extracts learnings and citations\n  * `conductResearch()` runs analysis passes over semantic chunks\n  * `writeFinalReport()` builds the final professional Markdown report\n* `src/ai/providers.ts` — GoogleGenAI wrapper for Gemini 2.5 Flash, batching, token control, optional tools\n* `src/ai/text-splitter.ts` — RecursiveCharacter and Semantic splitters\n* `src/mcp-server.ts` — MCP server entry point and types\n* `src/run.ts` — CLI entry point\n\nPipeline highlights:\n\n* Structured JSON outputs validated with Zod\n* Concurrency-limited batching (`generateBatch`, `generateBatchWithTools`)\n* LRU caches for prompts, SERP proposals, and reports\n* Optional Gemini tools via flags: Google Search Grounding, Code Execution, Functions\n\n## Project Structure\n\n```text\ndeep-research-mcp-server/\n├─ src/\n│  ├─ ai/\n│  │  ├─ providers.ts           # Gemini wrapper, tools, batching, caching\n│  │  └─ text-splitter.ts       # Semantic/recursive splitters\n│  ├─ mcp-server.ts             # MCP server entry/types\n│  ├─ deep-research.ts          # Orchestrator: queries → analysis → synthesis\n│  ├─ prompt.ts                 # System + templates\n│  ├─ feedback.ts               # Refinement/feedback loop\n│  ├─ output-manager.ts         # Report/output formatting\n│  ├─ progress-manager.ts       # CLI progress\n│  ├─ terminal-utils.ts         # CLI helpers\n│  ├─ types.ts                  # Zod schemas/types\n│  └─ utils/                    # JSON/sanitize helpers\n├─ dist/                        # Build output\n├─ .env.example                 # Environment template\n├─ package.json                 # Scripts/deps\n└─ README.md\n```\n\n## Requirements\n\n* [Node.js](https://nodejs.org/) v22.x\n* [Google Gemini API key](https://makersuite.google.com/app/apikey)\n\n## Setup\n\n### Node.js\n\n1. **Clone the repository:**\n\n    ```bash\n    git clone [your-repo-link-here]\n    ```\n\n2. **Install dependencies:**\n\n    ```bash\n    npm install\n    ```\n\n3. **Set up environment variables:** Create a `.env.local` file in the project root:\n\n    ```bash\n    # Required\n    GEMINI_API_KEY=\"your_gemini_key\"\n\n    # Recommended defaults\n    GEMINI_MODEL=gemini-2.5-flash\n    GEMINI_MAX_OUTPUT_TOKENS=65536\n    CONCURRENCY_LIMIT=5\n\n    # Gemini tools (enable as needed)\n    ENABLE_GEMINI_GOOGLE_SEARCH=true\n    ENABLE_GEMINI_CODE_EXECUTION=false\n    ENABLE_GEMINI_FUNCTIONS=false\n    ```\n\n4. **Build the project:**\n\n    ```bash\n    npm run build\n    ```\n\n## Usage\n\n### As MCP Tool\n\nTo run `deep-research` as an MCP tool, start the MCP server:\n\n```bash\nnode --env-file .env.local dist/mcp-server.js\n```\n\nYou can then invoke the `deep-research` tool from any MCP-compatible agent using the following parameters:\n\n* `query` (string, required): The research query.\n* `depth` (number, optional, 1-5): Research depth (default: moderate).\n* `breadth` (number, optional, 1-5): Research breadth (default: moderate).\n* `existingLearnings` (string[], optional):  Pre-existing research findings to guide research.\n\n**Example MCP Tool Arguments (JSON shape):**\n\n```json\n{\n  \"name\": \"deep-research\",\n  \"arguments\": {\n    \"query\": \"State of multi-agent research agents in 2025\",\n    \"depth\": 3,\n    \"breadth\": 3,\n    \"existingLearnings\": [\n      \"Tool use improves grounding\",\n      \"Batching reduces latency\"\n    ]\n  }\n}\n```\n\n```typescript\nconst mcp = new ModelContextProtocolClient(); // Assuming MCP client is initialized\n\nasync function invokeDeepResearchTool() {\n  try {\n    const result = await mcp.invoke(\"deep-research\", {\n      query: \"Explain the principles of blockchain technology\",\n      depth: 2,\n      breadth: 4\n    });\n\n    if (result.isError) {\n      console.error(\"MCP Tool Error:\", result.content[0].text);\n    } else {\n      console.log(\"Research Report:\\n\", result.content[0].text);\n      console.log(\"Sources:\\n\", result.metadata.sources);\n    }\n  } catch (error) {\n    console.error(\"MCP Invoke Error:\", error);\n  }\n}\n\ninvokeDeepResearchTool();\n```\n\n### Standalone CLI Usage\n\nTo run `deep-research` directly from the command line:\n\n```bash\nnpm run start \"your research query\"\n```\n\n**Example:**\n\n```bash\nnpm run start \"what are latest developments in ai research agents\"\n```\n\n### MCP Inspector Testing\n\nFor interactive testing and debugging of the MCP server, use the MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector node --env-file .env.local dist/mcp-server.js\n```\n\n### MCP Integration Tips\n\n* **Environment**: Provide `GEMINI_API_KEY` to the MCP server process; model and tool flags via env.\n* **Stateless calls**: The server derives behavior from env; keep flags in sync with your client profile.\n* **Latency**: Enable batching and reasonable `CONCURRENCY_LIMIT` to balance speed vs rate limits.\n\n## Configuration\n\n* `GEMINI_API_KEY` — required\n* `GEMINI_MODEL` — defaults to `gemini-2.5-flash`\n* `GEMINI_MAX_OUTPUT_TOKENS` — defaults to `65536`\n* `CONCURRENCY_LIMIT` — defaults to `5`\n* `ENABLE_GEMINI_GOOGLE_SEARCH` — enable Google Search Grounding tool\n* `ENABLE_GEMINI_CODE_EXECUTION` — enable code execution tool\n* `ENABLE_GEMINI_FUNCTIONS` — enable function calling\n\nOptional providers (planned/behind flags): Exa/Tavily can be integrated later; Firecrawl is not required for the current pipeline.\n\n## Quickstart\n\n1) Clone and install\n\n```bash\ngit clone https://github.com/ssdeanx/deep-research-mcp-server\ncd deep-research-mcp-server\nnpm i && npm run build\n```\n\n2) Create `.env.local` (see [Setup](#setup))\n\n3) Run as MCP server (Inspector)\n\n```bash\nnpx @modelcontextprotocol/inspector node --env-file .env.local dist/mcp-server.js\n```\n\n4) Or run as CLI\n\n```bash\nnpm run start \"state of multi-agent research agents in 2025\"\n```\n\n## Example Output\n\n```markdown\n# Abstract\nConcise overview of the research goal, scope, method, and key findings.\n\n# Table of Contents\n...\n\n# Introduction\nContext and framing.\n\n# Body\nEvidence-backed sections with citations.\n\n# Methodology\nHow sources were found and analyzed.\n\n# Limitations\nAssumptions and risks.\n\n# Key Learnings\nBulleted insights and takeaways.\n\n# References\nNormalized citations to visited URLs.\n```\n\n## Support\n\n* **Issues:** Use GitHub Issues for bugs and feature requests.\n* **Discussions:** Propose ideas or ask questions.\n* **Security:** Do not file public issues for sensitive disclosures; contact maintainers privately.\n\n## Contributing\n\n* **PRs welcome:** Please open an issue first for significant changes.\n* **Standards:** TypeScript 5.x, Node.js 22.x, lint/type-check before PRs.\n* **Checks:** `npm run build` and `tsc --noEmit` must pass.\n* **Docs:** Update `README.md` and `.env.example` when changing env/config.\n\n## Roadmap\n\n* **Exa search integration** (behind `ENABLE_EXA_PRIMARY`), Google grounding for augmentation.\n* **Provider cleanup:** Remove Firecrawl after Exa migration (explicit approval required).\n* **CI/CD:** Add GitHub Actions for build/lint/test and badge.\n* **Examples:** Add sample reports and prompts.\n\n## Troubleshooting\n\n* **Missing API key**: Ensure `GEMINI_API_KEY` is set in `.env.local` and processes are started with `--env-file .env.local`.\n* **Model/tool flags**: If grounding or functions aren’t active, verify `ENABLE_GEMINI_GOOGLE_SEARCH`, `ENABLE_GEMINI_CODE_EXECUTION`, `ENABLE_GEMINI_FUNCTIONS`.\n* **Rate limits/latency**: Lower `CONCURRENCY_LIMIT` (e.g., 3) or rerun with fewer simultaneous queries.\n* **Output too long**: Reduce depth/breadth or lower `GEMINI_MAX_OUTPUT_TOKENS`.\n* **Schema parse errors**: Rerun; the pipeline validates/repairs JSON, but extreme prompts may exceed budgets—trim prompt or reduce chunk size.\n\n## License\n\n[MIT License](LICENSE) - Free and Open Source. Use it freely!\n\n---\n\n## **🚀 Let's dive deep into research! 🚀**\n\n## Recent Improvements (v0.3.0)\n\n> ✨ Highlights of the latest changes. See also [Roadmap](#roadmap).\n\n<details>\n  <summary><strong>🧪 Enhanced Research Validation</strong></summary>\n\n* ✅ Input validation: Minimum 10 characters + 3 words\n* 📈 Output validation: Citation density (1.5+ per 100 words)\n* 🔍 Recent sources check (3+ post-2019 references)\n* ⚖️ Conflict disclosure enforcement\n</details>\n\n<details>\n  <summary><strong>🧠 Gemini Integration Upgrades</strong></summary>\n\n* Consolidated on Gemini 2.5 Flash (long-context, structured JSON)\n* Optional tools via env flags: Search Grounding, Code Execution, Functions\n* Semantic + recursive splitting for context management\n* Robust batching with concurrency control and caching\n* Enhanced context management via semantic search\n* Improved error handling and logging\n\n</details>\n\n<details>\n  <summary><strong>🧹 Code Quality Improvements</strong></summary>\n\n* 🚀 Added concurrent processing pipeline\n* Removed redundant academic-validators module\n* 🛡️ Enhanced type safety across interfaces\n* 📦 Optimized dependencies (≈30% smaller node_modules)\n\n</details>\n\n<details>\n  <summary><strong>🆕 New Features</strong></summary>\n\n* 📊 Research metrics tracking (sources/learnings ratio)\n\n</details>\n* 📑 Auto-generated conflict disclosure statements\n* 🔄 Recursive research depth control (1-5 levels)\n* 📈 Research metrics tracking (sources/learnings ratio)\n* 🤖 MCP tool integration improvements\n\n**Performance:**\n\n* 🚀 30% faster research cycles\n* ⚡ 40% faster initial research cycles\n* 📉 60% reduction in API errors\n* 🧮 25% more efficient token usage\n"}