# ppl-ai/modelcontextprotocol architecture

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

- Interactive diagram: https://gitdiagram.com/ppl-ai/modelcontextprotocol
- Repository: https://github.com/ppl-ai/modelcontextprotocol

## Overview

##### Main Components
- MCP Server Application – This is implemented in TypeScript (index.ts) within the “perplexity-ask” directory. It is the core of the service that accepts “messages” arrays, interacts with the Sonar API, and exposes functionalities to Claude as a web research tool.
- Docker Container – The project provides a Dockerfile used to build an image (mcp/perplexity-ask) that packages the application for deployment and consistent execution.
- API Integration – The server makes calls to the Sonar API using the provided API key (set as PERPLEXITY_API_KEY in the environment). This external dependency is critical for the “live web search” functionality.
- Claude Desktop Integration – As specified in the README, Claude is configured (via a JSON config file) to interact with this MCP server (using either Docker or NPX execution). The communication setup, showing how Claude invokes this tool (with mcpServers configuration), is essential.

##### Relationships and Interactions
- Client (Claude Desktop) – This external client initiates a conversation by sending messages (each with a “role” and “content”) to the MCP server.
- MCP Server – Receives the messages, processes them (and possibly modifies search parameters via index.ts as needed), and then makes a REST/HTTP (or similar API) call to the Sonar API.
- Sonar API – Processes the search request and returns results that the server then forwards back to the Claude client.
- Deployment Pipeline – The Docker container is built (using the Dockerfile) and can be run either via Docker commands or through NPX. Environment variables (such as PERPLEXITY_API_KEY) are used to configure the server at runtime.

- Communication from Claude Desktop to the MCP Server.
- Outbound API calls from MCP Server to the Sonar API.
- Data flow from the Sonar API back to the MCP Server and then to Claude Desktop.
- The deployment process of building and running the service inside a Docker container.

##### Relevant Technologies/Frameworks
- Node.js / TypeScript – The MCP server is built using TypeScript (index.ts, tsconfig.json) and managed via Node’s npm packages (package.json).
- Docker – Utilized to containerize the application for a reliable deployment form.
- Sonar API – An external web-search API that powers the real-time research feature.
- Claude Desktop – Acts as the client that leverages the MCP server for integrated research.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Deployment Pipeline"
        DC["Docker Container (mcp/perplexity-ask image)"]:::container
        MPC["MCP Server (TypeScript Application)"]:::internal
        DC -->|"runs"| MPC
    end

    CD["Claude Desktop Client"]:::external
    API["Sonar API"]:::external
    ASSET["Assets & Visual Components"]:::config

    CD -->|"sends_messages"| MPC
    MPC -->|"calls_API"| API
    API -->|"returns_data"| MPC
    MPC -->|"sends_response"| CD

    MPC ---|"env:PERPLEXITY_API_KEY"| API
    MPC ---|"uses"| ASSET

    click MPC "https://github.com/ppl-ai/modelcontextprotocol/blob/main/perplexity-ask/index.ts"
    click DC "https://github.com/ppl-ai/modelcontextprotocol/tree/main/perplexity-ask/Dockerfile"
    click ASSET "https://github.com/ppl-ai/modelcontextprotocol/tree/main/perplexity-ask/assets"

    classDef internal fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef external fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef container fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef config fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
