@perplexity-ai/mcp-server 0.3.1 → 0.4.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,49 @@
+{
+  "name": "perplexity-mcp-server",
+  "owner": {
+    "name": "Perplexity AI",
+    "email": "api@perplexity.ai"
+  },
+  "metadata": {
+    "description": "Official Perplexity AI plugin providing real-time web search, reasoning, and research capabilities",
+    "version": "0.4.1"
+  },
+  "plugins": [
+    {
+      "name": "perplexity",
+      "source": "./",
+      "description": "Real-time web search, reasoning, and research through Perplexity's API",
+      "version": "0.4.1",
+      "author": {
+        "name": "Perplexity AI",
+        "email": "api@perplexity.ai"
+      },
+      "homepage": "https://docs.perplexity.ai/guides/mcp-server",
+      "repository": "https://github.com/perplexityai/modelcontextprotocol",
+      "license": "MIT",
+      "keywords": [
+        "mcp",
+        "search",
+        "web-search",
+        "perplexity",
+        "research",
+        "reasoning",
+        "ai"
+      ],
+      "category": "productivity",
+      "strict": false,
+      "mcpServers": {
+        "perplexity": {
+          "type": "stdio",
+          "command": "npx",
+          "args": ["-y", "@perplexity-ai/mcp-server"],
+          "env": {
+            "PERPLEXITY_API_KEY": "${PERPLEXITY_API_KEY}",
+            "PERPLEXITY_TIMEOUT_MS": "${PERPLEXITY_TIMEOUT_MS:-600000}"
+          }
+        }
+      }
+    }
+  ]
+}
+

package/README.md

@@ -1,5 +1,11 @@
 # 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 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)
+ 
+[![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)
+
 The official MCP server implementation for the Perplexity API Platform, providing AI assistants with real-time web search, reasoning, and research capabilities through Sonar models and the Search API.
 
 Please refer to the official [DeepWiki page](https://deepwiki.com/ppl-ai/modelcontextprotocol) for assistance with implementation.
@@ -18,6 +24,11 @@ Deep, comprehensive research using the `sonar-deep-research` model. Ideal for th
 ### **perplexity_reason**
 Advanced reasoning and problem-solving using the `sonar-reasoning-pro` model. Perfect for complex analytical tasks.
 
+> [!TIP]
+> Available as an optional parameter for **perplexity_reason** and **perplexity_research**: `strip_thinking`
+>
+> Set to `true` to remove `<think>...</think>` tags from the response, saving context tokens. Default: `false`
+
 ## Configuration
 
 ### Get Your API Key
@@ -27,6 +38,25 @@ Advanced reasoning and problem-solving using the `sonar-reasoning-pro` model. Pe
 
 ### Claude Code
 
+#### Option 1: Install via Plugin (Recommended)
+
+The easiest way to get started with Perplexity in Claude Code:
+
+```bash
+# Add the Perplexity marketplace
+/plugin marketplace add perplexityai/modelcontextprotocol
+
+# Install the plugin
+/plugin install perplexity
+```
+
+Then set your API key:
+```bash
+export PERPLEXITY_API_KEY="your_key_here"
+```
+
+#### Option 2: Manual Configuration
+
 Run in your terminal:
 
 ```bash
@@ -52,9 +82,9 @@ Or add to your `claude.json`:
 }
 ```
 
-### Cursor
+### Cursor / VS Code
 
-Add to your `mcp.json`:
+Add to your `mcp.json` (Cursor) or `.vscode/mcp.json` (VS Code):
 
 ```json
 {
@@ -71,6 +101,8 @@ Add to your `mcp.json`:
 }
 ```
 
+Or use the one-click install badges at the top of this README.
+
 ### Codex
 
 Run in your terminal:
@@ -106,12 +138,44 @@ For any MCP-compatible client, use:
 npx @perplexity-ai/mcp-server
 ```
 
+### 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:
+
+**1. Get your proxy details**
+
+- Ask your IT department for your HTTPS proxy address and port.
+- You may also need a username and password.
+
+**2. Set the proxy environment variable**
+
+The easiest and most reliable way for Perplexity MCP is to use `PERPLEXITY_PROXY`. For example:
+
+```bash
+export PERPLEXITY_PROXY=https://your-proxy-host:8080
+```
+
+If your proxy needs a username and password, use:
+
+```bash
+export PERPLEXITY_PROXY=https://username:password@your-proxy-host:8080
+```
+
+**3. Alternate: Standard environment variables**
+
+If you'd rather use the standard variables, we support `HTTPS_PROXY` and `HTTP_PROXY`.
+
+> [!NOTE]
+> 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`.
+
 ## Troubleshooting
 
 - **API Key Issues**: Ensure `PERPLEXITY_API_KEY` is set correctly
 - **Connection Errors**: Check your internet connection and API key validity
 - **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.
 
 For support, visit [community.perplexity.ai](https://community.perplexity.ai) or [file an issue](https://github.com/perplexityai/modelcontextprotocol/issues).
 

package/dist/index.js

@@ -11,6 +11,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { fetch as undiciFetch, ProxyAgent } from "undici";
 /**
  * Definition of the Perplexity Ask Tool.
  * This tool accepts an array of messages and returns a chat completion response
@@ -18,6 +19,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
  */
 const PERPLEXITY_ASK_TOOL = {
     name: "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 ask completion response from the Perplexity model.",
@@ -45,6 +47,10 @@ const PERPLEXITY_ASK_TOOL = {
         },
         required: ["messages"],
     },
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+    },
 };
 /**
  * Definition of the Perplexity Research Tool.
@@ -52,6 +58,7 @@ const PERPLEXITY_ASK_TOOL = {
  */
 const PERPLEXITY_RESEARCH_TOOL = {
     name: "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.",
@@ -76,9 +83,17 @@ const PERPLEXITY_RESEARCH_TOOL = {
                 },
                 description: "Array of conversation messages",
             },
+            strip_thinking: {
+                type: "boolean",
+                description: "If true, removes <think>...</think> tags and their content from the response to save context tokens. Default is false.",
+            },
         },
         required: ["messages"],
     },
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+    },
 };
 /**
  * Definition of the Perplexity Reason Tool.
@@ -86,6 +101,7 @@ const PERPLEXITY_RESEARCH_TOOL = {
  */
 const PERPLEXITY_REASON_TOOL = {
     name: "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.",
@@ -110,9 +126,17 @@ const PERPLEXITY_REASON_TOOL = {
                 },
                 description: "Array of conversation messages",
             },
+            strip_thinking: {
+                type: "boolean",
+                description: "If true, removes <think>...</think> tags and their content from the response to save context tokens. Default is false.",
+            },
         },
         required: ["messages"],
     },
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+    },
 };
 /**
  * Definition of the Perplexity Search Tool.
@@ -120,8 +144,10 @@ const PERPLEXITY_REASON_TOOL = {
  */
 const PERPLEXITY_SEARCH_TOOL = {
     name: "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.",
+        "Returns ranked search results with titles, URLs, snippets, and metadata. " +
+        "Perfect for finding up-to-date facts, news, or specific information.",
     inputSchema: {
         type: "object",
         properties: {
@@ -148,6 +174,10 @@ const PERPLEXITY_SEARCH_TOOL = {
         },
         required: ["query"],
     },
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+    },
 };
 // Retrieve the Perplexity API key from environment variables
 const PERPLEXITY_API_KEY = process.env.PERPLEXITY_API_KEY;
@@ -155,6 +185,42 @@ if (!PERPLEXITY_API_KEY) {
     console.error("Error: PERPLEXITY_API_KEY environment variable is required");
     process.exit(1);
 }
+/**
+ * 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() {
+    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
+ */
+function proxyAwareFetch(url_1) {
+    return __awaiter(this, arguments, void 0, function* (url, options = {}) {
+        const proxyUrl = getProxyUrl();
+        if (proxyUrl) {
+            // Use undici with ProxyAgent when proxy is configured
+            const proxyAgent = new ProxyAgent(proxyUrl);
+            const response = yield undiciFetch(url, Object.assign(Object.assign({}, options), { dispatcher: proxyAgent }));
+            // Cast to native Response type for compatibility
+            return response;
+        }
+        else {
+            // 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.
@@ -180,17 +246,28 @@ 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) {
+    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 function performChatCompletion(messages_1) {
-    return __awaiter(this, arguments, void 0, function* (messages, model = "sonar-pro") {
+    return __awaiter(this, arguments, void 0, function* (messages, model = "sonar-pro", stripThinking = false) {
         // 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
@@ -206,7 +283,7 @@ export function performChatCompletion(messages_1) {
         const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
         let response;
         try {
-            response = yield fetch(url.toString(), {
+            response = yield proxyAwareFetch(url.toString(), {
                 method: "POST",
                 headers: {
                     "Content-Type": "application/json",
@@ -253,6 +330,10 @@ export function performChatCompletion(messages_1) {
         }
         // 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";
@@ -314,7 +395,7 @@ export function performSearch(query_1) {
         const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
         let response;
         try {
-            response = yield fetch(url.toString(), {
+            response = yield proxyAwareFetch(url.toString(), {
                 method: "POST",
                 headers: {
                     "Content-Type": "application/json",
@@ -355,12 +436,23 @@ export function performSearch(query_1) {
 }
 // Initialize the server with tool metadata and capabilities
 const server = new Server({
-    name: "example-servers/perplexity-ask",
-    version: "0.1.0",
+    name: "io.github.perplexityai/mcp-server",
+    version: "0.4.1",
 }, {
     capabilities: {
         tools: {},
     },
+    instructions: `You are the Perplexity MCP Server. Use these tools appropriately:
+
+- perplexity_search: For quick web searches when you need current information or facts. Returns ranked search results.
+
+- perplexity_ask: For general questions and conversational queries with real-time web search using the sonar-pro model.
+
+- perplexity_research: For deep, comprehensive research requiring thorough analysis using the sonar-deep-research model. Use this for complex topics that require detailed investigation.
+
+- perplexity_reason: For complex analytical tasks requiring advanced reasoning using the sonar-reasoning-pro model. Use this for logical problems, analysis, and decision-making.
+
+When using perplexity_research or perplexity_reason, consider setting strip_thinking=true to save context tokens if the reasoning process isn't needed in the final output.`,
 });
 /**
  * Registers a handler for listing available tools.
@@ -397,7 +489,8 @@ server.setRequestHandler(CallToolRequestSchema, (request) => __awaiter(void 0, v
             case "perplexity_research": {
                 validateMessages(args.messages, "perplexity_research");
                 const messages = args.messages;
-                const result = yield performChatCompletion(messages, "sonar-deep-research");
+                const stripThinking = typeof args.strip_thinking === "boolean" ? args.strip_thinking : false;
+                const result = yield performChatCompletion(messages, "sonar-deep-research", stripThinking);
                 return {
                     content: [{ type: "text", text: result }],
                     isError: false,
@@ -406,7 +499,8 @@ server.setRequestHandler(CallToolRequestSchema, (request) => __awaiter(void 0, v
             case "perplexity_reason": {
                 validateMessages(args.messages, "perplexity_reason");
                 const messages = args.messages;
-                const result = yield performChatCompletion(messages, "sonar-reasoning-pro");
+                const stripThinking = typeof args.strip_thinking === "boolean" ? args.strip_thinking : false;
+                const result = yield performChatCompletion(messages, "sonar-reasoning-pro", stripThinking);
                 return {
                     content: [{ type: "text", text: result }],
                     isError: false,

package/dist/index.test.js

@@ -484,4 +484,83 @@ describe("Perplexity MCP Server", () => {
             expect(formatted).not.toContain("12345");
         });
     });
+    describe("strip_thinking parameter", () => {
+        it("should strip thinking tokens when true and keep them when false", () => __awaiter(void 0, void 0, void 0, function* () {
+            const mockResponse = {
+                choices: [
+                    {
+                        message: {
+                            content: "<think>This is my reasoning process</think>\n\nThe answer is 4.",
+                        },
+                    },
+                ],
+            };
+            // Test with stripThinking = true
+            global.fetch = vi.fn().mockResolvedValue({
+                ok: true,
+                json: () => __awaiter(void 0, void 0, void 0, function* () { return mockResponse; }),
+            });
+            const messages = [{ role: "user", content: "What is 2+2?" }];
+            const resultStripped = yield performChatCompletion(messages, "sonar-reasoning-pro", true);
+            expect(resultStripped).not.toContain("<think>");
+            expect(resultStripped).not.toContain("</think>");
+            expect(resultStripped).not.toContain("This is my reasoning process");
+            expect(resultStripped).toContain("The answer is 4.");
+            // Test with stripThinking = false
+            global.fetch = vi.fn().mockResolvedValue({
+                ok: true,
+                json: () => __awaiter(void 0, void 0, void 0, function* () { return mockResponse; }),
+            });
+            const resultKept = yield performChatCompletion(messages, "sonar-reasoning-pro", false);
+            expect(resultKept).toContain("<think>This is my reasoning process</think>");
+            expect(resultKept).toContain("The answer is 4.");
+        }));
+    });
+    describe("Proxy Support", () => {
+        const originalEnv = process.env;
+        beforeEach(() => {
+            // Reset environment variables
+            process.env = Object.assign({}, originalEnv);
+            delete process.env.PERPLEXITY_PROXY;
+            delete process.env.HTTPS_PROXY;
+            delete process.env.HTTP_PROXY;
+        });
+        afterEach(() => {
+            process.env = originalEnv;
+        });
+        it("should use native fetch when no proxy is configured", () => __awaiter(void 0, void 0, void 0, function* () {
+            const mockResponse = {
+                choices: [{ message: { content: "Test response" } }],
+            };
+            global.fetch = vi.fn().mockResolvedValue({
+                ok: true,
+                json: () => __awaiter(void 0, void 0, void 0, function* () { return mockResponse; }),
+            });
+            const messages = [{ role: "user", content: "test" }];
+            yield performChatCompletion(messages);
+            // Verify native fetch was called (not undici)
+            expect(global.fetch).toHaveBeenCalled();
+        }));
+        it("should read PERPLEXITY_PROXY environment variable", () => {
+            process.env.PERPLEXITY_PROXY = "http://proxy.example.com:8080";
+            expect(process.env.PERPLEXITY_PROXY).toBe("http://proxy.example.com:8080");
+        });
+        it("should prioritize PERPLEXITY_PROXY over HTTPS_PROXY", () => {
+            process.env.PERPLEXITY_PROXY = "http://perplexity-proxy.example.com:8080";
+            process.env.HTTPS_PROXY = "http://https-proxy.example.com:8080";
+            // PERPLEXITY_PROXY should take precedence
+            expect(process.env.PERPLEXITY_PROXY).toBe("http://perplexity-proxy.example.com:8080");
+        });
+        it("should fall back to HTTPS_PROXY when PERPLEXITY_PROXY is not set", () => {
+            delete process.env.PERPLEXITY_PROXY;
+            process.env.HTTPS_PROXY = "http://https-proxy.example.com:8080";
+            expect(process.env.HTTPS_PROXY).toBe("http://https-proxy.example.com:8080");
+        });
+        it("should fall back to HTTP_PROXY when others are not set", () => {
+            delete process.env.PERPLEXITY_PROXY;
+            delete process.env.HTTPS_PROXY;
+            process.env.HTTP_PROXY = "http://http-proxy.example.com:8080";
+            expect(process.env.HTTP_PROXY).toBe("http://http-proxy.example.com:8080");
+        });
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perplexity-ai/mcp-server",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "mcpName": "io.github.perplexityai/mcp-server",
   "description": "Real-time web search, reasoning, and research through Perplexity's API",
   "keywords": [
@@ -29,7 +29,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    ".claude-plugin"
   ],
   "scripts": {
     "build": "tsc && shx chmod +x dist/*.js",
@@ -41,7 +42,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.21.1",
-    "dotenv": "^16.6.1"
+    "dotenv": "^16.6.1",
+    "undici": "^6.20.0"
   },
   "devDependencies": {
     "@types/node": "^20",