01-project

---

description: Deep Research MCP Server – Rules and integration guide

Deep Research MCP Server – Rules for Contributors

This document explains repo layout, environment, Gemini usage, search provider priority/fallbacks, and safe contribution steps for users.

• Repo: deep-research-mcp-server/
• Stack: Node.js 22.x, TypeScript 5.x
• Key libs: @google/genai (Gemini), @mendable/firecrawl-js, @modelcontextprotocol/sdk, zod, lru-cache
• Primary entry points:
  • CLI: src/run.ts
  • MCP server: src/mcp-server.ts
  • Core logic: src/deep-research.ts
  • AI wrapper: src/ai/providers.ts
  • Text splitting: src/ai/text-splitter.ts
  • Feedback: src/feedback.ts
  • Output/Progress: src/output-manager.ts, src/progress-manager.ts, src/terminal-utils.ts
  • Prompts: src/prompt.ts
  • Types/Utils: src/types.ts, src/utils/json.ts, src/utils/sanitize.ts

Environment & Config

• Required: GEMINI_API_KEY
• Optional: FIRECRAWL_API_KEY, FIRECRAWL_BASE_URL
• Config:
  • GEMINI_MODEL (default: gemini-2.5-flash)
  • CONCURRENCY_LIMIT (default: 5)

Gemini SDK Usage (TypeScript)

Use the official Google Gen AI SDK @google/genai.

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY!,
  ...(process.env.GEMINI_API_ENDPOINT ? { apiEndpoint: process.env.GEMINI_API_ENDPOINT } : {}),
});
const modelId = process.env.GEMINI_MODEL || "gemini-2.5-flash";
const model = client.getGenerativeModel({ model: modelId, systemInstruction: "You are a precise research assistant." });

• Long context: prefer gemini-2.5-flash for speed; chunk sources via src/ai/text-splitter.ts and trim with adaptivePrompt() in src/ai/providers.ts.
• Thinking: enable where useful (models that support it) and cap budgets; surface summaries only.
• Structured output: request JSON via schema; validate with zod.
• Function calling / tools: declare tool schemas and pass in; handle tool responses deterministically.
• Grounding: use Google Search Grounding or URL context when needed; keep citations.