# jsonallen/perplexity-mcp architecture

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

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

## Overview

##### Project type and purpose
- This is a small, single-service MCP (Model Context Protocol) server written in Python.
- Its purpose is to expose one “tool” (perplexity_search_web) via the MCP protocol so that Claude Desktop (or Cursor) can call it. Under the hood, it forwards queries to Perplexity AI’s HTTP API and returns results.

##### File structure
- Top‐level files:
- Dockerfile / smithery.yaml – deployment/config metadata
- pyproject.toml – Python packaging and dependencies
- README.md – describes the server’s function and integration points
- src/perplexity_mcp/server.py – the only runtime code, implementing an MCP‐compatible HTTP or IPC server

##### README for additional insights
- The server registers one prompt/tool (perplexity_search_web).
- It reads environment variables (PERPLEXITY_API_KEY, PERPLEXITY_MODEL).
- It integrates via two clients: Cursor (desktop) and Claude Desktop, both speaking MCP JSON over a local command or HTTP endpoint.
- Installation via Smithery/uv shows how it’s launched (uvx perplexity-mcp).

##### Main components
a. Client(s)
- Claude Desktop (or Cursor) – initiates an MCP request
- Configuration file (cursor_mcp.json or claude_desktop_config.json) – holds env vars and launch command
b. MCP Server
- Python process (server.py)
- Reads env vars, listens for MCP JSON calls on stdin/stdout or HTTP port
- Uses uvx/uv as the entrypoint
c. External Service
- Perplexity AI HTTP API – receives search queries with API key, returns JSON results
d. Optional Deployment
- Docker container / smithery-managed deployment

##### Relationships and data flow
1. Client loads config → spawns uvx perplexity-mcp process
2. Claude/ Cursor sends a JSON‐RPC tool call (`perplexity_search_web`) to server
3. Server parses arguments (query + recency) and env vars
4. Server issues HTTPS request to Perplexity API with API key
5. Perplexity responds with search results
6. Server wraps results in MCP response JSON, returns to client
7. Client displays results in the chat UI

##### Architectural patterns and design principles
- Plugin-style microservice: the server is a standalone process that plugs into multiple clients
- 12-factor config: uses environment variables for credentials and model choice
- Minimal surface area: only one tool, one endpoint, no persisted state
- Clear separation between protocol (MCP), business logic (Perplexity API wrapper), and deployment

##### Relevant technologies, frameworks, and libraries
- Python 3.x
- uv/uvx – fast Python package runner
- HTTP(S) + JSON for external API calls
- MCP JSON over stdio or HTTP for client integration
- Docker (optional)
- Smithery (optional CLI installer)

- Component is labeled
- How configuration flows into the server (env vars)
- That server.py is the core implementation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client"
        direction TB
        Config["Config File\n(cursor_mcp.json / claude_desktop_config.json)"]:::config
        ClientApp["Claude Desktop / Cursor"]:::client
    end

    %% Server Layer
    subgraph "MCP Server"
        direction TB
        Entrypoint["uvx/perplexity-mcp\n(entrypoint)"]:::server
        EnvVars["Env Vars:\nPERPLEXITY_API_KEY\nPERPLEXITY_MODEL"]:::server
        Package["src/perplexity_mcp/"]:::server
        ServerCore["server.py"]:::server
    end

    %% External Service
    External["Perplexity AI HTTP API"]:::external

    %% Deployment Layer
    subgraph "Deployment & Repo"
        direction TB
        DockerfileNode["Dockerfile"]:::deployment
        Smithery["smithery.yaml"]:::deployment
        PyProject["pyproject.toml"]:::deployment
        README["README.md"]:::deployment
        Gitignore[".gitignore"]:::deployment
    end

    %% Connections
    Config -->|loads config and spawns| ClientApp
    ClientApp -->|spawns process| Entrypoint
    Entrypoint -->|invokes| ServerCore
    EnvVars -->|injected into| ServerCore
    Package -->|contains| ServerCore
    ServerCore -->|HTTPS + JSON| External
    External -->|JSON results| ServerCore
    ServerCore -->|MCP JSON response| ClientApp

    %% Click Events
    click ServerCore "https://github.com/jsonallen/perplexity-mcp/blob/main/src/perplexity_mcp/server.py"
    click Package "https://github.com/jsonallen/perplexity-mcp/tree/main/src/perplexity_mcp/"
    click DockerfileNode "https://github.com/jsonallen/perplexity-mcp/tree/main/Dockerfile"
    click Smithery "https://github.com/jsonallen/perplexity-mcp/blob/main/smithery.yaml"
    click PyProject "https://github.com/jsonallen/perplexity-mcp/blob/main/pyproject.toml"
    click README "https://github.com/jsonallen/perplexity-mcp/blob/main/README.md"
    click Gitignore "https://github.com/jsonallen/perplexity-mcp/blob/main/.gitignore"

    %% Styles
    classDef client fill:#D0E6FF,stroke:#0055CC,color:#000
    classDef server fill:#D0FFD6,stroke:#00AA00,color:#000
    classDef external fill:#FFE0B3,stroke:#FF8000,color:#000
    classDef config fill:#F2F2F2,stroke:#AAAAAA,color:#000
    classDef deployment fill:#F3E5F5,stroke:#9C27B0,color:#000
```
