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

package/README.md

@@ -1,8 +1,12 @@
 # Perplexity API Platform 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.
+[![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)
 
-Please refer to the official [DeepWiki page](https://deepwiki.com/ppl-ai/modelcontextprotocol) for assistance with implementation.
+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.
 
 ## Available Tools
 
@@ -34,9 +38,15 @@ Advanced reasoning and problem-solving using the `sonar-reasoning-pro` model. Pe
 
 #### Option 1: Install via Plugin (Recommended)
 
-The easiest way to get started with Perplexity in Claude Code:
-
+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
 
@@ -44,11 +54,6 @@ The easiest way to get started with Perplexity in Claude Code:
 /plugin install perplexity
 ```
 
-Then set your API key:
-```bash
-export PERPLEXITY_API_KEY="your_key_here"
-```
-
 #### Option 2: Manual Configuration
 
 Run in your terminal:
@@ -76,9 +81,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
 {
@@ -95,6 +100,8 @@ Add to your `mcp.json`:
 }
 ```
 
+Or use the one-click install badges at the top of this README.
+
 ### Codex
 
 Run in your terminal:
@@ -136,7 +143,7 @@ If you are running this server at work—especially behind a company firewall or
 
 **1. Get your proxy details**
 
-- Ask your IT department for your HTTP(S) proxy address and port.
+- 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**
@@ -144,20 +151,56 @@ If you are running this server at work—especially behind a company firewall or
 The easiest and most reliable way for Perplexity MCP is to use `PERPLEXITY_PROXY`. For example:
 
 ```bash
-export PERPLEXITY_PROXY=http://your-proxy-host:8080
+export PERPLEXITY_PROXY=https://your-proxy-host:8080
 ```
 
-- If your proxy needs a username and password, use:
-  ```bash
-  export PERPLEXITY_PROXY=http://username:password@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.
+> 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:
+
+#### 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)
+
+#### Using 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
+
+```bash
+npm install
+npm run build
+npm run start:http
+```
+
+Connect your MCP client to: `http://localhost:8080/mcp`
+
 
 ## Troubleshooting
 
@@ -165,16 +208,7 @@ If you'd rather use the standard variables, we support `HTTPS_PROXY` and `HTTP_P
 - **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**: If you're behind a corporate firewall and experience connection errors, you likely need to set up a proxy:
-  - Obtain your proxy server address and port from your IT department.
-  - Set the environment variable before running the server, e.g.:
-    - `export PERPLEXITY_PROXY=http://proxy-address:port`
-    - If authentication is needed: `export PERPLEXITY_PROXY=http://username:password@proxy-address:port`
-    - Typical proxy ports include 8080, 3128, or 80.
-  - The format for authenticated proxies is:  
-    `http://username:password@proxy-host:port`
-  - Double-check the address, port, and credentials if connections fail or time out.
-  - If you continue to have issues, your firewall may be blocking traffic; ask IT if traffic for `api.perplexity.ai` is being restricted.
+- **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/http.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+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
+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);
+}
+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",
+];
+// CORS configuration for browser-based MCP clients
+app.use(cors({
+    origin: (origin, callback) => {
+        if (!origin)
+            return callback(null, true);
+        if (ALLOWED_ORIGINS.includes("*")) {
+            return callback(null, true);
+        }
+        if (ALLOWED_ORIGINS.includes(origin)) {
+            callback(null, true);
+        }
+        else {
+            callback(new Error(`Origin ${origin} not allowed by CORS`));
+        }
+    },
+    exposedHeaders: ["Mcp-Session-Id", "mcp-protocol-version"],
+    allowedHeaders: ["Content-Type", "mcp-session-id"],
+}));
+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({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+        });
+        res.on('close', () => {
+            transport.close();
+        });
+        await mcpServer.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    }
+    catch (error) {
+        console.error("Error handling MCP request:", error);
+        if (!res.headersSent) {
+            res.status(500).json({
+                jsonrpc: "2.0",
+                error: { code: -32603, message: "Internal server error" },
+                id: null,
+            });
+        }
+    }
+});
+/**
+ * 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(", ")}`);
+}).on("error", (error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});