Perplexity Interaction Module (PIM)

This module presents a Pythonic conduit to the advanced capabilities of the Perplexity API, furnishing functionality for issuing queries, sustaining dialogue context, and administering interaction transcripts. Configuration of the underlying AI model is managed via environment variables, and all conversation artifacts are durably stored locally.

The PIM is engineered to replicate the user experience found within the standard Perplexity web interface, empowering autonomous agents to pose inquiries, iteratively refine ongoing discussions, and enumerate existing chat sessions.

Integrated Capabilities (Tools)

execute_expert_query: Invokes the Perplexity engine for specialized technical guidance. Optimized for generating programming snippets, diagnosing runtime errors, and providing detailed technical breakdowns. Output incorporates source attribution and potential alternative approaches.
maintain_dialogue_flow: Orchestrates continuous interactions with the Perplexity intelligence core. It either initiates a novel conversational thread or seamlessly resumes a prior one, retaining the full context history. Returns a unique identifier for subsequent message injection.
enumerate_sessions: Fetches and presents a registry of all currently stored conversational threads. Output details the session identifier, a brief subject descriptor, and the elapsed time since creation (e.g., "1 hr ago"). Pagination is enforced, limiting results to 50 records per page.
retrieve_session_log: Fetches the comprehensive message sequence for a designated session identifier. Crucially, this operation exclusively reads from the local persistence layer; no external API calls are initiated.

Principal Attributes

Dynamic Model Specification: The operational model can be dictated by setting the PERPLEXITY_MODEL environment variable. Furthermore, distinct models can be assigned to specific functions using PERPLEXITY_MODEL_ASK and PERPLEXITY_MODEL_CHAT.

These granular settings supersede the base PERPLEXITY_MODEL. Consult the Perplexity documentation for model availability. - Contextual Memory: The maintain_dialogue_flow function ensures ongoing interactions retain prior context via session IDs, critical for complex, multi-turn problem-solving. - Latency Mitigation: Implements response streaming along with feedback reporting mechanisms to effectively counteract connection timeouts during protracted data retrieval.

Initialization Procedure

Pre-requisites

Ensure the environment satisfies these dependencies:

Python version 3.10 or newer
The uvx package manager (installation guidance available here)

Client Configuration Template

Clients must interface with the server using the following configuration structure (adjusting the method based on the client application):

"mcpServers": { "mcp-perplexity": { "command": "uvx", "args": ["mcp-perplexity"], "env": { "PERPLEXITY_API_KEY": "your-api-key", "PERPLEXITY_MODEL": "sonar-pro", "DB_PATH": "chats.db" } } }

Operational Environment Variables

Configuration parameters for the Perplexity PIM:

Variable	Purpose	Default	Mandatory
`PERPLEXITY_API_KEY`	Access credential for the API	None	Yes
`PERPLEXITY_MODEL`	Default model designation	`sonar-pro`	No
`PERPLEXITY_MODEL_ASK`	Model override for query tool	Inherits base	No
`PERPLEXITY_MODEL_CHAT`	Model override for dialogue tool	Inherits base	No
`DB_PATH`	Location for persistent session logs	`chats.db`	No
`WEB_UI_ENABLED`	Toggle for the auxiliary web portal	`false`	No
`WEB_UI_PORT`	TCP port for the web interface	`8050`	No
`WEB_UI_HOST`	Network interface binding for the web interface	`127.0.0.1`	No
`DEBUG_LOGS`	Activate verbose operational logging	`false`	No

Invocation via Smithery CLI

bash npx -y @smithery/cli@latest run @daniel-lxs/mcp-perplexity --config "{"perplexityApiKey":"pplx-abc","perplexityModel":"sonar-pro"}"

Tool Utilization Guide

execute_expert_query

This function is designed for atomic, single-turn problem resolution; it does not inherit past conversation context.

The model utilized will be PERPLEXITY_MODEL_ASK if explicitly set, otherwise it defaults to PERPLEXITY_MODEL.

maintain_dialogue_flow

This function facilitates ongoing, stateful interactions, relying on a session identifier (e.g., swift-river-45) generated upon chat initiation.

This is the preferred method for extended debugging sessions or iterative research tasks.

The model employed will be PERPLEXITY_MODEL_CHAT if specified, otherwise falling back to PERPLEXITY_MODEL.

enumerate_sessions

Retrieves a temporally ordered, paged manifest of all saved exchanges. Arguments allow specifying the desired page number (starting at 1, max 50 entries).

retrieve_session_log

Fetches the complete, timestamped sequence of exchanges for a given session ID. Note: This function operates solely on local disk storage; no network communication with Perplexity occurs during this retrieval.

Auxiliary Web Interface

A companion web portal is bundled with this server for streamlined session administration and interaction, activated when WEB_UI_ENABLED is set to true.

Interface Highlights

Interactive prompt/response console
Comprehensive history management tools
Live message rendering

Visual Previews

Session Roster View

Dialogue Console

Access Details

The interface binds to http://WEB_UI_HOST:WEB_UI_PORT by default, resolving to http://127.0.0.1:8050.

Development Workflow

This package relies on setuptools for its build and packaging infrastructure.

Environment Setup: bash python -m venv .venv source .venv/bin/activate # Unix-like systems .venv\Scripts\activate # Windows
Install in Editable Mode (including dependencies): bash pip install -e .
Package Creation: bash python -m build