@mastra/mcp-docs-server 1.1.26-alpha.8 → 1.1.26

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

@@ -0,0 +1,307 @@
+# Tavily tools
+
+**Added in:** `@mastra/tavily@0.1.0-alpha.0`
+
+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 returning 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.
+
+**clientSource** (`string`): Attribution string sent with each request. (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` is not passed to a factory function. |
+
+## Related
+
+- [`createTool()`](https://mastra.ai/reference/tools/create-tool)
+- [Tavily API documentation](https://docs.tavily.com)

package/.docs/reference/workflows/run-methods/resume.md

@@ -26,6 +26,8 @@ if (result.status === 'suspended') {
 
 **retryCount** (`number`): Optional retry count for nested workflow execution
 
+**forEachIndex** (`number`): Target a specific iteration of a suspended \`.foreach()\` step. Pass the zero-based index of the iteration you want to resume; other iterations remain suspended. Omit this field to resume all suspended iterations of the step with the same \`resumeData\`.
+
 **tracingContext** (`TracingContext`): Tracing context for creating child spans and adding metadata. Automatically injected when using Mastra's tracing system.
 
 **tracingContext.currentSpan** (`Span`): Current span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.
@@ -67,6 +69,28 @@ if (result.status === 'suspended') {
 
 > **Note:** When exactly one step is suspended, you can omit the `step` parameter and the workflow will automatically resume that step. For workflows with multiple suspended steps, you must explicitly specify which step to resume.
 
+### Resuming a single [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) iteration
+
+When a [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) step suspends across multiple iterations, use `forEachIndex` (zero-based) to resume one iteration at a time with different `resumeData`. Iterations not targeted by `forEachIndex` remain suspended until resumed.
+
+```typescript
+// Resume only the second iteration (index 1) with its own data
+await run.resume({
+  step: 'approve',
+  resumeData: { ok: true },
+  forEachIndex: 1,
+})
+
+// Later, resume the first iteration with different data
+await run.resume({
+  step: 'approve',
+  resumeData: { ok: false },
+  forEachIndex: 0,
+})
+```
+
+If `forEachIndex` is omitted, every suspended iteration of the step is resumed with the same `resumeData`.
+
 ## Related
 
 - [Workflows overview](https://mastra.ai/docs/workflows/overview)

package/.docs/reference/workflows/workflow-methods/foreach.md

@@ -113,6 +113,19 @@ Each progress event payload contains:
 
 **iterationOutput** (`Record<string, any>`): Output of the iteration (present when iterationStatus is 'success')
 
+### Resuming a single iteration
+
+When a step inside `.foreach()` suspends, each iteration suspends independently. Pass `forEachIndex` to [`run.resume()`](https://mastra.ai/reference/workflows/run-methods/resume) to resume one iteration at a time with its own `resumeData`. Omitting `forEachIndex` resumes every suspended iteration with the same data.
+
+```typescript
+await run.resume({
+  step: 'approve',
+  resumeData: { ok: true },
+  forEachIndex: 1,
+})
+```
+
 ## Related
 
-- [Looping with foreach](https://mastra.ai/docs/workflows/control-flow)
+- [Looping with foreach](https://mastra.ai/docs/workflows/control-flow)
+- [run.resume()](https://mastra.ai/reference/workflows/run-methods/resume)

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # @mastra/mcp-docs-server
 
+## 1.1.26
+
+### Patch Changes
+
+- Updated dependencies [[`20f59b8`](https://github.com/mastra-ai/mastra/commit/20f59b876cf91199efbc49a0e36b391240708f08), [`aba393e`](https://github.com/mastra-ai/mastra/commit/aba393e2da7390c69b80e516a4f153cda6f09376), [`3d83d06`](https://github.com/mastra-ai/mastra/commit/3d83d06f776f00fb5f4163dddd32a030c5c20844), [`e2687a7`](https://github.com/mastra-ai/mastra/commit/e2687a7408790c384563816a9a28ed06735684c9), [`fdd54cf`](https://github.com/mastra-ai/mastra/commit/fdd54cf612a9af876e9fdd85e534454f6e7dd518), [`6315317`](https://github.com/mastra-ai/mastra/commit/63153175fe9a7b224e5be7c209bbebc01dd9b0d5), [`a371ac5`](https://github.com/mastra-ai/mastra/commit/a371ac534aa1bb368a1acf9d8b313378dfdc787e), [`0474c2b`](https://github.com/mastra-ai/mastra/commit/0474c2b2e7c7e1ad8691dca031284841391ff1ef), [`0a5fa1d`](https://github.com/mastra-ai/mastra/commit/0a5fa1d3cb0583889d06687155f26fd7d2edc76c), [`7e0e63e`](https://github.com/mastra-ai/mastra/commit/7e0e63e2e485e84442351f4c7a79a424c83539dc), [`ea43e64`](https://github.com/mastra-ai/mastra/commit/ea43e646dd95d507694b6112b0bf1df22ad552b2), [`f607106`](https://github.com/mastra-ai/mastra/commit/f607106854c6416c4a07d4082604b9f66d047221), [`30456b6`](https://github.com/mastra-ai/mastra/commit/30456b6b08c8fd17e109dd093b73d93b65e83bc5), [`9d11a8c`](https://github.com/mastra-ai/mastra/commit/9d11a8c1c8924eb975a245a5884d40ca1b7e0491), [`9d3b24b`](https://github.com/mastra-ai/mastra/commit/9d3b24b19407ae9c09586cf7766d38dc4dff4a69), [`7020c06`](https://github.com/mastra-ai/mastra/commit/7020c0690b199d9da337f0e805f16948e557922e), [`00d1b16`](https://github.com/mastra-ai/mastra/commit/00d1b16b401199cb294fa23f43336547db4dca9b), [`47cee3e`](https://github.com/mastra-ai/mastra/commit/47cee3e137fe39109cf7fffd2a8cf47b76dc702e), [`62919a6`](https://github.com/mastra-ai/mastra/commit/62919a6ee0fbf3779ad21a97b1ec6696515d5104), [`d246696`](https://github.com/mastra-ai/mastra/commit/d246696139a3144a5b21b042d41c532688e957e1), [`354f9ce`](https://github.com/mastra-ai/mastra/commit/354f9ce1ca6af2074b6a196a23f8ec30012dccca), [`16e34ca`](https://github.com/mastra-ai/mastra/commit/16e34caa98b9a114b17a6125e4e3fd87f169d0d0), [`7020c06`](https://github.com/mastra-ai/mastra/commit/7020c0690b199d9da337f0e805f16948e557922e), [`8786a61`](https://github.com/mastra-ai/mastra/commit/8786a61fa54ba265f85eeff9985ca39863d18bb6), [`9467ea8`](https://github.com/mastra-ai/mastra/commit/9467ea87695749a53dfc041576410ebf9ee7bb67), [`7338d94`](https://github.com/mastra-ai/mastra/commit/7338d949380cf68b095342e8e42610dc51d557c1), [`c80dc16`](https://github.com/mastra-ai/mastra/commit/c80dc16e113e6cc159f510ffde501ad4711b2189), [`af8a57e`](https://github.com/mastra-ai/mastra/commit/af8a57ed9ba9685ad8601d5b71ae3706da6222f9), [`d63ffdb`](https://github.com/mastra-ai/mastra/commit/d63ffdbb2c11e76fe5ea45faab44bc15460f010c), [`47cee3e`](https://github.com/mastra-ai/mastra/commit/47cee3e137fe39109cf7fffd2a8cf47b76dc702e), [`1bd5104`](https://github.com/mastra-ai/mastra/commit/1bd51048b6da93507276d6623e3fd96a9e1a8944), [`e9837b5`](https://github.com/mastra-ai/mastra/commit/e9837b53699e18711b09e0ca010a4106376f2653), [`c65aec3`](https://github.com/mastra-ai/mastra/commit/c65aec356cc037ee7c4b30ccea946807d4c4f443), [`8f1b280`](https://github.com/mastra-ai/mastra/commit/8f1b280b7fe6999ec654f160cb69c1a8719e7a57), [`92dcf02`](https://github.com/mastra-ai/mastra/commit/92dcf029294210ac91b090900c1a0555a425c57a), [`0fd90a2`](https://github.com/mastra-ai/mastra/commit/0fd90a215caf5fca8099c15a67ca03e4427747a3), [`8fb2405`](https://github.com/mastra-ai/mastra/commit/8fb2405138f2d208b7962ad03f121ca25bcc28c5), [`12df98c`](https://github.com/mastra-ai/mastra/commit/12df98c4904643d9481f5c78f3bed443725b4c96)]:
+  - @mastra/core@1.26.0
+  - @mastra/mcp@1.5.1
+
+## 1.1.26-alpha.24
+
+### Patch Changes
+
+- Updated dependencies:
+  - @mastra/core@1.26.0-alpha.13
+
+## 1.1.26-alpha.23
+
+### Patch Changes
+
+- Updated dependencies [[`a371ac5`](https://github.com/mastra-ai/mastra/commit/a371ac534aa1bb368a1acf9d8b313378dfdc787e), [`47cee3e`](https://github.com/mastra-ai/mastra/commit/47cee3e137fe39109cf7fffd2a8cf47b76dc702e), [`c80dc16`](https://github.com/mastra-ai/mastra/commit/c80dc16e113e6cc159f510ffde501ad4711b2189), [`47cee3e`](https://github.com/mastra-ai/mastra/commit/47cee3e137fe39109cf7fffd2a8cf47b76dc702e)]:
+  - @mastra/core@1.26.0-alpha.12
+
+## 1.1.26-alpha.21
+
+### Patch Changes
+
+- Updated dependencies [[`20f59b8`](https://github.com/mastra-ai/mastra/commit/20f59b876cf91199efbc49a0e36b391240708f08), [`e2687a7`](https://github.com/mastra-ai/mastra/commit/e2687a7408790c384563816a9a28ed06735684c9), [`8f1b280`](https://github.com/mastra-ai/mastra/commit/8f1b280b7fe6999ec654f160cb69c1a8719e7a57), [`12df98c`](https://github.com/mastra-ai/mastra/commit/12df98c4904643d9481f5c78f3bed443725b4c96)]:
+  - @mastra/core@1.26.0-alpha.11
+
+## 1.1.26-alpha.19
+
+### Patch Changes
+
+- Updated dependencies [[`aba393e`](https://github.com/mastra-ai/mastra/commit/aba393e2da7390c69b80e516a4f153cda6f09376), [`0a5fa1d`](https://github.com/mastra-ai/mastra/commit/0a5fa1d3cb0583889d06687155f26fd7d2edc76c), [`ea43e64`](https://github.com/mastra-ai/mastra/commit/ea43e646dd95d507694b6112b0bf1df22ad552b2), [`00d1b16`](https://github.com/mastra-ai/mastra/commit/00d1b16b401199cb294fa23f43336547db4dca9b), [`af8a57e`](https://github.com/mastra-ai/mastra/commit/af8a57ed9ba9685ad8601d5b71ae3706da6222f9)]:
+  - @mastra/core@1.26.0-alpha.10
+
+## 1.1.26-alpha.17
+
+### Patch Changes
+
+- Updated dependencies [[`16e34ca`](https://github.com/mastra-ai/mastra/commit/16e34caa98b9a114b17a6125e4e3fd87f169d0d0)]:
+  - @mastra/core@1.26.0-alpha.9
+
+## 1.1.26-alpha.16
+
+### Patch Changes
+
+- Updated dependencies [[`1bd5104`](https://github.com/mastra-ai/mastra/commit/1bd51048b6da93507276d6623e3fd96a9e1a8944)]:
+  - @mastra/core@1.26.0-alpha.8
+
+## 1.1.26-alpha.14
+
+### Patch Changes
+
+- Updated dependencies [[`8786a61`](https://github.com/mastra-ai/mastra/commit/8786a61fa54ba265f85eeff9985ca39863d18bb6), [`8fb2405`](https://github.com/mastra-ai/mastra/commit/8fb2405138f2d208b7962ad03f121ca25bcc28c5)]:
+  - @mastra/core@1.26.0-alpha.7
+
+## 1.1.26-alpha.12
+
+### Patch Changes
+
+- Updated dependencies [[`6315317`](https://github.com/mastra-ai/mastra/commit/63153175fe9a7b224e5be7c209bbebc01dd9b0d5), [`9d3b24b`](https://github.com/mastra-ai/mastra/commit/9d3b24b19407ae9c09586cf7766d38dc4dff4a69)]:
+  - @mastra/core@1.26.0-alpha.6
+
+## 1.1.26-alpha.9
+
+### Patch Changes
+
+- Updated dependencies [[`92dcf02`](https://github.com/mastra-ai/mastra/commit/92dcf029294210ac91b090900c1a0555a425c57a)]:
+  - @mastra/core@1.26.0-alpha.5
+
 ## 1.1.26-alpha.7
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.26-alpha.8",
+  "version": "1.1.26",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,26 +29,26 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.26.0-alpha.4",
-    "@mastra/mcp": "^1.5.1-alpha.1"
+    "@mastra/core": "1.26.0",
+    "@mastra/mcp": "^1.5.1"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
     "@types/jsdom": "^21.1.7",
     "@types/node": "22.19.15",
-    "@vitest/coverage-v8": "4.0.18",
-    "@vitest/ui": "4.0.18",
+    "@vitest/coverage-v8": "4.1.4",
+    "@vitest/ui": "4.1.4",
     "@wong2/mcp-cli": "^1.13.0",
     "cross-env": "^10.1.0",
-    "eslint": "^9.39.4",
+    "eslint": "^10.2.1",
     "hono": "^4.12.8",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "4.0.18",
-    "@internal/lint": "0.0.83",
-    "@internal/types-builder": "0.0.58",
-    "@mastra/core": "1.26.0-alpha.4"
+    "vitest": "4.1.4",
+    "@internal/lint": "0.0.84",
+    "@mastra/core": "1.26.0",
+    "@internal/types-builder": "0.0.59"
   },
   "homepage": "https://mastra.ai",
   "repository": {