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

package/dist/server.js

@@ -43,16 +43,89 @@ 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 consumeSSEStream(response) {
+    const body = response.body;
+    if (!body) {
+        throw new Error("Response body is null");
+    }
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let contentParts = [];
+    let citations;
+    let usage;
+    let id;
+    let model;
+    let created;
+    let buffer = "";
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        // Keep the last potentially incomplete line in the buffer
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed || !trimmed.startsWith("data:"))
+                continue;
+            const data = trimmed.slice("data:".length).trim();
+            if (data === "[DONE]")
+                continue;
+            try {
+                const parsed = JSON.parse(data);
+                if (parsed.id)
+                    id = parsed.id;
+                if (parsed.model)
+                    model = parsed.model;
+                if (parsed.created)
+                    created = parsed.created;
+                if (parsed.citations)
+                    citations = parsed.citations;
+                if (parsed.usage)
+                    usage = parsed.usage;
+                const delta = parsed.choices?.[0]?.delta;
+                if (delta?.content) {
+                    contentParts.push(delta.content);
+                }
+            }
+            catch {
+                // Skip malformed JSON chunks (e.g. keep-alive pings)
+            }
+        }
+    }
+    const assembled = {
+        choices: [
+            {
+                message: { content: contentParts.join("") },
+                finish_reason: "stop",
+                index: 0,
+            },
+        ],
+        ...(citations && { citations }),
+        ...(usage && { usage }),
+        ...(id && { id }),
+        ...(model && { model }),
+        ...(created && { created }),
+    };
+    return ChatCompletionResponseSchema.parse(assembled);
+}
+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 useStreaming = model === "sonar-deep-research";
     const url = new URL(`${PERPLEXITY_BASE_URL}/chat/completions`);
     const body = {
         model: model,
         messages: messages,
+        ...(useStreaming && { stream: true }),
+        ...(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);
@@ -92,8 +165,13 @@ export async function performChatCompletion(messages, model = "sonar-pro", strip
     }
     let data;
     try {
-        const json = await response.json();
-        data = ChatCompletionResponseSchema.parse(json);
+        if (useStreaming) {
+            data = await consumeSSEStream(response);
+        }
+        else {
+            const json = await response.json();
+            data = ChatCompletionResponseSchema.parse(json);
+        }
     }
     catch (error) {
         if (error instanceof z.ZodError) {
@@ -200,36 +278,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.2",
+        version: "0.8.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 },
@@ -237,20 +355,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 },
@@ -258,20 +383,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 },
@@ -287,18 +421,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,7 +1,7 @@
 {
   "name": "@perplexity-ai/mcp-server",
-  "version": "0.6.2",
-  "mcpName": "io.github.perplexityai/mcp-server",
+  "version": "0.8.0",
+  "mcpName": "ai.perplexityai/mcp-server",
   "description": "Real-time web search, reasoning, and research through Perplexity's API",
   "keywords": [
     "ai",