@perplexity-ai/mcp-server 0.5.1 → 0.5.2

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.5.2"
   },
   "plugins": [
     {
       "name": "perplexity",
       "source": "./",
       "description": "Real-time web search, reasoning, and research through Perplexity's API",
-      "version": "0.5.1",
+      "version": "0.5.2",
       "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)
 
@@ -33,6 +33,7 @@ Advanced reasoning and problem-solving using the `sonar-reasoning-pro` model. Pe
 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.
+4. (Optional) Set log level for debugging: `PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR`. The default is ERROR.
 
 ### Claude Code
 
@@ -81,9 +82,9 @@ Or add to your `claude.json`:
 }
 ```
 
-### Cursor / VS Code
+### Cursor
 
-Add to your `mcp.json` (Cursor) or `.vscode/mcp.json` (VS Code):
+Add to your `mcp.json` (Cursor):
 
 ```json
 {
@@ -92,14 +93,35 @@ 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"
       }
     }
   }
 }
 ```
 
+### VS Code
+
+Add to your `.vscode/mcp.json` (VS Code):
+
+```json
+{
+	"servers": {
+		"perplexity": {
+			"type": "stdio",
+			"command": "npx",
+			"args": [
+				"-y",
+				"@perplexity-ai/mcp-server"
+			],
+			"env": {
+				"PERPLEXITY_API_KEY": "your_key_here"
+			}
+		}
+	}
+}
+```
+
 Or use the one-click install badges at the top of this README.
 
 ### Codex

package/dist/http.js

@@ -3,10 +3,11 @@ import express from "express";
 import cors from "cors";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { createPerplexityServer } from "./server.js";
+import { logger } from "./logger.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");
+    logger.error("PERPLEXITY_API_KEY environment variable is required");
     process.exit(1);
 }
 const app = express();
@@ -53,7 +54,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",
@@ -73,9 +74,9 @@ app.get("/health", (req, res) => {
  * 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/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,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { fetch as undiciFetch, ProxyAgent } from "undici";
+import { ChatCompletionResponseSchema, SearchResponseSchema } from "./validation.js";
 // Retrieve the Perplexity API key from environment variables
 const PERPLEXITY_API_KEY = process.env.PERPLEXITY_API_KEY;
 /**
@@ -9,7 +10,7 @@ const PERPLEXITY_API_KEY = process.env.PERPLEXITY_API_KEY;
  *
  * @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 ||
@@ -23,32 +24,31 @@ function getProxyUrl() {
  * @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,
-        });
+        };
+        const response = await undiciFetch(url, undiciOptions);
         // Cast to native Response type for compatibility
         return response;
     }
-    else {
-        // Use native fetch when no proxy is configured
-        return fetch(url, options);
-    }
+    // Use native fetch when no proxy is configured
+    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 {unknown} 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`);
     }
@@ -72,14 +72,14 @@ function validateMessages(messages, toolName) {
  * @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 {Message[]} 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.
@@ -130,22 +130,24 @@ 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();
+        const json = await response.json();
+        data = ChatCompletionResponseSchema.parse(json);
     }
-    catch (jsonError) {
-        throw new Error(`Failed to parse JSON response from Perplexity API: ${jsonError}`);
-    }
-    // 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
@@ -164,7 +166,7 @@ export async function performChatCompletion(messages, model = "sonar-pro", strip
 /**
  * Formats search results from the Perplexity Search API into a readable string.
  *
- * @param {any} data - The search response data from the API.
+ * @param {SearchResponse} data - The search response data from the API.
  * @returns {string} Formatted search results.
  */
 export function formatSearchResults(data) {
@@ -206,10 +208,8 @@ 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;
@@ -245,10 +245,11 @@ 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);
 }
@@ -261,7 +262,7 @@ export async function performSearch(query, maxResults = 10, maxTokensPerPage = 1
 export function createPerplexityServer() {
     const server = new McpServer({
         name: "io.github.perplexityai/mcp-server",
-        version: "0.5.1",
+        version: "0.5.2",
     });
     // Register perplexity_ask tool
     server.registerTool("perplexity_ask", {

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for the Perplexity MCP Server
+ */
+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.5.2",
   "mcpName": "io.github.perplexityai/mcp-server",
   "description": "Real-time web search, reasoning, and research through Perplexity's API",
   "keywords": [