@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-esbuild-bundle-worker-20260807182016

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

@@ -0,0 +1,155 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Perplexity tools
+
+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` isn't 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/.docs/reference/tools/submit-plan-tool.md

@@ -0,0 +1,93 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# submitPlanTool
+
+A built-in, agent-agnostic tool that submits an implementation plan for user review. The agent writes a plan to a markdown file and passes the file path to this tool. The tool suspends the run until the user approves or rejects the plan.
+
+The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/agent-approval) primitive: it calls `suspend({ path })`, which makes the agent emit a `tool-call-suspended` event. The host reads the plan file and presents it to the user. It then resumes with an approval or rejection.
+
+When executed outside an agent run (no `suspend` available), the tool returns a readable fallback string containing the file path.
+
+## Usage example
+
+Add `submitPlanTool` to an agent's toolset:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { submitPlanTool } from '@mastra/core/tools'
+
+const agent = new Agent({
+  id: 'planner',
+  name: 'Planner',
+  instructions: 'Write a plan to a file before starting work, then submit it for approval.',
+  model,
+  tools: { submitPlanTool },
+})
+```
+
+Handle the suspension and resume:
+
+```typescript
+import fs from 'node:fs'
+
+const stream = await agent.stream('Refactor the auth module')
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'tool-call-suspended' && chunk.payload.toolName === 'submit_plan') {
+    const { path } = chunk.payload.suspendPayload
+    const plan = fs.readFileSync(path, 'utf-8')
+    console.log(plan)
+
+    // Approve:
+    const resumed = await agent.resumeStream({ action: 'approved' }, { runId: stream.runId })
+    for await (const c of resumed.textStream) process.stdout.write(c)
+  }
+}
+```
+
+To reject with feedback:
+
+```typescript
+await agent.resumeStream(
+  { action: 'rejected', feedback: 'Add error handling steps' },
+  { runId: stream.runId },
+)
+```
+
+## Input schema
+
+The model calls this tool with the following parameters:
+
+**path** (`string`): Path to the plan markdown file on disk (e.g. '.mastracode/plans/add-dark-mode.md').
+
+## Suspend payload
+
+The `tool-call-suspended` event carries a `suspendPayload`:
+
+**path** (`string`): Path to the plan file the agent wrote.
+
+**title** (`string`): Plan title, filled by the host after reading the file.
+
+**plan** (`string`): Plan body, filled by the host after reading the file.
+
+## Resume data
+
+Pass an object to `agent.resumeStream()`:
+
+**action** (`'approved' | 'rejected'`): Whether the user approved or rejected the plan.
+
+**feedback** (`string`): Revision instructions when the plan is rejected. Surfaced to the model so it can revise and resubmit.
+
+**path** (`string`): The plan file path, echoed back for history replay.
+
+**title** (`string`): The plan title, echoed back for history replay.
+
+**plan** (`string`): The plan body, echoed back for history replay.
+
+## Approval behavior
+
+- **Approved:** The tool returns `"Plan approved. Proceed with implementation following the approved plan."` to the model.
+- **Rejected with feedback:** The tool returns the feedback and asks the model to revise the plan and submit again.
+- **Rejected without feedback:** The tool tells the model to wait for the user's next message before revising.
+
+When used inside an [AgentController](https://mastra.ai/docs/harness/agent-controller), plan approval switches from the current mode to the mode configured by `transitionsTo`. When no `transitionsTo` is configured, the controller switches to its resolved default mode. See [Modes](https://mastra.ai/docs/harness/agent-controller) for details.

package/.docs/reference/tools/task-tools.md

@@ -0,0 +1,132 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Task tools
+
+Four built-in, agent-agnostic tools that manage a structured task list for an agent run. The task list is persisted in the thread-scoped `threadState` storage domain and projected onto the agent [state-signal](https://mastra.ai/docs/long-running-agents/signals) lane so it survives [observational-memory](https://mastra.ai/docs/memory/observational-memory) truncation.
+
+Task tracking requires a memory-backed thread (`threadId` + `resourceId`). Without memory the tools return an error explaining that task tracking requires agent memory.
+
+The recommended setup is [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider), which bundles all four tools and the `TaskStateProcessor` in a single registration. See [Built-in tools](https://mastra.ai/docs/agents/using-tools) for the conceptual guide.
+
+## Usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { TaskSignalProvider } from '@mastra/core/signals'
+
+const agent = new Agent({
+  id: 'coder',
+  name: 'Coder',
+  instructions: 'Track your progress with the task tools.',
+  model,
+  memory: new Memory(),
+  signals: [new TaskSignalProvider()],
+})
+```
+
+Or import the tools directly:
+
+```typescript
+import { taskWriteTool, taskUpdateTool, taskCompleteTool, taskCheckTool } from '@mastra/core/tools'
+
+const agent = new Agent({
+  id: 'coder',
+  name: 'Coder',
+  instructions: 'Track your progress with the task tools.',
+  model,
+  memory: new Memory(),
+  tools: { taskWriteTool, taskUpdateTool, taskCompleteTool, taskCheckTool },
+})
+```
+
+## `task_write`
+
+Create or replace the entire task list. Each call replaces the previous list.
+
+### Input schema
+
+**tasks** (`TaskItemInput[]`): The complete updated task list.
+
+**tasks.id** (`string`): Stable task identifier (e.g. 'task\_investigate\_tests'). Keep this unchanged across updates. Auto-generated when omitted.
+
+**tasks.content** (`string`): Task description in imperative form (e.g. 'Fix authentication bug').
+
+**tasks.status** (`'pending' | 'in_progress' | 'completed'`): Current task status.
+
+**tasks.activeForm** (`string`): Present continuous form shown during execution (e.g. 'Fixing authentication bug').
+
+### Output
+
+Returns a `TaskToolResult` with a human-readable `content` summary, the full `tasks` array with assigned IDs, and an `isError` flag.
+
+### Behavior
+
+- IDs must be unique within a call. Duplicate explicit IDs get a generated fallback.
+- When an ID is omitted while rewriting an existing list, one unambiguous matching task reuses its previous ID for stability.
+- Only one task can have `in_progress` status at a time. Submitting multiple `in_progress` tasks returns an error.
+
+## `task_update`
+
+Update one task by its stable ID. Include only the fields that changed.
+
+### Input schema
+
+**id** (`string`): The stable task identifier to update.
+
+**content** (`string`): New task description in imperative form.
+
+**status** (`'pending' | 'in_progress' | 'completed'`): New task status.
+
+**activeForm** (`string`): New present continuous form.
+
+At least one of `content`, `status`, or `activeForm` is required.
+
+### Behavior
+
+- When the update sets a task to `in_progress`, any other `in_progress` task is automatically demoted to `pending`.
+- Returns an error with available task IDs when the ID isn't found.
+
+## `task_complete`
+
+Mark one task completed by its stable ID.
+
+### Input schema
+
+**id** (`string`): The stable task identifier to mark completed.
+
+### Behavior
+
+Returns an error with available task IDs when the ID isn't found.
+
+## `task_check`
+
+Check the completion status of the task list. Takes no input parameters.
+
+### Output
+
+Returns a `TaskCheckResult` with:
+
+**content** (`string`): Human-readable summary with task counts and incomplete task IDs.
+
+**tasks** (`TaskItem[]`): Full task list snapshot with stable IDs.
+
+**summary** (`TaskCheckSummary`): Structured counts.
+
+**summary.total** (`number`): Total tracked tasks.
+
+**summary.completed** (`number`): Completed tasks.
+
+**summary.inProgress** (`number`): In-progress tasks.
+
+**summary.pending** (`number`): Pending tasks.
+
+**summary.incomplete** (`number`): Tasks not yet completed (in-progress + pending).
+
+**summary.hasTasks** (`boolean`): True when at least one task exists.
+
+**summary.allCompleted** (`boolean`): True when at least one task exists and every task is completed.
+
+**incompleteTasks** (`TaskItem[]`): Tasks that still need work (in-progress and pending).
+
+**isError** (`boolean`): Whether the check encountered an error.

package/.docs/reference/tools/tavily.md

@@ -0,0 +1,307 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Tavily tools
+
+The `@mastra/tavily` package wraps the [Tavily](https://app.tavily.com) API as Mastra-compatible tools. It exposes factory functions for search, extract, crawl, and map. Each function returns a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) that includes full Zod input/output schemas.
+
+## Installation
+
+**npm**:
+
+```sh
+npm install @mastra/tavily @tavily/core zod
+```
+
+**pnpm**:
+
+```sh
+pnpm add @mastra/tavily @tavily/core zod
+```
+
+**Yarn**:
+
+```sh
+yarn add @mastra/tavily @tavily/core zod
+```
+
+**Bun**:
+
+```sh
+bun add @mastra/tavily @tavily/core zod
+```
+
+## Quick start
+
+Use `createTavilyTools()` to get all four tools with shared configuration:
+
+```typescript
+import { createTavilyTools } from '@mastra/tavily'
+
+const tools = createTavilyTools()
+// Or pass an explicit API key:
+// const tools = createTavilyTools({ apiKey: 'tvly-...' })
+```
+
+Each tool can also be created individually:
+
+```typescript
+import { createTavilySearchTool, createTavilyExtractTool } from '@mastra/tavily'
+
+const searchTool = createTavilySearchTool()
+const extractTool = createTavilyExtractTool({ apiKey: 'tvly-...' })
+```
+
+By default, all tools read `TAVILY_API_KEY` from the environment. You can pass `{ apiKey }` explicitly to override.
+
+## Configuration
+
+All factory functions accept `TavilyClientOptions` from `@tavily/core`:
+
+**apiKey** (`string`): Tavily API key. Falls back to the TAVILY\_API\_KEY environment variable.
+
+**clientName** (`string`): Attribution string sent with each request in the X-Client-Name header. (Default: `'mastra'`)
+
+**apiBaseURL** (`string`): Base URL for the Tavily API.
+
+**proxies** (`object`): Proxy configuration passed to the underlying HTTP client.
+
+**projectId** (`string`): Tavily project ID for request scoping.
+
+## `createTavilyTools()`
+
+Returns an object containing all four tools with a shared configuration.
+
+```typescript
+import { createTavilyTools } from '@mastra/tavily'
+
+const tools = createTavilyTools({ apiKey: 'tvly-...' })
+// tools.tavilySearch, tools.tavilyExtract, tools.tavilyCrawl, tools.tavilyMap
+```
+
+**Returns:** `{ tavilySearch, tavilyExtract, tavilyCrawl, tavilyMap }`
+
+## `createTavilySearchTool()`
+
+Creates a tool that searches the web using Tavily. Returns relevant results with content snippets, optional AI-generated answers, and images.
+
+**Tool ID:** `tavily-search`
+
+```typescript
+import { createTavilySearchTool } from '@mastra/tavily'
+
+const searchTool = createTavilySearchTool()
+```
+
+### Input
+
+**query** (`string`): The search query.
+
+**searchDepth** (`'basic' | 'advanced' | 'fast' | 'ultra-fast'`): Search depth. Use 'basic' for standard results, 'advanced' for more thorough results, or 'fast'/'ultra-fast' for low latency.
+
+**maxResults** (`number`): Maximum number of results to return (1-20).
+
+**includeAnswer** (`boolean | 'basic' | 'advanced'`): Include an AI-generated answer summary.
+
+**includeImages** (`boolean`): Include query-related images in the response.
+
+**includeImageDescriptions** (`boolean`): Include descriptions for returned images.
+
+**includeRawContent** (`false | 'markdown' | 'text'`): Include cleaned HTML content of each result. Pass false to disable, or 'markdown'/'text' for format.
+
+**includeDomains** (`string[]`): Restrict results to these domains.
+
+**excludeDomains** (`string[]`): Exclude results from these domains.
+
+**timeRange** (`'day' | 'week' | 'month' | 'year'`): Filter results by recency.
+
+### Output
+
+**query** (`string`): The original search query.
+
+**answer** (`string`): AI-generated answer summary.
+
+**images** (`{ url: string; description?: string }[]`): Related images.
+
+**results** (`SearchResult[]`): Array of search results.
+
+**results.title** (`string`): Result title.
+
+**results.url** (`string`): Result URL.
+
+**results.content** (`string`): Content snippet.
+
+**results.score** (`number`): Relevance score.
+
+**results.rawContent** (`string`): Full-page content (when requested).
+
+**responseTime** (`number`): Server response time in seconds.
+
+## `createTavilyExtractTool()`
+
+Creates a tool that extracts content from one or more URLs. Returns raw page content in markdown or text format with up to 20 URLs per request.
+
+**Tool ID:** `tavily-extract`
+
+```typescript
+import { createTavilyExtractTool } from '@mastra/tavily'
+
+const extractTool = createTavilyExtractTool()
+```
+
+### Input
+
+**urls** (`string[]`): URLs to extract content from (1-20).
+
+**extractDepth** (`'basic' | 'advanced'`): Extraction depth. Use 'advanced' to retrieve tables and embedded content.
+
+**query** (`string`): User intent for reranking extracted content chunks by relevance.
+
+**includeImages** (`boolean`): Include images extracted from the pages.
+
+**format** (`'markdown' | 'text'`): Output format for extracted content. (Default: `'markdown'`)
+
+### Output
+
+**results** (`ExtractResult[]`): Successfully extracted pages.
+
+**results.url** (`string`): Page URL.
+
+**results.rawContent** (`string`): Extracted page content.
+
+**results.images** (`string[]`): Extracted image URLs.
+
+**failedResults** (`FailedResult[]`): URLs that failed extraction.
+
+**failedResults.url** (`string`): Failed URL.
+
+**failedResults.error** (`string`): Error message.
+
+**responseTime** (`number`): Server response time in seconds.
+
+## `createTavilyCrawlTool()`
+
+Creates a tool that crawls a website starting from a URL. Extracts content from discovered pages with configurable depth, breadth, and domain constraints.
+
+**Tool ID:** `tavily-crawl`
+
+```typescript
+import { createTavilyCrawlTool } from '@mastra/tavily'
+
+const crawlTool = createTavilyCrawlTool()
+```
+
+### Input
+
+**url** (`string`): The root URL to begin the crawl.
+
+**maxDepth** (`number`): Maximum depth of the crawl from the base URL.
+
+**maxBreadth** (`number`): Maximum number of links to follow per page.
+
+**limit** (`number`): Total number of pages the crawler processes before stopping.
+
+**instructions** (`string`): Natural language instructions for the crawler.
+
+**selectPaths** (`string[]`): Regex patterns to select specific URL paths.
+
+**selectDomains** (`string[]`): Regex patterns to restrict to specific domains.
+
+**excludePaths** (`string[]`): Regex patterns to exclude specific URL paths.
+
+**excludeDomains** (`string[]`): Regex patterns to exclude specific domains.
+
+**allowExternal** (`boolean`): Whether to follow links to external domains.
+
+**extractDepth** (`'basic' | 'advanced'`): Extraction depth. Use 'advanced' to retrieve tables and embedded content.
+
+**includeImages** (`boolean`): Include images from crawled pages.
+
+**format** (`'markdown' | 'text'`): Output format for extracted content. (Default: `'markdown'`)
+
+### Output
+
+**baseUrl** (`string`): The root URL that was crawled.
+
+**results** (`CrawlResult[]`): Content extracted from discovered pages.
+
+**results.url** (`string`): Page URL.
+
+**results.rawContent** (`string`): Extracted page content.
+
+**results.images** (`string[]`): Image URLs found on the page.
+
+**responseTime** (`number`): Server response time in seconds.
+
+## `createTavilyMapTool()`
+
+Creates a tool that maps a website's structure starting from a URL. Discovers and returns a list of URLs without extracting page content. Use this to understand site structure before targeted extraction.
+
+**Tool ID:** `tavily-map`
+
+```typescript
+import { createTavilyMapTool } from '@mastra/tavily'
+
+const mapTool = createTavilyMapTool()
+```
+
+### Input
+
+**url** (`string`): The root URL to begin mapping.
+
+**maxDepth** (`number`): Maximum depth of the mapping from the base URL.
+
+**maxBreadth** (`number`): Maximum number of links to follow per page.
+
+**limit** (`number`): Total number of links the mapper processes before stopping.
+
+**instructions** (`string`): Natural language instructions for the mapper.
+
+**selectPaths** (`string[]`): Regex patterns to select specific URL paths.
+
+**selectDomains** (`string[]`): Regex patterns to restrict to specific domains.
+
+**excludePaths** (`string[]`): Regex patterns to exclude specific URL paths.
+
+**excludeDomains** (`string[]`): Regex patterns to exclude specific domains.
+
+**allowExternal** (`boolean`): Whether to include external domain links.
+
+### Output
+
+**baseUrl** (`string`): The root URL that was mapped.
+
+**results** (`string[]`): Discovered URLs.
+
+**responseTime** (`number`): Server response time in seconds.
+
+## Agent example
+
+The following example demonstrates a research agent that combines search and extract:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createTavilySearchTool, createTavilyExtractTool } from '@mastra/tavily'
+
+const agent = new Agent({
+  id: 'web-search-agent',
+  name: 'Web Search Agent',
+  model: 'anthropic/claude-sonnet-4-6',
+  instructions:
+    'You are a web search assistant. Use search tool to find relevant pages, then use extract tool to get full content from the best results.',
+  tools: {
+    search: createTavilySearchTool(),
+    extract: createTavilyExtractTool(),
+  },
+})
+```
+
+## Environment variables
+
+| Variable         | Description                                                                                |
+| ---------------- | ------------------------------------------------------------------------------------------ |
+| `TAVILY_API_KEY` | Your Tavily API key. Used as the default when `apiKey` isn't passed to a factory function. |
+
+## Related
+
+- [`createTool()`](https://mastra.ai/reference/tools/create-tool)
+- [Tavily API documentation](https://docs.tavily.com)