# wysh3/perplexity-mcp-zerver architecture

> Architecture diagram of the GitHub repository wysh3/perplexity-mcp-zerver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wysh3/perplexity-mcp-zerver
- Repository: https://github.com/wysh3/perplexity-mcp-zerver

## Overview

##### Project Type and Purpose
- This is a Node.js/TypeScript-based server implementation that serves as an MCP (Model Context Protocol) server.
- Its main purpose is to provide AI-powered research capabilities by interacting with the Perplexity website (via Puppeteer for browser automation), delivering tools like search, documentation retrieval, API discovery, deprecation analysis, URL content extraction, and chat functionality.
- The server is designed to be integrated with MCP clients (e.g., VS Code extensions or desktop applications like Claude Desktop) through a configuration file.

##### File Structure
- Top-level files such as .gitignore, LICENSE.md, README.md, package.json, and tsconfig.json set up the project environment.
- The core logic is found in the “src” directory with a single entry point (index.ts). This indicates that most functionality is likely imported or internally defined within this file or as additional modules (even if they are not split into separate directories, the different tools as explained in the README suggest modular functionality).
- There are no separate front-end or extensive multi-layer directories; the design is modular within one core server file.

##### Key Components
- Client/Integration Layer:
- MCP Clients (e.g., VS Code extension (Cline/RooCode), Claude Desktop) that call the server.
- Server Core:
- The entry point (index.ts) that initializes the server.
- An internal routing and command processing layer that receives MCP requests and maps them to the relevant tool.
- Tools/Modules:
- Search Module: Handles various search requests (brief, normal, detailed) interacting with Perplexity’s web interface.
- Documentation Retrieval Module (“get_documentation”): Fetches documentation and examples.
- API Finder Module (“find_apis”): Queries for APIs using provided requirements.
- Code Analysis Module (“check_deprecated_code”): Analyzes code for deprecated features.
- URL Content Extraction Module (“extract_url_content”): Uses Puppeteer combined with Mozilla’s Readability to obtain structured JSON output.
- Chat Module (“chat_perplexity”): Manages chat sessions and maintains a persistent chat history stored in a local file (chat_history.db).
- External Services and Integrations:
- Perplexity Website: The external website that is queried via browser automation.
- Puppeteer: The tool for controlling headless Chromium instances.
- Local Chat History File: Represents the persistence store (chat_history.db) for chat conversations.

##### Relationships and Interactions
- MCP Clients make requests that are routed into the server’s main entry point.
- The server interprets these requests and forwards them to the appropriate internal module.
- The Chat module both receives user requests and writes/reads its state from the local chat_history.db.
- Once the modules complete their operations, the results are sent back up to the client in a structured response (typically a stringified JSON object).

##### Architectural Patterns and Technologies
- Use of a centralized server process (the Node.js application) that routes commands based on the MCP request – a common Command pattern.
- Use of Puppeteer for external interactions.
- That the project leans on modularity (each “tool” or command acts as a separate responsibility even if all code is bundled in a small codebase).
- Mention the TypeScript-first implementation, reinforcing type safety in communication between the components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/Integration Layer
    subgraph "Client/Integration Layer"
        client1["MCP Client (VS Code Extension)"]:::client
        client2["MCP Client (Claude Desktop)"]:::client
    end

    %% Server Core
    subgraph "Server Core"
        server["Server (index.ts)"]:::server
    end

    %% Internal Modules
    subgraph "Internal Modules"
        search["Search Module"]:::module
        doc["Documentation Module (get_documentation)"]:::module
        api["API Finder Module (find_apis)"]:::module
        code["Code Analysis Module (check_deprecated_code)"]:::module
        urlExt["URL Content Extraction Module (extract_url_content)"]:::module
        chat["Chat Module (chat_perplexity)"]:::module
    end

    %% External Service: Browser Automation
    externalNode["Puppeteer & Perplexity Website"]:::external

    %% Storage: Chat History Persistence
    storage["Local Chat History (chat_history.db)"]:::storage

    %% Data Flow Connections
    client1 -->|"request"| server
    client2 -->|"request"| server

    server -->|"routesTo"| search
    server -->|"routesTo"| doc
    server -->|"routesTo"| api
    server -->|"routesTo"| code
    server -->|"routesTo"| urlExt
    server -->|"routesTo"| chat

    search -->|"invokes"| externalNode
    doc -->|"invokes"| externalNode
    api -->|"invokes"| externalNode
    code -->|"invokes"| externalNode
    urlExt -->|"invokes"| externalNode

    chat -->|"readsWrites"| storage

    %% Click Events
    click server "https://github.com/wysh3/perplexity-mcp-zerver/blob/main/src/index.ts"

    %% Styles
    classDef client fill:#f4d03f,stroke:#000,stroke-width:2px;
    classDef server fill:#85c1e9,stroke:#000,stroke-width:2px;
    classDef module fill:#a3e4d7,stroke:#000,stroke-width:2px;
    classDef external fill:#f1948a,stroke:#000,stroke-width:2px;
    classDef storage fill:#82e0aa,stroke:#000,stroke-width:2px;
```
