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

package/.docs/docs/agents/overview.md

@@ -210,7 +210,7 @@ Once your agent is running, use this table to find the right page for what you w
 | Keep your agent safe                                           | [Guardrails](https://mastra.ai/docs/agents/guardrails)                 |
 | Build agents that correct their work                           | [Rubric scorer](https://mastra.ai/docs/agents/supervisor-agents)       |
 | Swap instructions or models based on request context           | [Dynamic configuration](https://mastra.ai/docs/server/request-context) |
-| Add speech-to-text or text-to-speech                           | [Voice](https://mastra.ai/docs/voice/overview)                         |
+| Add speech-to-text or text-to-speech                           | [Voice](https://mastra.ai/guides/voice/overview)                       |
 | Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/capabilities/channels/overview)      |
 
 ## Multi-agent systems

package/.docs/docs/agents/supervisor-agents.md

@@ -420,12 +420,12 @@ const result = await supervisor.generate('Research and write about AI safety', {
 })
 ```
 
-Version overrides propagate automatically through delegation. See [Subagent versioning](https://mastra.ai/docs/editor/overview) for details on resolution order and server API usage.
+Version overrides propagate automatically through delegation. See [Subagent versioning](https://mastra.ai/reference/editor/versioning) for details on resolution order and server API usage.
 
 ## Related
 
 - [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks)
-- [Subagent versioning](https://mastra.ai/docs/editor/overview)
+- [Subagent versioning](https://mastra.ai/reference/editor/versioning)
 - [Guide: Research coordinator](https://mastra.ai/guides/guide/research-coordinator)
 - [Agent.stream() reference](https://mastra.ai/reference/streaming/agents/stream)
 - [Agent.streamUntilIdle() reference](https://mastra.ai/reference/streaming/agents/streamUntilIdle)

package/.docs/docs/agents/using-tools.md

@@ -478,6 +478,7 @@ Mastra includes agent-agnostic built-in tools in `@mastra/core/tools` that add i
 | `task_complete` | Mark one tracked task completed                      |
 | `task_check`    | Check task list completion status                    |
 | `webSearchTool` | Run provider-native web search with the active model |
+| `webFetchTool`  | Fetch a web page by URL and return its text content  |
 
 ### Use provider web search
 
@@ -502,6 +503,34 @@ export const researchAgent = new Agent({
 
 The `search` key is only the agent-local tool name. Use any key. The `webSearchTool` value tells Mastra to use provider web search.
 
+### Fetch a web page
+
+Import `webFetchTool` from `@mastra/core/tools` when the agent needs to read a specific URL. The tool requests the page over HTTP or HTTPS and returns its text content plus response metadata.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { webFetchTool } from '@mastra/core/tools'
+
+export const readerAgent = new Agent({
+  id: 'reader-agent',
+  name: 'Reader Agent',
+  instructions: 'Fetch the page the user links to before answering.',
+  model: 'openai/gpt-5.6-sol',
+  tools: {
+    fetch: webFetchTool,
+  },
+})
+```
+
+The tool takes a single `url` input and returns `content`, `truncated`, `status`, `statusText`, `contentType`, `url`, and `ok`. It applies these limits:
+
+- Only `http:` and `https:` URLs are allowed.
+- Requests to `localhost` and to private or reserved IP addresses are blocked, including addresses returned by DNS resolution.
+- Responses are truncated at 100,000 characters, with `truncated: true` in the result.
+- Requests follow at most 5 redirects and time out after 15 seconds.
+
+Failures don't throw. The tool returns `isError: true` with the reason in `content`, so the agent can retry or explain the problem.
+
 ### Ask the user a question
 
 Import [`askUserTool`](https://mastra.ai/reference/tools/ask-user-tool) and add it to the agent's toolset.

package/.docs/docs/capabilities/channels/imessage.md

@@ -0,0 +1,181 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# iMessage
+
+iMessage channels let a Mastra agent receive direct messages and group messages from iMessage. Mastra handles the agent wiring, the webhook route, and the gateway listener; the Photon iMessage adapter docs cover number provisioning, credentials, and webhook registration.
+
+## Install the adapter
+
+Install the Photon iMessage adapter:
+
+**npm**:
+
+```bash
+npm install @photon-ai/chat-adapter-imessage
+```
+
+**pnpm**:
+
+```bash
+pnpm add @photon-ai/chat-adapter-imessage
+```
+
+**Yarn**:
+
+```bash
+yarn add @photon-ai/chat-adapter-imessage
+```
+
+**Bun**:
+
+```bash
+bun add @photon-ai/chat-adapter-imessage
+```
+
+## Agent configuration
+
+Add `createiMessageAdapter()` to the agent's `channels.adapters` object:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createiMessageAdapter } from '@photon-ai/chat-adapter-imessage'
+
+export const imessageAgent = new Agent({
+  id: 'imessage-agent',
+  name: 'iMessage Agent',
+  instructions: 'Answer questions and help with tasks over iMessage.',
+  model: 'openai/gpt-5.6-sol',
+  channels: {
+    adapters: {
+      imessage: {
+        adapter: createiMessageAdapter(),
+        toolDisplay: 'text',
+      },
+    },
+    threadContext: { maxMessages: 0 },
+  },
+})
+```
+
+Register the agent on the Mastra instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { imessageAgent } from './agents/imessage-agent'
+
+export const mastra = new Mastra({
+  agents: { imessageAgent },
+})
+```
+
+Use `imessage` as the adapter key. Mastra derives the webhook path and the `platform` value on `requestContext` from this key.
+
+`toolDisplay: 'text'` describes tool calls in the message, since iMessage has no interactive cards for Approve and Deny actions. `threadContext: { maxMessages: 0 }` skips the platform history lookup Mastra runs when an agent is first mentioned in a group chat, which the adapter can't perform. Both override defaults that assume platform features iMessage lacks.
+
+## Adapter setup
+
+Follow the [Photon iMessage adapter docs](https://github.com/photon-hq/vercel-chat-adapter-imessage) for iMessage-specific setup, including number provisioning, hosted and self-hosted modes, and webhook registration. The adapter picks its mode from the environment variables you set.
+
+For the hosted service, create a project at [app.photon.codes](https://app.photon.codes) and use the project credentials:
+
+```bash
+IMESSAGE_PROJECT_ID=your-project-id
+IMESSAGE_PROJECT_SECRET=your-project-secret
+IMESSAGE_WEBHOOK_SECRET=your-webhook-signing-secret
+```
+
+For a self-hosted server, point the adapter at its gRPC address, written as `host:port`. The adapter strips any URL scheme and appends `:443` to a bare host:
+
+```bash
+IMESSAGE_SERVER_URL=imessage.example.com:443
+IMESSAGE_API_KEY=your-server-token
+IMESSAGE_PHONE=+15551234567
+```
+
+`IMESSAGE_PHONE` is optional and routes messages when a self-hosted server has several numbers. You can also pass these values to `createiMessageAdapter()` directly, including a `credentials` function that resolves the project ID and secret at first use from a secret store.
+
+## Webhook URL
+
+Mastra generates the iMessage webhook route from the agent ID and adapter key:
+
+```text
+/api/agents/imessage-agent/channels/imessage/webhook
+```
+
+Use your public Mastra server URL as the base URL:
+
+```text
+https://your-app.example.com/api/agents/imessage-agent/channels/imessage/webhook
+```
+
+Register this URL in the [Photon dashboard](https://app.photon.codes), then set the signing secret it returns as `IMESSAGE_WEBHOOK_SECRET`. The secret is shown once at registration. The adapter verifies the signature on every delivery and rejects requests that don't match. Webhooks are available in hosted mode only.
+
+Photon retries failed deliveries with backoff and delivers at least once, so the same message can arrive twice. Chat SDK drops the repeat using the channel state adapter, and Mastra's default keeps those dedup keys in memory. That covers a single long-running server.
+
+A repeat can still reach the agent after a restart, or on serverless where the retry is routed to a different instance. Pass a shared state adapter on `channels.state` so dedup keys are visible everywhere. Install one alongside the adapter:
+
+**npm**:
+
+```bash
+npm install @chat-adapter/state-redis
+```
+
+**pnpm**:
+
+```bash
+pnpm add @chat-adapter/state-redis
+```
+
+**Yarn**:
+
+```bash
+yarn add @chat-adapter/state-redis
+```
+
+**Bun**:
+
+```bash
+bun add @chat-adapter/state-redis
+```
+
+`createRedisState()` reads the `REDIS_URL` environment variable:
+
+```typescript
+import { createRedisState } from '@chat-adapter/state-redis'
+
+channels: {
+  adapters: {
+    imessage: {
+      adapter: createiMessageAdapter(),
+      toolDisplay: 'text',
+    },
+  },
+  threadContext: { maxMessages: 0 },
+  state: createRedisState(),
+},
+```
+
+This matters most for tools with side effects, where handling the same message twice is visible to the user.
+
+> **Note:** Photon delivers to public HTTPS endpoints only. It won't deliver to `http://`, to private addresses like `localhost`, or through a redirect. For local development, use a tunnel as described in the [Channels overview](https://mastra.ai/docs/capabilities/channels/overview).
+
+## Gateway listener
+
+The adapter can hold an open connection and stream messages in real time instead of receiving webhooks. This works in both hosted and self-hosted modes.
+
+Mastra starts this listener during initialization and reconnects it if it drops, so no cron job or extra route is needed on a long-running server. Set `gateway: false` on the adapter config to turn it off when you use webhooks:
+
+```typescript
+imessage: {
+  adapter: createiMessageAdapter(),
+  toolDisplay: 'text',
+  gateway: false,
+},
+```
+
+On serverless platforms, prefer webhooks. A gateway listener needs a process that stays alive. See [Serverless deployment](https://mastra.ai/docs/capabilities/channels/overview).
+
+## Related
+
+- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
+- [More](https://mastra.ai/docs/capabilities/channels/other-adapters)

package/.docs/docs/capabilities/channels/overview.md

@@ -13,6 +13,7 @@ Start with the page for your platform:
 - [Discord](https://mastra.ai/docs/capabilities/channels/discord)
 - [Telegram](https://mastra.ai/docs/capabilities/channels/telegram)
 - [WhatsApp](https://mastra.ai/docs/capabilities/channels/whatsapp)
+- [iMessage](https://mastra.ai/docs/capabilities/channels/imessage)
 
 [More](https://mastra.ai/docs/capabilities/channels/other-adapters) lists additional platforms. Mastra channels work with compatible [Chat SDK adapters](https://chat-sdk.dev/adapters) beyond the platforms listed here, and the same Mastra configuration pattern applies across adapters.
 

package/.docs/docs/{evals/datasets → datasets}/overview.md

@@ -49,7 +49,7 @@ Visit the [`DatasetsManager` reference](https://mastra.ai/reference/datasets/dat
 
 You can also manage datasets in [Studio](https://mastra.ai/docs/studio/overview). After opening Studio, select **Datasets** from the sidebar to see all your available datasets or create a new one.
 
-To get started, select **Create Dataset** and set a name, description, and optional schemas. After confirming, you'll see the dataset details page with two tabs: **Items** and [**Experiments**](https://mastra.ai/docs/evals/datasets/running-experiments).
+To get started, select **Create Dataset** and set a name, description, and optional schemas. After confirming, you'll see the dataset details page with two tabs: **Items** and [**Experiments**](https://mastra.ai/docs/datasets/running-experiments).
 
 In the **Items** view you can add, update, and delete items, and view version history. Select **Add Item** to insert a new item with JSON editors for input and ground truth. From this view you can also import items in bulk from a CSV or JSON file. When importing, map each column to the corresponding dataset field.
 
@@ -198,11 +198,11 @@ Fetch the exact items that existed at a past version:
 const items = await dataset.listItems({ version: 2 })
 ```
 
-You can also pin experiments to a version, see [running experiments](https://mastra.ai/docs/evals/datasets/running-experiments). Visit the [`Dataset` reference](https://mastra.ai/reference/datasets/dataset) for the full list of methods and parameters.
+You can also pin experiments to a version, see [running experiments](https://mastra.ai/docs/datasets/running-experiments). Visit the [`Dataset` reference](https://mastra.ai/reference/datasets/dataset) for the full list of methods and parameters.
 
 ## Related
 
-- [Running experiments](https://mastra.ai/docs/evals/datasets/running-experiments)
+- [Running experiments](https://mastra.ai/docs/datasets/running-experiments)
 - [Scorers overview](https://mastra.ai/docs/evals/overview)
 - [DatasetsManager reference](https://mastra.ai/reference/datasets/datasets-manager)
 - [Dataset reference](https://mastra.ai/reference/datasets/dataset)

package/.docs/docs/{evals/datasets → datasets}/running-experiments.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.4.0`
 
-An experiment runs every item in a dataset through a target (an agent, a workflow, or a scorer) and then optionally scores the outputs. Use a scorer as the target when you want to evaluate an LLM judge itself. Results are persisted to storage so you can compare runs across different prompts, models, or code changes.
+An experiment runs every item in a dataset through a target (an agent, a workflow, or a scorer) and then optionally scores the outputs. Use a scorer as the target when you want to evaluate an LLM judge itself. By default, results are persisted to storage so you can compare runs across different prompts, models, or code changes.
 
 **For AI agents:** Run `npx mastra api experiment run dataset_123 '{"name":"translation-baseline"}'` to start an experiment directly instead of opening Studio or writing a temporary script. Use a dataset ID returned by `npx mastra api dataset list` in place of the sample ID. The command requires a running Mastra server with dataset storage and registered experiment targets; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api experiment run --schema` before constructing different input, and get user approval before starting an experiment because it can make model calls. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
 
@@ -131,6 +131,63 @@ for (const item of summary.results) {
 
 Visit the [Scorers overview](https://mastra.ai/docs/evals/overview) for details on available and custom scorers.
 
+## Control persistence per run
+
+Use `persistence` to skip storage writes for a specific run. Experiment records and score records can be disabled independently:
+
+```typescript
+const summary = await dataset.startExperiment({
+  targetType: 'agent',
+  targetId: 'translation-agent',
+  scorers: ['accuracy'],
+  persistence: {
+    experiments: 'none',
+    scores: 'none',
+  },
+})
+```
+
+The target and scorers still run, and `startExperiment()` still returns the item results and scores in `summary`. The settings are independent. For example, set only `scores: 'none'` to persist the experiment and its item results without creating score records.
+
+Omitted settings default to `'default'`, which preserves the standard storage behavior. This policy only controls experiment and score records created by the run. It doesn't disable storage used by the target, such as agent memory, vectors, observability, or custom tool storage.
+
+When `startExperimentAsync()` runs with `experiments: 'none'`, it doesn't persist an experiment record, progress updates, or item results. Score persistence remains controlled separately by `persistence.scores`. Without an experiment event observer, the run is fire-and-forget, and the experiment API can't report whether it completed or failed.
+
+Use synchronous `startExperiment()` when the caller needs the returned summary. An experiment event observer can receive lifecycle events and the terminal summary.
+
+## Observe experiment events
+
+Use `onEvent` to receive versioned, JSON-safe lifecycle events while an experiment runs. This works with `startExperiment()`, `startExperimentAsync()`, and `runExperiment()`.
+
+```typescript
+import type { ExperimentEvent } from '@mastra/core/datasets'
+
+const events: ExperimentEvent[] = []
+
+await dataset.startExperimentAsync({
+  task: async ({ input }) => processItem(input),
+  persistence: { experiments: 'none' },
+  onEvent: async event => {
+    events.push(event)
+    await publishEvent(event)
+  },
+})
+```
+
+The observer receives these event types:
+
+- `experiment.run.started`: Identifies the run, target, resolved dataset version, and item count.
+- `experiment.item.completed`: Reports a committed item result after scoring, including scores, errors, retry count, tool mock details, and stable item identity.
+- `experiment.run.finished`: Reports the terminal outcome and summary counters.
+
+Mastra awaits each observer call before delivering the next event. This serialized delivery applies backpressure and ensures event `sequence` values match delivery order, while item execution can remain concurrent.
+
+If the observer throws or rejects, Mastra aborts the remaining run and rejects `runExperiment()` with a `MastraError` whose `id` is `EXPERIMENT_EVENT_OBSERVER_FAILED`. It doesn't send a terminal event through the failed observer. For `startExperimentAsync()`, the method has already returned when a detached observer fails, so handle delivery failures inside the observer when the caller needs direct error reporting.
+
+The `experiment.run.finished` event is awaited before Mastra persists the final experiment status. Treat the event as the authoritative terminal signal when experiment persistence is disabled, but don't use it as a read-after-write signal for storage.
+
+The exported event types are `ExperimentEvent`, `ExperimentRunStartedEvent`, `ExperimentItemCompletedEvent`, and `ExperimentRunFinishedEvent`. Use the discriminated `type` field to narrow an event before reading event-specific properties.
+
 ## Tool mocks
 
 When an experiment runs an agent that calls side-effecting tools, attach static tool mocks to individual dataset items to make the run deterministic. During the experiment, a mocked tool returns its declared output instead of executing. Tools without a mock on the item run live by default.
@@ -374,7 +431,7 @@ Visit the [`startExperiment` reference](https://mastra.ai/reference/datasets/sta
 
 ## Related
 
-- [Datasets overview](https://mastra.ai/docs/evals/datasets/overview)
+- [Datasets overview](https://mastra.ai/docs/datasets/overview)
 - [Scorers overview](https://mastra.ai/docs/evals/overview)
 - [`startExperiment` reference](https://mastra.ai/reference/datasets/startExperiment)
 - [`listExperimentResults` reference](https://mastra.ai/reference/datasets/listExperimentResults)