# sv/mcp-paradex-py architecture

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

- Interactive diagram: https://gitdiagram.com/sv/mcp-paradex-py
- Repository: https://github.com/sv/mcp-paradex-py

## Overview

##### Project Type & Purpose
- Type: A backend microservice (MCP server) written in Python 3.10+, packaged for CLI/Docker, exposing Model Context Protocol (MCP) endpoints.
- Purpose: Acts as a bridge between AI assistants (e.g., Claude) and the Paradex perpetual-futures trading platform, providing standardized “resource” and “tool” endpoints for market data, orders, accounts, vaults, and system health.

##### High-Level Components
a. Entry Point
- `__main__.py`: CLI launcher (via `uvx` or `python -m mcp_paradex`) that boots up the MCP server.
b. Configuration & Environment
- `.env.template` → `.env`: Holds Paradex API keys, environment (`testnet`/`mainnet`), etc.
- `src/mcp_paradex/utils/config.py`: Loads and validates env variables.
c. Core Server
- `src/mcp_paradex/server/server.py`: Instantiates the MCP framework, registers resources/tools, listens on STDIN/STDOUT.
d. Resources Layer (stateless request handlers)
- `src/mcp_paradex/resources/`
- market.py – market://public/...
- system.py – system://status, version, health
- vaults.py – vaults://list, balance, details
e. Tools Layer (actionable commands)
- `src/mcp_paradex/tools/`
- account.py, market.py, orders.py, system.py, vaults.py
- Implements higher-level operations (create order, cancel order, fetch account summary, etc.)
f. Paradex Client
- `src/mcp_paradex/utils/paradex_client.py`: Encapsulates HTTP/WebSocket calls to the Paradex API.
g. Models & Utilities
- `models.py`: Domain objects (Orders, Vaults, MarketData).
- `formatter.py`, `jmespath_utils.py`: Data transformation utilities.
h. Packaging & Deployment
- `pyproject.toml`, `Makefile`, `Dockerfile`: Build scripts, Docker image for containerized deployment.
- `smithery.yaml`: Metadata for Smithery.ai registry.
- GitHub Actions: `.github/workflows/build-test.yml` for CI/CD.

##### External Dependencies & Integrations
- AI Assistant (Claude Desktop) via MCP (STDIN/STDOUT or via Smithery.ai).
- Paradex Trading Platform (external HTTP/WebSocket API).
- Smithery.ai Registry (publish/discover the server).
- Optional: Docker Hub / Private Registry for container image.

##### Relationships & Data Flow
1. AI Assistant → (MCP Protocol) → Entry Point
- Commands arrive as MCP requests.
2. Server Framework → Dispatch → Resource/Tool Handlers
3. Handler → uses Paradex Client → external Paradex API
4. Response → formatted → returned over MCP protocol → AI Assistant
5. Configuration is read once at startup.
6. CI/CD pipeline tests code, builds Docker image, and optionally publishes to Smithery.ai.

##### Architectural Patterns & Principles
- Layered Architecture: Entry → Server → Handlers (Resources/Tools) → Client → External API
- Separation of Concerns:
- Resources: read-only data retrieval
- Tools: state-changing commands
- Utils: pure helper functions
- Twelve-factor app principles: config via environment, stateless handlers, explicit dependencies.

##### Final Checklist
[ ] Environment/config injection path
[ ] Registration flow (server → handlers)
[ ] External API integration path
[ ] Packaging/deployment artifacts (Docker, CI/CD, Smithery)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry & Server Layer
    subgraph "Entry & Server"
        Entry["Entry Point\n__main__.py"]:::entry
        ConfigLoader["Config Loader\nconfig.py"]:::entry
        Server["Core Server\nserver.py"]:::entry
    end

    %% Resource Handlers
    subgraph "Resource Handlers"
        MarketRes["Market Resource\nmarket.py"]:::resource
        SystemRes["System Resource\nsystem.py"]:::resource
        VaultsRes["Vaults Resource\nvaults.py"]:::resource
    end

    %% Tool Handlers
    subgraph "Tool Handlers"
        AcctTool["Account Tool\naccount.py"]:::tool
        MktTool["Market Tool\nmarket.py"]:::tool
        OrdersTool["Orders Tool\norders.py"]:::tool
        SysTool["System Tool\nsystem.py"]:::tool
        VaultsTool["Vaults Tool\nvaults.py"]:::tool
    end

    %% Utilities & Models
    subgraph "Utilities & Models"
        Models["Domain Models\nmodels.py"]:::util
        Formatter["Formatter\nformatter.py"]:::util
        JMES["JMESPath Utils\njmespath_utils.py"]:::util
    end

    %% Paradex Client
    ParadexClient["Paradex Client\nparadex_client.py"]:::client

    %% External Services
    subgraph "External Services"
        AIAssist["AI Assistant (Claude)"]:::external
        ParadexAPI["Paradex API\nHTTP/WebSocket"]:::external
        Smithery["Smithery.ai Registry"]:::external
    end

    %% Packaging & Deployment
    subgraph "Packaging & Deployment"
        PyProj["pyproject.toml"]:::pkg
        Dock["Dockerfile"]:::pkg
        CI["build-test.yml"]:::pkg
        SmithMeta["smithery.yaml"]:::pkg
        Make["Makefile"]:::pkg
        EnvT[".env.template"]:::pkg
    end

    %% Relationships
    AIAssist <-->|"MCP Request/Response"| Server
    EnvT -->|"Env Vars"| ConfigLoader
    ConfigLoader --> Server
    Server -->|"registers"| MarketRes
    Server -->|"registers"| SystemRes
    Server -->|"registers"| VaultsRes
    Server -->|"registers"| AcctTool
    Server -->|"registers"| MktTool
    Server -->|"registers"| OrdersTool
    Server -->|"registers"| SysTool
    Server -->|"registers"| VaultsTool
    MarketRes -->|"uses"| ParadexClient
    SystemRes -->|"uses"| ParadexClient
    VaultsRes -->|"uses"| ParadexClient
    AcctTool -->|"uses"| ParadexClient
    MktTool -->|"uses"| ParadexClient
    OrdersTool -->|"uses"| ParadexClient
    SysTool -->|"uses"| ParadexClient
    VaultsTool -->|"uses"| ParadexClient
    ParadexClient -->|"HTTP/WebSocket"| ParadexAPI
    Models -->|"used by"| MarketRes
    Models -->|"used by"| AcctTool
    Formatter -->|"transforms"| Server
    JMES -->|"transforms"| Server
    CI -->|"build/tests"| Dock
    CI -->|"publishes"| Smithery
    PyProj -->|"defines package"| Dock
    Make -->|"tasks"| CI

    %% Click Events
    click Entry "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/__main__.py"
    click ConfigLoader "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/utils/config.py"
    click Server "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/server/server.py"
    click MarketRes "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/resources/market.py"
    click SystemRes "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/resources/system.py"
    click VaultsRes "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/resources/vaults.py"
    click AcctTool "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/tools/account.py"
    click MktTool "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/tools/market.py"
    click OrdersTool "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/tools/orders.py"
    click SysTool "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/tools/system.py"
    click VaultsTool "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/tools/vaults.py"
    click ParadexClient "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/utils/paradex_client.py"
    click Models "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/models.py"
    click Formatter "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/utils/formatter.py"
    click JMES "https://github.com/sv/mcp-paradex-py/blob/main/src/mcp_paradex/utils/jmespath_utils.py"
    click PyProj "https://github.com/sv/mcp-paradex-py/blob/main/pyproject.toml"
    click Dock "https://github.com/sv/mcp-paradex-py/tree/main/Dockerfile"
    click CI "https://github.com/sv/mcp-paradex-py/blob/main/.github/workflows/build-test.yml"
    click SmithMeta "https://github.com/sv/mcp-paradex-py/blob/main/smithery.yaml"
    click Make "https://github.com/sv/mcp-paradex-py/tree/main/Makefile"
    click EnvT "https://github.com/sv/mcp-paradex-py/blob/main/.env.template"

    %% Styles
    classDef entry fill:#e0ffe0,stroke:#006600,stroke-width:2px;
    classDef resource fill:#e0f0ff,stroke:#0033cc,stroke-width:2px;
    classDef tool fill:#ffe8cc,stroke:#cc6600,stroke-width:2px;
    classDef util fill:#f0f0f0,stroke:#666666,stroke-width:2px;
    classDef client fill:#f4e1ff,stroke:#9933cc,stroke-width:2px;
    classDef external fill:#f5e6d3,stroke:#663300,stroke-width:2px;
    classDef pkg fill:#ffffff,stroke:#000000,stroke-width:1px,stroke-dasharray: 2 2;
    classDef default stroke:#000,stroke-width:1px;
```
