# ameeralns/deepresearchmcp architecture

> Architecture diagram of the GitHub repository ameeralns/deepresearchmcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ameeralns/deepresearchmcp
- Repository: https://github.com/ameeralns/deepresearchmcp

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["MCP Client\nsrc/client-example.ts"]:::client

    %% Server Layer
    Server["MCP Server Layer\nsrc/index.ts"]:::internal

    %% Services
    Research["Research Service\nsrc/services/research.ts"]:::internal
    Search["Search Service\nsrc/services/firecrawl.ts"]:::internal
    OpenAI["OpenAI Service\nsrc/services/openai.ts"]:::internal

    %% Shared Types
    Types["Shared Types\nsrc/types/index.ts"]:::internal

    %% Configuration Files
    Env[".env.example\nENV vars"]:::config
    ClaudeCfg["claude_desktop_config_sample.json"]:::config
    Package["package.json"]:::config
    TSConfig["tsconfig.json"]:::config

    %% External APIs
    FirecrawlAPI["Firecrawl API"]:::external
    OpenAIAPI["OpenAI API"]:::external

    %% Data Flow
    Client -->|"stdio: initialize-research"| Server
    Server -->|"initialize-research\n{query,maxDepth}"| Research
    Research -->|"execute-research-step"| Search
    Search -.->|"API request"| FirecrawlAPI
    FirecrawlAPI -.->|"response"| Search
    Search -->|"results\n{content,urls}"| Research
    Research -->|"generate-report"| OpenAI
    OpenAI -.->|"API request"| OpenAIAPI
    OpenAIAPI -.->|"response"| OpenAI
    OpenAI -->|"reportSections"| Server
    Server -->|"stdio response"| Client

    %% Config Links
    Env --> Server
    ClaudeCfg --> Server
    Types --> Server
    Types --> Research
    Types --> Search
    Types --> OpenAI

    %% Click Events
    click Client "https://github.com/ameeralns/deepresearchmcp/blob/main/src/client-example.ts"
    click Server "https://github.com/ameeralns/deepresearchmcp/blob/main/src/index.ts"
    click Research "https://github.com/ameeralns/deepresearchmcp/blob/main/src/services/research.ts"
    click Search "https://github.com/ameeralns/deepresearchmcp/blob/main/src/services/firecrawl.ts"
    click OpenAI "https://github.com/ameeralns/deepresearchmcp/blob/main/src/services/openai.ts"
    click Types "https://github.com/ameeralns/deepresearchmcp/blob/main/src/types/index.ts"
    click Env "https://github.com/ameeralns/deepresearchmcp/blob/main/.env.example"
    click ClaudeCfg "https://github.com/ameeralns/deepresearchmcp/blob/main/claude_desktop_config_sample.json"
    click Package "https://github.com/ameeralns/deepresearchmcp/blob/main/package.json"
    click TSConfig "https://github.com/ameeralns/deepresearchmcp/blob/main/tsconfig.json"

    %% Styles
    classDef client fill:#ffffff,stroke:#666,stroke-width:2px;
    classDef internal fill:#b3e5fc,stroke:#0288d1,stroke-width:2px;
    classDef external fill:#ffe0b2,stroke:#fb8c00,stroke-dasharray: 5 5,stroke-width:2px;
    classDef config fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
```
