@mastra/mcp-docs-server 1.1.32-alpha.2 → 1.1.32-alpha.3

package/.docs/reference/index.md

@@ -224,6 +224,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [createVectorQueryTool()](https://mastra.ai/reference/tools/vector-query-tool)
 - [MCPClient](https://mastra.ai/reference/tools/mcp-client)
 - [MCPServer](https://mastra.ai/reference/tools/mcp-server)
+- [Perplexity Tools](https://mastra.ai/reference/tools/perplexity)
 - [Tavily Tools](https://mastra.ai/reference/tools/tavily)
 - [Amazon S3 Vector Store](https://mastra.ai/reference/vectors/s3vectors)
 - [Astra Vector Store](https://mastra.ai/reference/vectors/astra)

package/.docs/reference/tools/perplexity.md

@@ -0,0 +1,155 @@
+# Perplexity tools
+
+Added in: `@mastra/perplexity@0.1.0-alpha.0`
+
+The `@mastra/perplexity` package wraps the [Perplexity Search API](https://docs.perplexity.ai/docs/search/quickstart) as a Mastra-compatible tool. It exposes a factory function that returns a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) and full Zod input/output schemas.
+
+For chat completions or agentic workflows powered by Perplexity, use Mastra's built-in [Perplexity model provider](https://mastra.ai/models/providers/perplexity) or [Perplexity Agent provider](https://mastra.ai/models/providers/perplexity-agent). Those are separate from this Search tool.
+
+## Installation
+
+Install the package alongside Zod:
+
+**npm**:
+
+```sh
+npm install @mastra/perplexity zod
+```
+
+**pnpm**:
+
+```sh
+pnpm add @mastra/perplexity zod
+```
+
+**Yarn**:
+
+```sh
+yarn add @mastra/perplexity zod
+```
+
+**Bun**:
+
+```sh
+bun add @mastra/perplexity zod
+```
+
+## Usage example
+
+The following example creates the search tool with the default configuration. By default, the tool reads `PERPLEXITY_API_KEY` (with `PPLX_API_KEY` as a fallback) from the environment. Pass `{ apiKey }` explicitly to override.
+
+```typescript
+import { createPerplexitySearchTool } from '@mastra/perplexity'
+
+const searchTool = createPerplexitySearchTool()
+```
+
+To pass an API key explicitly:
+
+```typescript
+import { createPerplexitySearchTool } from '@mastra/perplexity'
+
+const searchTool = createPerplexitySearchTool({ apiKey: 'pplx-...' })
+```
+
+## Configuration
+
+All factory functions accept a `PerplexityClientOptions` object:
+
+**apiKey** (`string`): Perplexity API key. Falls back to the \`PERPLEXITY\_API\_KEY\` then \`PPLX\_API\_KEY\` environment variables.
+
+**baseUrl** (`string`): Override the API base URL. (Default: `'https://api.perplexity.ai'`)
+
+**fetch** (`typeof fetch`): Custom \`fetch\` implementation. Useful for tests, retries, or instrumentation.
+
+## Methods
+
+### Factory functions
+
+#### `createPerplexityTools(config?)`
+
+Returns an object containing all Perplexity tools that share the supplied configuration.
+
+```typescript
+import { createPerplexityTools } from '@mastra/perplexity'
+
+const tools = createPerplexityTools({ apiKey: 'pplx-...' })
+// tools.perplexitySearch
+```
+
+Returns: `{ perplexitySearch }`
+
+#### `createPerplexitySearchTool(config?)`
+
+Creates a tool that searches the web using the Perplexity Search API. Returns ranked results with titles, URLs, snippets, and optional publication dates.
+
+The tool is registered with the ID `perplexity-search`.
+
+```typescript
+import { createPerplexitySearchTool } from '@mastra/perplexity'
+
+const searchTool = createPerplexitySearchTool()
+```
+
+##### Input
+
+**query** (`string`): The search query.
+
+**maxResults** (`number`): Maximum number of results to return (1-20).
+
+**searchDomainFilter** (`string[]`): Restrict (or exclude) results by domain. Prefix a domain with \`-\` to exclude it (for example, \`-pinterest.com\`). Do not mix allow- and deny-list entries in the same call.
+
+**searchRecencyFilter** (`'hour' | 'day' | 'week' | 'month' | 'year'`): Only return results from within the given recency window.
+
+**searchAfterDateFilter** (`string`): Only return results published on or after this date. Format: m/d/yyyy.
+
+**searchBeforeDateFilter** (`string`): Only return results published on or before this date. Format: m/d/yyyy.
+
+##### Output
+
+**query** (`string`): The original search query.
+
+**results** (`SearchResult[]`): Array of search results.
+
+**results.title** (`string`): Result title.
+
+**results.url** (`string`): Result URL.
+
+**results.snippet** (`string`): Content snippet.
+
+**results.date** (`string`): Publication date when available.
+
+## Agent example
+
+The following example registers the search tool on an agent so it can fetch fresh web results before answering.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createPerplexitySearchTool } from '@mastra/perplexity'
+
+const agent = new Agent({
+  id: 'research-agent',
+  name: 'Research Agent',
+  model: 'anthropic/claude-sonnet-4-6',
+  instructions:
+    'You are a research assistant. Use the perplexity-search tool to find up-to-date information from the web before answering.',
+  tools: {
+    search: createPerplexitySearchTool(),
+  },
+})
+```
+
+## Environment variables
+
+| Variable             | Description                                                                                     |
+| -------------------- | ----------------------------------------------------------------------------------------------- |
+| `PERPLEXITY_API_KEY` | Your Perplexity API key. Used as the default when `apiKey` is not passed to a factory function. |
+| `PPLX_API_KEY`       | Fallback used when `PERPLEXITY_API_KEY` is unset.                                               |
+
+## Related
+
+- [`createTool()`](https://mastra.ai/reference/tools/create-tool)
+- [Perplexity Search quickstart](https://docs.perplexity.ai/docs/search/quickstart)
+- [Perplexity Agent quickstart](https://docs.perplexity.ai/docs/agent/quickstart)
+- [Perplexity model provider](https://mastra.ai/models/providers/perplexity)
+- [Perplexity Agent provider](https://mastra.ai/models/providers/perplexity-agent)

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.1.32-alpha.3
+
+### Patch Changes
+
+- Updated dependencies [[`2b0f355`](https://github.com/mastra-ai/mastra/commit/2b0f3553be3e9e5524da539a66e5cf82668440a4)]:
+  - @mastra/core@1.31.0-alpha.2
+
 ## 1.1.32-alpha.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.32-alpha.2",
+  "version": "1.1.32-alpha.3",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.31.0-alpha.1",
-    "@mastra/mcp": "^1.6.0"
+    "@mastra/mcp": "^1.6.0",
+    "@mastra/core": "1.31.0-alpha.2"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -48,7 +48,7 @@
     "vitest": "4.1.5",
     "@internal/lint": "0.0.89",
     "@internal/types-builder": "0.0.64",
-    "@mastra/core": "1.31.0-alpha.1"
+    "@mastra/core": "1.31.0-alpha.2"
   },
   "homepage": "https://mastra.ai",
   "repository": {