How ameeralns/deepresearchmcp works
Project Type and Purpose
• This is a TypeScript‐based Node.js application implementing an MCP (Model Context Protocol) “server” and accompanying example client. Its purpose is to orchestrate iterative web‐based research by combining a “Research Service” (session management), a “Search Service” (via Firecrawl), and an “Analysis/Report Service” (via OpenAI) into a unified research assistant.
File Structure
• Top‐Level Files
– package.json, tsconfig.json, .env.example: standard Node/TypeScript project setup
– README.md: high‐level design & usage
– claude_desktop_config_sample.json: sample integration config for Claude Desktop
• src/index.ts
– Entry point: initializes the MCP server layer, registers tools (initialize-research, execute-research-step, generate-report, complete-research)
• src/client-example.ts
– Example “MCP client” illustrating how to connect via stdio, call tools in sequence, and consume results
• src/services
– firecrawl.ts: wrapper around the Firecrawl API (web scraping/search)
– research.ts: implements session management, iteration logic (tracks depth, queries, findings)
– openai.ts: calls OpenAI endpoints to perform analysis and generate structured reports
• src/types/index.ts
– Shared TypeScript interfaces/types for sessions, tool arguments, response payloads
README Architecture Section
MCP Server Layer (tools & prompts) → Research Service → Search Service (Firecrawl) → OpenAI Service (analysis/report)
Main Components and Relationships
a. MCP Server Layer
• Hosts and exposes MCP “tools”
• Listens on stdio for client connections
• Routes tool calls into the Research Service module
b. Research Service (src/services/research.ts)
• Manages session state (currentDepth, maxDepth, findings)
• Invokes Search Service for each research step
• Aggregates search results and hands them off to analysis
c. Search Service (src/services/firecrawl.ts)
• Performs web scraping/search queries via Firecrawl API
• Returns raw content, metadata, URLs
d. OpenAI Service (src/services/openai.ts)
• Processes intermediate search results
• Generates summaries, analyses, full report sections (executive summary, bibliography, visualizations)
e. External Dependencies / Configuration
• Environment variables: OPENAI_API_KEY, FIRECRAWL_API_KEY
• Claude Desktop integration via JSON config
• MCP client SDK (imported in client‐example.ts)
Architectural Patterns & Design Principles
– Layered Architecture: clear separation between orchestration (MCP server), session logic, search, and analysis/reporting.
– Tool‐Based Modularization: each MCP “tool” is a discrete function with well‐defined inputs/outputs, facilitating extension and error resilience.
– Single‐Process Microservices: logical service separation within one process, avoiding network overhead.
– Environment‐Driven Configuration: API keys and external integration endpoints are injected via .env or JSON config.
– Clear labels for each component and file locations (e.g., src/services/research.ts)
• Internal modules (solid fill)
• Clients/transport (outline only)