@perplexity-ai/mcp-server 0.5.1 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official Perplexity AI plugin providing real-time web search, reasoning, and research capabilities",
-    "version": "0.5.1"
+    "version": "0.6.0"
   },
   "plugins": [
     {
       "name": "perplexity",
       "source": "./",
       "description": "Real-time web search, reasoning, and research through Perplexity's API",
-      "version": "0.5.1",
+      "version": "0.6.0",
       "author": {
         "name": "Perplexity AI",
         "email": "api@perplexity.ai"

package/README.md

@@ -1,8 +1,8 @@
 # Perplexity API Platform MCP Server
 
-[![Install in Cursor](https://custom-icon-badges.demolab.com/badge/Install_in_Cursor-000000?style=for-the-badge&logo=cursor-ai-white)](https://cursor.com/en/install-mcp?name=perplexity&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwZXJwbGV4aXR5LWFpL21jcC1zZXJ2ZXIiXX0=)
+[![Install in Cursor](https://custom-icon-badges.demolab.com/badge/Install_in_Cursor-000000?style=for-the-badge&logo=cursor-ai-white)](https://cursor.com/en/install-mcp?name=perplexity&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwZXJwbGV4aXR5LWFpL21jcC1zZXJ2ZXIiXSwiZW52Ijp7IlBFUlBMRVhJVFlfQVBJX0tFWSI6IiJ9fQ==)
  
-[![Install in VS Code](https://custom-icon-badges.demolab.com/badge/Install_in_VS_Code-007ACC?style=for-the-badge&logo=vsc&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=perplexity&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40perplexity-ai%2Fmcp-server%22%5D%7D)
+[![Install in VS Code](https://custom-icon-badges.demolab.com/badge/Install_in_VS_Code-007ACC?style=for-the-badge&logo=vsc&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=perplexity&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40perplexity-ai%2Fmcp-server%22%5D%2C%22env%22%3A%7B%22PERPLEXITY_API_KEY%22%3A%22%22%7D%7D)
  
 [![npm version](https://img.shields.io/npm/v/%40perplexity-ai%2Fmcp-server?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@perplexity-ai/mcp-server)
 
@@ -13,7 +13,7 @@ The official MCP server implementation for the Perplexity API Platform, providin
 ### **perplexity_search**
 Direct web search using the Perplexity Search API. Returns ranked search results with metadata, perfect for finding current information.
 
-### **perplexity_ask** 
+### **perplexity_ask**
 General-purpose conversational AI with real-time web search using the `sonar-pro` model. Great for quick questions and everyday searches.
 
 ### **perplexity_research**
@@ -30,60 +30,37 @@ Advanced reasoning and problem-solving using the `sonar-reasoning-pro` model. Pe
 ## Configuration
 
 ### Get Your API Key
+
 1. Get your Perplexity API Key from the [API Portal](https://www.perplexity.ai/account/api/group)
-2. Set it as an environment variable: `PERPLEXITY_API_KEY=your_key_here`
-3. (Optional) Set a timeout for requests: `PERPLEXITY_TIMEOUT_MS=600000`. The default is 5 minutes.
+2. Replace `your_key_here` in the configurations below with your API key
+3. (Optional) Set timeout: `PERPLEXITY_TIMEOUT_MS=600000` (default: 5 minutes)
+4. (Optional) Set log level: `PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR` (default: ERROR)
 
 ### Claude Code
 
-#### Option 1: Install via Plugin (Recommended)
-
-The easiest way to get started with Perplexity in Claude Code, set your API key:
-```bash
-export PERPLEXITY_API_KEY="your_key_here"
-```
-Then:
 ```bash
-# Open Claude Code
-claude
-
-# Add the Perplexity marketplace
-/plugin marketplace add perplexityai/modelcontextprotocol
-
-# Install the plugin
-/plugin install perplexity
+claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server
 ```
 
-#### Option 2: Manual Configuration
-
-Run in your terminal:
-
+Or install via plugin:
 ```bash
-claude mcp add perplexity --transport stdio --env PERPLEXITY_API_KEY=your_key_here -- npx -y perplexity-mcp
+export PERPLEXITY_API_KEY="your_key_here"
+claude
+# Then run: /plugin marketplace add perplexityai/modelcontextprotocol
+# Then run: /plugin install perplexity
 ```
 
-Or add to your `claude.json`:
+### Cursor, Claude Desktop & Windsurf
 
-```json
-"mcpServers": {
-  "perplexity": {
-    "type": "stdio",
-    "command": "npx",
-    "args": [
-      "-y",
-      "perplexity-mcp"
-    ],
-    "env": {
-      "PERPLEXITY_API_KEY": "your_key_here",
-      "PERPLEXITY_TIMEOUT_MS": "600000"
-    }
-  }
-}
-```
+We recommend using the one-click install badge at the top of this README for Cursor.
 
-### Cursor / VS Code
+For manual setup, all these clients use the same `mcpServers` format:
 
-Add to your `mcp.json` (Cursor) or `.vscode/mcp.json` (VS Code):
+| Client | Config File |
+|--------|-------------|
+| Cursor | `~/.cursor/mcp.json` |
+| Claude Desktop | `claude_desktop_config.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
 
 ```json
 {
@@ -92,51 +69,42 @@ Add to your `mcp.json` (Cursor) or `.vscode/mcp.json` (VS Code):
       "command": "npx",
       "args": ["-y", "@perplexity-ai/mcp-server"],
       "env": {
-        "PERPLEXITY_API_KEY": "your_key_here",
-        "PERPLEXITY_TIMEOUT_MS": "600000"
+        "PERPLEXITY_API_KEY": "your_key_here"
       }
     }
   }
 }
 ```
 
-Or use the one-click install badges at the top of this README.
-
-### Codex
+### VS Code
 
-Run in your terminal:
-
-```bash
-codex mcp add perplexity --env PERPLEXITY_API_KEY=your_key_here -- npx -y @perplexity-ai/mcp-server
-```
-
-### Claude Desktop
-
-Add to your `claude_desktop_config.json`:
+We recommend using the one-click install badge at the top of this README for VS Code, or for manual setup, add to `.vscode/mcp.json`:
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "perplexity": {
+      "type": "stdio",
       "command": "npx",
       "args": ["-y", "@perplexity-ai/mcp-server"],
       "env": {
-        "PERPLEXITY_API_KEY": "your_key_here",
-        "PERPLEXITY_TIMEOUT_MS": "600000"
+        "PERPLEXITY_API_KEY": "your_key_here"
       }
     }
   }
 }
 ```
 
-### Other MCP Clients
-
-For any MCP-compatible client, use:
+### Codex
 
 ```bash
-npx @perplexity-ai/mcp-server
+codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server
 ```
 
+### Other MCP Clients
+
+Most clients can be manually configured to use the `mcpServers` wrapper in their configuration file (like Cursor). If your client doesn't work, check its documentation for the correct wrapper format.
+
 ### Proxy Setup (For Corporate Networks)
 
 If you are running this server at work—especially behind a company firewall or proxy—you may need to tell the program how to send its internet traffic through your network's proxy. Follow these steps:
@@ -168,39 +136,34 @@ If you'd rather use the standard variables, we support `HTTPS_PROXY` and `HTTP_P
 > The server checks proxy settings in this order: `PERPLEXITY_PROXY` → `HTTPS_PROXY` → `HTTP_PROXY`. If none are set, it connects directly to the internet.
 > URLs must include `https://`. Typical ports are `8080`, `3128`, and `80`.
 
-
 ### HTTP Server Deployment
 
-For cloud or shared deployments, you can run the server in HTTP mode:
+For cloud or shared deployments, run the server in HTTP mode.
 
 #### Environment Variables
 
-The HTTP server supports these configuration options:
-
-- **`PORT`** - HTTP server port (default: `8080`)
-- **`BIND_ADDRESS`** - Network interface to bind to (default: `127.0.0.1` for local, use `0.0.0.0` for hosted)
-- **`ALLOWED_ORIGINS`** - Comma-separated list of allowed CORS origins (default: `http://localhost:3000,http://127.0.0.1:3000`, use `*` for public service)
-- **`PERPLEXITY_API_KEY`** - Your Perplexity API key (required)
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PERPLEXITY_API_KEY` | Your Perplexity API key | *Required* |
+| `PORT` | HTTP server port | `8080` |
+| `BIND_ADDRESS` | Network interface to bind to | `0.0.0.0` |
+| `ALLOWED_ORIGINS` | CORS origins (comma-separated) | `*` |
 
-#### Using Docker
+#### Docker
 
 ```bash
 docker build -t perplexity-mcp-server .
 docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server
 ```
 
-The server will be accessible at `http://localhost:8080/mcp`
-
-#### Using Node.js Directly
+#### Node.js
 
 ```bash
-npm install
-npm run build
-npm run start:http
+export PERPLEXITY_API_KEY=your_key_here
+npm install && npm run build && npm run start:http
 ```
 
-Connect your MCP client to: `http://localhost:8080/mcp`
-
+The server will be accessible at `http://localhost:8080/mcp`
 
 ## Troubleshooting
 
@@ -209,6 +172,7 @@ Connect your MCP client to: `http://localhost:8080/mcp`
 - **Tool Not Found**: Make sure the package is installed and the command path is correct
 - **Timeout Errors**: For very long research queries, set `PERPLEXITY_TIMEOUT_MS` to a higher value
 - **Proxy Issues**: Verify your `PERPLEXITY_PROXY` or `HTTPS_PROXY` setup and ensure `api.perplexity.ai` isn't blocked by your firewall.
+- **EOF / Initialize Errors**: Some strict MCP clients fail because `npx` writes installation messages to stdout. Use `npx -yq` instead of `npx -y` to suppress this output.
 
 For support, visit [community.perplexity.ai](https://community.perplexity.ai) or [file an issue](https://github.com/perplexityai/modelcontextprotocol/issues).
 

package/dist/http.js

@@ -3,19 +3,16 @@ import express from "express";
 import cors from "cors";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { createPerplexityServer } from "./server.js";
-// Check for required API key
+import { logger } from "./logger.js";
 const PERPLEXITY_API_KEY = process.env.PERPLEXITY_API_KEY;
 if (!PERPLEXITY_API_KEY) {
-    console.error("Error: PERPLEXITY_API_KEY environment variable is required");
+    logger.error("PERPLEXITY_API_KEY environment variable is required");
     process.exit(1);
 }
 const app = express();
 const PORT = parseInt(process.env.PORT || "8080", 10);
-const BIND_ADDRESS = process.env.BIND_ADDRESS || "127.0.0.1";
-const ALLOWED_ORIGINS = process.env.ALLOWED_ORIGINS?.split(",") || [
-    "http://localhost:3000",
-    "http://127.0.0.1:3000",
-];
+const BIND_ADDRESS = process.env.BIND_ADDRESS || "0.0.0.0";
+const ALLOWED_ORIGINS = process.env.ALLOWED_ORIGINS?.split(",") || ["*"];
 // CORS configuration for browser-based MCP clients
 app.use(cors({
     origin: (origin, callback) => {
@@ -36,10 +33,6 @@ app.use(cors({
 }));
 app.use(express.json());
 const mcpServer = createPerplexityServer();
-/**
- * POST: client-to-server messages (requests, responses, notifications)
- * GET: SSE stream for server-to-client messages (notifications, requests)
- */
 app.all("/mcp", async (req, res) => {
     try {
         const transport = new StreamableHTTPServerTransport({
@@ -53,7 +46,7 @@ app.all("/mcp", async (req, res) => {
         await transport.handleRequest(req, res, req.body);
     }
     catch (error) {
-        console.error("Error handling MCP request:", error);
+        logger.error("Error handling MCP request", { error: String(error) });
         if (!res.headersSent) {
             res.status(500).json({
                 jsonrpc: "2.0",
@@ -63,19 +56,13 @@ app.all("/mcp", async (req, res) => {
         }
     }
 });
-/**
- * Health check endpoint
- */
 app.get("/health", (req, res) => {
     res.json({ status: "ok", service: "perplexity-mcp-server" });
 });
-/**
- * Start the HTTP server
- */
 app.listen(PORT, BIND_ADDRESS, () => {
-    console.log(`Perplexity MCP Server listening on http://${BIND_ADDRESS}:${PORT}/mcp`);
-    console.log(`Allowed origins: ${ALLOWED_ORIGINS.join(", ")}`);
+    logger.info(`Perplexity MCP Server listening on http://${BIND_ADDRESS}:${PORT}/mcp`);
+    logger.info(`Allowed origins: ${ALLOWED_ORIGINS.join(", ")}`);
 }).on("error", (error) => {
-    console.error("Server error:", error);
+    logger.error("Server error", { error: String(error) });
     process.exit(1);
 });

package/dist/index.js

@@ -1,19 +1,14 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createPerplexityServer } from "./server.js";
-// Check for required API key
 const PERPLEXITY_API_KEY = process.env.PERPLEXITY_API_KEY;
 if (!PERPLEXITY_API_KEY) {
     console.error("Error: PERPLEXITY_API_KEY environment variable is required");
     process.exit(1);
 }
-/**
- * Initializes and runs the server using standard I/O for communication.
- * Logs an error and exits if the server fails to start.
- */
 async function main() {
     try {
-        const server = createPerplexityServer();
+        const server = createPerplexityServer("local-mcp");
         const transport = new StdioServerTransport();
         await server.connect(transport);
     }
@@ -22,7 +17,6 @@ async function main() {
         process.exit(1);
     }
 }
-// Start the server and catch any startup errors
 main().catch((error) => {
     console.error("Fatal error running server:", error);
     process.exit(1);

package/dist/logger.js

@@ -0,0 +1,82 @@
+/**
+ * Simple structured logger for the Perplexity MCP Server
+ * Outputs to stderr to avoid interfering with STDIO transport
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+})(LogLevel || (LogLevel = {}));
+const LOG_LEVEL_NAMES = {
+    [LogLevel.DEBUG]: "DEBUG",
+    [LogLevel.INFO]: "INFO",
+    [LogLevel.WARN]: "WARN",
+    [LogLevel.ERROR]: "ERROR",
+};
+/**
+ * Gets the configured log level from environment variable
+ * Defaults to ERROR to minimize noise in production
+ */
+function getLogLevel() {
+    const level = process.env.PERPLEXITY_LOG_LEVEL?.toUpperCase();
+    switch (level) {
+        case "DEBUG":
+            return LogLevel.DEBUG;
+        case "INFO":
+            return LogLevel.INFO;
+        case "WARN":
+            return LogLevel.WARN;
+        case "ERROR":
+            return LogLevel.ERROR;
+        default:
+            return LogLevel.ERROR;
+    }
+}
+const currentLogLevel = getLogLevel();
+function safeStringify(obj) {
+    try {
+        return JSON.stringify(obj);
+    }
+    catch {
+        return "[Unstringifiable]";
+    }
+}
+/**
+ * Formats a log message with timestamp and level
+ */
+function formatMessage(level, message, meta) {
+    const timestamp = new Date().toISOString();
+    const levelName = LOG_LEVEL_NAMES[level];
+    if (meta && Object.keys(meta).length > 0) {
+        return `[${timestamp}] ${levelName}: ${message} ${safeStringify(meta)}`;
+    }
+    return `[${timestamp}] ${levelName}: ${message}`;
+}
+/**
+ * Logs a message if the configured log level allows it
+ */
+function log(level, message, meta) {
+    if (level >= currentLogLevel) {
+        const formatted = formatMessage(level, message, meta);
+        console.error(formatted); // Use stderr to avoid interfering with STDIO
+    }
+}
+/**
+ * Structured logger interface
+ */
+export const logger = {
+    debug(message, meta) {
+        log(LogLevel.DEBUG, message, meta);
+    },
+    info(message, meta) {
+        log(LogLevel.INFO, message, meta);
+    },
+    warn(message, meta) {
+        log(LogLevel.WARN, message, meta);
+    },
+    error(message, meta) {
+        log(LogLevel.ERROR, message, meta);
+    },
+};

package/dist/server.js

@@ -1,54 +1,28 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { fetch as undiciFetch, ProxyAgent } from "undici";
-// Retrieve the Perplexity API key from environment variables
+import { ChatCompletionResponseSchema, SearchResponseSchema } from "./validation.js";
 const PERPLEXITY_API_KEY = process.env.PERPLEXITY_API_KEY;
-/**
- * Gets the proxy URL from environment variables.
- * Checks PERPLEXITY_PROXY, HTTPS_PROXY, HTTP_PROXY in order.
- *
- * @returns {string | undefined} The proxy URL if configured, undefined otherwise
- */
-function getProxyUrl() {
+export function getProxyUrl() {
     return process.env.PERPLEXITY_PROXY ||
         process.env.HTTPS_PROXY ||
         process.env.HTTP_PROXY ||
         undefined;
 }
-/**
- * Creates a proxy-aware fetch function.
- * Uses undici with ProxyAgent when a proxy is configured, otherwise uses native fetch.
- *
- * @param {string} url - The URL to fetch
- * @param {RequestInit} options - Fetch options
- * @returns {Promise<Response>} The fetch response
- */
-async function proxyAwareFetch(url, options = {}) {
+export async function proxyAwareFetch(url, options = {}) {
     const proxyUrl = getProxyUrl();
     if (proxyUrl) {
-        // Use undici with ProxyAgent when proxy is configured
         const proxyAgent = new ProxyAgent(proxyUrl);
-        const response = await undiciFetch(url, {
+        const undiciOptions = {
             ...options,
             dispatcher: proxyAgent,
-        });
-        // Cast to native Response type for compatibility
+        };
+        const response = await undiciFetch(url, undiciOptions);
         return response;
     }
-    else {
-        // Use native fetch when no proxy is configured
-        return fetch(url, options);
-    }
+    return fetch(url, options);
 }
-/**
- * Validates an array of message objects for chat completion tools.
- * Ensures each message has a valid role and content field.
- *
- * @param {any} messages - The messages to validate
- * @param {string} toolName - The name of the tool calling this validation (for error messages)
- * @throws {Error} If messages is not an array or if any message is invalid
- */
-function validateMessages(messages, toolName) {
+export function validateMessages(messages, toolName) {
     if (!Array.isArray(messages)) {
         throw new Error(`Invalid arguments for ${toolName}: 'messages' must be an array`);
     }
@@ -65,33 +39,15 @@ function validateMessages(messages, toolName) {
         }
     }
 }
-/**
- * Strips thinking tokens (content within <think>...</think> tags) from the response.
- * This helps reduce context usage when the thinking process is not needed.
- *
- * @param {string} content - The content to process
- * @returns {string} The content with thinking tokens removed
- */
-function stripThinkingTokens(content) {
+export function stripThinkingTokens(content) {
     return content.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
 }
-/**
- * Performs a chat completion by sending a request to the Perplexity API.
- * Appends citations to the returned message content if they exist.
- *
- * @param {Array<{ role: string; content: string }>} messages - An array of message objects.
- * @param {string} model - The model to use for the completion.
- * @param {boolean} stripThinking - If true, removes <think>...</think> tags from the response.
- * @returns {Promise<string>} The chat completion result with appended citations.
- * @throws Will throw an error if the API request fails.
- */
-export async function performChatCompletion(messages, model = "sonar-pro", stripThinking = false) {
+export async function performChatCompletion(messages, model = "sonar-pro", stripThinking = false, serviceOrigin) {
     if (!PERPLEXITY_API_KEY) {
         throw new Error("PERPLEXITY_API_KEY environment variable is required");
     }
     // Read timeout fresh each time to respect env var changes
     const TIMEOUT_MS = parseInt(process.env.PERPLEXITY_TIMEOUT_MS || "300000", 10);
-    // Construct the API endpoint URL and request body
     const url = new URL("https://api.perplexity.ai/chat/completions");
     const body = {
         model: model,
@@ -101,12 +57,16 @@ export async function performChatCompletion(messages, model = "sonar-pro", strip
     const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
     let response;
     try {
+        const headers = {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${PERPLEXITY_API_KEY}`,
+        };
+        if (serviceOrigin) {
+            headers["X-Service"] = serviceOrigin;
+        }
         response = await proxyAwareFetch(url.toString(), {
             method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "Authorization": `Bearer ${PERPLEXITY_API_KEY}`,
-            },
+            headers,
             body: JSON.stringify(body),
             signal: controller.signal,
         });
@@ -119,7 +79,6 @@ export async function performChatCompletion(messages, model = "sonar-pro", strip
         }
         throw new Error(`Network error while calling Perplexity API: ${error}`);
     }
-    // Check for non-successful HTTP status
     if (!response.ok) {
         let errorText;
         try {
@@ -130,29 +89,28 @@ export async function performChatCompletion(messages, model = "sonar-pro", strip
         }
         throw new Error(`Perplexity API error: ${response.status} ${response.statusText}\n${errorText}`);
     }
-    // Attempt to parse the JSON response from the API
     let data;
     try {
-        data = await response.json();
-    }
-    catch (jsonError) {
-        throw new Error(`Failed to parse JSON response from Perplexity API: ${jsonError}`);
+        const json = await response.json();
+        data = ChatCompletionResponseSchema.parse(json);
     }
-    // Validate response structure
-    if (!data.choices || !Array.isArray(data.choices) || data.choices.length === 0) {
-        throw new Error("Invalid API response: missing or empty choices array");
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const issues = error.issues;
+            if (issues.some(i => i.path.includes('message') || i.path.includes('content'))) {
+                throw new Error("Invalid API response: missing message content");
+            }
+            if (issues.some(i => i.path.includes('choices'))) {
+                throw new Error("Invalid API response: missing or empty choices array");
+            }
+        }
+        throw new Error(`Failed to parse JSON response from Perplexity API: ${error}`);
     }
     const firstChoice = data.choices[0];
-    if (!firstChoice.message || typeof firstChoice.message.content !== 'string') {
-        throw new Error("Invalid API response: missing message content");
-    }
-    // Directly retrieve the main message content from the response
     let messageContent = firstChoice.message.content;
-    // Strip thinking tokens if requested
     if (stripThinking) {
         messageContent = stripThinkingTokens(messageContent);
     }
-    // If citations are provided, append them to the message content
     if (data.citations && Array.isArray(data.citations) && data.citations.length > 0) {
         messageContent += "\n\nCitations:\n";
         data.citations.forEach((citation, index) => {
@@ -161,12 +119,6 @@ export async function performChatCompletion(messages, model = "sonar-pro", strip
     }
     return messageContent;
 }
-/**
- * Formats search results from the Perplexity Search API into a readable string.
- *
- * @param {any} data - The search response data from the API.
- * @returns {string} Formatted search results.
- */
 export function formatSearchResults(data) {
     if (!data.results || !Array.isArray(data.results)) {
         return "No search results found.";
@@ -185,17 +137,7 @@ export function formatSearchResults(data) {
     });
     return formattedResults;
 }
-/**
- * Performs a web search using the Perplexity Search API.
- *
- * @param {string} query - The search query string.
- * @param {number} maxResults - Maximum number of results to return (1-20).
- * @param {number} maxTokensPerPage - Maximum tokens to extract per webpage.
- * @param {string} country - Optional ISO country code for regional results.
- * @returns {Promise<string>} The formatted search results.
- * @throws Will throw an error if the API request fails.
- */
-export async function performSearch(query, maxResults = 10, maxTokensPerPage = 1024, country) {
+export async function performSearch(query, maxResults = 10, maxTokensPerPage = 1024, country, serviceOrigin) {
     if (!PERPLEXITY_API_KEY) {
         throw new Error("PERPLEXITY_API_KEY environment variable is required");
     }
@@ -206,20 +148,22 @@ export async function performSearch(query, maxResults = 10, maxTokensPerPage = 1
         query: query,
         max_results: maxResults,
         max_tokens_per_page: maxTokensPerPage,
+        ...(country && { country }),
     };
-    if (country) {
-        body.country = country;
-    }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
     let response;
     try {
+        const headers = {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${PERPLEXITY_API_KEY}`,
+        };
+        if (serviceOrigin) {
+            headers["X-Service"] = serviceOrigin;
+        }
         response = await proxyAwareFetch(url.toString(), {
             method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "Authorization": `Bearer ${PERPLEXITY_API_KEY}`,
-            },
+            headers,
             body: JSON.stringify(body),
             signal: controller.signal,
         });
@@ -232,7 +176,6 @@ export async function performSearch(query, maxResults = 10, maxTokensPerPage = 1
         }
         throw new Error(`Network error while calling Perplexity Search API: ${error}`);
     }
-    // Check for non-successful HTTP status
     if (!response.ok) {
         let errorText;
         try {
@@ -245,25 +188,19 @@ export async function performSearch(query, maxResults = 10, maxTokensPerPage = 1
     }
     let data;
     try {
-        data = await response.json();
+        const json = await response.json();
+        data = SearchResponseSchema.parse(json);
     }
-    catch (jsonError) {
-        throw new Error(`Failed to parse JSON response from Perplexity Search API: ${jsonError}`);
+    catch (error) {
+        throw new Error(`Failed to parse JSON response from Perplexity Search API: ${error}`);
     }
     return formatSearchResults(data);
 }
-/**
- * Creates and configures the Perplexity MCP server with all tools.
- * This factory function is transport-agnostic and returns a configured server instance.
- *
- * @returns The configured MCP server instance
- */
-export function createPerplexityServer() {
+export function createPerplexityServer(serviceOrigin) {
     const server = new McpServer({
         name: "io.github.perplexityai/mcp-server",
-        version: "0.5.1",
+        version: "0.6.0",
     });
-    // Register perplexity_ask tool
     server.registerTool("perplexity_ask", {
         title: "Ask Perplexity",
         description: "Engages in a conversation using the Sonar API. " +
@@ -284,13 +221,12 @@ export function createPerplexityServer() {
         },
     }, async ({ messages }) => {
         validateMessages(messages, "perplexity_ask");
-        const result = await performChatCompletion(messages, "sonar-pro");
+        const result = await performChatCompletion(messages, "sonar-pro", false, serviceOrigin);
         return {
             content: [{ type: "text", text: result }],
             structuredContent: { response: result },
         };
     });
-    // Register perplexity_research tool
     server.registerTool("perplexity_research", {
         title: "Deep Research",
         description: "Performs deep research using the Perplexity API. " +
@@ -314,13 +250,12 @@ export function createPerplexityServer() {
     }, async ({ messages, strip_thinking }) => {
         validateMessages(messages, "perplexity_research");
         const stripThinking = typeof strip_thinking === "boolean" ? strip_thinking : false;
-        const result = await performChatCompletion(messages, "sonar-deep-research", stripThinking);
+        const result = await performChatCompletion(messages, "sonar-deep-research", stripThinking, serviceOrigin);
         return {
             content: [{ type: "text", text: result }],
             structuredContent: { response: result },
         };
     });
-    // Register perplexity_reason tool
     server.registerTool("perplexity_reason", {
         title: "Advanced Reasoning",
         description: "Performs reasoning tasks using the Perplexity API. " +
@@ -344,13 +279,12 @@ export function createPerplexityServer() {
     }, async ({ messages, strip_thinking }) => {
         validateMessages(messages, "perplexity_reason");
         const stripThinking = typeof strip_thinking === "boolean" ? strip_thinking : false;
-        const result = await performChatCompletion(messages, "sonar-reasoning-pro", stripThinking);
+        const result = await performChatCompletion(messages, "sonar-reasoning-pro", stripThinking, serviceOrigin);
         return {
             content: [{ type: "text", text: result }],
             structuredContent: { response: result },
         };
     });
-    // Register perplexity_search tool
     server.registerTool("perplexity_search", {
         title: "Search the Web",
         description: "Performs web search using the Perplexity Search API. " +
@@ -376,7 +310,7 @@ export function createPerplexityServer() {
         const maxResults = typeof max_results === "number" ? max_results : 10;
         const maxTokensPerPage = typeof max_tokens_per_page === "number" ? max_tokens_per_page : 1024;
         const countryCode = typeof country === "string" ? country : undefined;
-        const result = await performSearch(query, maxResults, maxTokensPerPage, countryCode);
+        const result = await performSearch(query, maxResults, maxTokensPerPage, countryCode, serviceOrigin);
         return {
             content: [{ type: "text", text: result }],
             structuredContent: { results: result },

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validation.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+export const ChatMessageSchema = z.object({
+    content: z.string(),
+    role: z.string().optional(),
+});
+export const ChatChoiceSchema = z.object({
+    message: ChatMessageSchema,
+    finish_reason: z.string().optional(),
+    index: z.number().optional(),
+});
+export const TokenUsageSchema = z.object({
+    prompt_tokens: z.number().optional(),
+    completion_tokens: z.number().optional(),
+    total_tokens: z.number().optional(),
+});
+export const ChatCompletionResponseSchema = z.object({
+    choices: z.array(ChatChoiceSchema).min(1),
+    citations: z.array(z.string()).optional(),
+    usage: TokenUsageSchema.optional(),
+    id: z.string().optional(),
+    model: z.string().optional(),
+    created: z.number().optional(),
+});
+export const SearchResultSchema = z.object({
+    title: z.string(),
+    url: z.string(),
+    snippet: z.string().optional(),
+    date: z.string().optional(),
+    score: z.number().optional(),
+});
+export const SearchUsageSchema = z.object({
+    tokens: z.number().optional(),
+});
+export const SearchResponseSchema = z.object({
+    results: z.array(SearchResultSchema),
+    query: z.string().optional(),
+    usage: SearchUsageSchema.optional(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perplexity-ai/mcp-server",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "mcpName": "io.github.perplexityai/mcp-server",
   "description": "Real-time web search, reasoning, and research through Perplexity's API",
   "keywords": [