How sv/mcp-paradex-py works
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)