@perplexity-ai/mcp-server 0.6.1 → 0.7.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.6.1"
+    "version": "0.7.0"
   },
   "plugins": [
     {
       "name": "perplexity",
       "source": "./",
       "description": "Real-time web search, reasoning, and research through Perplexity's API",
-      "version": "0.6.1",
+      "version": "0.7.0",
       "author": {
         "name": "Perplexity AI",
         "email": "api@perplexity.ai"

package/README.md

@@ -34,7 +34,8 @@ 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. 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)
+4. (Optional) Set custom base URL: `PERPLEXITY_BASE_URL=https://your-custom-url.com` (default: https://api.perplexity.ai)
+5. (Optional) Set log level: `PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR` (default: ERROR)
 
 ### Claude Code
 
@@ -145,6 +146,7 @@ For cloud or shared deployments, run the server in HTTP mode.
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `PERPLEXITY_API_KEY` | Your Perplexity API key | *Required* |
+| `PERPLEXITY_BASE_URL` | Custom base URL for API requests | `https://api.perplexity.ai` |
 | `PORT` | HTTP server port | `8080` |
 | `BIND_ADDRESS` | Network interface to bind to | `0.0.0.0` |
 | `ALLOWED_ORIGINS` | CORS origins (comma-separated) | `*` |

package/dist/server.js

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { fetch as undiciFetch, ProxyAgent } from "undici";
 import { ChatCompletionResponseSchema, SearchResponseSchema } from "./validation.js";
 const PERPLEXITY_API_KEY = process.env.PERPLEXITY_API_KEY;
+const PERPLEXITY_BASE_URL = process.env.PERPLEXITY_BASE_URL || "https://api.perplexity.ai";
 export function getProxyUrl() {
     return process.env.PERPLEXITY_PROXY ||
         process.env.HTTPS_PROXY ||
@@ -42,16 +43,20 @@ export function validateMessages(messages, toolName) {
 export function stripThinkingTokens(content) {
     return content.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
 }
-export async function performChatCompletion(messages, model = "sonar-pro", stripThinking = false, serviceOrigin) {
+export async function performChatCompletion(messages, model = "sonar-pro", stripThinking = false, serviceOrigin, options) {
     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);
-    const url = new URL("https://api.perplexity.ai/chat/completions");
+    const url = new URL(`${PERPLEXITY_BASE_URL}/chat/completions`);
     const body = {
         model: model,
         messages: messages,
+        ...(options?.search_recency_filter && { search_recency_filter: options.search_recency_filter }),
+        ...(options?.search_domain_filter && { search_domain_filter: options.search_domain_filter }),
+        ...(options?.search_context_size && { web_search_options: { search_context_size: options.search_context_size } }),
+        ...(options?.reasoning_effort && { reasoning_effort: options.reasoning_effort }),
     };
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
@@ -143,7 +148,7 @@ export async function performSearch(query, maxResults = 10, maxTokensPerPage = 1
     }
     // Read timeout fresh each time to respect env var changes
     const TIMEOUT_MS = parseInt(process.env.PERPLEXITY_TIMEOUT_MS || "300000", 10);
-    const url = new URL("https://api.perplexity.ai/search");
+    const url = new URL(`${PERPLEXITY_BASE_URL}/search`);
     const body = {
         query: query,
         max_results: maxResults,
@@ -199,36 +204,76 @@ export async function performSearch(query, maxResults = 10, maxTokensPerPage = 1
 export function createPerplexityServer(serviceOrigin) {
     const server = new McpServer({
         name: "io.github.perplexityai/mcp-server",
-        version: "0.6.1",
+        version: "0.7.0",
+    }, {
+        instructions: "Perplexity AI server for web-grounded search, research, and reasoning. " +
+            "Use perplexity_search for finding URLs, facts, and recent news. " +
+            "Use perplexity_ask for quick AI-answered questions with citations. Supports recency filters, domain restrictions, and search context size control. " +
+            "Use perplexity_research for in-depth multi-source investigation (slow, 30s+). Supports reasoning_effort parameter to control depth. " +
+            "Use perplexity_reason for complex analysis requiring step-by-step logic. Supports recency filters, domain restrictions, and search context size control. " +
+            "All tools are read-only and access live web data.",
     });
     const messageSchema = z.object({
-        role: z.string().describe("Role of the message (e.g., system, user, assistant)"),
+        role: z.enum(["system", "user", "assistant"]).describe("Role of the message sender"),
         content: z.string().describe("The content of the message"),
     });
     const messagesField = z.array(messageSchema).describe("Array of conversation messages");
     const stripThinkingField = z.boolean().optional()
         .describe("If true, removes <think>...</think> tags and their content from the response to save context tokens. Default is false.");
+    const searchRecencyFilterField = z.enum(["hour", "day", "week", "month", "year"]).optional()
+        .describe("Filter search results by recency. Use 'hour' for very recent news, 'day' for today's updates, 'week' for this week, etc.");
+    const searchDomainFilterField = z.array(z.string()).optional()
+        .describe("Restrict search results to specific domains (e.g., ['wikipedia.org', 'arxiv.org']). Use '-' prefix for exclusion (e.g., ['-reddit.com']).");
+    const searchContextSizeField = z.enum(["low", "medium", "high"]).optional()
+        .describe("Controls how much web context is retrieved. 'low' (default) is fastest, 'high' provides more comprehensive results.");
+    const reasoningEffortField = z.enum(["minimal", "low", "medium", "high"]).optional()
+        .describe("Controls depth of deep research reasoning. Higher values produce more thorough analysis.");
     const responseOutputSchema = {
-        response: z.string().describe("The response from Perplexity"),
+        response: z.string().describe("AI-generated text response with numbered citation references"),
     };
     // Input schemas
-    const messagesOnlyInputSchema = { messages: messagesField };
-    const messagesWithStripThinkingInputSchema = { messages: messagesField, strip_thinking: stripThinkingField };
+    const messagesOnlyInputSchema = {
+        messages: messagesField,
+        search_recency_filter: searchRecencyFilterField,
+        search_domain_filter: searchDomainFilterField,
+        search_context_size: searchContextSizeField,
+    };
+    const messagesWithStripThinkingInputSchema = {
+        messages: messagesField,
+        strip_thinking: stripThinkingField,
+        search_recency_filter: searchRecencyFilterField,
+        search_domain_filter: searchDomainFilterField,
+        search_context_size: searchContextSizeField,
+    };
+    const researchInputSchema = {
+        messages: messagesField,
+        strip_thinking: stripThinkingField,
+        reasoning_effort: reasoningEffortField,
+    };
     server.registerTool("perplexity_ask", {
         title: "Ask Perplexity",
-        description: "Engages in a conversation using the Sonar API. " +
-            "Accepts an array of messages (each with a role and content) " +
-            "and returns a chat completion response from the Perplexity model.",
+        description: "Answer a question using web-grounded AI (Sonar Pro model). " +
+            "Best for: quick factual questions, summaries, explanations, and general Q&A. " +
+            "Returns a text response with numbered citations. Fastest and cheapest option. " +
+            "Supports filtering by recency (hour/day/week/month/year), domain restrictions, and search context size. " +
+            "For in-depth multi-source research, use perplexity_research instead. " +
+            "For step-by-step reasoning and analysis, use perplexity_reason instead.",
         inputSchema: messagesOnlyInputSchema,
         outputSchema: responseOutputSchema,
         annotations: {
             readOnlyHint: true,
             openWorldHint: true,
+            idempotentHint: true,
         },
     }, async (args) => {
-        const { messages } = args;
+        const { messages, search_recency_filter, search_domain_filter, search_context_size } = args;
         validateMessages(messages, "perplexity_ask");
-        const result = await performChatCompletion(messages, "sonar-pro", false, serviceOrigin);
+        const options = {
+            ...(search_recency_filter && { search_recency_filter }),
+            ...(search_domain_filter && { search_domain_filter }),
+            ...(search_context_size && { search_context_size }),
+        };
+        const result = await performChatCompletion(messages, "sonar-pro", false, serviceOrigin, Object.keys(options).length > 0 ? options : undefined);
         return {
             content: [{ type: "text", text: result }],
             structuredContent: { response: result },
@@ -236,20 +281,27 @@ export function createPerplexityServer(serviceOrigin) {
     });
     server.registerTool("perplexity_research", {
         title: "Deep Research",
-        description: "Performs deep research using the Perplexity API. " +
-            "Accepts an array of messages (each with a role and content) " +
-            "and returns a comprehensive research response with citations.",
-        inputSchema: messagesWithStripThinkingInputSchema,
+        description: "Conduct deep, multi-source research on a topic (Sonar Deep Research model). " +
+            "Best for: literature reviews, comprehensive overviews, investigative queries needing " +
+            "many sources. Returns a detailed response with numbered citations. " +
+            "Significantly slower than other tools (30+ seconds). " +
+            "For quick factual questions, use perplexity_ask instead. " +
+            "For logical analysis and reasoning, use perplexity_reason instead.",
+        inputSchema: researchInputSchema,
         outputSchema: responseOutputSchema,
         annotations: {
             readOnlyHint: true,
             openWorldHint: true,
+            idempotentHint: true,
         },
     }, async (args) => {
-        const { messages, strip_thinking } = args;
+        const { messages, strip_thinking, reasoning_effort } = args;
         validateMessages(messages, "perplexity_research");
         const stripThinking = typeof strip_thinking === "boolean" ? strip_thinking : false;
-        const result = await performChatCompletion(messages, "sonar-deep-research", stripThinking, serviceOrigin);
+        const options = {
+            ...(reasoning_effort && { reasoning_effort }),
+        };
+        const result = await performChatCompletion(messages, "sonar-deep-research", stripThinking, serviceOrigin, Object.keys(options).length > 0 ? options : undefined);
         return {
             content: [{ type: "text", text: result }],
             structuredContent: { response: result },
@@ -257,20 +309,29 @@ export function createPerplexityServer(serviceOrigin) {
     });
     server.registerTool("perplexity_reason", {
         title: "Advanced Reasoning",
-        description: "Performs reasoning tasks using the Perplexity API. " +
-            "Accepts an array of messages (each with a role and content) " +
-            "and returns a well-reasoned response using the sonar-reasoning-pro model.",
+        description: "Analyze a question using step-by-step reasoning with web grounding (Sonar Reasoning Pro model). " +
+            "Best for: math, logic, comparisons, complex arguments, and tasks requiring chain-of-thought. " +
+            "Returns a reasoned response with numbered citations. " +
+            "Supports filtering by recency (hour/day/week/month/year), domain restrictions, and search context size. " +
+            "For quick factual questions, use perplexity_ask instead. " +
+            "For comprehensive multi-source research, use perplexity_research instead.",
         inputSchema: messagesWithStripThinkingInputSchema,
         outputSchema: responseOutputSchema,
         annotations: {
             readOnlyHint: true,
             openWorldHint: true,
+            idempotentHint: true,
         },
     }, async (args) => {
-        const { messages, strip_thinking } = args;
+        const { messages, strip_thinking, search_recency_filter, search_domain_filter, search_context_size } = args;
         validateMessages(messages, "perplexity_reason");
         const stripThinking = typeof strip_thinking === "boolean" ? strip_thinking : false;
-        const result = await performChatCompletion(messages, "sonar-reasoning-pro", stripThinking, serviceOrigin);
+        const options = {
+            ...(search_recency_filter && { search_recency_filter }),
+            ...(search_domain_filter && { search_domain_filter }),
+            ...(search_context_size && { search_context_size }),
+        };
+        const result = await performChatCompletion(messages, "sonar-reasoning-pro", stripThinking, serviceOrigin, Object.keys(options).length > 0 ? options : undefined);
         return {
             content: [{ type: "text", text: result }],
             structuredContent: { response: result },
@@ -286,18 +347,20 @@ export function createPerplexityServer(serviceOrigin) {
             .describe("ISO 3166-1 alpha-2 country code for regional results (e.g., 'US', 'GB')"),
     };
     const searchOutputSchema = {
-        results: z.string().describe("Formatted search results"),
+        results: z.string().describe("Formatted search results, each with title, URL, snippet, and date"),
     };
     server.registerTool("perplexity_search", {
         title: "Search the Web",
-        description: "Performs web search using the Perplexity Search API. " +
-            "Returns ranked search results with titles, URLs, snippets, and metadata. " +
-            "Perfect for finding up-to-date facts, news, or specific information.",
+        description: "Search the web and return a ranked list of results with titles, URLs, snippets, and dates. " +
+            "Best for: finding specific URLs, checking recent news, verifying facts, discovering sources. " +
+            "Returns formatted results (title, URL, snippet, date) — no AI synthesis. " +
+            "For AI-generated answers with citations, use perplexity_ask instead.",
         inputSchema: searchInputSchema,
         outputSchema: searchOutputSchema,
         annotations: {
             readOnlyHint: true,
             openWorldHint: true,
+            idempotentHint: true,
         },
     }, async (args) => {
         const { query, max_results, max_tokens_per_page, country } = args;

package/package.json

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