@kkaminsk/modelcontextprotocol 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 perplexity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# Perplexity MCP Server
+
+An unofficial Model Context Protocol (MCP) server fork that provides AI assistants with Perplexity API capabilities including real-time web search, deep research, and advanced reasoning.
+
+## Available Tools
+
+### perplexity_ask
+Real-time AI-powered answers with web search. Supports model selection for balancing speed and quality.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `messages` | array | **Required.** Conversation messages with `role` and `content` |
+| `model` | string | `sonar` (fast/cheap) or `sonar-pro` (high quality, default) |
+| `stream` | boolean | Enable streaming responses (default: false) |
+| `return_images` | boolean | Include relevant images in response (default: false) |
+| `return_related_questions` | boolean | Include follow-up suggestions (default: false) |
+
+### perplexity_research
+Deep, comprehensive research using the `sonar-deep-research` model. Ideal for thorough analysis and detailed reports.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `messages` | array | **Required.** Conversation messages with `role` and `content` |
+| `reasoning_effort` | string | `low`, `medium` (default), or `high` for research depth |
+| `return_images` | boolean | Include relevant images in response (default: false) |
+| `return_related_questions` | boolean | Include follow-up suggestions (default: false) |
+
+### perplexity_reason
+Advanced reasoning and problem-solving using the `sonar-reasoning-pro` model. Perfect for complex analytical tasks.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `messages` | array | **Required.** Conversation messages with `role` and `content` |
+| `stream` | boolean | Enable streaming responses (default: false) |
+
+### perplexity_search
+Direct web search using the Perplexity Search API. Supports single or batch queries.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string or array | **Required.** Single query or up to 5 queries for batch search |
+| `max_results` | number | Results per query (1-20, default: 10) |
+| `max_tokens_per_page` | number | Tokens per webpage (256-2048, default: 1024) |
+| `country` | string | ISO 3166-1 alpha-2 code for regional results (e.g., `US`, `GB`) |
+
+### perplexity_research_async
+Start an async deep research job for complex queries that may take several minutes.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `messages` | array | **Required.** Conversation messages with `role` and `content` |
+| `reasoning_effort` | string | `low`, `medium` (default), or `high` for research depth |
+| `search_domain_filter` | array | Domain allowlist/denylist (max 20) |
+
+Returns a `request_id` to poll with `perplexity_research_status`.
+
+### perplexity_research_status
+Check status and retrieve results from an async research job.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `request_id` | string | **Required.** The request_id from `perplexity_research_async` |
+
+## Common Parameters
+
+The following parameters are available on `perplexity_ask`, `perplexity_research`, and `perplexity_reason`:
+
+### Generation Controls
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `temperature` | number | Randomness (0-2). Default: 0.2 |
+| `max_tokens` | integer | Maximum response tokens |
+| `top_p` | number | Nucleus sampling (0-1). Default: 0.9 |
+| `top_k` | integer | Top-k sampling. 0 = disabled |
+
+### Search Filters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `search_domain_filter` | array | Domain list (max 20). Prefix with `-` to exclude |
+| `search_mode` | string | `web` (default), `academic`, or `sec` (SEC filings) |
+
+### Date Filters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `search_recency_filter` | string | `day`, `week`, `month`, or `year` |
+| `search_after_date` | string | Only results after date (MM/DD/YYYY) |
+| `search_before_date` | string | Only results before date (MM/DD/YYYY) |
+| `last_updated_after` | string | Only results updated after date (MM/DD/YYYY) |
+| `last_updated_before` | string | Only results updated before date (MM/DD/YYYY) |
+
+> **Note:** `perplexity_search` supports `search_domain_filter` and all date filters, but not generation controls or `search_mode`.
+
+## Installation
+
+### Windows Installer (Recommended for Windows)
+
+Download and run the MSI installer for a one-click setup:
+
+1. Download `PerplexityMCP.msi` from the [Releases](https://github.com/perplexityai/modelcontextprotocol/releases) page
+2. Run the installer and enter your Perplexity API key when prompted
+3. The installer automatically configures Claude Desktop, Claude Code, Cursor, and Codex
+
+The installer bundles Node.js, so no prerequisites are required.
+
+**Silent install:**
+```powershell
+msiexec /i PerplexityMCP.msi PERPLEXITY_API_KEY="your_key_here" /qn
+```
+
+### npm / npx
+
+For manual installation or non-Windows platforms:
+
+```bash
+npx @perplexity-ai/mcp-server
+```
+
+Or install globally:
+
+```bash
+npm install -g @perplexity-ai/mcp-server
+```
+
+## Configuration
+
+### Get Your API Key
+1. Get your Perplexity API Key from the [API Portal](https://www.perplexity.ai/account/api)
+2. Set it as an environment variable: `PERPLEXITY_API_KEY=your_key_here`
+3. (Optional) Set a timeout for requests: `PERPLEXITY_TIMEOUT_MS=600000` (default: 5 minutes)
+
+### Claude Code
+
+Run in your terminal:
+
+```bash
+claude mcp add perplexity --transport stdio --env PERPLEXITY_API_KEY=your_key_here -- npx -y perplexity-mcp
+```
+
+Or add to your `claude.json`:
+
+```json
+"mcpServers": {
+  "perplexity": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "perplexity-mcp"],
+    "env": {
+      "PERPLEXITY_API_KEY": "your_key_here",
+      "PERPLEXITY_TIMEOUT_MS": "600000"
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "perplexity": {
+      "command": "npx",
+      "args": ["-y", "@perplexity-ai/mcp-server"],
+      "env": {
+        "PERPLEXITY_API_KEY": "your_key_here",
+        "PERPLEXITY_TIMEOUT_MS": "600000"
+      }
+    }
+  }
+}
+```
+
+### Codex
+
+Run in your terminal:
+
+```bash
+codex mcp add perplexity --env PERPLEXITY_API_KEY=your_key_here -- npx -y @perplexity-ai/mcp-server
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "perplexity": {
+      "command": "npx",
+      "args": ["-y", "@perplexity-ai/mcp-server"],
+      "env": {
+        "PERPLEXITY_API_KEY": "your_key_here",
+        "PERPLEXITY_TIMEOUT_MS": "600000"
+      }
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+For any MCP-compatible client, use:
+
+```bash
+npx @perplexity-ai/mcp-server
+```
+
+## 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 long research queries, increase `PERPLEXITY_TIMEOUT_MS`
+
+For support, visit [community.perplexity.ai](https://community.perplexity.ai) or [file an issue](https://github.com/perplexityai/modelcontextprotocol/issues).

package/dist/buildCommonOptions.test.js

@@ -0,0 +1,183 @@
+import { describe, it, expect } from "vitest";
+import { buildCommonOptions, MAX_DOMAIN_FILTERS, MAX_BATCH_QUERIES, DEFAULT_MODEL, DEFAULT_TIMEOUT_MS, } from "./utils.js";
+describe("buildCommonOptions", () => {
+    describe("search_domain_filter validation", () => {
+        it("should extract valid string array for search_domain_filter", () => {
+            const args = { search_domain_filter: ["example.com", "test.org"] };
+            const result = buildCommonOptions(args);
+            expect(result.search_domain_filter).toEqual(["example.com", "test.org"]);
+        });
+        it("should filter out non-string values from search_domain_filter", () => {
+            const args = { search_domain_filter: ["valid.com", 123, null, "also-valid.org"] };
+            const result = buildCommonOptions(args);
+            expect(result.search_domain_filter).toEqual(["valid.com", "also-valid.org"]);
+        });
+        it("should not set search_domain_filter for empty array", () => {
+            const args = { search_domain_filter: [] };
+            const result = buildCommonOptions(args);
+            expect(result.search_domain_filter).toBeUndefined();
+        });
+        it("should not set search_domain_filter for non-array", () => {
+            const args = { search_domain_filter: "not-an-array" };
+            const result = buildCommonOptions(args);
+            expect(result.search_domain_filter).toBeUndefined();
+        });
+    });
+    describe("temperature validation", () => {
+        it("should extract valid temperature", () => {
+            const args = { temperature: 0.5 };
+            const result = buildCommonOptions(args);
+            expect(result.temperature).toBe(0.5);
+        });
+        it("should accept temperature at boundaries (0 and 2)", () => {
+            expect(buildCommonOptions({ temperature: 0 }).temperature).toBe(0);
+            expect(buildCommonOptions({ temperature: 2 }).temperature).toBe(2);
+        });
+        it("should not set temperature for non-number", () => {
+            const args = { temperature: "0.5" };
+            const result = buildCommonOptions(args);
+            expect(result.temperature).toBeUndefined();
+        });
+    });
+    describe("max_tokens validation", () => {
+        it("should extract valid max_tokens", () => {
+            const args = { max_tokens: 1000 };
+            const result = buildCommonOptions(args);
+            expect(result.max_tokens).toBe(1000);
+        });
+        it("should not set max_tokens for non-number", () => {
+            const args = { max_tokens: "1000" };
+            const result = buildCommonOptions(args);
+            expect(result.max_tokens).toBeUndefined();
+        });
+    });
+    describe("top_p validation", () => {
+        it("should extract valid top_p", () => {
+            const args = { top_p: 0.9 };
+            const result = buildCommonOptions(args);
+            expect(result.top_p).toBe(0.9);
+        });
+        it("should accept top_p at boundaries (0 and 1)", () => {
+            expect(buildCommonOptions({ top_p: 0 }).top_p).toBe(0);
+            expect(buildCommonOptions({ top_p: 1 }).top_p).toBe(1);
+        });
+        it("should not set top_p for non-number", () => {
+            const args = { top_p: "0.9" };
+            const result = buildCommonOptions(args);
+            expect(result.top_p).toBeUndefined();
+        });
+    });
+    describe("top_k validation", () => {
+        it("should extract valid top_k", () => {
+            const args = { top_k: 50 };
+            const result = buildCommonOptions(args);
+            expect(result.top_k).toBe(50);
+        });
+        it("should accept top_k of 0 (disabled)", () => {
+            const args = { top_k: 0 };
+            const result = buildCommonOptions(args);
+            expect(result.top_k).toBe(0);
+        });
+        it("should not set top_k for non-number", () => {
+            const args = { top_k: "50" };
+            const result = buildCommonOptions(args);
+            expect(result.top_k).toBeUndefined();
+        });
+    });
+    describe("search_mode validation", () => {
+        it("should extract valid search_mode values", () => {
+            expect(buildCommonOptions({ search_mode: "web" }).search_mode).toBe("web");
+            expect(buildCommonOptions({ search_mode: "academic" }).search_mode).toBe("academic");
+            expect(buildCommonOptions({ search_mode: "sec" }).search_mode).toBe("sec");
+        });
+        it("should not set invalid search_mode", () => {
+            const args = { search_mode: "invalid" };
+            const result = buildCommonOptions(args);
+            expect(result.search_mode).toBeUndefined();
+        });
+        it("should not set search_mode for non-string", () => {
+            const args = { search_mode: 123 };
+            const result = buildCommonOptions(args);
+            expect(result.search_mode).toBeUndefined();
+        });
+    });
+    describe("search_recency_filter validation", () => {
+        it("should extract valid search_recency_filter values", () => {
+            expect(buildCommonOptions({ search_recency_filter: "day" }).search_recency_filter).toBe("day");
+            expect(buildCommonOptions({ search_recency_filter: "week" }).search_recency_filter).toBe("week");
+            expect(buildCommonOptions({ search_recency_filter: "month" }).search_recency_filter).toBe("month");
+            expect(buildCommonOptions({ search_recency_filter: "year" }).search_recency_filter).toBe("year");
+        });
+        it("should not set invalid search_recency_filter", () => {
+            const args = { search_recency_filter: "hour" };
+            const result = buildCommonOptions(args);
+            expect(result.search_recency_filter).toBeUndefined();
+        });
+    });
+    describe("date filters", () => {
+        it("should extract date filter strings", () => {
+            const args = {
+                search_after_date: "01/01/2024",
+                search_before_date: "12/31/2024",
+                last_updated_after: "06/01/2024",
+                last_updated_before: "09/30/2024",
+            };
+            const result = buildCommonOptions(args);
+            expect(result.search_after_date).toBe("01/01/2024");
+            expect(result.search_before_date).toBe("12/31/2024");
+            expect(result.last_updated_after).toBe("06/01/2024");
+            expect(result.last_updated_before).toBe("09/30/2024");
+        });
+        it("should not set date filters for non-strings", () => {
+            const args = {
+                search_after_date: 123,
+                search_before_date: null,
+            };
+            const result = buildCommonOptions(args);
+            expect(result.search_after_date).toBeUndefined();
+            expect(result.search_before_date).toBeUndefined();
+        });
+    });
+    describe("boolean options", () => {
+        it("should extract return_images when true", () => {
+            const args = { return_images: true };
+            const result = buildCommonOptions(args);
+            expect(result.return_images).toBe(true);
+        });
+        it("should not set return_images when false", () => {
+            const args = { return_images: false };
+            const result = buildCommonOptions(args);
+            expect(result.return_images).toBeUndefined();
+        });
+        it("should extract return_related_questions when true", () => {
+            const args = { return_related_questions: true };
+            const result = buildCommonOptions(args);
+            expect(result.return_related_questions).toBe(true);
+        });
+        it("should not set return_related_questions when false", () => {
+            const args = { return_related_questions: false };
+            const result = buildCommonOptions(args);
+            expect(result.return_related_questions).toBeUndefined();
+        });
+    });
+    describe("empty input", () => {
+        it("should return empty object for empty args", () => {
+            const result = buildCommonOptions({});
+            expect(result).toEqual({});
+        });
+    });
+});
+describe("Constants", () => {
+    it("should have correct MAX_DOMAIN_FILTERS value", () => {
+        expect(MAX_DOMAIN_FILTERS).toBe(20);
+    });
+    it("should have correct MAX_BATCH_QUERIES value", () => {
+        expect(MAX_BATCH_QUERIES).toBe(5);
+    });
+    it("should have correct DEFAULT_MODEL value", () => {
+        expect(DEFAULT_MODEL).toBe("sonar-pro");
+    });
+    it("should have correct DEFAULT_TIMEOUT_MS value", () => {
+        expect(DEFAULT_TIMEOUT_MS).toBe(300000);
+    });
+});

package/dist/formatMultiQueryResults.test.js

@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import { formatMultiQueryResults, } from "./utils.js";
+describe("formatMultiQueryResults", () => {
+    it("should format a single query result", () => {
+        const results = [
+            {
+                query: "test query",
+                data: {
+                    results: [{ title: "Result 1", url: "https://example.com" }],
+                },
+                error: null,
+            },
+        ];
+        const result = formatMultiQueryResults(results);
+        expect(result).toContain('## Query 1: "test query"');
+        expect(result).toContain("Found 1 results");
+        expect(result).toContain("**Result 1**");
+    });
+    it("should format multiple query results", () => {
+        const results = [
+            {
+                query: "first query",
+                data: {
+                    results: [{ title: "First Result", url: "https://first.com" }],
+                },
+                error: null,
+            },
+            {
+                query: "second query",
+                data: {
+                    results: [{ title: "Second Result", url: "https://second.com" }],
+                },
+                error: null,
+            },
+        ];
+        const result = formatMultiQueryResults(results);
+        expect(result).toContain('## Query 1: "first query"');
+        expect(result).toContain('## Query 2: "second query"');
+        expect(result).toContain("**First Result**");
+        expect(result).toContain("**Second Result**");
+        expect(result).toContain("---"); // Separator between queries
+    });
+    it("should format a query with error", () => {
+        const results = [
+            {
+                query: "error query",
+                data: null,
+                error: "API rate limit exceeded",
+            },
+        ];
+        const result = formatMultiQueryResults(results);
+        expect(result).toContain('## Query 1: "error query"');
+        expect(result).toContain("**Error:** API rate limit exceeded");
+    });
+    it("should format mixed success and error results", () => {
+        const results = [
+            {
+                query: "successful query",
+                data: {
+                    results: [{ title: "Good Result", url: "https://good.com" }],
+                },
+                error: null,
+            },
+            {
+                query: "failed query",
+                data: null,
+                error: "Network timeout",
+            },
+        ];
+        const result = formatMultiQueryResults(results);
+        expect(result).toContain('## Query 1: "successful query"');
+        expect(result).toContain("**Good Result**");
+        expect(result).toContain('## Query 2: "failed query"');
+        expect(result).toContain("**Error:** Network timeout");
+    });
+    it("should handle query with null data and no error", () => {
+        const results = [
+            {
+                query: "empty query",
+                data: null,
+                error: null,
+            },
+        ];
+        const result = formatMultiQueryResults(results);
+        expect(result).toContain('## Query 1: "empty query"');
+        expect(result).toContain("No search results found.");
+    });
+});

package/dist/formatSearchResults.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+import { formatSearchResults, } from "./utils.js";
+describe("formatSearchResults", () => {
+    it("should return 'No search results found.' for empty results array", () => {
+        const data = { results: [] };
+        const result = formatSearchResults(data);
+        expect(result).toContain("Found 0 search results");
+    });
+    it("should return 'No search results found.' for undefined results", () => {
+        const data = {};
+        const result = formatSearchResults(data);
+        expect(result).toBe("No search results found.");
+    });
+    it("should format a single result with all fields", () => {
+        const data = {
+            results: [
+                {
+                    title: "Test Title",
+                    url: "https://example.com",
+                    snippet: "This is a test snippet",
+                    date: "2024-01-15",
+                },
+            ],
+        };
+        const result = formatSearchResults(data);
+        expect(result).toContain("Found 1 search results");
+        expect(result).toContain("**Test Title**");
+        expect(result).toContain("URL: https://example.com");
+        expect(result).toContain("This is a test snippet");
+        expect(result).toContain("Date: 2024-01-15");
+    });
+    it("should format multiple results", () => {
+        const data = {
+            results: [
+                { title: "First Result", url: "https://first.com" },
+                { title: "Second Result", url: "https://second.com" },
+                { title: "Third Result", url: "https://third.com" },
+            ],
+        };
+        const result = formatSearchResults(data);
+        expect(result).toContain("Found 3 search results");
+        expect(result).toContain("1. **First Result**");
+        expect(result).toContain("2. **Second Result**");
+        expect(result).toContain("3. **Third Result**");
+    });
+    it("should handle missing optional fields (snippet, date)", () => {
+        const data = {
+            results: [{ title: "Title Only", url: "https://example.com" }],
+        };
+        const result = formatSearchResults(data);
+        expect(result).toContain("**Title Only**");
+        expect(result).toContain("URL: https://example.com");
+        expect(result).not.toContain("Date:");
+    });
+});